pytest-twinport 0.1.0__tar.gz

pytest_twinport-0.1.0/.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns: ["*"]

pytest_twinport-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint and type check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.11"
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run mypy
+
+  test:
+    name: ${{ matrix.os }}, Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+        include:
+          - os: macos-latest
+            python: "3.15"
+          - os: windows-latest
+            python: "3.15"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv run pytest
+
+  lowest-dependencies:
+    name: Lowest supported pytest
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.11"
+      - run: uv run --no-dev --resolution lowest-direct pytest

pytest_twinport-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Check that the tag matches the project version
+        run: |
+          version=$(uv version --short)
+          if [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match version $version in pyproject.toml"
+            exit 1
+          fi
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write # PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

pytest_twinport-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

pytest_twinport-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Petr Messner
+
+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.

pytest_twinport-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.5
+Name: pytest-twinport
+Version: 0.1.0
+Summary: Pytest plugin that leases free TCP/UDP ports without race conditions between parallel test runs
+Project-URL: Repository, https://github.com/messa/pytest-twinport
+Project-URL: Issues, https://github.com/messa/pytest-twinport/issues
+Author: Petr Messner
+License-Expression: MIT
+License-File: LICENSE
+Keywords: e2e,free port,port,pytest,unused port,xdist
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pytest>=7
+Description-Content-Type: text/markdown
+
+# pytest-twinport
+
+Pytest plugin that gives your tests a free TCP/UDP port, without collisions
+between tests running in parallel.
+
+The usual recipe, `bind(0)`, read the port number, close the socket, has a race
+condition: between closing the socket and starting your server, anyone else can
+get the same port. With many E2E tests running at once, this shows up as random
+`Address already in use` failures.
+
+`pytest-twinport` keeps the port reserved for the whole test, across processes
+and across separate pytest runs. It needs no daemon and no lock files.
+
+## Installation
+
+```bash
+pip install pytest-twinport
+```
+
+## Usage
+
+Use the `twinport` fixture to get a port reserved until the end of the test:
+
+```python
+def test_server(twinport):
+    server = start_server(port=twinport)
+    ...
+```
+
+Use `twinport_factory` when a test needs more ports:
+
+```python
+def test_cluster(twinport_factory):
+    ports = [twinport_factory() for _ in range(3)]
+    ...
+```
+
+Use `lease_port()` for any other fixture scope, or outside of fixtures. Make the
+server fixture depend on the lease, so that the server stops first:
+
+```python
+import pytest
+from pytest_twinport import lease_port
+
+
+@pytest.fixture(scope="session")
+def server():
+    with lease_port() as port:
+        process = start_server(port=port)
+        yield process
+        process.stop()
+```
+
+`lease_port()` can also be used without `with`. Keep the returned object for as
+long as you need the port, because a garbage collected lease is released:
+
+```python
+lease = lease_port()
+start_server(port=lease.port)
+...
+lease.release()
+```
+
+If your server can bind to port 0 and report the port it got, you don't need
+this plugin. It is meant for servers that must be told their port up front, such
+as external processes, Docker containers and services configured by a file.
+
+## How it works
+
+Ports are split into fixed pairs: an even _guard_ port and the odd port after it.
+
+1. Pick a random pair and bind the guard port. `bind()` is atomic, so only one
+   process can succeed.
+2. Check that the odd port is free.
+3. Give the odd port to the caller and keep the guard bound.
+
+Other processes can't take the pair, because they fail on the guard. When the
+process ends, even with `SIGKILL`, the kernel closes the guard. Nothing stale is
+left behind.
+
+The lock lives in the network namespace of the process that holds it, so it only
+protects ports used in that same namespace. See the note on containers below.
+
+Ports are only chosen outside the ephemeral range. This matters: outgoing
+connections take their source port from that range at any moment, and they know
+nothing about guards. Linux, macOS and BSD report the range, Windows uses a fixed
+assumption (see [Platform support](#platform-support)). On Linux, ports listed in
+`ip_local_reserved_ports` are skipped too.
+
+## Guarantees
+
+| Scenario | Protected? |
+| --- | --- |
+| Tests in one `pytest-xdist` run | Yes |
+| Separate pytest runs in one network namespace | Yes |
+| Pytest runs in separate network namespaces publishing ports to one host | No, see below |
+| Outgoing connections from anything on the machine | Yes, leased ports are outside the ephemeral range |
+| Server restarting during a test | Yes, nobody else gets the port |
+| Crashed or killed pytest process | Yes, the kernel releases the port |
+| Software using a fixed port in the same range | No, the port is only checked when it is leased |
+| Port allocation by other tools | No, every allocator has to use guards |
+
+The port is free on TCP and UDP, on IPv4 and IPv6, and the first bind works
+without `SO_REUSEADDR`. A server that restarts needs `SO_REUSEADDR` as usual,
+because its old connections can keep the port in `TIME_WAIT`. Every lease uses two
+port numbers.
+
+A process created with `fork()` without `exec()` inherits the guard, and the
+port stays blocked until that process ends too. This can last for a whole test
+session, but can't cause a collision.
+
+Containers with their own network stack have their own ports, so tests running
+inside them don't collide. That changes once they publish ports to a shared host,
+for example when pytest runs in a container and starts other containers with
+`docker run -p PORT:80` through a shared Docker socket. The guard is then in a
+different namespace than the published port, so two such runs can get the same
+port. To avoid this, run pytest with `--network host`, give every run its own
+`TWINPORT_RANGE`, or let Docker choose the port with `-p 80` and read it with
+`docker port`.
+
+## Configuration
+
+Ports are chosen from 15000-65535, minus the ephemeral range. To change this:
+
+```bash
+export TWINPORT_RANGE=20000-30000
+```
+
+`lease_port(port_range=(20000, 30000))` does the same for a single lease.
+Ephemeral ports are left out in both cases. If no pair can be leased,
+`NoFreePortError` is raised. This also happens when the ephemeral range of the
+system covers nearly all ports, and then the only fix is to make it smaller.
+
+## Measurements
+
+`scripts/stress.py` runs parallel processes that repeatedly get a port, wait up
+to 2 ms like a starting server, then bind the port without `SO_REUSEADDR`. It
+counts failed binds. These are the results of three runs. Each run used 16
+processes, 8000 allocations in total and a range of 200 ports (Linux, 6 cores):
+
+| Method | Collisions |
+| --- | --- |
+| `lease_port()` | 0, 0, 0 |
+| Random port checked by bind and close | 15, 16, 15 |
+| `bind(0)` and close | 1, 0, 0 |
+
+`bind(0)` is not limited to the small range, so it collides less often in this
+test. An additional run of `lease_port()` with 32 processes and 64000
+allocations had 0 collisions too.
+
+## Platform support
+
+The tests pass on Linux, macOS and Windows. BSD systems have not been tried out.
+
+There are two limits on Windows:
+
+- A bind to a wildcard address does not conflict with a bind to a specific
+  address. Ports are checked on wildcard and loopback addresses, so a service
+  listening only on another address of the machine is not detected.
+- The ephemeral range is not read from the system. Ports from 32768 up are left
+  out, which covers the default range. If the range was changed with `netsh` to
+  start lower, set `TWINPORT_RANGE` to stay out of it.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+uv run ruff format
+uv run mypy
+uv run scripts/stress.py
+```
+
+## Releasing
+
+Set the new version in `pyproject.toml` and commit it. Publishing a GitHub
+release then runs the tests, builds the package and uploads it to PyPI. The
+release fails if its tag does not match the version:
+
+```bash
+gh release create v0.1.0 --generate-notes
+```
+
+## Related projects
+
+These get a free port for a moment and don't reserve it, so they have the race
+condition described above:
+
+- [pytest-asyncio](https://pypi.org/project/pytest-asyncio/) has the
+  `unused_tcp_port` and `unused_udp_port` fixtures and their factories, based on
+  `bind(0)` and close.
+- [anyio](https://pypi.org/project/anyio/) has the `free_tcp_port` and
+  `free_udp_port` fixtures and their factories. They work the same way, and the
+  TCP and UDP ports are checked on both IPv4 and IPv6.
+- [pytest-unused-port](https://pypi.org/project/pytest-unused-port/) has an
+  `unused_port` fixture based on `bind(0)` and close.
+- [pytest-server-fixtures](https://pypi.org/project/pytest-server-fixtures/)
+  picks a random port below the usual ephemeral range, on a random loopback
+  address.
+
+These coordinate between processes in other ways:
+
+- [portpicker](https://pypi.org/project/portpicker/) by Google, which inspired
+  this project, solves the race with an optional `portserver` daemon.
+  `pytest-twinport` is not an integration of that library.
+- [pytest-services](https://pypi.org/project/pytest-services/) has a
+  `port_getter` fixture that keeps the list of used ports in a shared lock file.
+- [pytest-postgresql](https://pypi.org/project/pytest-postgresql/) marks its
+  port with a file in the temporary directory of the test run, which coordinates
+  `pytest-xdist` workers.
+- [portkeeper](https://pypi.org/project/portkeeper/) keeps reservations in a JSON
+  registry protected by a file lock.
+
+These solve neighboring problems:
+
+- [port-for](https://pypi.org/project/port-for/) manages persistent port
+  assignments. It avoids the ephemeral range as well.
+- [ephemeral-port-reserve](https://pypi.org/project/ephemeral-port-reserve/)
+  forces an ephemeral port into the `TIME_WAIT` state before releasing it.
+- [portlock](https://pypi.org/project/portlock/) uses a bound port to make sure
+  that only one instance of a script is running.
+- [pytest-localserver](https://pypi.org/project/pytest-localserver/) provides
+  test servers that bind to port 0 themselves, so they don't need a free port up
+  front.
+
+## License
+
+MIT