Skip to main content

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

Distinguish runtime capability, service-facade exposure, and dedicated Python convenience API (see docs/PYTHON_BINDINGS.md and architecture/python-bindings.md):

  • Shadowsocks TCP uses standard SIP003 AEAD framing (wire-compatible with shadowsocks-rust/ssserver/sslocal); multi-hop TCP chains and UDP through composed SOCKS5/Shadowsocks hop chains are supported (see docs/CAPABILITIES.md)
  • Generic RuntimeConfig/EggressConfig::from_toml supports Shadowsocks/Trojan listener sections; Python convenience paths focus on SOCKS5/HTTP inbound plus TCP/UDP upstream Shadowsocks in the current release
  • Legacy stream ciphers (aes-ctr, aes-cfb, rc4-md5, etc.) behind opt-in legacy-crypto (compatibility-only)
  • SSH upstreams behind opt-in ssh (upstream-only); Unix-domain listeners supported by the runtime (UnixListenerConfig, configure via TOML/EggressConfig); transparent redir:// supported on Linux
  • Linux pproxy daemon mode (--daemon) behind opt-in pproxy-daemon
  • Standalone UDP relay (-ul, mode standalone_pproxy_udp) supported
  • Multiple remotes default to round-robin (matches pproxy behavior)
  • Direct fallback requires explicit config

Metadata

Release files for eggress 1.0.11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for eggress 1.0.11
File Size Uploaded Provenance Actions
eggress-1.0.11.tar.gz 1.1 MB With provenance Details for eggress-1.0.11.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for eggress 1.0.11
File Actions
eggress-1.0.11-cp39-abi3-win_arm64.whl CPython 3.9 abi3 Windows ARM64 Details for eggress-1.0.11-cp39-abi3-win_arm64.whl
eggress-1.0.11-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for eggress-1.0.11-cp39-abi3-win_amd64.whl
eggress-1.0.11-cp39-abi3-musllinux_1_2_x86_64.whl CPython 3.9 abi3 Linux musl 1.2+ x86-64 Details for eggress-1.0.11-cp39-abi3-musllinux_1_2_x86_64.whl
eggress-1.0.11-cp39-abi3-musllinux_1_2_armv7l.whl CPython 3.9 abi3 Linux musl 1.2+ ARMv7l Details for eggress-1.0.11-cp39-abi3-musllinux_1_2_armv7l.whl
eggress-1.0.11-cp39-abi3-musllinux_1_2_aarch64.whl CPython 3.9 abi3 Linux musl 1.2+ ARM64 Details for eggress-1.0.11-cp39-abi3-musllinux_1_2_aarch64.whl
eggress-1.0.11-cp39-abi3-manylinux_2_28_armv7l.whl CPython 3.9 abi3 Linux glibc 2.28+ ARMv7l Details for eggress-1.0.11-cp39-abi3-manylinux_2_28_armv7l.whl
eggress-1.0.11-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for eggress-1.0.11-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
eggress-1.0.11-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for eggress-1.0.11-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
eggress-1.0.11-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for eggress-1.0.11-cp39-abi3-macosx_11_0_arm64.whl
eggress-1.0.11-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for eggress-1.0.11-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 52.7 MB

Release files / eggress-1.0.11.tar.gz

Download URL eggress-1.0.11.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
f3cef956a125be3611878969cbfc4e7bb11cbdca29e6cd786c2e68f668cea357
BLAKE2b-256 checksum
How to use checksums
0b43adafa055d457883aee600600ae03d31e342a00afd29969fbe19c84852575
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-win_arm64.whl

Download URL eggress-1.0.11-cp39-abi3-win_arm64.whl
Size 5.1 MB
Tags CPython 3.9 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
051be9ca9520b7cff667d279417649a6ec8da619bf164b238c1d0d1b128086f5
BLAKE2b-256 checksum
How to use checksums
7e9854b6ffc214448b1a3bb38a9cc15d54c21a84b7259a862205d0e9ddd47b5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-win_amd64.whl

Download URL eggress-1.0.11-cp39-abi3-win_amd64.whl
Size 5.5 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
497a570ae8c9dab86c36339be9ada7de35e8835a56baa17fa1059092fd7e1a39
BLAKE2b-256 checksum
How to use checksums
cdf90ca58888be1635ad2c10babcb92189b308e86294be3daf114836972c4461
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-musllinux_1_2_x86_64.whl

Download URL eggress-1.0.11-cp39-abi3-musllinux_1_2_x86_64.whl
Size 5.6 MB
Tags CPython 3.9 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
9fa9b9ce8004757396ee4d658c2e6e4723485be3ae0657e91ba735d16dc1ccdb
BLAKE2b-256 checksum
How to use checksums
32e15d1e6a1ee2d05d9e46b86260f99b824a3251415343307dc54cbbbece11ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-musllinux_1_2_armv7l.whl

Download URL eggress-1.0.11-cp39-abi3-musllinux_1_2_armv7l.whl
Size 5.1 MB
Tags CPython 3.9 Linux musl 1.2+ ARMv7l abi3
SHA-256 checksum
How to use checksums
9d4e0c1e3ccd635a59d3948d7613361e18bfb80f2d7cb7fc78c03907791edb8b
BLAKE2b-256 checksum
How to use checksums
d310944aef23070da83d691facfe5de63a5044bc2a19cdcd246e41a3e68d1cbc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-musllinux_1_2_aarch64.whl

Download URL eggress-1.0.11-cp39-abi3-musllinux_1_2_aarch64.whl
Size 5.2 MB
Tags CPython 3.9 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
ae2a81ebe39716e1f0727b86e64d4e4e45c6d3bf0663949ed0c0ed2944188d44
BLAKE2b-256 checksum
How to use checksums
dd5a7b9b8eb7b75c0e89e31f35def4c0d54585fd75514c3038fb3b8b4a265246
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-manylinux_2_28_armv7l.whl

Download URL eggress-1.0.11-cp39-abi3-manylinux_2_28_armv7l.whl
Size 4.9 MB
Tags CPython 3.9 Linux glibc 2.28+ ARMv7l abi3
SHA-256 checksum
How to use checksums
71261a1a679f3042804444800767ecc3c0bbe736f612d14d736ba19c05f92791
BLAKE2b-256 checksum
How to use checksums
579cee82497353f4d952cceb69904ac283c24a28ef728fb05d1c9fa6e763fe6f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL eggress-1.0.11-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 5.4 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
c82311d1f5f9cb9848e9ed0a759665ad43c2efb08e1f9699c4f3cb57591a7147
BLAKE2b-256 checksum
How to use checksums
dc9939bbf5dd1957dc1573b6f6940a8841e2dda22f6b6408100c46879ff6dac8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL eggress-1.0.11-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 5.1 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
b43e62c45ba212c39e9acd23c60d751c5b9b61b52d7f645c66b4126eaabbe3b2
BLAKE2b-256 checksum
How to use checksums
9def34ed8e069b7ea45c33300c28477cd0d47b3c71b585ba6f6f27eec6f25590
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-macosx_11_0_arm64.whl

Download URL eggress-1.0.11-cp39-abi3-macosx_11_0_arm64.whl
Size 4.8 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c978b172223559675c2deb6b67cd336f91889d4f81279b5bf4fb01e0e0db6e43
BLAKE2b-256 checksum
How to use checksums
03249e6309f78a22b753364258d070a23611027c84fcbbd82b7c8309b7063ac9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / eggress-1.0.11-cp39-abi3-macosx_10_12_x86_64.whl

Download URL eggress-1.0.11-cp39-abi3-macosx_10_12_x86_64.whl
Size 5.1 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
88daf5a4350d7d19685a90f95551f5b1971eb3a7a403d6cf1d267031a7f64775
BLAKE2b-256 checksum
How to use checksums
8d06525298a2f58814a2cd3bc60fb7c9cd962737d5a3c3ec226ed878883c7d56
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Security for eggress 1.0.11

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 11 files in this release have been uploaded with provenance metadata.

Select from 11 files

Attestation for eggress-1.0.11.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page