pytest-postgresql 7.0.2__tar.gz → 8.1.0__tar.gz

{pytest_postgresql-7.0.2 → pytest_postgresql-8.1.0}/CHANGES.rst

@@ -3,6 +3,97 @@ CHANGELOG
 
 .. towncrier release notes start
 
+pytest-postgresql 8.1.0 (2026-05-15)
+====================================
+
+Features
+--------
+
+- Add Windows support for ``PostgreSQLExecutor``, including platform-specific start/stop handling. (`#1182 <https://github.com/dbfixtures/pytest-postgresql/issues/1182>`__)
+
+
+Documentation
+-------------
+
+- Make sure diagrams are using unified terminology.
+
+
+Miscellaneus
+------------
+
+- Fix typos (`#1267 <https://github.com/dbfixtures/pytest-postgresql/issues/1267>`__)
+- Add ``pytest-postgresql`` as an editable self-install in the Pipfile; remove the manual ``from pytest_postgresql.plugin import *`` import from ``tests/conftest.py`` and the ``makeconftest`` call in ``tests/test_postgres_options_plugin.py`` that re-registered the plugin and caused duplicate-plugin errors under editable install.
+- Add coderabbitai configuration with instructions to keep an eye for newsfragments.
+- Attempt to overcome random failure on CI on MacOS on xdist workers where test_executor_init_with_password is receiving
+  `FATAL: the database system is starting up` error message from psycopg.
+
+  That's the only test that doesn't have guards against attempting to start on the same port as other xdist worker.
+- Fix codecov pipeline configuration.
+- Fixes for diagram workflow.
+- Improve reliability of Coverage reporting on CI
+- Migrate package publishing step to trusted publishing.
+
+
+pytest-postgresql 8.0.0 (2026-01-23)
+====================================
+
+Breaking changes
+----------------
+
+- Refactor ``DatabaseJanitor`` to use explicit template management. This includes a new ``as_template`` flag and making ``dbname`` a required parameter. (`#890 <https://github.com/dbfixtures/pytest-postgresql/issues/890>`__)
+- Bump the minimum supported pytest version to 8.2.
+
+  The previous minimum was about two years old, and older pytest versions
+  can be flaky with fixture chaining that relies on `getfixturevalue` on
+  Python 3.12-3.13 when used alongside xdist. (`#890 <https://github.com/dbfixtures/pytest-postgresql/issues/890>`__)
+- Support only PostgreSQL version 14 and up. (`#1250 <https://github.com/dbfixtures/pytest-postgresql/issues/1250>`__)
+- Dropped support for Python 3.9 as it has reached End of Life
+
+
+Bugfixes
+--------
+
+- Fix issue where `--postgresql-drop-test-database` was applied in process fixture.
+
+  It was already being read in client and noprocess fixtures. (`#1148 <https://github.com/dbfixtures/pytest-postgresql/issues/1148>`__)
+
+
+Documentation
+-------------
+
+- Add a Mermaid sequence diagram to the documentation to illustrate fixture chaining and hierarchical cloning. (`#890 <https://github.com/dbfixtures/pytest-postgresql/issues/890>`__)
+- Improve code examples by adding types (`#1233 <https://github.com/dbfixtures/pytest-postgresql/issues/1233>`__)
+- Add plugins' architecture diagram and display it in project's README. (`#1244 <https://github.com/dbfixtures/pytest-postgresql/issues/1244>`__)
+- Improved README.rst:
+  - Added a "Quick Start" section with a simple example.
+  - Clarified `psycopg` 3 requirement for the plugin vs. `psycopg` 2 support for the application.
+  - Updated PostgreSQL versioning notes (>= 10).
+  - Explained the binary discovery mechanism (`pg_config` vs. fallbacks).
+  - Promoted `DatabaseJanitor` as an advanced API.
+  - Fixed broken table layouts and corrected various typos.
+
+
+Features
+--------
+
+- Add ``depends_on`` parameter to ``postgresql_noproc`` factory to allow hierarchical cloning and chaining of process fixtures. (`#890 <https://github.com/dbfixtures/pytest-postgresql/issues/890>`__)
+- Convert Config kept in TypedDict into a dataclass (`#1225 <https://github.com/dbfixtures/pytest-postgresql/issues/1225>`__)
+- Marked support for Python 3.14
+
+
+Miscellaneus
+------------
+
+- `#1127 <https://github.com/dbfixtures/pytest-postgresql/issues/1127>`__, `#1218 <https://github.com/dbfixtures/pytest-postgresql/issues/1218>`__
+- Add new release workflow, which will allow releasing new versions directly from GitHub.
+- Drop PostgreSQL 13 and add PostgreSQL 18 to the CI
+- Update github-actions for actions-reuse 4.x
+- Updates to pre-commit
+
+  Replaced black with ruff-format, Added https://github.com/fizyk/pyproject-validator,
+  Moved mypy configuration into pyproject.toml, extended line length to 120 characters.
+
+
 7.0.2 (2025-05-17)
 ==================
 

pytest_postgresql-8.1.0/PKG-INFO

@@ -0,0 +1,443 @@
+Metadata-Version: 2.4
+Name: pytest-postgresql
+Version: 8.1.0
+Summary: Postgresql fixtures and fixture factories for Pytest.
+Author-email: Grzegorz Śliwiński <fizyk+pypi@fizyk.dev>
+Project-URL: Source, https://github.com/dbfixtures/pytest-postgresql
+Project-URL: Bug Tracker, https://github.com/dbfixtures/pytest-postgresql/issues
+Project-URL: Changelog, https://github.com/dbfixtures/pytest-postgresql/blob/v8.1.0/CHANGES.rst
+Keywords: tests,pytest,fixture,postgresql
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: Pytest
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: COPYING
+License-File: COPYING.lesser
+License-File: AUTHORS.rst
+Requires-Dist: pytest>=8.2
+Requires-Dist: port-for>=0.7.3
+Requires-Dist: mirakuru>=2.6.0
+Requires-Dist: packaging
+Requires-Dist: psycopg>=3.0.0
+Dynamic: license-file
+
+.. image:: https://raw.githubusercontent.com/dbfixtures/pytest-postgresql/main/logo.png
+    :width: 100px
+    :height: 100px
+
+pytest-postgresql
+=================
+
+.. image:: https://img.shields.io/pypi/v/pytest-postgresql.svg
+    :target: https://pypi.python.org/pypi/pytest-postgresql/
+    :alt: Latest PyPI version
+
+.. image:: https://img.shields.io/pypi/wheel/pytest-postgresql.svg
+    :target: https://pypi.python.org/pypi/pytest-postgresql/
+    :alt: Wheel Status
+
+.. image:: https://img.shields.io/pypi/pyversions/pytest-postgresql.svg
+    :target: https://pypi.python.org/pypi/pytest-postgresql/
+    :alt: Supported Python Versions
+
+.. image:: https://img.shields.io/pypi/l/pytest-postgresql.svg
+    :target: https://pypi.python.org/pypi/pytest-postgresql/
+    :alt: License
+
+What is this?
+=============
+
+This is a pytest plugin that enables you to test code relying on a running PostgreSQL database.
+It provides fixtures for managing both the PostgreSQL process and the client connections.
+
+Quick Start
+===========
+
+1. **Install the plugin:**
+
+   .. code-block:: sh
+
+       pip install pytest-postgresql
+
+   You will also need to install ``psycopg`` (version 3). See `its installation instructions <https://www.psycopg.org/psycopg3/docs/basic/install.html>`_.
+
+   .. note::
+
+       While this plugin requires ``psycopg`` 3 to manage the database, your application code can still use ``psycopg`` 2.
+
+2. **Run a test:**
+
+   Simply include the ``postgresql`` fixture in your test. It provides a connected ``psycopg.Connection`` object.
+
+   .. code-block:: python
+
+       def test_example(postgresql):
+           """Check main postgresql fixture."""
+           with postgresql.cursor() as cur:
+               cur.execute("CREATE TABLE test (id serial PRIMARY KEY, num integer, data varchar);")
+               postgresql.commit()
+
+How to use
+==========
+
+.. warning::
+
+    Tested on PostgreSQL versions >= 14. See tests for more details.
+
+How does it work
+----------------
+
+.. image:: https://raw.githubusercontent.com/dbfixtures/pytest-postgresql/main/docs/images/architecture.svg
+    :alt: Project Architecture Diagram
+    :align: center
+
+The plugin provides two main types of fixtures:
+
+**1. Client Fixtures**
+    These provide a connection to a database for your tests.
+
+    * **postgresql** - A function-scoped fixture. It returns a connected ``psycopg.Connection``.
+      After each test, it terminates leftover connections and drops the test database to ensure isolation.
+
+**2. Process Fixtures**
+    These manage the PostgreSQL server lifecycle.
+
+    * **postgresql_proc** - A session-scoped fixture that starts a PostgreSQL instance on its first use and stops it when all tests are finished.
+    * **postgresql_noproc** - A fixture for connecting to an already running PostgreSQL instance (e.g., in Docker or CI).
+
+Customizing Fixtures
+--------------------
+
+You can create additional fixtures using factories:
+
+.. code-block:: python
+
+    from pytest_postgresql import factories
+
+    # Create a custom process fixture
+    postgresql_my_proc = factories.postgresql_proc(
+        port=None, unixsocketdir='/var/run')
+
+    # Create a client fixture that uses the custom process
+    postgresql_my = factories.postgresql('postgresql_my_proc')
+
+.. note::
+
+    Each process fixture can be configured independently through factory arguments.
+
+Pre-populating the database for tests
+-------------------------------------
+
+If you want the database to be automatically pre-populated with your schema and data, there are two levels you can achieve it:
+
+#. **Per test:** In a client fixture, by using an intermediary fixture.
+#. **Per session:** In a process fixture.
+
+The process fixture accepts a ``load`` parameter, which supports:
+
+* **SQL file paths:** Loads and executes the SQL files.
+* **Loading functions:** A callable or an import string (e.g., ``"path.to.module:function"``).
+  These functions receive **host**, **port**, **user**, **dbname**, and **password** and must perform the connection themselves (or use an ORM).
+
+The process fixture pre-populates the database once per session into a **template database**. The client fixture then clones this template for each test, which significantly **speeds up your tests**.
+
+.. code-block:: python
+
+    from pathlib import Path
+    postgresql_my_proc = factories.postgresql_proc(
+        load=[
+            Path("schemafile.sql"),
+            "import.path.to.function",
+            load_this_callable
+        ]
+    )
+
+Defining pre-population on the command line:
+
+.. code-block:: sh
+
+    pytest --postgresql-populate-template=path/to/file.sql --postgresql-populate-template=path.to.function
+
+Connecting to an existing PostgreSQL database
+----------------------------------------------
+
+To connect to an external server (e.g., running in Docker), use the ``postgresql_noproc`` fixture.
+
+.. code-block:: python
+
+    postgresql_external = factories.postgresql('postgresql_noproc')
+
+By default, it connects to ``127.0.0.1:5432``.
+
+Chaining fixtures
+-----------------
+
+You can chain multiple ``postgresql_noproc`` fixtures to layer your data pre-population. Each fixture in the chain will create its own template database based on the previous one.
+
+.. code-block:: python
+
+    from pytest_postgresql import factories
+
+    # 1. Start with a process or a no-process base
+    base_proc = factories.postgresql_proc(load=[load_schema])
+
+    # 2. Add a layer with some data
+    seeded_noproc = factories.postgresql_noproc(depends_on="base_proc", load=[load_data])
+
+    # 3. Add another layer with more data
+    more_seeded_noproc = factories.postgresql_noproc(depends_on="seeded_noproc", load=[load_more_data])
+
+    # 4. Use the final layer in your test
+    client = factories.postgresql("more_seeded_noproc")
+
+
+
+.. image:: https://raw.githubusercontent.com/dbfixtures/pytest-postgresql/main/docs/images/architecture_chaining.svg
+    :alt: Fixture Chaining Diagram
+    :align: center
+
+Configuration
+=============
+
+You can define settings via fixture factory arguments, command line options, or ``pytest.ini``. They are resolved in this order:
+
+1. ``Fixture factory argument``
+2. ``Command line option``
+3. ``pytest.ini configuration option``
+
+.. list-table:: Configuration options
+   :header-rows: 1
+
+   * - PostgreSQL option
+     - Fixture factory argument
+     - Command line option
+     - pytest.ini option
+     - Noop process fixture
+     - Default
+   * - Path to executable
+     - executable
+     - --postgresql-exec
+     - postgresql_exec
+     - -
+     - ``pg_config --bindir`` + ``pg_ctl``
+   * - host
+     - host
+     - --postgresql-host
+     - postgresql_host
+     - yes
+     - 127.0.0.1
+   * - port
+     - port
+     - --postgresql-port
+     - postgresql_port
+     - yes (5432)
+     - random
+   * - Port search count
+     -
+     - --postgresql-port-search-count
+     - postgresql_port_search_count
+     - -
+     - 5
+   * - postgresql user
+     - user
+     - --postgresql-user
+     - postgresql_user
+     - yes
+     - postgres
+   * - password
+     - password
+     - --postgresql-password
+     - postgresql_password
+     - yes
+     -
+   * - Starting parameters (extra pg_ctl arguments)
+     - startparams
+     - --postgresql-startparams
+     - postgresql_startparams
+     - -
+     - -w
+   * - Postgres exe extra arguments (passed via pg_ctl's -o argument)
+     - postgres_options
+     - --postgresql-postgres-options
+     - postgresql_postgres_options
+     - -
+     -
+   * - Location for unixsockets
+     - unixsocket
+     - --postgresql-unixsocketdir
+     - postgresql_unixsocketdir
+     - -
+     - $TMPDIR
+   * - Database name
+     - dbname
+     - --postgresql-dbname
+     - postgresql_dbname
+     - yes (handles xdist)
+     - test
+   * - Default Schema (load list)
+     - load
+     - --postgresql-load
+     - postgresql_load
+     - yes
+     -
+   * - PostgreSQL connection options
+     - options
+     - --postgresql-options
+     - postgresql_options
+     - yes
+     -
+   * - Drop test database on start
+     -
+     - --postgresql-drop-test-database
+     -
+     - -
+     - false
+
+.. note::
+
+    If the ``executable`` is not provided, the plugin attempts to find it by calling ``pg_config``. If that fails, it fallbacks to a common path like ``/usr/lib/postgresql/13/bin/pg_ctl``.
+
+Examples
+========
+
+Using SQLAlchemy
+----------------
+
+This example shows how to create an SQLAlchemy session fixture:
+
+.. code-block:: python
+
+    from typing import Iterator
+    import pytest
+    from psycopg import Connection
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import Session, sessionmaker, scoped_session
+    from sqlalchemy.pool import NullPool
+
+    @pytest.fixture
+    def db_session(postgresql: Connection) -> Iterator[Session]:
+        """Session for SQLAlchemy."""
+        user = postgresql.info.user
+        host = postgresql.info.host
+        port = postgresql.info.port
+        dbname = postgresql.info.dbname
+
+        connection_str = f'postgresql+psycopg://{user}:@{host}:{port}/{dbname}'
+        engine = create_engine(connection_str, echo=False, poolclass=NullPool)
+
+        # Assuming you use a Base model
+        from my_app.models import Base
+        Base.metadata.create_all(engine)
+
+        SessionLocal = scoped_session(sessionmaker(bind=engine))
+        yield SessionLocal()
+
+        SessionLocal.close()
+        Base.metadata.drop_all(engine)
+
+Advanced Usage: DatabaseJanitor
+-------------------------------
+
+``DatabaseJanitor`` is an advanced API for managing database state outside of standard fixtures. It is used by projects like `Warehouse <https://github.com/pypa/warehouse>`_ (pypi.org).
+
+.. code-block:: python
+
+    import psycopg
+    from pytest_postgresql.janitor import DatabaseJanitor
+
+    def test_manual_janitor(postgresql_proc):
+        with DatabaseJanitor(
+            user=postgresql_proc.user,
+            host=postgresql_proc.host,
+            port=postgresql_proc.port,
+            dbname="my_custom_db",
+            version=postgresql_proc.version,
+            password="secret_password",
+        ):
+            with psycopg.connect(
+                dbname="my_custom_db",
+                user=postgresql_proc.user,
+                host=postgresql_proc.host,
+                port=postgresql_proc.port,
+                password="secret_password",
+            ) as conn:
+                # use connection
+                pass
+
+Connecting to PostgreSQL in Docker
+----------------------------------
+
+To connect to a Docker-run PostgreSQL, use the ``noproc`` fixture.
+
+.. code-block:: sh
+
+    docker run --name some-postgres -e POSTGRES_PASSWORD=mysecret -d postgres
+
+In your tests:
+
+.. code-block:: python
+
+    from pytest_postgresql import factories
+
+    postgresql_in_docker = factories.postgresql_noproc()
+    postgresql = factories.postgresql("postgresql_in_docker", dbname="test")
+
+    def test_docker(postgresql):
+        with postgresql.cursor() as cur:
+            cur.execute("SELECT 1")
+
+Run with:
+
+.. code-block:: sh
+
+    pytest --postgresql-host=172.17.0.2 --postgresql-password=mysecret
+
+Basic database state for all tests
+----------------------------------
+
+You can define a ``load`` function and pass it to your process fixture factory:
+
+.. code-block:: python
+
+    import psycopg
+    from pytest_postgresql import factories
+
+    def load_database(**kwargs):
+        with psycopg.connect(**kwargs) as conn:
+            with conn.cursor() as cur:
+                cur.execute("CREATE TABLE stories (id serial PRIMARY KEY, name varchar);")
+                cur.execute("INSERT INTO stories (name) VALUES ('Silmarillion'), ('The Expanse');")
+
+    postgresql_proc = factories.postgresql_proc(load=[load_database])
+    postgresql = factories.postgresql("postgresql_proc")
+
+    def test_stories(postgresql):
+        with postgresql.cursor() as cur:
+            cur.execute("SELECT count(*) FROM stories")
+            assert cur.fetchone()[0] == 2
+
+The process fixture populates the **template database** once, and the client fixture clones it for every test. This is fast, clean, and ensures no dangling transactions. This approach works with both ``postgresql_proc`` and ``postgresql_noproc``.
+
+Release
+=======
+
+Install ``pipenv`` and dev dependencies, then run:
+
+.. code-block:: sh
+
+    pipenv run tbump [NEW_VERSION]