Add type hints

.github/workflows/test.yml

@@ -18,7 +18,10 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install .[async,dev,test]
+          pip install .[async,dev,test,types]
+      - name: Type-check
+        run: |
+          mypy tweepy
       - name: Run tests
         run: |
           coverage run -m unittest discover tests

README.md

@@ -25,6 +25,8 @@ To use the `tweepy.asynchronous` subpackage, be sure to install with the
 
     pip install tweepy[async]
 
+For type hint dependencies, install with the `types` extra.
+
 You can also use Git to clone the repository from GitHub to install the latest
 development version:
 

docs/conf.py

@@ -35,6 +35,9 @@
   'sphinx_tabs.tabs'
 ]
 
+autodoc_typehints = 'description'
+autodoc_type_aliases = {'JSON': 'tweepy.client.JSON'}
+
 hoverxref_auto_ref = True
 hoverxref_domains = ['py']
 hoverxref_intersphinx = ['aiohttp', 'requests', 'requests_oauthlib']

docs/install.rst

@@ -12,6 +12,8 @@ To use the ``tweepy.asynchronous`` subpackage, be sure to install with the
 
     pip install tweepy[async]
 
+For type hint dependencies, install with the ``types`` extra.
+
 You can also use Git to clone the repository from GitHub to install the latest
 development version::
 

setup.cfg

@@ -6,6 +6,11 @@ omit =
     */python?.?/*
     */site-packages/*
 
+[mypy]
+show_error_codes = True
+pretty = True
+# strict = True
+
 [tox:tox]
 envlist = py37, py38, py39, py310, py311
 

setup.py

@@ -57,7 +57,15 @@
             "tox>=3.21.0",
          ],
         "socks": ["requests[socks]>=2.27.0,<3"],
-        "test": ["vcrpy>=1.10.3"],
+        "test": [
+            "mypy>=0.931",
+            "vcrpy>=1.10.3",
+        ],
+        "types": [
+            "types-oauthlib>=3.1.6,<4",
+            "types-requests>=2.27.11,<3",
+            "typing-extensions>=4.0,<5",
+        ],
     },
     test_suite="tests",
     keywords="twitter library",

tweepy/asynchronous/__init__.py

@@ -10,7 +10,7 @@
 
 try:
     import aiohttp
-    import async_lru
+    import async_lru  # type: ignore[import]
     import oauthlib
 except ModuleNotFoundError:
     from tweepy.errors import TweepyException

tweepy/asynchronous/client.py

@@ -3,7 +3,7 @@
 # See LICENSE for details.
 
 try:
-    from functools import cache
+    from functools import cache  # type: ignore[attr-defined]
 except ImportError:  # Remove when support for Python 3.8 is dropped
     from functools import lru_cache
     cache = lru_cache(maxsize=None)
@@ -14,7 +14,7 @@
 import time
 
 import aiohttp
-from async_lru import alru_cache
+from async_lru import alru_cache  # type: ignore[import]
 from oauthlib.oauth1 import Client as OAuthClient
 from yarl import URL
 

tweepy/auth.py

@@ -7,7 +7,9 @@
 
 import requests
 from requests.auth import AuthBase, HTTPBasicAuth
-from requests_oauthlib import OAuth1, OAuth1Session, OAuth2Session
+from requests_oauthlib import (  # type: ignore[import]
+    OAuth1, OAuth1Session, OAuth2Session
+)
 
 from tweepy.errors import TweepyException
 

tweepy/cache.py

@@ -2,6 +2,8 @@
 # Copyright 2009-2022 Joshua Roesslein
 # See LICENSE for details.
 
+from __future__ import annotations
+
 import datetime
 import hashlib
 import logging
@@ -129,7 +131,7 @@ class FileCache(Cache):
     """File-based cache"""
 
     # locks used to make cache thread-safe
-    cache_locks = {}
+    cache_locks: dict[str, threading.Lock] = {}
 
     def __init__(self, cache_dir, timeout=60):
         Cache.__init__(self, timeout)
@@ -398,7 +400,7 @@ def __init__(self, db, timeout=3600, collection='tweepy_cache'):
         self.col.create_index('created', expireAfterSeconds=timeout)
 
     def store(self, key, value):
-        from bson.binary import Binary
+        from bson.binary import Binary  # type: ignore[import]
 
         now = datetime.datetime.utcnow()
         blob = Binary(pickle.dumps(value))