fix: add PEP 561 py.typed markers for type checker support

andres-ito-traversal · andres-ito-traversal · commit 6e5a5e069bb7 · 2025-11-14T09:58:30.000-05:00
Add py.typed marker files to core and all module packages to indicate
  type information is available. This enables type checkers like Pyright
  and mypy to recognize and validate type hints in testcontainers packages.

  Resolves "Stub file not found" errors when running type checkers on
  code that imports testcontainers modules.
diff --git a/core/testcontainers/compose/__init__.py b/core/testcontainers/compose/__init__.py
@@ -1,4 +1,3 @@
-# flake8: noqa: F401
 from testcontainers.compose.compose import (
     ComposeContainer,
     DockerCompose,
diff --git a/core/testcontainers/py.typed b/core/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/arangodb/testcontainers/py.typed b/modules/arangodb/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/aws/testcontainers/py.typed b/modules/aws/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/azurite/testcontainers/py.typed b/modules/azurite/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/cassandra/testcontainers/py.typed b/modules/cassandra/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/chroma/testcontainers/py.typed b/modules/chroma/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/clickhouse/testcontainers/py.typed b/modules/clickhouse/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/cockroachdb/testcontainers/py.typed b/modules/cockroachdb/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/cosmosdb/testcontainers/py.typed b/modules/cosmosdb/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/db2/testcontainers/py.typed b/modules/db2/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/elasticsearch/testcontainers/py.typed b/modules/elasticsearch/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/generic/example_basic.py b/modules/generic/example_basic.py
@@ -59,7 +59,7 @@ def basic_example():
         print(f"\nPython container ID: {container_id}")
 
         # Execute command in container
-        exit_code, output = python.exec_run("python -c 'print(\"Hello from container!\")'")
+        _exit_code, output = python.exec(["python", "-c", 'print("Hello from container!")'])
         print(f"Command output: {output.decode()}")
 
     # Example 5: Container with health check
diff --git a/modules/generic/testcontainers/py.typed b/modules/generic/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/google/testcontainers/py.typed b/modules/google/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/influxdb/testcontainers/py.typed b/modules/influxdb/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/k3s/testcontainers/py.typed b/modules/k3s/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/kafka/testcontainers/py.typed b/modules/kafka/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/keycloak/testcontainers/py.typed b/modules/keycloak/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/localstack/testcontainers/py.typed b/modules/localstack/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/mailpit/testcontainers/py.typed b/modules/mailpit/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/memcached/testcontainers/py.typed b/modules/memcached/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/milvus/testcontainers/py.typed b/modules/milvus/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/minio/testcontainers/py.typed b/modules/minio/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/mongodb/testcontainers/py.typed b/modules/mongodb/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/mqtt/testcontainers/py.typed b/modules/mqtt/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/mssql/testcontainers/py.typed b/modules/mssql/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/mysql/testcontainers/py.typed b/modules/mysql/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/nats/testcontainers/py.typed b/modules/nats/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/neo4j/testcontainers/py.typed b/modules/neo4j/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/nginx/testcontainers/py.typed b/modules/nginx/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/ollama/testcontainers/py.typed b/modules/ollama/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/openfga/testcontainers/py.typed b/modules/openfga/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/opensearch/testcontainers/py.typed b/modules/opensearch/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/oracle-free/testcontainers/py.typed b/modules/oracle-free/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/postgres/example_basic.py b/modules/postgres/example_basic.py
@@ -1,11 +1,11 @@
-import pandas as pd
+import pandas as pd  # type: ignore[import-untyped]
 import sqlalchemy
 from sqlalchemy import text
 
 from testcontainers.postgres import PostgresContainer
 
 
-def basic_example():
+def basic_example() -> None:
     with PostgresContainer() as postgres:
         # Get connection URL
         connection_url = postgres.get_connection_url()
diff --git a/modules/postgres/testcontainers/postgres/__init__.py b/modules/postgres/testcontainers/postgres/__init__.py
@@ -11,7 +11,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 import os
-from typing import Optional
+from typing import Any, Optional, Union, cast
 
 from testcontainers.core.generic import DbContainer
 from testcontainers.core.utils import raise_for_deprecated_parameter
@@ -53,13 +53,14 @@ def __init__(
         password: Optional[str] = None,
         dbname: Optional[str] = None,
         driver: Optional[str] = "psycopg2",
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
         raise_for_deprecated_parameter(kwargs, "user", "username")
         super().__init__(image=image, **kwargs)
-        self.username: str = username or os.environ.get("POSTGRES_USER", "test")
-        self.password: str = password or os.environ.get("POSTGRES_PASSWORD", "test")
-        self.dbname: str = dbname or os.environ.get("POSTGRES_DB", "test")
+        # Ensure concrete str types while preserving "falsy" fallback semantics
+        self.username: str = cast("str", username or os.environ.get("POSTGRES_USER", "test"))
+        self.password: str = cast("str", password or os.environ.get("POSTGRES_PASSWORD", "test"))
+        self.dbname: str = cast("str", dbname or os.environ.get("POSTGRES_DB", "test"))
         self.port = port
         self.driver = f"+{driver}" if driver else ""
 
@@ -70,7 +71,7 @@ def _configure(self) -> None:
         self.with_env("POSTGRES_PASSWORD", self.password)
         self.with_env("POSTGRES_DB", self.dbname)
 
-    def get_connection_url(self, host: Optional[str] = None, driver: Optional[str] = _UNSET) -> str:
+    def get_connection_url(self, host: Optional[str] = None, driver: Union[str, None, object] = _UNSET) -> str:
         """Get a DB connection URL to connect to the PG DB.
 
         If a driver is set in the constructor (defaults to psycopg2!), the URL will contain the
diff --git a/modules/postgres/testcontainers/postgres/py.typed b/modules/postgres/testcontainers/postgres/py.typed
diff --git a/modules/postgres/testcontainers/py.typed b/modules/postgres/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/postgres/tests/test_postgres.py b/modules/postgres/tests/test_postgres.py
@@ -1,4 +1,5 @@
 from pathlib import Path
+from typing import TypedDict
 
 import pytest
 import sqlalchemy
@@ -70,7 +71,13 @@ def test_quoted_password():
     password = "p@$%25+0&%rd :/!=?"
     quoted_password = "p%40%24%2525+0%26%25rd %3A%2F%21%3D%3F"
     driver = "psycopg2"
-    kwargs = {
+
+    class ConnKwargs(TypedDict, total=False):
+        driver: str
+        username: str
+        password: str
+
+    kwargs: ConnKwargs = {
         "driver": driver,
         "username": user,
         "password": password,
@@ -106,15 +113,20 @@ def test_show_how_to_initialize_db_via_initdb_dir():
         with engine.begin() as connection:
             connection.execute(sqlalchemy.text(insert_query))
             result = connection.execute(sqlalchemy.text(select_query))
-            result = result.fetchall()
-            assert len(result) == 1
-            assert result[0] == (1, "sally", "sells seashells")
+            rows = result.fetchall()
+            assert len(rows) == 1
+            assert rows[0] == (1, "sally", "sells seashells")
 
 
 def test_none_driver_urls():
     user = "root"
     password = "pass"
-    kwargs = {
+
+    class ConnKwargs(TypedDict, total=False):
+        username: str
+        password: str
+
+    kwargs: ConnKwargs = {
         "username": user,
         "password": password,
     }
diff --git a/modules/qdrant/testcontainers/py.typed b/modules/qdrant/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/rabbitmq/testcontainers/py.typed b/modules/rabbitmq/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/redis/testcontainers/py.typed b/modules/redis/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/registry/testcontainers/py.typed b/modules/registry/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/scylla/testcontainers/py.typed b/modules/scylla/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/selenium/testcontainers/py.typed b/modules/selenium/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/sftp/testcontainers/py.typed b/modules/sftp/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/test_module_import/testcontainers/py.typed b/modules/test_module_import/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/trino/testcontainers/py.typed b/modules/trino/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/vault/testcontainers/py.typed b/modules/vault/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/modules/weaviate/testcontainers/py.typed b/modules/weaviate/testcontainers/py.typed
@@ -0,0 +1 @@
+partial
diff --git a/pyproject.toml b/pyproject.toml
@@ -28,6 +28,8 @@ classifiers = [
     "Operating System :: Unix",
     "Operating System :: MacOS",
 ]
+# Ensure PEP 561 typing marker files are included in distributions
+include = ["**/py.typed"]
 # testcontainers-core is a proper package dependency - only modules needed here
 packages = [
     { include = "testcontainers", from = "core" },
@@ -354,7 +356,7 @@ mypy_path = [
     #    "modules/openfga",
     #    "modules/opensearch",
     #    "modules/oracle",
-    #    "modules/postgres",
+       "modules/postgres",
     #    "modules/rabbitmq",
     #    "modules/redis",
     #    "modules/selenium"

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,3 @@`
`1`		`-# flake8: noqa: F401`
`2`	`1`	`from testcontainers.compose.compose import (`
`3`	`2`	`ComposeContainer,`
`4`	`3`	`DockerCompose,`