pytest-neon 0.6.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

pytest_neon/__init__.py

@@ -9,7 +9,7 @@ from pytest_neon.plugin import (
     neon_engine,
 )
 
-__version__ = "0.6.0"
+__version__ = "2.0.0"
 __all__ = [
     "NeonBranch",
     "neon_branch",

pytest_neon/plugin.py

@@ -5,15 +5,17 @@ instant branching feature. Each test gets a clean database state via
 branch reset after each test.
 
 Main fixtures:
-    neon_branch: Primary fixture - one branch per session, reset after each test
-    neon_branch_shared: Shared branch without reset (fastest, no isolation)
+    neon_branch_readwrite: Read-write access with reset after each test (recommended)
+    neon_branch_readonly: Read-only access, no reset (fastest for read-only tests)
+    neon_branch: Deprecated alias for neon_branch_readwrite
+    neon_branch_shared: Shared branch without reset (module-scoped)
     neon_connection: psycopg2 connection (requires psycopg2 extra)
     neon_connection_psycopg: psycopg v3 connection (requires psycopg extra)
     neon_engine: SQLAlchemy engine (requires sqlalchemy extra)
 
 SQLAlchemy Users:
     If you create your own SQLAlchemy engine (not using neon_engine fixture),
-    you MUST use pool_pre_ping=True:
+    you MUST use pool_pre_ping=True when using neon_branch_readwrite:
 
         engine = create_engine(DATABASE_URL, pool_pre_ping=True)
 
@@ -21,6 +23,9 @@ SQLAlchemy Users:
     Without pool_pre_ping, SQLAlchemy may try to reuse dead pooled connections,
     causing "SSL connection has been closed unexpectedly" errors.
 
+    Note: pool_pre_ping is not required for neon_branch_readonly since no
+    resets occur.
+
 Configuration:
     Set NEON_API_KEY and NEON_PROJECT_ID environment variables, or use
     --neon-api-key and --neon-project-id CLI options.
@@ -33,6 +38,7 @@ from __future__ import annotations
 import contextlib
 import os
 import time
+import warnings
 from collections.abc import Generator
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
@@ -373,8 +379,19 @@ def _create_neon_branch(
                 )
 
 
-def _reset_branch_to_parent(branch: NeonBranch, api_key: str) -> None:
-    """Reset a branch to its parent's state using the Neon API."""
+def _reset_branch_to_parent(
+    branch: NeonBranch, api_key: str, max_retries: int = 3
+) -> None:
+    """Reset a branch to its parent's state using the Neon API.
+
+    Uses exponential backoff retry logic to handle transient API errors
+    that can occur during parallel test execution.
+
+    Args:
+        branch: The branch to reset
+        api_key: Neon API key
+        max_retries: Maximum number of retry attempts (default: 3)
+    """
     if not branch.parent_id:
         raise RuntimeError(f"Branch {branch.branch_id} has no parent - cannot reset")
 
@@ -383,10 +400,27 @@ def _reset_branch_to_parent(branch: NeonBranch, api_key: str) -> None:
         "Authorization": f"Bearer {api_key}",
         "Content-Type": "application/json",
     }
-    response = requests.post(
-        url, headers=headers, json={"source_branch_id": branch.parent_id}, timeout=30
-    )
-    response.raise_for_status()
+
+    last_error: Exception | None = None
+    for attempt in range(max_retries + 1):
+        try:
+            response = requests.post(
+                url,
+                headers=headers,
+                json={"source_branch_id": branch.parent_id},
+                timeout=30,
+            )
+            response.raise_for_status()
+            return  # Success
+        except requests.RequestException as e:
+            last_error = e
+            if attempt < max_retries:
+                # Exponential backoff: 1s, 2s, 4s
+                wait_time = 2**attempt
+                time.sleep(wait_time)
+
+    # All retries exhausted
+    raise last_error  # type: ignore[misc]
 
 
 @pytest.fixture(scope="session")
@@ -538,16 +572,21 @@ def _neon_branch_for_reset(
 
 
 @pytest.fixture(scope="function")
-def neon_branch(
+def neon_branch_readwrite(
     request: pytest.FixtureRequest,
     _neon_branch_for_reset: NeonBranch,
 ) -> Generator[NeonBranch, None, None]:
     """
-    Provide an isolated Neon database branch for each test.
+    Provide a read-write Neon database branch with reset after each test.
+
+    This is the recommended fixture for tests that modify database state.
+    It creates one branch per test session, then resets it to the parent
+    branch's state after each test. This provides test isolation with
+    ~0.5s overhead per test.
 
-    This is the primary fixture for database testing. It creates one branch per
-    test session, then resets it to the parent branch's state after each test.
-    This provides test isolation with ~0.5s overhead per test.
+    Use this fixture when your tests INSERT, UPDATE, or DELETE data.
+    For read-only tests, use ``neon_branch_readonly`` instead for better
+    performance (no reset overhead).
 
     The branch is automatically deleted after all tests complete, unless
     --neon-keep-branches is specified. Branches also auto-expire after
@@ -575,11 +614,16 @@ def neon_branch(
 
     Example::
 
-        def test_database_operation(neon_branch):
+        def test_insert_user(neon_branch_readwrite):
             # DATABASE_URL is automatically set
             conn_string = os.environ["DATABASE_URL"]
             # or use directly
-            conn_string = neon_branch.connection_string
+            conn_string = neon_branch_readwrite.connection_string
+
+            # Insert data - branch will reset after this test
+            with psycopg.connect(conn_string) as conn:
+                conn.execute("INSERT INTO users (name) VALUES ('test')")
+                conn.commit()
     """
     config = request.config
     api_key = _get_config_value(config, "neon_api_key", "NEON_API_KEY", "neon_api_key")
@@ -588,8 +632,9 @@ def neon_branch(
     if not _neon_branch_for_reset.parent_id:
         pytest.fail(
             f"\n\nBranch {_neon_branch_for_reset.branch_id} has no parent. "
-            f"The neon_branch fixture requires a parent branch for reset.\n\n"
-            f"Use neon_branch_shared if you don't need reset, or specify "
+            f"The neon_branch_readwrite fixture requires a parent branch for "
+            f"reset.\n\n"
+            f"Use neon_branch_readonly if you don't need reset, or specify "
             f"a parent branch with --neon-parent-branch or NEON_PARENT_BRANCH_ID."
         )
 
@@ -608,6 +653,77 @@ def neon_branch(
             )
 
 
+@pytest.fixture(scope="function")
+def neon_branch_readonly(
+    _neon_branch_for_reset: NeonBranch,
+) -> NeonBranch:
+    """
+    Provide a read-only Neon database branch without reset.
+
+    This is the recommended fixture for tests that only read data (SELECT queries).
+    No branch reset occurs after each test, making it faster than
+    ``neon_branch_readwrite`` (~0.5s saved per test).
+
+    Use this fixture when your tests only perform SELECT queries and don't
+    modify database state. For tests that INSERT, UPDATE, or DELETE data,
+    use ``neon_branch_readwrite`` instead to ensure test isolation.
+
+    Warning:
+        If you accidentally write data using this fixture, subsequent tests
+        will see those modifications. The fixture does not enforce read-only
+        access at the database level - it simply skips the reset step.
+
+    The connection string is automatically set in the DATABASE_URL environment
+    variable (configurable via --neon-env-var).
+
+    Requires either:
+        - NEON_API_KEY and NEON_PROJECT_ID environment variables, or
+        - --neon-api-key and --neon-project-id command line options
+
+    Yields:
+        NeonBranch: Object with branch_id, project_id, connection_string, and host.
+
+    Example::
+
+        def test_query_users(neon_branch_readonly):
+            # DATABASE_URL is automatically set
+            conn_string = os.environ["DATABASE_URL"]
+
+            # Read-only query - no reset needed after this test
+            with psycopg.connect(conn_string) as conn:
+                result = conn.execute("SELECT * FROM users").fetchall()
+                assert len(result) > 0
+    """
+    return _neon_branch_for_reset
+
+
+@pytest.fixture(scope="function")
+def neon_branch(
+    request: pytest.FixtureRequest,
+    neon_branch_readwrite: NeonBranch,
+) -> Generator[NeonBranch, None, None]:
+    """
+    Deprecated: Use ``neon_branch_readwrite`` or ``neon_branch_readonly`` instead.
+
+    This fixture is an alias for ``neon_branch_readwrite`` and will be removed
+    in a future version. Please migrate to the explicit fixture names:
+
+    - ``neon_branch_readwrite``: For tests that modify data (INSERT/UPDATE/DELETE)
+    - ``neon_branch_readonly``: For tests that only read data (SELECT)
+
+    .. deprecated:: 1.1.0
+        Use ``neon_branch_readwrite`` for read-write access with reset,
+        or ``neon_branch_readonly`` for read-only access without reset.
+    """
+    warnings.warn(
+        "neon_branch is deprecated. Use neon_branch_readwrite (for tests that "
+        "modify data) or neon_branch_readonly (for read-only tests) instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    yield neon_branch_readwrite
+
+
 @pytest.fixture(scope="module")
 def neon_branch_shared(
     request: pytest.FixtureRequest,

{pytest_neon-0.6.0.dist-info → pytest_neon-2.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 0.6.0
+Version: 2.0.0
 Summary: Pytest plugin for Neon database branch isolation in tests
 Project-URL: Homepage, https://github.com/ZainRizvi/pytest-neon
 Project-URL: Repository, https://github.com/ZainRizvi/pytest-neon
@@ -97,7 +97,7 @@ export NEON_PROJECT_ID="your-project-id"
 2. Write tests:
 
 ```python
-def test_user_creation(neon_branch):
+def test_user_creation(neon_branch_readwrite):
     # DATABASE_URL is automatically set to the test branch
     import psycopg  # Your own install
 
@@ -105,6 +105,7 @@ def test_user_creation(neon_branch):
         with conn.cursor() as cur:
             cur.execute("INSERT INTO users (email) VALUES ('test@example.com')")
         conn.commit()
+    # Branch automatically resets after test - next test sees clean state
 ```
 
 3. Run tests:
@@ -115,33 +116,75 @@ pytest
 
 ## Fixtures
 
-### `neon_branch` (default, recommended)
+**Which fixture should I use?**
 
-The primary fixture for database testing. Creates one branch per test session, then resets it to the parent branch's state after each test. This provides test isolation with ~0.5s overhead per test.
+- **Use `neon_branch_readonly`** if your test only reads data (SELECT queries). This is the fastest option with no per-test overhead.
+- **Use `neon_branch_readwrite`** if your test modifies data (INSERT, UPDATE, DELETE). This resets the branch after each test for isolation.
 
-Returns a `NeonBranch` dataclass with:
+### `neon_branch_readonly` (recommended, fastest)
 
-- `branch_id`: The Neon branch ID
-- `project_id`: The Neon project ID
-- `connection_string`: Full PostgreSQL connection URI
-- `host`: The database host
-- `parent_id`: The parent branch ID (used for resets)
+**Use this fixture by default** if your tests don't need to write data. It provides the best performance by skipping the branch reset step (~0.5s saved per test), which also reduces API calls and avoids rate limiting issues.
+
+```python
+def test_query_users(neon_branch_readonly):
+    # DATABASE_URL is set automatically
+    import psycopg
+    with psycopg.connect(neon_branch_readonly.connection_string) as conn:
+        result = conn.execute("SELECT * FROM users").fetchall()
+        assert len(result) >= 0
+    # No reset after this test - fast!
+```
+
+**Use this when**:
+- Tests only perform SELECT queries
+- Tests don't modify database state
+- You want maximum performance
+
+**Warning**: If you accidentally write data using this fixture, subsequent tests will see those modifications. The fixture does not enforce read-only access at the database level.
+
+**Performance**: ~1.5s initial setup per session, **no per-test overhead**. For 10 read-only tests, expect only ~1.5s total overhead (vs ~6.5s with readwrite).
+
+### `neon_branch_readwrite` (for write tests)
+
+Use this fixture when your tests need to INSERT, UPDATE, or DELETE data. Creates one branch per test session, then resets it to the parent branch's state after each test. This provides test isolation with ~0.5s overhead per test.
 
 ```python
 import os
 
-def test_branch_info(neon_branch):
+def test_insert_user(neon_branch_readwrite):
     # DATABASE_URL is set automatically
-    assert os.environ["DATABASE_URL"] == neon_branch.connection_string
+    assert os.environ["DATABASE_URL"] == neon_branch_readwrite.connection_string
 
     # Use with any driver
     import psycopg
-    conn = psycopg.connect(neon_branch.connection_string)
+    with psycopg.connect(neon_branch_readwrite.connection_string) as conn:
+        conn.execute("INSERT INTO users (name) VALUES ('test')")
+        conn.commit()
+    # Branch resets after this test - changes won't affect other tests
 ```
 
-**Performance**: ~1.5s initial setup per session + ~0.5s reset per test. For 10 tests, expect ~6.5s total overhead.
+**Performance**: ~1.5s initial setup per session + ~0.5s reset per test. For 10 write tests, expect ~6.5s total overhead.
 
-### `neon_branch_shared` (fastest, no isolation)
+### `NeonBranch` dataclass
+
+Both fixtures return a `NeonBranch` dataclass with:
+
+- `branch_id`: The Neon branch ID
+- `project_id`: The Neon project ID
+- `connection_string`: Full PostgreSQL connection URI
+- `host`: The database host
+- `parent_id`: The parent branch ID (used for resets)
+
+### `neon_branch` (deprecated)
+
+> **Deprecated**: Use `neon_branch_readwrite` or `neon_branch_readonly` instead.
+
+This fixture is an alias for `neon_branch_readwrite` and will emit a deprecation warning. Migrate to the explicit fixture names for clarity:
+
+- `neon_branch_readwrite`: For tests that modify data (INSERT/UPDATE/DELETE)
+- `neon_branch_readonly`: For tests that only read data (SELECT)
+
+### `neon_branch_shared` (module-scoped, no isolation)
 
 Creates one branch per test module and shares it across all tests without resetting. This is the fastest option but tests can see each other's data modifications.
 
@@ -207,19 +250,21 @@ def test_query(neon_engine):
 
 ### Using Your Own SQLAlchemy Engine
 
-If you have a module-level SQLAlchemy engine (common pattern), you **must** use `pool_pre_ping=True`:
+If you have a module-level SQLAlchemy engine (common pattern) and use `neon_branch_readwrite`, you **must** use `pool_pre_ping=True`:
 
 ```python
 # database.py
 from sqlalchemy import create_engine
 from config import DATABASE_URL
 
-# pool_pre_ping=True is REQUIRED for pytest-neon
+# pool_pre_ping=True is REQUIRED when using neon_branch_readwrite
 # It verifies connections are alive before using them
 engine = create_engine(DATABASE_URL, pool_pre_ping=True)
 ```
 
-**Why?** After each test, pytest-neon resets the branch which terminates server-side connections. Without `pool_pre_ping`, SQLAlchemy may try to reuse a dead pooled connection, causing `SSL connection has been closed unexpectedly` errors.
+**Why?** After each test, `neon_branch_readwrite` resets the branch which terminates server-side connections. Without `pool_pre_ping`, SQLAlchemy may try to reuse a dead pooled connection, causing `SSL connection has been closed unexpectedly` errors.
+
+**Note**: If you only use `neon_branch_readonly`, `pool_pre_ping` is not required since no resets occur.
 
 This is also a best practice for any cloud database (Neon, RDS, etc.) where connections can be terminated externally.
 
@@ -435,7 +480,7 @@ Branches use copy-on-write storage, so you only pay for data that differs from t
 
 ### What Reset Does
 
-The `neon_branch` fixture uses Neon's branch restore API to reset database state after each test:
+The `neon_branch_readwrite` fixture uses Neon's branch restore API to reset database state after each test:
 
 - **Data changes are reverted**: All INSERT, UPDATE, DELETE operations are undone
 - **Schema changes are reverted**: CREATE TABLE, ALTER TABLE, DROP TABLE, etc. are undone
@@ -472,12 +517,12 @@ pip install pytest-neon[psycopg2]
 pip install pytest-neon[sqlalchemy]
 ```
 
-Or use the core `neon_branch` fixture with your own driver:
+Or use the core fixtures with your own driver:
 
 ```python
-def test_example(neon_branch):
+def test_example(neon_branch_readwrite):
     import my_preferred_driver
-    conn = my_preferred_driver.connect(neon_branch.connection_string)
+    conn = my_preferred_driver.connect(neon_branch_readwrite.connection_string)
 ```
 
 ### "Neon API key not configured"

pytest_neon-2.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pytest_neon/__init__.py,sha256=Ti_bjX7CgEZjtaY_uoNnkSvRUXnEw4MkfsbFie_K6Mo,398
+pytest_neon/plugin.py,sha256=9VH7h2UYp0AoJj3FagpP6Xqtd1_qqkcuS0sLF-cqYpo,33877
+pytest_neon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_neon-2.0.0.dist-info/METADATA,sha256=bQ7y0oOcymrho3AY9NhHRFT1FNM4jPK27rRFh217FN4,18386
+pytest_neon-2.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pytest_neon-2.0.0.dist-info/entry_points.txt,sha256=5U88Idj_G8-PSDb9VF3OwYFbGLHnGOo_GxgYvi0dtXw,37
+pytest_neon-2.0.0.dist-info/licenses/LICENSE,sha256=aKKp_Ex4WBHTByY4BhXJ181dzB_qYhi2pCUmZ7Spn_0,1067
+pytest_neon-2.0.0.dist-info/RECORD,,

pytest_neon-0.6.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-pytest_neon/__init__.py,sha256=54UgijfJx44ra6-LyAS2fKVPTdqOKofrD3wQeCt8ydQ,398
-pytest_neon/plugin.py,sha256=6wcZe9E90y2kya4wM0ur9EtUhqWFUll_ebN4xgsogPk,29601
-pytest_neon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pytest_neon-0.6.0.dist-info/METADATA,sha256=Aw8Y8MHYAo9Wt8TbthiN-pd8pAQenaHckwobPipvtsk,16057
-pytest_neon-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-pytest_neon-0.6.0.dist-info/entry_points.txt,sha256=5U88Idj_G8-PSDb9VF3OwYFbGLHnGOo_GxgYvi0dtXw,37
-pytest_neon-0.6.0.dist-info/licenses/LICENSE,sha256=aKKp_Ex4WBHTByY4BhXJ181dzB_qYhi2pCUmZ7Spn_0,1067
-pytest_neon-0.6.0.dist-info/RECORD,,