Make mypy-docs pass and add it to CI + env_list

.github/workflows/test.yaml

@@ -85,6 +85,7 @@ jobs:
               - "mypy-py3.14"
               - "mypy-py3.9"
               - "mypy-test"
+              - "mypy-docs"
               - "poetry-check"
               - "pylint"
               - "test-lazy-imports"

changelog.d/20260814_174036_sirosen_final_mypy_docs.rst

@@ -0,0 +1,6 @@
+Documentation
+-------------
+
+- All example files in the globus-sdk documentation are now required to pass
+  type checking. Documentation examples will feature type annotations where they
+  are instructive and clarifying. (:pr:`NUMBER`)

docs/mypy.ini

@@ -0,0 +1,14 @@
+[mypy]
+# baseline at --strict, but then allow exemptions
+strict = true
+sqlite_cache = true
+warn_unreachable = true
+warn_no_return = true
+allow_untyped_calls = true
+allow_untyped_defs = true
+explicit_package_bases = true
+
+[mypy-docs.examples.token_storage.dynamodb_token_storage]
+# example needs to be allowed to import boto3
+ignore_missing_imports = true
+disable_error_code = import-not-found

docs/user_guide/getting_started/list_groups_noapp_with_storage.py

@@ -1,4 +1,5 @@
 import os
+import sys
 
 import globus_sdk
 from globus_sdk.token_storage import JSONTokenStorage
@@ -32,6 +33,10 @@
 
 # load the tokens from the storage -- either freshly stored or loaded from disk
 token_data = token_storage.get_token_data(globus_sdk.GroupsClient.resource_server)
+if token_data is None or token_data.refresh_token is None:
+    print("error: token data was not present or was malformed")
+    print(f"       try removing the token file at {token_storage.filepath!r}")
+    sys.exit(1)
 
 # construct the RefreshTokenAuthorizer which writes back to storage on refresh
 authorizer = globus_sdk.RefreshTokenAuthorizer(

tox.ini

@@ -2,6 +2,7 @@
 envlist =
     lint
     mypy
+    mypy-docs
     pylint
     test-lazy-imports
     coverage_clean