Add type annotations

- Add CI to check these work for oldest and newest supported Python versions
- Add the py.typed marker file

Author: cjw296

.github/workflows/ci.yml

@@ -116,3 +116,25 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: cjw296/python-action/check-coverage@v1
+
+  typing:
+    name: python ${{ matrix.python-version }} type checking
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.9"
+          - "3.13"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache-dependency-glob: "**/pyproject.toml"
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run mypy pytest_sqlalchemy.py tests

pyproject.toml

@@ -29,8 +29,10 @@ sqlalchemy = "pytest_sqlalchemy"
 
 [dependency-groups]
 dev = [
+    "mypy>=1.15.0",
     "pytest-xdist>=3.6.1",
 ]
+
 [build-system]
 requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
@@ -39,5 +41,13 @@ build-backend = "setuptools.build_meta"
 source = ["pytest_sqlalchemy", "tests"]
 parallel = true
 
+[tool.mypy]
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[[tool.mypy.overrides]]
+module = "sqlalchemy_utils.*"
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 norecursedirs = ["tests/examples"]

pytest_sqlalchemy.py

@@ -1,12 +1,17 @@
 #!/usr/bin/env python
 # encoding: utf-8
 
+from typing import Any, Dict, Mapping, Optional
+
 import pytest
 import sqlalchemy_utils.functions
+from pytest import FixtureRequest, Parser
+from sqlalchemy import engine_from_config
+from sqlalchemy.engine import Connection, create_engine, Engine
 
 
 @pytest.fixture(scope="session")
-def engine(request, sqlalchemy_connect_url, app_config):
+def engine(request: FixtureRequest, sqlalchemy_connect_url: Optional[str], app_config: Optional[Dict[str, str]]) -> Engine:
     """Engine configuration.
     See http://docs.sqlalchemy.org/en/latest/core/engines.html
     for more details.
@@ -19,10 +24,8 @@ def engine(request, sqlalchemy_connect_url, app_config):
 
     """
     if app_config:
-        from sqlalchemy import engine_from_config
         engine = engine_from_config(app_config)
     elif sqlalchemy_connect_url:
-        from sqlalchemy.engine import create_engine
         engine = create_engine(sqlalchemy_connect_url)
     else:
         raise RuntimeError("Can not establish a connection to the database")
@@ -34,7 +37,7 @@ def engine(request, sqlalchemy_connect_url, app_config):
         url = engine.url.set(database=f'{engine.url.database}_{xdist_suffix}')
         engine = create_engine(url)  # override engine
 
-    def fin():
+    def fin() -> None:
         print ("Disposing engine")
         engine.dispose()
 
@@ -43,7 +46,7 @@ def fin():
 
 
 @pytest.fixture(scope="session")
-def db_schema(request, engine, sqlalchemy_manage_db, sqlalchemy_keep_db):
+def db_schema(request: FixtureRequest, engine: Engine, sqlalchemy_manage_db: bool, sqlalchemy_keep_db: bool) -> Optional[None]:
     if not sqlalchemy_manage_db:
         return
 
@@ -55,18 +58,18 @@ def db_schema(request, engine, sqlalchemy_manage_db, sqlalchemy_keep_db):
         sqlalchemy_utils.functions.create_database(engine.url)
 
     if not sqlalchemy_keep_db:
-        def fin():
+        def fin() -> None:
             print ("Tearing down DB")
             sqlalchemy_utils.functions.drop_database(engine.url)
 
         request.addfinalizer(fin)
 
 
 @pytest.fixture(scope="module")
-def connection(request, engine, db_schema):
+def connection(request: FixtureRequest, engine: Engine, db_schema: Optional[None]) -> Connection:
     connection = engine.connect()
 
-    def fin():
+    def fin() -> None:
         print ("Closing connection")
         connection.close()
 
@@ -75,12 +78,12 @@ def fin():
 
 
 @pytest.fixture()
-def transaction(request, connection):
+def transaction(request: FixtureRequest, connection: Connection) -> Connection:
     """Will start a transaction on the connection. The connection will
     be rolled back after it leaves its scope."""
     transaction = connection.begin()
 
-    def fin():
+    def fin() -> None:
         print ("Rollback")
         transaction.rollback()
 
@@ -89,34 +92,34 @@ def fin():
 
 
 @pytest.fixture()
-def dbsession(request, connection):
+def dbsession(request: FixtureRequest, connection: Connection) -> Any:
     from sqlalchemy.orm import sessionmaker
     return sessionmaker()(bind=connection)
 
 
 # Config options
 @pytest.fixture(scope="session")
-def sqlalchemy_connect_url(request):
+def sqlalchemy_connect_url(request: FixtureRequest) -> Optional[str]:
     return request.config.getoption("--sqlalchemy-connect-url")
 
 
 @pytest.fixture(scope="session")
-def connect_uri(request, sqlalchemy_connect_url):
+def connect_uri(request: FixtureRequest, sqlalchemy_connect_url: Optional[str]) -> Optional[str]:
     return sqlalchemy_connect_url
 
 
 @pytest.fixture(scope="session")
-def sqlalchemy_manage_db(request):
+def sqlalchemy_manage_db(request: FixtureRequest) -> Optional[bool]:
     return request.config.getoption("--sqlalchemy-manage-db")
 
 
 @pytest.fixture(scope="session")
-def sqlalchemy_keep_db(request):
+def sqlalchemy_keep_db(request: FixtureRequest) -> Optional[bool]:
     return request.config.getoption("--sqlalchemy-keep-db")
 
 
 @pytest.fixture(scope="session")
-def app_config(request):
+def app_config(request: FixtureRequest) -> Optional[Mapping[str, str]]:
     """Example of a config file:
 
     [DEFAULT]
@@ -132,7 +135,7 @@ def app_config(request):
     return None
 
 
-def pytest_addoption(parser):
+def pytest_addoption(parser: Parser) -> None:
     parser.addoption("--sqlalchemy-connect-url", action="store",
                      default=None,
                      help="Name of the database to connect to")

tests/examples/test_connect_uri.py

@@ -1,2 +1,2 @@
-def test_uri(connect_uri):
+def test_uri(connect_uri: str) -> None:
     assert isinstance(connect_uri, str)

tests/examples/test_db_schema.py

@@ -1,7 +1,7 @@
-from sqlalchemy.engine import Connection
+from sqlalchemy.engine import Engine
 from sqlalchemy_utils import database_exists
 
 
-def test_db_schema(db_schema, engine):
+def test_db_schema(db_schema: None, engine: Engine) -> None:
     assert db_schema is None  # Not very helpful?
     assert database_exists(engine.url)

tests/examples/test_dbsession.py

@@ -1,5 +1,5 @@
 from sqlalchemy.orm import Session
 
 
-def test_session(dbsession):
+def test_session(dbsession: Session) -> None:
     assert isinstance(dbsession, Session)

tests/examples/test_minimal.py

@@ -1,6 +1,6 @@
 from sqlalchemy.engine import Connection
 
 
-def test_connection(connection):
+def test_connection(connection: Connection) -> None:
     assert isinstance(connection, Connection)
     assert not connection.in_transaction()

tests/examples/test_transaction.py

@@ -1,6 +1,6 @@
 from sqlalchemy.engine import Connection
 
 
-def test_transaction(transaction):
+def test_transaction(transaction: Connection) -> None:
     assert isinstance(transaction, Connection)
     assert transaction.in_transaction()

tests/examples/test_xdist.py

@@ -1,5 +1,9 @@
-def test_one(engine):
-    assert '_gw' in engine.url.database
+from sqlalchemy.engine import Engine
 
-def test_two(engine):
-    assert '_gw' in engine.url.database
+def test_one(engine: Engine) -> None:
+    db_name = str(engine.url.database) if engine.url.database is not None else ""
+    assert '_gw' in db_name
+
+def test_two(engine: Engine) -> None:
+    db_name = str(engine.url.database) if engine.url.database is not None else ""
+    assert '_gw' in db_name