eggress Python bindings

Python bindings for the eggress proxy framework, powered by PyO3 and the Rust embed API.

Installation (local development)

pip install maturin
cd crates/eggress-python
rm -f ../../target/wheels/eggress-*.whl   # stale wheels break the install glob below
maturin build --target x86_64-apple-darwin   # adjust target for your platform
pip install --force-reinstall target/wheels/eggress-*.whl

Prebuilt wheels

Prebuilt wheels are published to PyPI for:

Linux x86_64 and aarch64 (manylinux)
macOS x86_64 and arm64
Windows x86_64

The wheel uses the Python stable ABI (abi3-py39), so one wheel per platform supports all declared Python versions (3.9–3.13). Other platforms can install from the source distribution (requires Rust toolchain).

Supported Python versions: 3.9, 3.10, 3.11, 3.12, 3.13.

Quick start

from eggress import EggressService

with EggressService.from_toml("""
    version = 1
    [[listeners]]
    name = "socks"
    bind = "127.0.0.1:0"
    protocols = ["socks5"]
""").start() as handle:
    addr = handle.bound_addresses["socks"]
    print(f"SOCKS5 listening on {addr}")
    print(handle.metrics_text())

Async usage

import asyncio
from eggress import EggressService

async def main():
    async with await EggressService.from_toml(TOML).astart() as handle:
        print("Listening on", await handle.bound_addresses)

asyncio.run(main())

API

EggressConfig.from_toml(toml) / EggressConfig.from_file(path) — parse config
EggressService(config) / EggressService.from_toml(toml) — create service
service.start() — start proxy, returns EggressHandle
handle.bound_addresses — dict of listener name -> address
handle.status() — generation, readiness, uptime, connections
handle.metrics_text() — Prometheus metrics
handle.reload_toml(toml) — hot-reload config
handle.shutdown() — graceful shutdown (idempotent; safe to call twice)
Context manager support: with service.start() as handle: ...

Always use explicit lifecycle management. Prefer context managers or explicit handle.shutdown() in a finally block. Do not rely on Python garbage collection to shut down the service — object destruction is a best-effort fallback, not the lifecycle API.

pproxy Compatibility

Eggress provides a pproxy compatibility surface validated against pproxy==2.7.9 and bounded by the canonical capability manifest. Legacy cipher implementations and unsupported native transports fail explicitly rather than being silently substituted:

URI Translation: translate_pproxy_args() converts pproxy CLI arguments to eggress TOML
Same Protocols: HTTP, SOCKS4/4a, SOCKS5, Shadowsocks (AEAD), Trojan
Same Schedulers: Round-robin, least-connections, first-available
Enhanced Features: Hot-reload, structured errors, context managers

See docs/python/PPROXY_EMBEDDED_USAGE_PATTERNS.md for migration guidance.

pproxy drop-in API

from eggress import PPProxyService, start_pproxy, check_pproxy_args

# Check compatibility before starting
report = check_pproxy_args(["-l", "socks5://:1080", "-r", "http://proxy:8080"])
print(f"Tier: {report.tier}, OK: {report.ok}")

# Start from pproxy args
with start_pproxy(["-l", "socks5://127.0.0.1:0"]) as handle:
    print(handle.bound_addresses)

# Start from local URI
with PPProxyService.from_uri("socks5://127.0.0.1:0") as handle:
    print(handle.bound_addresses)

# Start from TOML
with PPProxyService.from_toml(toml_str) as handle:
    print(handle.bound_addresses)

The optional eggress-pproxy-compat distribution additionally provides python -m pproxy, a pproxy console script, and the top-level pproxy package backed by the same compatibility entry point. pproxy.server helper calls reuse the existing protocol/proxy adapters, while pproxy.sysproxy delegates system-proxy apply/rollback to the native backend where the platform supports it. See the namespace strategy below before installing it.

API Contract (Phase C1)

A machine-readable contract of the bounded pproxy adapter is maintained at python/compat/pproxy_api_contract.json. The exact upstream installed-package inventory is maintained separately in compat/pproxy-2.7.9/namespace-baseline.json and the active parity manifest. Use scripts/pproxy_surface_probe.py with isolated oracle and wheel interpreters to compare module names, top-level exports, tracked signatures, async classification, and class bases. Importability is not a claim that private pproxy internals are functionally reproduced.

Classification summary

Tier	Count	Examples
adapted_target	3	Connection, Server, Rule → PPProxyService
intentional_non_parity	1	DIRECT sentinel
internal_observed	87	Protocol classes, cipher classes, server internals

Validation

# Regenerate the contract
python3.11 python/compat/extract_api.py

# Run 56 contract validation tests
python3.11 -m pytest tests/compat/test_pproxy_api_contract.py -v

# Run 46 behavioral probes
python3.11 python/compat/behavioral_probes.py

Namespace strategy

The optional eggress-pproxy-compat distribution installs a bounded top-level pproxy package containing the documented connection/server factories and protocol/cipher submodules. The canonical eggress distribution retains eggress.pproxy and eggress.start_pproxy() for translation and managed-service workflows. Do not install the compatibility distribution alongside upstream pproxy in the same environment. See docs/python/PPROXY_NAMESPACE_STRATEGY.md for the compatibility boundary.

Migrating from pproxy

from eggress import start_pproxy

# Same arguments you'd pass to pproxy
with start_pproxy(["-l", "socks5://:1080", "-r", "http://proxy:8080"]) as handle:
    print(handle.bound_addresses)

Or inspect the translation first:

from eggress import translate_pproxy_args

result = translate_pproxy_args(["-l", "socks5://:1080", "-r", "http://proxy:8080"])
print(result.toml)         # generated eggress TOML
print(result.warnings)     # partial-behavior notes
print(result.unsupported)  # unsupported features

Error model

Exception	Meaning
`EggressError`	Base exception
`ConfigError`	TOML parsing or validation error
`StartupError`	Listener bind or readiness timeout
`ReloadError`	Config reload failure
`ShutdownError`	Runtime shutdown error
`UnsupportedFeatureError`	Feature not supported
`InternalError`	Unexpected internal error

Limitations

GIL is released for blocking Rust calls
Requires Python >= 3.9
Listener bind changes require restart (not reloadable)
No logging initialization unless configured in TOML

Non-parity with pproxy

Shadowsocks TCP uses standard SIP003 AEAD framing (wire-compatible with shadowsocks-rust/ssserver/sslocal); single-hop upstream only
No inbound Shadowsocks or Trojan listeners (upstream-only) — inbound Shadowsocks listener is available in the Rust binary; Python bindings expose the embed API which omits this for now
No legacy stream ciphers (aes-ctr, aes-cfb, rc4-md5, etc.)
No SSH, Unix socket, or transparent proxy (redir) transport
No pproxy daemon mode (--daemon)
No -ul/-ur standalone UDP relay (uses SOCKS5 UDP ASSOCIATE)
Multiple remotes default to round-robin (matches pproxy behavior)
Direct fallback requires explicit config

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

eggress-1.0.6.tar.gz (1.0 MB view details)

Uploaded Sep 12, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

eggress-1.0.6-cp39-abi3-win_amd64.whl (5.6 MB view details)

Uploaded Sep 12, 2026 CPython 3.9+Windows x86-64

eggress-1.0.6-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.6 MB view details)

Uploaded Sep 12, 2026 CPython 3.9+manylinux: glibc 2.17+ x86-64

eggress-1.0.6-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.2 MB view details)

Uploaded Sep 12, 2026 CPython 3.9+manylinux: glibc 2.17+ ARM64

eggress-1.0.6-cp39-abi3-macosx_11_0_arm64.whl (5.0 MB view details)

Uploaded Sep 12, 2026 CPython 3.9+macOS 11.0+ ARM64

eggress-1.0.6-cp39-abi3-macosx_10_12_x86_64.whl (5.3 MB view details)

Uploaded Sep 12, 2026 CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file eggress-1.0.6.tar.gz.

File metadata

Download URL: eggress-1.0.6.tar.gz
Upload date: Sep 12, 2026
Size: 1.0 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for eggress-1.0.6.tar.gz
Algorithm	Hash digest
SHA256	`0e5f5a10581cc7ea6cc0984d62a049234416799e62a1464cb39271a723fc508e`
MD5	`e972a22f80b4015000fd0fe7004edb5d`
BLAKE2b-256	`f80a217cae9ecc0edd24493b4edbac20a14f638634d9c8aa2b9ab3c5ed2507d0`

See more details on using hashes here.

Provenance

The following attestation bundles were made for eggress-1.0.6.tar.gz:

Publisher: publish-python.yml on eggstack/eggress

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: eggress-1.0.6.tar.gz
- Subject digest: 0e5f5a10581cc7ea6cc0984d62a049234416799e62a1464cb39271a723fc508e
- Sigstore transparency entry: 2801328961
- Sigstore integration time: Sep 12, 2026
Source repository:
- Permalink: eggstack/eggress@5e2268d663667bad74f309c959bcb755effaac22
- Branch / Tag: refs/tags/v1.0.6
- Owner: https://github.com/eggstack
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-python.yml@5e2268d663667bad74f309c959bcb755effaac22
- Trigger Event: push

File details

Details for the file eggress-1.0.6-cp39-abi3-win_amd64.whl.

File metadata

Download URL: eggress-1.0.6-cp39-abi3-win_amd64.whl
Upload date: Sep 12, 2026
Size: 5.6 MB
Tags: CPython 3.9+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for eggress-1.0.6-cp39-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`1dcf064aa7de08d2a84aac0d7b6c5243008be1d13b43d0f312800ce02d8aead7`
MD5	`2345f8e53471478b4341c0f4874eb7a8`
BLAKE2b-256	`ea1a0a02dd5ff8e4cb0f68c7813be10350d7d7bb515146511a97985fe362a59a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for eggress-1.0.6-cp39-abi3-win_amd64.whl:

Publisher: publish-python.yml on eggstack/eggress

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: eggress-1.0.6-cp39-abi3-win_amd64.whl
- Subject digest: 1dcf064aa7de08d2a84aac0d7b6c5243008be1d13b43d0f312800ce02d8aead7
- Sigstore transparency entry: 2801329202
- Sigstore integration time: Sep 12, 2026
Source repository:
- Permalink: eggstack/eggress@5e2268d663667bad74f309c959bcb755effaac22
- Branch / Tag: refs/tags/v1.0.6
- Owner: https://github.com/eggstack
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-python.yml@5e2268d663667bad74f309c959bcb755effaac22
- Trigger Event: push

File details

Details for the file eggress-1.0.6-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: eggress-1.0.6-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Sep 12, 2026
Size: 5.6 MB
Tags: CPython 3.9+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for eggress-1.0.6-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`a9f0ebc81ad5327aa09add7e1932f813106f7106752ae88ac7098f66dc696e22`
MD5	`d8fa512b56a8ec8ea3d2641c4b96f7a5`
BLAKE2b-256	`c98f34ae3c246db8a9a7d75fe78c7d60c3c4c5034b3ac6af8294938b4ce41006`

See more details on using hashes here.

Provenance

The following attestation bundles were made for eggress-1.0.6-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-python.yml on eggstack/eggress

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: eggress-1.0.6-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: a9f0ebc81ad5327aa09add7e1932f813106f7106752ae88ac7098f66dc696e22
- Sigstore transparency entry: 2801329803
- Sigstore integration time: Sep 12, 2026
Source repository:
- Permalink: eggstack/eggress@5e2268d663667bad74f309c959bcb755effaac22
- Branch / Tag: refs/tags/v1.0.6
- Owner: https://github.com/eggstack
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-python.yml@5e2268d663667bad74f309c959bcb755effaac22
- Trigger Event: push

File details

Details for the file eggress-1.0.6-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: eggress-1.0.6-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Sep 12, 2026
Size: 5.2 MB
Tags: CPython 3.9+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for eggress-1.0.6-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`dcab70363780df2e54e45799034242eaa6d2594b961c33f95f0433f1e9e03fd6`
MD5	`3b5067cad2cad5281d2ea36e2d313bcf`
BLAKE2b-256	`dc054bfb22ab8b1a9b93c88db024b342b9effb1e78a28efd066d1b1d758c1015`

See more details on using hashes here.

Provenance

The following attestation bundles were made for eggress-1.0.6-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-python.yml on eggstack/eggress

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: eggress-1.0.6-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: dcab70363780df2e54e45799034242eaa6d2594b961c33f95f0433f1e9e03fd6
- Sigstore transparency entry: 2801329319
- Sigstore integration time: Sep 12, 2026
Source repository:
- Permalink: eggstack/eggress@5e2268d663667bad74f309c959bcb755effaac22
- Branch / Tag: refs/tags/v1.0.6
- Owner: https://github.com/eggstack
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-python.yml@5e2268d663667bad74f309c959bcb755effaac22
- Trigger Event: push

File details

Details for the file eggress-1.0.6-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: eggress-1.0.6-cp39-abi3-macosx_11_0_arm64.whl
Upload date: Sep 12, 2026
Size: 5.0 MB
Tags: CPython 3.9+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for eggress-1.0.6-cp39-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`8d8cdece4a8ddee28ecf483a6e56193fe2038f2c7d9ec2f273f385ae26cc9ea3`
MD5	`c696bf06b98a9b606aae405e4ee13759`
BLAKE2b-256	`0c4c02aabc65b31c11ec6063b26020a1ade6500ec5affb6072ebf207bc3b0d56`

See more details on using hashes here.

Provenance

The following attestation bundles were made for eggress-1.0.6-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: publish-python.yml on eggstack/eggress

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: eggress-1.0.6-cp39-abi3-macosx_11_0_arm64.whl
- Subject digest: 8d8cdece4a8ddee28ecf483a6e56193fe2038f2c7d9ec2f273f385ae26cc9ea3
- Sigstore transparency entry: 2801330024
- Sigstore integration time: Sep 12, 2026
Source repository:
- Permalink: eggstack/eggress@5e2268d663667bad74f309c959bcb755effaac22
- Branch / Tag: refs/tags/v1.0.6
- Owner: https://github.com/eggstack
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-python.yml@5e2268d663667bad74f309c959bcb755effaac22
- Trigger Event: push

File details

Details for the file eggress-1.0.6-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: eggress-1.0.6-cp39-abi3-macosx_10_12_x86_64.whl
Upload date: Sep 12, 2026
Size: 5.3 MB
Tags: CPython 3.9+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for eggress-1.0.6-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`2b5367d4325ee8ca68e9c7a81bbc0ea679dd54357da18b6978f482f8c0e6dc31`
MD5	`8f91eb3fd0f399fd4e757a79ecf5e865`
BLAKE2b-256	`af432f48336e2161e3e72d45d9af9ef17fdedae4c75a3bfb912ebda7c72c87de`

See more details on using hashes here.

Provenance

The following attestation bundles were made for eggress-1.0.6-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: publish-python.yml on eggstack/eggress

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: eggress-1.0.6-cp39-abi3-macosx_10_12_x86_64.whl
- Subject digest: 2b5367d4325ee8ca68e9c7a81bbc0ea679dd54357da18b6978f482f8c0e6dc31
- Sigstore transparency entry: 2801329530
- Sigstore integration time: Sep 12, 2026
Source repository:
- Permalink: eggstack/eggress@5e2268d663667bad74f309c959bcb755effaac22
- Branch / Tag: refs/tags/v1.0.6
- Owner: https://github.com/eggstack
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-python.yml@5e2268d663667bad74f309c959bcb755effaac22
- Trigger Event: push

Release history Release notifications | RSS feed

This release

1.0.6 This release

Sep 12, 2026 6 files

1.0.5

Sep 12, 2026 6 files

1.0.4

Sep 4, 2026 6 files

1.0.1

Jul 29, 2026 1 file

eggress 1.0.6

eggress Python bindings

Installation (local development)

Prebuilt wheels

Quick start

Async usage

API

pproxy Compatibility

pproxy drop-in API

API Contract (Phase C1)

Classification summary

Validation

Namespace strategy

Migrating from pproxy

Error model

Limitations

Non-parity with pproxy

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed