| Name | pytest-once JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | xdist-safe 'run once' fixture decorator for pytest (setup/teardown across workers) |
| upload_time | 2025-10-10 23:12:08 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT |
| keywords |
concurrency
fixture
lock
pytest
testing
xdist
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pytest-once
[](https://github.com/kiarina/pytest-once/actions/workflows/ci.yml)
[](https://badge.fury.io/py/pytest-once)
[](https://pypi.org/project/pytest-once/)
[](https://opensource.org/licenses/MIT)
**xdist-safe** "run once" pytest fixture decorator. Setup runs **exactly once** even with multiple workers (`pytest-xdist`).
## Features
- ✅ **Prevents duplicate execution** with file lock-based inter-process synchronization
- ✅ **Works with or without xdist** - seamless integration
- ✅ **Simple API** - just one decorator
- ✅ **Type-safe** - full type hints and mypy support
- ✅ **No teardown complexity** - encourages idempotent setup patterns
## Installation
```bash
pip install pytest-once
# If using with xdist
pip install pytest-xdist
```
## Quick Start
```python
from pytest_once import once_fixture
import pytest
@once_fixture(autouse=True, scope="session")
def bootstrap_db():
"""Setup database container - runs once across all workers."""
cleanup_old_containers() # Idempotent cleanup
start_db_container()
@pytest.fixture
def client(bootstrap_db): # Explicit dependency
"""Create a client that depends on the database."""
return create_client()
@once_fixture(autouse=True, scope="session")
def seed_data():
"""Load seed data - runs once after bootstrap_db."""
load_seed_dataset()
# You can also explicitly specify the fixture name
@once_fixture("db", autouse=True, scope="session")
def bootstrap_database():
"""Alternative: explicit fixture name."""
start_db_container()
```
### Key Points
- **Return values**: This decorator doesn't return values. Use a separate regular fixture that depends on the once_fixture if you need to share resources.
- **Idempotent setup recommended**: Clean up previous runs within setup to ensure safe re-execution.
## How It Works
When running tests in parallel with `pytest-xdist`, normal fixtures run independently in each worker process. Even with `scope="session"`, setup runs multiple times (once per worker), causing:
- ⚠️ Resource waste (e.g., multiple identical containers)
- ⚠️ Port conflicts and runtime errors
- ⚠️ Increased test execution time
`pytest-once` uses **file lock-based synchronization** to ensure setup runs exactly once:
1. First worker acquires lock and runs setup
2. Other workers wait for the lock
3. After setup completes, a marker file is created
4. Subsequent workers see the marker and skip setup
## Teardown Strategy
This decorator **does not support teardown**. Instead, we recommend these patterns:
### Pattern 1: Idempotent Setup (Recommended)
Clean up in the setup phase to ensure safe re-runs:
```python
@once_fixture("db_container", autouse=True, scope="session")
def db_container():
"""Setup with built-in cleanup."""
# Clean up any previous containers
stop_and_remove_old_containers()
# Start fresh container
start_db_container()
```
### Pattern 2: External Cleanup Tools
Use external tools for cleanup:
```bash
# Run tests
pytest -n 4
# Clean up after tests
docker-compose down
```
### Pattern 3: CI Auto-Cleanup
Let CI environments handle cleanup automatically:
```yaml
# GitHub Actions example
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run tests
run: pytest -n 4
# Environment is automatically destroyed after job completes
```
### Pattern 4: Temporary Files
Use pytest's built-in temporary directory fixtures:
```python
@pytest.fixture(scope="session")
def temp_data(tmp_path_factory):
"""Temporary files are automatically cleaned up."""
data_dir = tmp_path_factory.mktemp("data")
# pytest cleans this up automatically
return data_dir
```
## API Reference
```python
once_fixture(
fixture_name: str | None = None,
*,
scope: str = "session",
autouse: bool = False,
lock_timeout: float = 60.0,
namespace: str = "pytest-once",
)
```
### Parameters
- **fixture_name** (optional): Name of the registered fixture. If `None`, uses the decorated function's name. Use this when you need to reference the fixture in test dependencies.
- **scope**: Pytest fixture scope. Default: `"session"`
- `"session"`: Once per test session (recommended)
- `"module"`: Once per test module
- `"class"`: Once per test class
- `"function"`: Once per test function
- **autouse**: Whether to automatically use this fixture. Default: `False`
- `True`: Runs automatically without explicit dependency
- `False`: Must be explicitly referenced in test parameters
- **lock_timeout**: Timeout in seconds for acquiring the file lock. Default: `60.0`
- Increase if setup takes longer than 60 seconds
- Decrease for faster failure detection
- **namespace**: Directory name under pytest's temp directory for lock files. Default: `"pytest-once"`
- Change if you need to isolate different test suites
## Advanced Examples
### Multiple Once Fixtures with Dependencies
```python
@once_fixture(autouse=True, scope="session")
def setup_infrastructure():
"""First: setup infrastructure."""
start_docker_network()
start_database()
@once_fixture(autouse=True, scope="session")
def setup_data(setup_infrastructure):
"""Second: setup data (depends on infrastructure)."""
migrate_database()
load_seed_data()
@pytest.fixture
def api_client(setup_data):
"""Regular fixture that depends on once_fixture."""
return APIClient()
```
### Explicit Fixture Names
```python
@once_fixture("db", autouse=True, scope="session")
def bootstrap_database():
"""Fixture registered as 'db'."""
start_db_container()
@pytest.fixture
def db_client(db): # Reference by explicit name
"""Create client that depends on 'db' fixture."""
return create_db_client()
```
### Custom Lock Timeout
```python
@once_fixture(autouse=True, scope="session", lock_timeout=300.0)
def slow_setup():
"""Setup that takes up to 5 minutes."""
download_large_dataset()
process_data()
```
## Known Limitations
1. **No return values**: The decorator doesn't return values. Create a separate regular fixture if you need to share resources:
```python
@once_fixture("db_setup", autouse=True, scope="session")
def db_setup():
start_database()
@pytest.fixture
def db_connection(db_setup):
"""Regular fixture that returns a connection."""
return create_connection()
```
2. **No generator functions**: Functions with `yield` are not supported and will raise `TypeError`:
```python
# ❌ This will raise TypeError
@once_fixture(autouse=True, scope="session")
def bad_fixture():
setup()
yield # Not supported!
teardown()
```
3. **Crash recovery**: If a worker crashes while holding the lock, the marker file may be left behind. The next run will automatically recover, but you can also manually delete the lock directory or change the `namespace` parameter.
## Troubleshooting
### Lock Timeout Errors
If you see timeout errors:
```python
TimeoutError: Timed out acquiring lock for once_fixture 'my_fixture'
```
**Solutions:**
- Increase `lock_timeout` parameter
- Check if a previous worker crashed (restart pytest)
- Manually clean up lock files in pytest's temp directory
### Setup Running Multiple Times
If setup runs more than once:
1. Verify you're using `scope="session"`
2. Check that `autouse=True` or the fixture is properly referenced
3. Ensure the fixture name is unique across your test suite
### Import Errors
If you see import errors:
```python
ImportError: cannot import name 'once_fixture'
```
**Solution:** Ensure pytest-once is installed:
```bash
pip install pytest-once
```
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
## License
MIT License © 2025 kiarina
## Links
- **Documentation**: [GitHub README](https://github.com/kiarina/pytest-once#readme)
- **Source Code**: [GitHub Repository](https://github.com/kiarina/pytest-once)
- **Issue Tracker**: [GitHub Issues](https://github.com/kiarina/pytest-once/issues)
- **Changelog**: [CHANGELOG.md](https://github.com/kiarina/pytest-once/blob/main/CHANGELOG.md)
- **PyPI**: [pytest-once](https://pypi.org/project/pytest-once/)
Raw data
{
"_id": null,
"home_page": null,
"name": "pytest-once",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "concurrency, fixture, lock, pytest, testing, xdist",
"author": null,
"author_email": "kiarina <kiarinadawa@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2c/f5/da1d13650b3813d61d715b423efe9c73b42f030497db531f317f9ad816c2/pytest_once-0.1.0.tar.gz",
"platform": null,
"description": "# pytest-once\n\n[](https://github.com/kiarina/pytest-once/actions/workflows/ci.yml)\n[](https://badge.fury.io/py/pytest-once)\n[](https://pypi.org/project/pytest-once/)\n[](https://opensource.org/licenses/MIT)\n\n**xdist-safe** \"run once\" pytest fixture decorator. Setup runs **exactly once** even with multiple workers (`pytest-xdist`).\n\n## Features\n\n- \u2705 **Prevents duplicate execution** with file lock-based inter-process synchronization\n- \u2705 **Works with or without xdist** - seamless integration\n- \u2705 **Simple API** - just one decorator\n- \u2705 **Type-safe** - full type hints and mypy support\n- \u2705 **No teardown complexity** - encourages idempotent setup patterns\n\n## Installation\n\n```bash\npip install pytest-once\n\n# If using with xdist\npip install pytest-xdist\n```\n\n## Quick Start\n\n```python\nfrom pytest_once import once_fixture\nimport pytest\n\n@once_fixture(autouse=True, scope=\"session\")\ndef bootstrap_db():\n \"\"\"Setup database container - runs once across all workers.\"\"\"\n cleanup_old_containers() # Idempotent cleanup\n start_db_container()\n\n@pytest.fixture\ndef client(bootstrap_db): # Explicit dependency\n \"\"\"Create a client that depends on the database.\"\"\"\n return create_client()\n\n@once_fixture(autouse=True, scope=\"session\")\ndef seed_data():\n \"\"\"Load seed data - runs once after bootstrap_db.\"\"\"\n load_seed_dataset()\n\n# You can also explicitly specify the fixture name\n@once_fixture(\"db\", autouse=True, scope=\"session\")\ndef bootstrap_database():\n \"\"\"Alternative: explicit fixture name.\"\"\"\n start_db_container()\n```\n\n### Key Points\n\n- **Return values**: This decorator doesn't return values. Use a separate regular fixture that depends on the once_fixture if you need to share resources.\n- **Idempotent setup recommended**: Clean up previous runs within setup to ensure safe re-execution.\n\n## How It Works\n\nWhen running tests in parallel with `pytest-xdist`, normal fixtures run independently in each worker process. Even with `scope=\"session\"`, setup runs multiple times (once per worker), causing:\n\n- \u26a0\ufe0f Resource waste (e.g., multiple identical containers)\n- \u26a0\ufe0f Port conflicts and runtime errors\n- \u26a0\ufe0f Increased test execution time\n\n`pytest-once` uses **file lock-based synchronization** to ensure setup runs exactly once:\n\n1. First worker acquires lock and runs setup\n2. Other workers wait for the lock\n3. After setup completes, a marker file is created\n4. Subsequent workers see the marker and skip setup\n\n## Teardown Strategy\n\nThis decorator **does not support teardown**. Instead, we recommend these patterns:\n\n### Pattern 1: Idempotent Setup (Recommended)\n\nClean up in the setup phase to ensure safe re-runs:\n\n```python\n@once_fixture(\"db_container\", autouse=True, scope=\"session\")\ndef db_container():\n \"\"\"Setup with built-in cleanup.\"\"\"\n # Clean up any previous containers\n stop_and_remove_old_containers()\n\n # Start fresh container\n start_db_container()\n```\n\n### Pattern 2: External Cleanup Tools\n\nUse external tools for cleanup:\n\n```bash\n# Run tests\npytest -n 4\n\n# Clean up after tests\ndocker-compose down\n```\n\n### Pattern 3: CI Auto-Cleanup\n\nLet CI environments handle cleanup automatically:\n\n```yaml\n# GitHub Actions example\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Run tests\n run: pytest -n 4\n # Environment is automatically destroyed after job completes\n```\n\n### Pattern 4: Temporary Files\n\nUse pytest's built-in temporary directory fixtures:\n\n```python\n@pytest.fixture(scope=\"session\")\ndef temp_data(tmp_path_factory):\n \"\"\"Temporary files are automatically cleaned up.\"\"\"\n data_dir = tmp_path_factory.mktemp(\"data\")\n # pytest cleans this up automatically\n return data_dir\n```\n\n## API Reference\n\n```python\nonce_fixture(\n fixture_name: str | None = None,\n *,\n scope: str = \"session\",\n autouse: bool = False,\n lock_timeout: float = 60.0,\n namespace: str = \"pytest-once\",\n)\n```\n\n### Parameters\n\n- **fixture_name** (optional): Name of the registered fixture. If `None`, uses the decorated function's name. Use this when you need to reference the fixture in test dependencies.\n\n- **scope**: Pytest fixture scope. Default: `\"session\"`\n - `\"session\"`: Once per test session (recommended)\n - `\"module\"`: Once per test module\n - `\"class\"`: Once per test class\n - `\"function\"`: Once per test function\n\n- **autouse**: Whether to automatically use this fixture. Default: `False`\n - `True`: Runs automatically without explicit dependency\n - `False`: Must be explicitly referenced in test parameters\n\n- **lock_timeout**: Timeout in seconds for acquiring the file lock. Default: `60.0`\n - Increase if setup takes longer than 60 seconds\n - Decrease for faster failure detection\n\n- **namespace**: Directory name under pytest's temp directory for lock files. Default: `\"pytest-once\"`\n - Change if you need to isolate different test suites\n\n## Advanced Examples\n\n### Multiple Once Fixtures with Dependencies\n\n```python\n@once_fixture(autouse=True, scope=\"session\")\ndef setup_infrastructure():\n \"\"\"First: setup infrastructure.\"\"\"\n start_docker_network()\n start_database()\n\n@once_fixture(autouse=True, scope=\"session\")\ndef setup_data(setup_infrastructure):\n \"\"\"Second: setup data (depends on infrastructure).\"\"\"\n migrate_database()\n load_seed_data()\n\n@pytest.fixture\ndef api_client(setup_data):\n \"\"\"Regular fixture that depends on once_fixture.\"\"\"\n return APIClient()\n```\n\n### Explicit Fixture Names\n\n```python\n@once_fixture(\"db\", autouse=True, scope=\"session\")\ndef bootstrap_database():\n \"\"\"Fixture registered as 'db'.\"\"\"\n start_db_container()\n\n@pytest.fixture\ndef db_client(db): # Reference by explicit name\n \"\"\"Create client that depends on 'db' fixture.\"\"\"\n return create_db_client()\n```\n\n### Custom Lock Timeout\n\n```python\n@once_fixture(autouse=True, scope=\"session\", lock_timeout=300.0)\ndef slow_setup():\n \"\"\"Setup that takes up to 5 minutes.\"\"\"\n download_large_dataset()\n process_data()\n```\n\n## Known Limitations\n\n1. **No return values**: The decorator doesn't return values. Create a separate regular fixture if you need to share resources:\n\n ```python\n @once_fixture(\"db_setup\", autouse=True, scope=\"session\")\n def db_setup():\n start_database()\n\n @pytest.fixture\n def db_connection(db_setup):\n \"\"\"Regular fixture that returns a connection.\"\"\"\n return create_connection()\n ```\n\n2. **No generator functions**: Functions with `yield` are not supported and will raise `TypeError`:\n\n ```python\n # \u274c This will raise TypeError\n @once_fixture(autouse=True, scope=\"session\")\n def bad_fixture():\n setup()\n yield # Not supported!\n teardown()\n ```\n\n3. **Crash recovery**: If a worker crashes while holding the lock, the marker file may be left behind. The next run will automatically recover, but you can also manually delete the lock directory or change the `namespace` parameter.\n\n## Troubleshooting\n\n### Lock Timeout Errors\n\nIf you see timeout errors:\n\n```python\nTimeoutError: Timed out acquiring lock for once_fixture 'my_fixture'\n```\n\n**Solutions:**\n- Increase `lock_timeout` parameter\n- Check if a previous worker crashed (restart pytest)\n- Manually clean up lock files in pytest's temp directory\n\n### Setup Running Multiple Times\n\nIf setup runs more than once:\n\n1. Verify you're using `scope=\"session\"`\n2. Check that `autouse=True` or the fixture is properly referenced\n3. Ensure the fixture name is unique across your test suite\n\n### Import Errors\n\nIf you see import errors:\n\n```python\nImportError: cannot import name 'once_fixture'\n```\n\n**Solution:** Ensure pytest-once is installed:\n```bash\npip install pytest-once\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\nMIT License \u00a9 2025 kiarina\n\n## Links\n\n- **Documentation**: [GitHub README](https://github.com/kiarina/pytest-once#readme)\n- **Source Code**: [GitHub Repository](https://github.com/kiarina/pytest-once)\n- **Issue Tracker**: [GitHub Issues](https://github.com/kiarina/pytest-once/issues)\n- **Changelog**: [CHANGELOG.md](https://github.com/kiarina/pytest-once/blob/main/CHANGELOG.md)\n- **PyPI**: [pytest-once](https://pypi.org/project/pytest-once/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "xdist-safe 'run once' fixture decorator for pytest (setup/teardown across workers)",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/kiarina/pytest-once/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/kiarina/pytest-once/tree/main#readme",
"Homepage": "https://github.com/kiarina/pytest-once",
"Issues": "https://github.com/kiarina/pytest-once/issues",
"Repository": "https://github.com/kiarina/pytest-once"
},
"split_keywords": [
"concurrency",
" fixture",
" lock",
" pytest",
" testing",
" xdist"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c15e0706452985836e85482edf637029ace0e7e905a2d428dbaa31a103ae4eea",
"md5": "138648ea9df3efc1c558f3e09900a712",
"sha256": "15b7d651e917f52210afbacc88f205c14f3458043703a39730864ddd16e62e70"
},
"downloads": -1,
"filename": "pytest_once-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "138648ea9df3efc1c558f3e09900a712",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 7537,
"upload_time": "2025-10-10T23:12:06",
"upload_time_iso_8601": "2025-10-10T23:12:06.996415Z",
"url": "https://files.pythonhosted.org/packages/c1/5e/0706452985836e85482edf637029ace0e7e905a2d428dbaa31a103ae4eea/pytest_once-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2cf5da1d13650b3813d61d715b423efe9c73b42f030497db531f317f9ad816c2",
"md5": "5e614e4f89fabbde7210e6a7a682e6bf",
"sha256": "3b7d4b6a984779e37e954af799270332762c0ddba685ddaf3065edfeccbb8c4a"
},
"downloads": -1,
"filename": "pytest_once-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5e614e4f89fabbde7210e6a7a682e6bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 33018,
"upload_time": "2025-10-10T23:12:08",
"upload_time_iso_8601": "2025-10-10T23:12:08.311162Z",
"url": "https://files.pythonhosted.org/packages/2c/f5/da1d13650b3813d61d715b423efe9c73b42f030497db531f317f9ad816c2/pytest_once-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 23:12:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kiarina",
"github_project": "pytest-once",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pytest-once"
}
