pytest_pg 0.0.28__py3-none-any.whl

pytest_pg/__init__.py

@@ -0,0 +1,19 @@
+from importlib.metadata import version as _get_version
+
+from .fixtures import PG, pg, pg_11, pg_12, pg_13, pg_14, pg_15, pg_16, pg_17, pg_18, run_pg
+
+__all__: tuple[str, ...] = (
+    "PG",
+    "run_pg",
+    "pg",
+    "pg_11",
+    "pg_12",
+    "pg_13",
+    "pg_14",
+    "pg_15",
+    "pg_16",
+    "pg_17",
+    "pg_18",
+)
+
+__version__ = _get_version("pytest_pg")

pytest_pg/fixtures.py

@@ -0,0 +1,139 @@
+import contextlib
+import dataclasses
+import time
+import uuid
+from collections.abc import Generator
+
+import docker
+import docker.errors
+import pytest
+
+from .utils import find_unused_local_port, is_pg_ready, resolve_docker_host
+
+LOCALHOST = "127.0.0.1"
+DEFAULT_PG_USER = "postgres"
+DEFAULT_PG_PASSWORD = "mysecretpassword"
+DEFAULT_PG_DATABASE = "postgres"
+
+
+@dataclasses.dataclass(frozen=True)
+class PG:
+    host: str
+    port: int
+    user: str
+    password: str
+    database: str
+
+
+@contextlib.contextmanager
+def run_pg(image: str, ready_timeout: float = 30.0) -> Generator[PG, None, None]:
+    docker_client = docker.APIClient(base_url=resolve_docker_host(), version="auto")
+    try:
+        docker_client.inspect_image(image)
+    except docker.errors.ImageNotFound:
+        docker_client.pull(image)
+
+    unused_port = find_unused_local_port()
+
+    postgresql_data_path = "/var/lib/postgresql/data"
+
+    container = docker_client.create_container(
+        image=image,
+        name=f"pytest-pg-{uuid.uuid4()}",
+        ports=[5432],
+        detach=True,
+        host_config=docker_client.create_host_config(
+            port_bindings={5432: (LOCALHOST, unused_port)}, tmpfs=[postgresql_data_path]
+        ),
+        environment={
+            "POSTGRES_HOST_AUTH_METHOD": "trust",
+            "PGDATA": postgresql_data_path,
+            "POSTGRES_INITDB_ARGS": "--no-sync",
+        },
+        command="-c fsync=off -c full_page_writes=off -c synchronous_commit=off -c bgwriter_lru_maxpages=0 -c jit=off",
+    )
+
+    try:
+        docker_client.start(container=container["Id"])
+
+        started_at = time.monotonic()
+
+        while time.monotonic() - started_at < ready_timeout:
+            if is_pg_ready(
+                host=LOCALHOST,
+                port=unused_port,
+                database=DEFAULT_PG_DATABASE,
+                user=DEFAULT_PG_USER,
+                password=DEFAULT_PG_PASSWORD,
+            ):
+                break
+
+            time.sleep(0.05)
+        else:
+            container_logs = docker_client.logs(container["Id"]).decode()
+            pytest.fail(f"Failed to start postgres using {image} in {ready_timeout} seconds: {container_logs}")
+
+        yield PG(
+            host=LOCALHOST,
+            port=unused_port,
+            user=DEFAULT_PG_USER,
+            password=DEFAULT_PG_PASSWORD,
+            database=DEFAULT_PG_DATABASE,
+        )
+    finally:
+        docker_client.kill(container=container["Id"])
+        docker_client.remove_container(container["Id"], v=True)
+
+
+@pytest.fixture(scope="session")
+def pg() -> Generator[PG, None, None]:
+    with run_pg("postgres:latest") as pg:
+        yield pg
+
+
+@pytest.fixture(scope="session")
+def pg_11() -> Generator[PG, None, None]:
+    with run_pg("postgres:11") as pg:
+        yield pg
+
+
+@pytest.fixture(scope="session")
+def pg_12() -> Generator[PG, None, None]:
+    with run_pg("postgres:12") as pg:
+        yield pg
+
+
+@pytest.fixture(scope="session")
+def pg_13() -> Generator[PG, None, None]:
+    with run_pg("postgres:13") as pg:
+        yield pg
+
+
+@pytest.fixture(scope="session")
+def pg_14() -> Generator[PG, None, None]:
+    with run_pg("postgres:14") as pg:
+        yield pg
+
+
+@pytest.fixture(scope="session")
+def pg_15() -> Generator[PG, None, None]:
+    with run_pg("postgres:15") as pg:
+        yield pg
+
+
+@pytest.fixture(scope="session")
+def pg_16() -> Generator[PG, None, None]:
+    with run_pg("postgres:16") as pg:
+        yield pg
+
+
+@pytest.fixture(scope="session")
+def pg_17() -> Generator[PG, None, None]:
+    with run_pg("postgres:17") as pg:
+        yield pg
+
+
+@pytest.fixture(scope="session")
+def pg_18() -> Generator[PG, None, None]:
+    with run_pg("postgres:18") as pg:
+        yield pg

pytest_pg/py.typed

@@ -0,0 +1 @@
+Marker

pytest_pg/utils.py

@@ -0,0 +1,118 @@
+import asyncio
+import os
+import shutil
+import socket
+import subprocess
+from typing import Any, Protocol
+
+
+class IsReadyFunc(Protocol):
+    def __call__(
+        self,
+        *,
+        host: str,
+        port: int,
+        database: str,
+        user: str,
+        password: str,
+    ) -> bool: ...
+
+
+def _try_get_is_postgres_ready_based_on_psycopg2() -> IsReadyFunc | None:
+    try:
+        # noinspection PyPackageRequirements
+        import psycopg2
+
+        def _is_postgres_ready(**params: Any) -> bool:
+            try:
+                with psycopg2.connect(**params, connect_timeout=5):
+                    return True
+            except psycopg2.OperationalError:
+                return False
+
+        return _is_postgres_ready
+    except ImportError:
+        return None
+
+
+def _try_get_is_postgres_ready_based_on_psycopg3() -> IsReadyFunc | None:
+    try:
+        import psycopg  # pyright: ignore[reportMissingImports]
+
+        def _is_postgres_ready(**params: Any) -> bool:
+            try:
+                params.pop("database")
+                with psycopg.connect(**params, connect_timeout=5):
+                    return True
+            except psycopg.OperationalError:
+                return False
+
+        return _is_postgres_ready
+    except ImportError:
+        return None
+
+
+def _try_get_is_postgres_ready_based_on_asyncpg() -> IsReadyFunc | None:
+    try:
+        # noinspection PyPackageRequirements
+        import asyncpg  # pyright: ignore[reportMissingImports]
+
+        def _is_postgres_ready(**params: Any) -> bool:
+            async def _is_postgres_ready_async() -> bool:
+                try:
+                    connection = await asyncpg.connect(**params, timeout=5.0)
+                    await connection.close()
+                    return True
+                except (asyncpg.exceptions.PostgresError, OSError):
+                    return False
+
+            return asyncio.run(_is_postgres_ready_async())
+
+        return _is_postgres_ready
+
+    except ImportError:
+        return None
+
+
+def _get_dummy_is_postgresql_ready() -> IsReadyFunc:
+    def _is_postgres_ready(**_: Any) -> bool:
+        return True
+
+    return _is_postgres_ready
+
+
+is_pg_ready = (
+    _try_get_is_postgres_ready_based_on_asyncpg()
+    or _try_get_is_postgres_ready_based_on_psycopg2()
+    or _try_get_is_postgres_ready_based_on_psycopg3()
+    or _get_dummy_is_postgresql_ready()
+)
+
+
+def find_unused_local_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]  # type: ignore
+
+
+def resolve_docker_host() -> str | None:
+    # The `docker` Python SDK doesn't read `docker context` like the CLI does.
+    # Hand DOCKER_HOST to it from the active context so non-default setups
+    # (Colima, custom contexts) work without the user exporting it manually.
+    # No-op when the docker CLI is missing or DOCKER_HOST is already set.
+    host = os.environ.get("DOCKER_HOST")
+    if host:
+        return host
+    if shutil.which("docker") is None:
+        return None
+    try:
+        result = subprocess.run(
+            ["docker", "context", "inspect", "--format", "{{.Endpoints.docker.Host}}"],
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return result.stdout.strip() or None

pytest_pg-0.0.28.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: pytest_pg
+Version: 0.0.28
+Summary: A tiny plugin for pytest which runs PostgreSQL in Docker
+Project-URL: Homepage, https://github.com/anna-money/pytest-pg
+Author-email: Yury Pliner <yury.pliner@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: docker>=7.0.0
+Requires-Dist: pytest>=8.0
+Provides-Extra: dev
+Requires-Dist: pyright==1.1.407; extra == 'dev'
+Requires-Dist: pytest==9.0.2; extra == 'dev'
+Requires-Dist: ruff==0.14.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytest-pg
+
+A pytest plugin that provides session-scoped fixtures for running PostgreSQL inside Docker containers.
+It automatically spins up a container, waits for PostgreSQL to become ready, exposes connection details
+(`host`, `port`, `user`, `password`, `database`) via a `PG` dataclass, and tears the container down after
+the test session. Pre-built fixtures are available for PostgreSQL versions 11 through 18 as well as `latest`.
+
+Readiness checks work with any of the common drivers — asyncpg, psycopg2, or psycopg3.
+
+To speed up tests, pytest-pg does the following tweaks:
+
+1. fsync=off
+2. full_page_writes=off
+3. synchronous_commit=off
+4. jit=off
+5. bgwriter_lru_maxpages=0
+6. data directory is mounted to a tmpfs 
+
+
+# How to use?
+
+You can use the following fixtures:
+
+* `pg` – the latest PostgreSQL image available
+* `pg_11` – PostgreSQL 11
+* `pg_12` – PostgreSQL 12
+* `pg_13` – PostgreSQL 13
+* `pg_14` – PostgreSQL 14
+* `pg_15` – PostgreSQL 15
+* `pg_16` – PostgreSQL 16
+* `pg_17` – PostgreSQL 17
+* `pg_18` – PostgreSQL 18
+
+```python
+import asyncpg
+
+
+async def test_asyncpg_query(pg):
+    conn = await asyncpg.connect(
+        user=pg.user,
+        password=pg.password,
+        database=pg.database,
+        host=pg.host,
+        port=pg.port,
+    )
+
+    await conn.execute("CREATE TABLE test_table (id serial PRIMARY KEY, value text);")
+    await conn.execute("INSERT INTO test_table (value) VALUES ($1)", "hello")
+    row = await conn.fetchrow("SELECT value FROM test_table WHERE id = $1", 1)
+
+    assert row["value"] == "hello"
+
+    await conn.close()
+```
+
+
+Also `run_pg` context manager is available, you can use it to create your own fixture, using docker image you need:
+
+```python
+import os
+
+import pytest
+import pytest_pg
+
+
+@pytest.fixture(scope='session', autouse=True)
+def postgres_env_vars() -> Generator[None]:
+    docker_image = 'postgres:18'
+    with pytest_pg.run_pg(docker_image) as pg:
+        os.environ['POSTGRES_USER'] = pg.user
+        os.environ['POSTGRES_PASSWORD'] = pg.password
+        os.environ['POSTGRES_HOST'] = pg.host
+        os.environ['POSTGRES_PORT'] = str(pg.port)
+        os.environ['POSTGRES_DBNAME'] = pg.database
+        yield
+
+
+# or like so:
+@pytest.fixture(scope='session', autouse=True)
+def postgres_env_vars(pg_18: pytest_pg.PG) -> Generator[None]:
+    os.environ['POSTGRES_USER'] = pg_18.user
+    os.environ['POSTGRES_PASSWORD'] = pg_18.password
+    os.environ['POSTGRES_HOST'] = pg_18.host
+    os.environ['POSTGRES_PORT'] = str(pg_18.port)
+    os.environ['POSTGRES_DBNAME'] = pg_18.database
+    yield
+```

pytest_pg-0.0.28.dist-info/RECORD

@@ -0,0 +1,9 @@
+pytest_pg/__init__.py,sha256=UkijuJE4fi_pOvZ1D1qwiqRSmU5LDXWoyX8fa-KKH04,360
+pytest_pg/fixtures.py,sha256=9tknPHXI0tAVlJNRK_XZZVUjxgUPBGYG0R7nJiMt18w,3694
+pytest_pg/py.typed,sha256=E84IaZyFwfLqvXjOVW4LS6WH7QOaKEFpNh9TFyzHNQc,6
+pytest_pg/utils.py,sha256=KkulNEwm_u8_-iSiWOMjE1x65jGSGttpBCe0rOXJj6c,3410
+pytest_pg-0.0.28.dist-info/METADATA,sha256=PiFDdSDK_urBk_Eo6LcBBw5JfpTvu1yxNnpJZ5Wmh-U,3717
+pytest_pg-0.0.28.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pytest_pg-0.0.28.dist-info/entry_points.txt,sha256=YItrIbbORp9wVDzM2aXaYi6XDi7Qw38rD3RaqAoZLe8,33
+pytest_pg-0.0.28.dist-info/licenses/LICENSE,sha256=aVmBXoo4joWuu-u1A14wOPPZKjKO4JZUOo4LuX4RQqQ,1068
+pytest_pg-0.0.28.dist-info/RECORD,,

pytest_pg-0.0.28.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_pg-0.0.28.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+pytest_pg = pytest_pg

pytest_pg-0.0.28.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Yury Pliner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.