testgres 1.11.1__tar.gz → 1.12.0__tar.gz

testgres-1.12.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: testgres
+Version: 1.12.0
+Summary: Testing utility for PostgreSQL and its extensions
+Home-page: https://github.com/postgrespro/testgres
+Author: Postgres Professional
+Author-email: testgres@postgrespro.ru
+License: PostgreSQL
+Keywords: test,testing,postgresql
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pg8000
+Requires-Dist: port-for>=0.4
+Requires-Dist: six>=1.9.0
+Requires-Dist: psutil
+Requires-Dist: packaging
+Requires-Dist: testgres.os_ops<1.0.0,>=0.0.2
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+[![Build Status](https://api.travis-ci.com/postgrespro/testgres.svg?branch=master)](https://travis-ci.com/github/postgrespro/testgres)
+[![codecov](https://codecov.io/gh/postgrespro/testgres/branch/master/graph/badge.svg)](https://codecov.io/gh/postgrespro/testgres)
+[![PyPI version](https://badge.fury.io/py/testgres.svg)](https://badge.fury.io/py/testgres)
+
+[Documentation](https://postgrespro.github.io/testgres/)
+
+# testgres
+
+Utility for orchestrating temporary PostgreSQL clusters in Python tests. Supports Python 3.7.17 and newer.
+
+## Installation
+
+Install `testgres` from PyPI:
+
+```sh
+pip install testgres
+```
+
+Use a dedicated virtual environment for isolated test dependencies.
+
+## Usage
+
+### Environment
+
+> Note: by default `testgres` invokes `initdb`, `pg_ctl`, and `psql` binaries found in `PATH`.
+
+Specify a custom PostgreSQL installation in one of the following ways:
+
+- Set the `PG_CONFIG` environment variable to point to the `pg_config` executable.
+- Set the `PG_BIN` environment variable to point to the directory with PostgreSQL binaries.
+
+Example:
+
+```sh
+export PG_BIN=$HOME/pg_16/bin
+python my_tests.py
+```
+
+### Examples
+
+Create a temporary node, run queries, and let `testgres` clean up automatically:
+
+```python
+# create a node with a random name, port, and data directory
+with testgres.get_new_node() as node:
+
+    # run initdb
+    node.init()
+
+    # start PostgreSQL
+    node.start()
+
+    # execute a query in the default database
+    print(node.execute('select 1'))
+
+# the node is stopped and its files are removed automatically
+```
+
+### Query helpers
+
+`testgres` provides four helpers for executing queries against the node:
+
+| Command | Description |
+|---------|-------------|
+| `node.psql(query, ...)` | Runs the query via `psql` and returns a tuple `(returncode, stdout, stderr)`. |
+| `node.safe_psql(query, ...)` | Same as `psql()` but returns only `stdout` and raises if the command fails. |
+| `node.execute(query, ...)` | Connects via `psycopg2` or `pg8000` (whichever is available) and returns a list of tuples. |
+| `node.connect(dbname, ...)` | Returns a `NodeConnection` wrapper for executing multiple statements within a transaction. |
+
+Example of transactional usage:
+
+```python
+with node.connect() as con:
+    con.begin('serializable')
+    print(con.execute('select %s', 1))
+    con.rollback()
+```
+
+### Logging
+
+By default `cleanup()` removes all temporary files (data directories, logs, and so on) created by the API. Call `configure_testgres(node_cleanup_full=False)` before starting nodes if you want to keep logs for inspection.
+
+> Note: context managers (the `with` statement) call `stop()` and `cleanup()` automatically.
+
+`testgres` integrates with the standard [Python logging](https://docs.python.org/3/library/logging.html) module, so you can aggregate logs from multiple nodes:
+
+```python
+import logging
+
+# write everything to /tmp/testgres.log
+logging.basicConfig(filename='/tmp/testgres.log')
+
+# enable logging and create two nodes
+testgres.configure_testgres(use_python_logging=True)
+node1 = testgres.get_new_node().init().start()
+node2 = testgres.get_new_node().init().start()
+
+node1.execute('select 1')
+node2.execute('select 2')
+
+# disable logging
+testgres.configure_testgres(use_python_logging=False)
+```
+
+See `tests/test_simple.py` for a complete logging example.
+
+### Backup and replication
+
+Creating backups and spawning replicas is straightforward:
+
+```python
+with testgres.get_new_node('master') as master:
+    master.init().start()
+
+    with master.backup() as backup:
+        replica = backup.spawn_replica('replica').start()
+        replica.catchup()
+
+        print(replica.execute('postgres', 'select 1'))
+```
+
+### Benchmarks
+
+Use `pgbench` through `testgres` to run quick benchmarks:
+
+```python
+with testgres.get_new_node('master') as master:
+    master.init().start()
+
+    result = master.pgbench_init(scale=2).pgbench_run(time=10)
+    print(result)
+```
+
+### Custom configuration
+
+`testgres` ships with sensible defaults. Adjust them as needed with `default_conf()` and `append_conf()`:
+
+```python
+extra_conf = "shared_preload_libraries = 'postgres_fdw'"
+
+with testgres.get_new_node().init() as master:
+    master.default_conf(fsync=True, allow_streaming=True)
+    master.append_conf('postgresql.conf', extra_conf)
+```
+
+`default_conf()` is called by `init()` and rewrites the configuration file. Apply `append_conf()` afterwards to keep custom lines.
+
+### Remote mode
+
+You can provision nodes on a remote host (Linux only) by wiring `RemoteOperations` into the configuration:
+
+```python
+from testgres import ConnectionParams, RemoteOperations, TestgresConfig, get_remote_node
+
+conn_params = ConnectionParams(
+    host='example.com',
+    username='postgres',
+    ssh_key='/path/to/ssh/key'
+)
+os_ops = RemoteOperations(conn_params)
+
+TestgresConfig.set_os_ops(os_ops=os_ops)
+
+def test_basic_query():
+    with get_remote_node(conn_params=conn_params) as node:
+        node.init().start()
+        assert node.execute('SELECT 1') == [(1,)]
+```
+
+### Pytest integration
+
+Use fixtures to create and clean up nodes automatically when testing with `pytest`:
+
+```python
+import pytest
+import testgres
+
+@pytest.fixture
+def pg_node():
+    node = testgres.get_new_node().init().start()
+    try:
+        yield node
+    finally:
+        node.stop()
+        node.cleanup()
+
+def test_simple(pg_node):
+    assert pg_node.execute('select 1')[0][0] == 1
+```
+
+This pattern keeps tests concise and ensures that every node is stopped and removed even if the test fails.
+
+### Scaling tips
+
+- Run tests in parallel with `pytest -n auto` (requires `pytest-xdist`). Ensure each node uses a distinct port by setting `PGPORT` in the fixture or by passing the `port` argument to `get_new_node()`.
+- Always call `node.cleanup()` after each test, or rely on context managers/fixtures that do it for you, to avoid leftover data directories.
+- Prefer `node.safe_psql()` for lightweight assertions that should fail fast; use `node.execute()` when you need structured Python results.
+
+## Authors
+
+[Ildar Musin](https://github.com/zilder)  
+[Dmitry Ivanov](https://github.com/funbringer)  
+[Ildus Kurbangaliev](https://github.com/ildus)  
+[Yury Zhuravlev](https://github.com/stalkerg)

testgres-1.12.0/README.md

@@ -0,0 +1,204 @@
+[![Build Status](https://api.travis-ci.com/postgrespro/testgres.svg?branch=master)](https://travis-ci.com/github/postgrespro/testgres)
+[![codecov](https://codecov.io/gh/postgrespro/testgres/branch/master/graph/badge.svg)](https://codecov.io/gh/postgrespro/testgres)
+[![PyPI version](https://badge.fury.io/py/testgres.svg)](https://badge.fury.io/py/testgres)
+
+[Documentation](https://postgrespro.github.io/testgres/)
+
+# testgres
+
+Utility for orchestrating temporary PostgreSQL clusters in Python tests. Supports Python 3.7.17 and newer.
+
+## Installation
+
+Install `testgres` from PyPI:
+
+```sh
+pip install testgres
+```
+
+Use a dedicated virtual environment for isolated test dependencies.
+
+## Usage
+
+### Environment
+
+> Note: by default `testgres` invokes `initdb`, `pg_ctl`, and `psql` binaries found in `PATH`.
+
+Specify a custom PostgreSQL installation in one of the following ways:
+
+- Set the `PG_CONFIG` environment variable to point to the `pg_config` executable.
+- Set the `PG_BIN` environment variable to point to the directory with PostgreSQL binaries.
+
+Example:
+
+```sh
+export PG_BIN=$HOME/pg_16/bin
+python my_tests.py
+```
+
+### Examples
+
+Create a temporary node, run queries, and let `testgres` clean up automatically:
+
+```python
+# create a node with a random name, port, and data directory
+with testgres.get_new_node() as node:
+
+    # run initdb
+    node.init()
+
+    # start PostgreSQL
+    node.start()
+
+    # execute a query in the default database
+    print(node.execute('select 1'))
+
+# the node is stopped and its files are removed automatically
+```
+
+### Query helpers
+
+`testgres` provides four helpers for executing queries against the node:
+
+| Command | Description |
+|---------|-------------|
+| `node.psql(query, ...)` | Runs the query via `psql` and returns a tuple `(returncode, stdout, stderr)`. |
+| `node.safe_psql(query, ...)` | Same as `psql()` but returns only `stdout` and raises if the command fails. |
+| `node.execute(query, ...)` | Connects via `psycopg2` or `pg8000` (whichever is available) and returns a list of tuples. |
+| `node.connect(dbname, ...)` | Returns a `NodeConnection` wrapper for executing multiple statements within a transaction. |
+
+Example of transactional usage:
+
+```python
+with node.connect() as con:
+    con.begin('serializable')
+    print(con.execute('select %s', 1))
+    con.rollback()
+```
+
+### Logging
+
+By default `cleanup()` removes all temporary files (data directories, logs, and so on) created by the API. Call `configure_testgres(node_cleanup_full=False)` before starting nodes if you want to keep logs for inspection.
+
+> Note: context managers (the `with` statement) call `stop()` and `cleanup()` automatically.
+
+`testgres` integrates with the standard [Python logging](https://docs.python.org/3/library/logging.html) module, so you can aggregate logs from multiple nodes:
+
+```python
+import logging
+
+# write everything to /tmp/testgres.log
+logging.basicConfig(filename='/tmp/testgres.log')
+
+# enable logging and create two nodes
+testgres.configure_testgres(use_python_logging=True)
+node1 = testgres.get_new_node().init().start()
+node2 = testgres.get_new_node().init().start()
+
+node1.execute('select 1')
+node2.execute('select 2')
+
+# disable logging
+testgres.configure_testgres(use_python_logging=False)
+```
+
+See `tests/test_simple.py` for a complete logging example.
+
+### Backup and replication
+
+Creating backups and spawning replicas is straightforward:
+
+```python
+with testgres.get_new_node('master') as master:
+    master.init().start()
+
+    with master.backup() as backup:
+        replica = backup.spawn_replica('replica').start()
+        replica.catchup()
+
+        print(replica.execute('postgres', 'select 1'))
+```
+
+### Benchmarks
+
+Use `pgbench` through `testgres` to run quick benchmarks:
+
+```python
+with testgres.get_new_node('master') as master:
+    master.init().start()
+
+    result = master.pgbench_init(scale=2).pgbench_run(time=10)
+    print(result)
+```
+
+### Custom configuration
+
+`testgres` ships with sensible defaults. Adjust them as needed with `default_conf()` and `append_conf()`:
+
+```python
+extra_conf = "shared_preload_libraries = 'postgres_fdw'"
+
+with testgres.get_new_node().init() as master:
+    master.default_conf(fsync=True, allow_streaming=True)
+    master.append_conf('postgresql.conf', extra_conf)
+```
+
+`default_conf()` is called by `init()` and rewrites the configuration file. Apply `append_conf()` afterwards to keep custom lines.
+
+### Remote mode
+
+You can provision nodes on a remote host (Linux only) by wiring `RemoteOperations` into the configuration:
+
+```python
+from testgres import ConnectionParams, RemoteOperations, TestgresConfig, get_remote_node
+
+conn_params = ConnectionParams(
+    host='example.com',
+    username='postgres',
+    ssh_key='/path/to/ssh/key'
+)
+os_ops = RemoteOperations(conn_params)
+
+TestgresConfig.set_os_ops(os_ops=os_ops)
+
+def test_basic_query():
+    with get_remote_node(conn_params=conn_params) as node:
+        node.init().start()
+        assert node.execute('SELECT 1') == [(1,)]
+```
+
+### Pytest integration
+
+Use fixtures to create and clean up nodes automatically when testing with `pytest`:
+
+```python
+import pytest
+import testgres
+
+@pytest.fixture
+def pg_node():
+    node = testgres.get_new_node().init().start()
+    try:
+        yield node
+    finally:
+        node.stop()
+        node.cleanup()
+
+def test_simple(pg_node):
+    assert pg_node.execute('select 1')[0][0] == 1
+```
+
+This pattern keeps tests concise and ensures that every node is stopped and removed even if the test fails.
+
+### Scaling tips
+
+- Run tests in parallel with `pytest -n auto` (requires `pytest-xdist`). Ensure each node uses a distinct port by setting `PGPORT` in the fixture or by passing the `port` argument to `get_new_node()`.
+- Always call `node.cleanup()` after each test, or rely on context managers/fixtures that do it for you, to avoid leftover data directories.
+- Prefer `node.safe_psql()` for lightweight assertions that should fail fast; use `node.execute()` when you need structured Python results.
+
+## Authors
+
+[Ildar Musin](https://github.com/zilder)  
+[Dmitry Ivanov](https://github.com/funbringer)  
+[Ildus Kurbangaliev](https://github.com/ildus)  
+[Yury Zhuravlev](https://github.com/stalkerg)

{testgres-1.11.1 → testgres-1.12.0}/setup.py

@@ -11,7 +11,8 @@ install_requires = [
     "port-for>=0.4",
     "six>=1.9.0",
     "psutil",
-    "packaging"
+    "packaging",
+    "testgres.os_ops>=0.0.2,<1.0.0"
 ]
 
 # Add compatibility enum class
@@ -27,9 +28,10 @@ with open('README.md', 'r') as f:
     readme = f.read()
 
 setup(
-    version='1.11.1',
+    version='1.12.0',
     name='testgres',
-    packages=['testgres', 'testgres.operations', 'testgres.impl'],
+    packages=['testgres', 'testgres.impl'],
+    package_dir={"testgres": "src"},
     description='Testing utility for PostgreSQL and its extensions',
     url='https://github.com/postgrespro/testgres',
     long_description=readme,

{testgres-1.11.1/testgres → testgres-1.12.0/src}/__init__.py

@@ -51,9 +51,9 @@ from .standby import \
 
 from .config import testgres_config
 
-from .operations.os_ops import OsOperations, ConnectionParams
-from .operations.local_ops import LocalOperations
-from .operations.remote_ops import RemoteOperations
+from testgres.operations.os_ops import OsOperations, ConnectionParams
+from testgres.operations.local_ops import LocalOperations
+from testgres.operations.remote_ops import RemoteOperations
 
 __all__ = [
     "get_new_node",

{testgres-1.11.1/testgres → testgres-1.12.0/src}/backup.py

@@ -13,7 +13,7 @@ from .consts import \
 
 from .exceptions import BackupException
 
-from .operations.os_ops import OsOperations
+from testgres.operations.os_ops import OsOperations
 
 from .utils import \
     get_bin_path2, \

{testgres-1.11.1/testgres → testgres-1.12.0/src}/cache.py

@@ -16,8 +16,8 @@ from .utils import \
     get_bin_path2, \
     execute_utility2
 
-from .operations.local_ops import LocalOperations
-from .operations.os_ops import OsOperations
+from testgres.operations.local_ops import LocalOperations
+from testgres.operations.os_ops import OsOperations
 
 
 def cached_initdb(data_dir, logfile=None, params=None, os_ops: OsOperations = None, bin_path=None, cached=True):

{testgres-1.11.1/testgres → testgres-1.12.0/src}/config.py

@@ -9,8 +9,8 @@ import tempfile
 from contextlib import contextmanager
 
 from .consts import TMP_CACHE
-from .operations.os_ops import OsOperations
-from .operations.local_ops import LocalOperations
+from testgres.operations.os_ops import OsOperations
+from testgres.operations.local_ops import LocalOperations
 
 log_level = os.getenv('LOGGING_LEVEL', 'WARNING').upper()
 log_format = os.getenv('LOGGING_FORMAT', '%(asctime)s - %(levelname)s - %(message)s')

testgres-1.12.0/src/exceptions.py

@@ -0,0 +1,71 @@
+# coding: utf-8
+
+import six
+
+from testgres.operations.exceptions import TestgresException
+from testgres.operations.exceptions import ExecUtilException
+from testgres.operations.exceptions import InvalidOperationException
+
+
+class PortForException(TestgresException):
+    pass
+
+
+@six.python_2_unicode_compatible
+class QueryException(TestgresException):
+    def __init__(self, message=None, query=None):
+        super(QueryException, self).__init__(message)
+
+        self.message = message
+        self.query = query
+
+    def __str__(self):
+        msg = []
+
+        if self.message:
+            msg.append(self.message)
+
+        if self.query:
+            msg.append(u'Query: {}'.format(self.query))
+
+        return six.text_type('\n').join(msg)
+
+
+class TimeoutException(QueryException):
+    pass
+
+
+class CatchUpException(QueryException):
+    pass
+
+
+@six.python_2_unicode_compatible
+class StartNodeException(TestgresException):
+    def __init__(self, message=None, files=None):
+        super(StartNodeException, self).__init__(message)
+
+        self.message = message
+        self.files = files
+
+    def __str__(self):
+        msg = []
+
+        if self.message:
+            msg.append(self.message)
+
+        for f, lines in self.files or []:
+            msg.append(u'{}\n----\n{}\n'.format(f, lines))
+
+        return six.text_type('\n').join(msg)
+
+
+class InitNodeException(TestgresException):
+    pass
+
+
+class BackupException(TestgresException):
+    pass
+
+
+assert ExecUtilException.__name__ == "ExecUtilException"
+assert InvalidOperationException.__name__ == "InvalidOperationException"

{testgres-1.11.1/testgres → testgres-1.12.0/src}/impl/port_manager__generic.py

@@ -1,4 +1,4 @@
-from ..operations.os_ops import OsOperations
+from testgres.operations.os_ops import OsOperations
 
 from ..port_manager import PortManager
 from ..exceptions import PortForException

{testgres-1.11.1/testgres → testgres-1.12.0/src}/node.py

@@ -104,9 +104,9 @@ from .utils import \
 
 from .backup import NodeBackup
 
-from .operations.os_ops import ConnectionParams
-from .operations.os_ops import OsOperations
-from .operations.local_ops import LocalOperations
+from testgres.operations.os_ops import ConnectionParams
+from testgres.operations.os_ops import OsOperations
+from testgres.operations.local_ops import LocalOperations
 
 InternalError = pglib.InternalError
 ProgrammingError = pglib.ProgrammingError

{testgres-1.11.1/testgres → testgres-1.12.0/src}/utils.py

@@ -15,10 +15,10 @@ from six import iteritems
 
 from .exceptions import ExecUtilException
 from .config import testgres_config as tconf
-from .operations.os_ops import OsOperations
-from .operations.remote_ops import RemoteOperations
-from .operations.local_ops import LocalOperations
-from .operations.helpers import Helpers as OsHelpers
+from testgres.operations.os_ops import OsOperations
+from testgres.operations.remote_ops import RemoteOperations
+from testgres.operations.local_ops import LocalOperations
+from testgres.operations.helpers import Helpers as OsHelpers
 
 from .impl.port_manager__generic import PortManager__Generic