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.12

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.12
File Size Uploaded Provenance Actions
eggress-1.0.12.tar.gz 1.1 MB With provenance Details for eggress-1.0.12.tar.gz

Built distributions (wheels)

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

Total release size: 52.7 MB

Release files / eggress-1.0.12.tar.gz

Download URL eggress-1.0.12.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
007b2f81b20432f6c4b35516a36f723e051ceba621abc4c9ccaff7637b45f835
BLAKE2b-256 checksum
How to use checksums
7f137398aa1bcecd0d14c325d2429d64a9865e21ad484fb0eb96ed5fda793f30
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-cp39-abi3-win_arm64.whl
Size 5.1 MB
Tags CPython 3.9 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
5964458ee433142b712bb5bc7d3ba6649b5c99f5122ddac6ef790f8a4d65b7ae
BLAKE2b-256 checksum
How to use checksums
2f8437681e533627f685cf4eccd84bd24158d66bdf26c66b1a449d8abbda8f18
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-cp39-abi3-win_amd64.whl
Size 5.5 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
7aee614b7e5e52b33362096d2d4d4971599e5d14d2b806051407b8137e5537a3
BLAKE2b-256 checksum
How to use checksums
7eb6e0ad46a369c2d8c4362d8fca10c976175e82281db8e79d809a15701d75ab
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-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
d7a5837293d2359638209a258ff45145f20493f491f5f7aae504458feb0d55ea
BLAKE2b-256 checksum
How to use checksums
8e12f26355ebd7659866058b4f61a24c1ca7a29730ffb4e29967e33c47cda011
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-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
1aed50f0b7b033546107086c15c8170caef2444709b9da41ec36609bc1956586
BLAKE2b-256 checksum
How to use checksums
9f15c4f9accdd014781b5a67a074b9263c24d7bd148aa4db38d2206adcd4107e
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-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
24e634f335032de90effb04f086a3934150702149d041399de361ddde4c4f7b7
BLAKE2b-256 checksum
How to use checksums
0688da4e2d83f4951952ea19594e6780ebff40c4aebd8e84000b296104a3037f
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-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
a3d4b05830976195a71feaf523112e2c92ef92258c06befd3871173a82e75793
BLAKE2b-256 checksum
How to use checksums
298d117c4609d55bbff87342de99e3a84517f80761f4d647982cc43a805f9c39
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-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
60f501776956367119b00981f9c517be00f13a1db0f785d20b9620820d82d701
BLAKE2b-256 checksum
How to use checksums
0dc15ab5fa267fbdd573edb937dc36baccad53272253fbf1c81cb7779e2ee7bc
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-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
5de83519aabac17a95a857f2fa8c284f8dc0fcb75a25e9d6ca021cd8ae24e0a7
BLAKE2b-256 checksum
How to use checksums
690faca0ad9ce263fc85bfe1c9d93a6a484df061760adb6228e7b3bb7cfa3cca
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-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
9ec86434d2b8b0f04a8ea4ad36c3768d420fd30878f2d7328e7b8fa662752a8e
BLAKE2b-256 checksum
How to use checksums
fec25026e4aa83f23876271d18aecd36c96d28c724249351d8cc89be9c11ede6
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 Oct 8, 2026.

Transparency log

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

Download URL eggress-1.0.12-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
7352eb3420691953553b13d639e6eb42ba2cb2eab6b00b0a422986908a34747d
BLAKE2b-256 checksum
How to use checksums
66ecfb792e8742461db18e508fb21287ffdbcf76b144648ff62cd314d62a8581
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 Oct 8, 2026.

Transparency log

Security for eggress 1.0.12

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.12.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 Oct 8, 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