feat: Type Annotate the *heck* out of social-core (#986)

* Add py.typed and pyright to the build

This enables typing in social_core and gives us the tools for testing

* Many type annotation updates

- ignore several errors that are endemic to mixin-type test strategies
- in several cases assert that tests are set up correctly to give the
  type checker some help
- for tidiness, mark some test-like class names as not-a-test

* Most backends updated

* Add type testing to the test action workflow

* Ignore two very common type errors in the codebase

* Restrict lxml to 5.2

xmlsec/python-xmlsec#320

* Undo a TODO that is not actually a bug

* Correctly use __future__ annotations in models.py


Co-authored-by: Michal Čihař <[email protected]>

Author: offbyone

.github/workflows/test.yml

@@ -3,6 +3,43 @@ name: Tests
 on: [push, pull_request]
 
 jobs:
+  types:
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+        - '3.9'
+        - '3.13'
+    env:
+      PYTHON_VERSION: ${{ matrix.python-version }}
+      PYTHONUNBUFFERED: 1
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: pip
+        cache-dependency-path: requirements*.txt
+
+    - name: Install System dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -qq -y --no-install-recommends libxmlsec1-dev swig
+
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install tox
+
+    - name: Type check with tox
+      run: tox -e "py${PYTHON_VERSION/\./}-pyright"
+
   test:
     runs-on: ubuntu-22.04
     strategy:

pyproject.toml

@@ -119,6 +119,8 @@ Homepage = "https://github.com/python-social-auth/social-core"
 [project.optional-dependencies]
 saml = [
    "python3-saml>=1.5.0",
+   # pinned to 5.2 until a new wheel of xmlsec is released
+   "lxml~=5.2.1",
 ]
 azuread = [
     "cryptography>=2.1.1",
@@ -140,6 +142,7 @@ dev = [
     "pytest-cov>=2.7.1",
     # pinned because of https://github.com/gabrielfalcao/HTTPretty/issues/484
     "urllib3~=2.2.0",
+    "pyright>=1.1.391",
 ]
 
 [build-system]
@@ -155,4 +158,6 @@ dev = [
     "pytest-cov>=2.7.1",
     # pinned because of https://github.com/gabrielfalcao/HTTPretty/issues/484
     "urllib3~=2.2.0",
+    "pyright>=1.1.391",
+    "pytest-xdist>=3.6.1",
 ]

pyrightconfig.json

@@ -0,0 +1,4 @@
+{
+    "reportOptionalMemberAccess": "none",
+    "reportPossiblyUnboundVariable": "none"
+}

social_core/actions.py

@@ -101,6 +101,8 @@ def do_complete(backend, login, user=None, redirect_name="next", *args, **kwargs
     else:
         url = setting_url(backend, "LOGIN_ERROR_URL", "LOGIN_URL")
 
+    assert url, "By this point URL has to have been set"
+
     if redirect_value and redirect_value != url:
         redirect_value = quote(redirect_value)
         url += ("&" if "?" in url else "?") + f"{redirect_name}={redirect_value}"

social_core/backends/apple.py

@@ -21,8 +21,11 @@
                                                    login
 """
 
+from __future__ import annotations
+
 import json
 import time
+from typing import TYPE_CHECKING
 
 import jwt
 from jwt.algorithms import RSAAlgorithm
@@ -31,6 +34,9 @@
 from social_core.backends.oauth import BaseOAuth2
 from social_core.exceptions import AuthFailed
 
+if TYPE_CHECKING:
+    from jwt.types import JWKDict
+
 
 class AppleIdAuth(BaseOAuth2):
     name = "apple-id"
@@ -96,7 +102,7 @@ def get_key_and_secret(self):
         client_secret = self.generate_client_secret()
         return client_id, client_secret
 
-    def get_apple_jwk(self, kid=None):
+    def get_apple_jwk(self, kid=None) -> str | JWKDict:
         """
         Return requested Apple public key or all available.
         """
@@ -107,7 +113,9 @@ def get_apple_jwk(self, kid=None):
 
         if kid:
             return json.dumps(next(key for key in keys if key["kid"] == kid))
-        return (json.dumps(key) for key in keys)
+        # TODO: this should actually return a JWKDict; the caller expects it.
+        # I suspect this code path is never hit in practice
+        return (json.dumps(key) for key in keys)  # type:ignore[reportReturnType]
 
     def decode_id_token(self, id_token):
         """
@@ -120,9 +128,10 @@ def decode_id_token(self, id_token):
         try:
             kid = jwt.get_unverified_header(id_token).get("kid")
             public_key = RSAAlgorithm.from_jwk(self.get_apple_jwk(kid))
+
             decoded = jwt.decode(
                 id_token,
-                key=public_key,
+                key=public_key,  # type: ignore[reportArgumentType]
                 audience=self.get_audience(),
                 algorithms=["RS256"],
             )

social_core/backends/auth0.py

@@ -61,6 +61,7 @@ def get_user_details(self, response):
             else:
                 break
         else:
+            assert signature_error is not None
             # raise last esception found during iteration
             raise signature_error
 

social_core/backends/azuread_b2c.py

@@ -128,7 +128,10 @@ def jwt_key_to_pem(self, key_json_dict):
         Builds a PEM formatted key string from a JWT public key dict.
         """
         pub_key = RSAAlgorithm.from_jwk(json.dumps(key_json_dict))
-        return pub_key.public_bytes(
+
+        # TODO: clarify the types of this; JWKs can apparently include both public and private,
+        # but this code assumes public.
+        return pub_key.public_bytes(  # type: ignore[reportAttributeAccessIssue]
             encoding=serialization.Encoding.PEM,
             format=serialization.PublicFormat.SubjectPublicKeyInfo,
         )

social_core/backends/azuread_tenant.py

@@ -97,7 +97,7 @@ def user_data(self, access_token, *args, **kwargs):
 
             return jwt_decode(
                 id_token,
-                key=certificate.public_key(),
+                key=certificate.public_key(),  # type: ignore[reportArgumentType]
                 algorithms=["RS256"],
                 audience=self.setting("KEY"),
             )

social_core/backends/base.py

@@ -1,4 +1,5 @@
 import time
+from typing import Any
 
 from requests import ConnectionError, request
 
@@ -118,7 +119,9 @@ def run_pipeline(self, pipeline, pipeline_index=0, *args, **kwargs):
             out.update(result)
         return out
 
-    def extra_data(self, user, uid, response, details=None, *args, **kwargs):
+    def extra_data(
+        self, user, uid, response, details=None, *args, **kwargs
+    ) -> dict[str, Any]:
         """Return default extra data to store in extra_data field"""
         data = {
             # store the last time authentication toke place
@@ -137,9 +140,9 @@ def extra_data(self, user, uid, response, details=None, *args, **kwargs):
             size = len(entry)
             if size >= 1 and size <= 3:
                 if size == 3:
-                    name, alias, discard = entry
+                    name, alias, discard = entry  # type: ignore[reportAssignmentType]
                 elif size == 2:
-                    (name, alias), discard = entry, False
+                    (name, alias), discard = entry, False  # type: ignore[reportAssignmentType]
                 elif size == 1:
                     name = alias = entry[0]
                     discard = False
@@ -213,7 +216,7 @@ def auth_extra_arguments(self):
         )
         return extra_arguments
 
-    def uses_redirect(self):
+    def uses_redirect(self) -> bool:
         """Return True if this provider uses redirect url method,
         otherwise return false."""
         return True

social_core/backends/bitbucket.py

@@ -12,13 +12,13 @@ class BitbucketOAuthBase:
 
     def get_user_id(self, details, response):
         id_key = self.ID_KEY
-        if self.setting("USERNAME_AS_ID", False):
+        if self.setting("USERNAME_AS_ID", False):  # type: ignore[reportAttributeAccessIssue]
             id_key = "username"
         return response.get(id_key)
 
     def get_user_details(self, response):
         """Return user details from Bitbucket account"""
-        fullname, first_name, last_name = self.get_user_names(response["display_name"])
+        fullname, first_name, last_name = self.get_user_names(response["display_name"])  # type: ignore[reportAttributeAccessIssue]
 
         return {
             "username": response.get("username", ""),
@@ -38,7 +38,7 @@ def user_data(self, access_token, *args, **kwargs):
             if address["is_primary"]:
                 break
 
-        if self.setting("VERIFIED_EMAILS_ONLY", False) and not address["is_confirmed"]:
+        if self.setting("VERIFIED_EMAILS_ONLY", False) and not address["is_confirmed"]:  # type: ignore[reportAttributeAccessIssue]
             raise AuthForbidden(self, "Bitbucket account has no verified email")
 
         user = self._get_user(access_token)