Python bindings for enry
Python bindings through cFFI (ABI, out-of-line) for calling enry Go functions exposed by CGo wrapper.
Build
# from python/
python -m pip install -e .
The editable install builds the Go shared library and CFFI bindings automatically.
Build requirements and runtime dependencies come from pyproject.toml.
Why a shared library?
Historically, the Python package shipped a static library and used CFFI API mode (a compiled extension that links against libenry).
That approach relied on Go-generated headers/types (e.g. GoString, GoSlice, and struct return wrappers) and a locally-built archive at build time, which made builds and cross-platform packaging more fragile.
We now build a Go-built shared library (-buildmode=c-shared) that is bundled inside the wheel and loaded via CFFI out-of-line (ABI) mode.
This makes installation simpler and allows pip install enry-python without requiring a Go toolchain. Source builds require Go and a C compiler; the sdist bundles its Go sources under _go/.
Implementation note: the shared library is located and loaded at import time in enry/definitions.py (see _load_library()), which prefers the packaged enry/libenry.* shipped in wheels and falls back to local dev build locations.
Future-proof note: if we later change the binding strategy (or revisit linking/packaging), we should reevaluate whether a shared library is still the best tradeoff and update this documentation accordingly.
Installation
From PyPI (Recommended)
For Python 3.12+, install pre-built wheels:
pip install enry-python
No Go compiler required! Pre-built wheels are available for:
- Linux: x86_64 (manylinux)
- macOS 12+: x86_64 (Intel) and arm64 (Apple Silicon)
From Source
If you need to build from source or use an unsupported platform, you'll need Go installed:
git clone https://github.com/Esoiya/go-enry.git
cd go-enry
cd python
pip install -e .
Requirements for building:
- Go 1.26.x (used by release CI)
- GCC or compatible C compiler
- Python 3.12 or later
Developer: publishing to PyPI
Releases are published by the tagged wheel workflow using PyPI Trusted Publishing (OIDC).
Note: CI publishing via OIDC is gated on PyPI Trusted Publisher configuration for the enry-python project (must be set up by a PyPI project owner/maintainer for this repo/workflow).
Until that is configured, you can publish manually using a PyPI API token.
Versioning
The package version is derived by setuptools-scm from python-vX.Y.Z tags;
there is no version number to edit in pyproject.toml. For example, tagging
python-v0.3.0 builds version 0.3.0. Go's v* tags are ignored. Untagged
commits receive development versions and do not trigger publication.
Automated releases
The Prepare Python Release workflow runs after pushes to master. Release
Please opens or updates a release PR with the next version and changelog.
Review and merge that PR when ready to publish: the workflow then creates the
python-vX.Y.Z tag and GitHub release, and explicitly starts Build Python
Wheels at that tag. All wheel and source tests must pass before PyPI upload.
The first proposed release after adopting this workflow is python-v0.3.0.
Use conventional commit titles when merging changes:
fix(python): ...requests a patch release.feat(python): ...requests a minor release.feat(python)!: ...or aBREAKING CHANGE:footer requests a breaking release; before 1.0 this increments the minor version, and from 1.0 it increments major.docs,choreand other non-release types do not request a release themselves.
For squash merges, put the conventional title and any breaking-change footer in the squash commit. Review the proposed version before merging the release PR.
.github/.release-please-manifest.json records the last released version for
Release Please; the bot updates it. It is not the Python package's version source.
The root package configuration includes Go detector and native binding changes.
The migration boundary (last-release-sha) starts the first changelog at the
Python refresh, excluding imported upstream history; later releases stop at
their own release commits.
The Go release strategy writes only the changelog, leaving setuptools-scm to
supply Python metadata from the tag. CI verifies artifact versions against that
tag, and sdists retain their version when rebuilt without Git.
The workflow uses the built-in GITHUB_TOKEN, with no personal access token.
Enable Allow GitHub Actions to create and approve pull requests in the
repository's Actions settings. Bot-created PRs and tags do not trigger normal
PR/push workflows with this token; the explicit wheel workflow dispatch handles
release validation. If branch rules require PR checks, provide those checks
before merging (for example, by using a GitHub App token for Release Please).
Do not bypass required checks. This repository's automation does not configure
an App or bypass branch protection.
If the dispatch job fails, rerun that failed job. To retry the complete tagged build, run:
gh workflow run python-wheels.yml --repo Esoiya/go-enry --ref python-vX.Y.Z
This command can publish to PyPI once tests pass. Reuse the existing tag when retrying a failed build; never move a published tag. A GitHub release indicates tag creation, not successful PyPI publication—check Build Python Wheels. Build from a Git clone or published sdist; unversioned source copies are unsupported.
Manual fallback: upload CI-built artifacts
This mirrors what the CI does (cibuildwheel builds platform wheels + an sdist). You simply upload the produced artifacts yourself.
- Prefer merging the automated release PR. If automation is unavailable, create an unused release tag manually (this triggers the workflow):
git tag python-vX.Y.Z
git push origin python-vX.Y.Z
- Download the workflow artifacts from GitHub Actions:
- the built wheels (wheels-*)
- the source distribution (sdist)
- Upload with Twine using a PyPI token:
python -m pip install --upgrade twine
# from the directory where you downloaded artifacts:
TWINE_USERNAME=__token__ TWINE_PASSWORD='pypi-***' python -m twine upload **/*.whl **/*.tar.gz
Notes:
- The token must be created on PyPI by an account with upload permission for the enry-python project.
- This approach is preferred because wheels must be built per-platform/per-arch (Linux manylinux + macOS x86_64/arm64).
- PyPI token notes: set username to token and password to the token value (including the pypi- prefix).
Manual publish (local, single-platform only)
For a local validation build, use the default build command: it creates an sdist, then builds the wheel from that archive. Native build failures abort packaging.
# from repo root
cd python
python -m pip install --upgrade pip
python -m pip install --group ci
python -m build
TWINE_USERNAME=__token__ TWINE_PASSWORD='pypi-***' python -m twine upload dist/*
This requires Go locally and only produces a wheel for the current OS/arch.
Development dependencies
python/pyproject.toml is the source of truth: [build-system].requires supplies
isolated build environments, [project].dependencies supplies runtime packages,
and [dependency-groups] defines test and ci tools. Requirements files are
no longer needed. CFFI is declared for both build and runtime because both use it.
# from python/; dependency groups require pip 25.1 or later
python -m pip install --upgrade pip
python -m pip install --group test -e .
python -m pytest tests -q
python -m pip install --group ci
python -m unittest discover -s packaging_tests -v
The workflows use these same groups; cibuildwheel reads test-groups directly.
The SHA-pinned cibuildwheel action owns its tool version, updated by Dependabot,
so there is no second cibuildwheel pin in a requirements file. Runner operating
systems and Go versions remain workflow settings.
Usage
import enry
# Detect language by filename and content
language = enry.get_language("example.py", b"print('Hello, world!')")
print(f"Detected language: {language}")
FFI / API design notes
The Python get_language_by_* functions return Guess(language, safe).
safe is true only when Go reports an unambiguous result. The shared library
provides additive ...WithSafety(..., int* out_safe) exports; the original
string-only exports remain available for existing C consumers. Returned strings
and string arrays are freed by the bindings, including when decoding fails.
Supported Python Versions
- Python 3.12+
- CPython only (PyPy not yet supported)
Python 3.12 remains the minimum in requires-python. Release CI builds and tests
all stable standard (GIL-enabled) CPython versions supported by its pinned
cibuildwheel release and satisfying that minimum (currently 3.12–3.14).
New versions are selected automatically when supported by an updated
cibuildwheel action; Dependabot proposes these updates, which still need to be
merged. There is no per-version wheel list to maintain. A new Python release
does not itself trigger a PyPI upload: merge the next release PR to publish
a new enry release with the expanded wheel set. If a tooling update needs a
release, use a fix(python): ... commit describing the newly supported wheels.
Python 3.11 and older, prerelease interpreters, free-threaded CPython and PyPy are outside the tested support matrix. Wheels do not upgrade the user's Python installation, and the minimum version is never raised automatically. Older Python installations must use an older compatible enry release.
Platform Support
- ✅ Linux (x86_64)
- ✅ macOS 12+ (Intel x86_64 and Apple Silicon arm64)
- ❌ Linux ARM/aarch64 (not yet available)
Known Issues
- Memory leak fixed in version 0.2.0 (see #36)
- Java bindings still target an older shared-library ABI and need a separate migration.
Run
Example for single exposed API function is provided.
$ python enry.py
TODOs
- helpers for sending/receiving Go slices to C
- read
libenry.hand generateffibuilder.cdef(...)content - cover the rest of enry API
- add
setup.py - build/release automation on CI (publish on pypi)
- try ABI mode, to avoid dependency on C compiler on install (+perf test?)
Metadata
Release files for enry-python 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| enry_python-0.3.0.tar.gz | 1.9 MB | With provenance | Details for enry_python-0.3.0.tar.gz |
Built distributions (wheels)
Total release size: 35.5 MB
Release files / enry_python-0.3.0.tar.gz
| Download URL | enry_python-0.3.0.tar.gz |
|---|---|
| Size | 1.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9708db7c83460cab0b89d0cfceab082ccde097b93d9c26c623d801505064b82a
|
|
BLAKE2b-256 checksum How to use checksums |
a020c17204395b41d28f4d053927171597c1deb63756ca19aaeef6a8589e2b6e
|
| 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 1, 2026.
Transparency logRelease files / enry_python-0.3.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | enry_python-0.3.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 5.1 MB |
| Tags | CPython 3.14 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
e1671d54782483201b917bc5d2f2be31e80bfecad796d17923e89cc72f0539c1
|
|
BLAKE2b-256 checksum How to use checksums |
38e438a72e5aeb828db327064c5ef4adca41dc2d6c9494da7bce6e44419d9240
|
| 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 1, 2026.
Transparency logRelease files / enry_python-0.3.0-cp314-cp314-macosx_12_0_x86_64.whl
| Download URL | enry_python-0.3.0-cp314-cp314-macosx_12_0_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.14 macOS 12.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
e198224ee26796d7cc3e4a3e41610413e2a1591c6bb04bad2156d3ec1279680f
|
|
BLAKE2b-256 checksum How to use checksums |
69651e411c8ca8f445b8bf493cda41e7660594bfcf8f21c2405b98e5242facf5
|
| 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 1, 2026.
Transparency logRelease files / enry_python-0.3.0-cp314-cp314-macosx_12_0_arm64.whl
| Download URL | enry_python-0.3.0-cp314-cp314-macosx_12_0_arm64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.14 macOS 12.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ec426be7c84b55b38df7cba3396b1af6f42d61ad695077d5f0cb91727576d4d4
|
|
BLAKE2b-256 checksum How to use checksums |
e984e102ae58cff0945f89310554eaa05dd92b55a16363d2895c32a35a2e2346
|
| 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 1, 2026.
Transparency logRelease files / enry_python-0.3.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | enry_python-0.3.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 5.1 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
acb15dd037b538a897b6eb4495293a0dc360293e75f7400e895f0f64a93a9618
|
|
BLAKE2b-256 checksum How to use checksums |
4d5eb6463f64cd3d154e3ce651b894ce46792b180e435811cbeb3e555c877b29
|
| 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 1, 2026.
Transparency logRelease files / enry_python-0.3.0-cp313-cp313-macosx_12_0_x86_64.whl
| Download URL | enry_python-0.3.0-cp313-cp313-macosx_12_0_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.13 macOS 12.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
ab1ef29210c7646237281d45eb30a9a163a94050e686c408d9bb30797c646eb6
|
|
BLAKE2b-256 checksum How to use checksums |
3ef3be4029a15a5b531c0c9dd08f6236a6530f2e4c8c7b6d33cbad772bb07777
|
| 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 1, 2026.
Transparency logRelease files / enry_python-0.3.0-cp313-cp313-macosx_12_0_arm64.whl
| Download URL | enry_python-0.3.0-cp313-cp313-macosx_12_0_arm64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.13 macOS 12.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a967b2ee13bee97e546ab65269c3a6db42e925d70dc0e9bad40ddcc3c9febaa6
|
|
BLAKE2b-256 checksum How to use checksums |
ac1d07e52bd29b32ecca47e43c351230c321ecdd4b1adf6a73b77ee984da6620
|
| 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 1, 2026.
Transparency logRelease files / enry_python-0.3.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | enry_python-0.3.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 5.1 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
121a0f7865bb1f02791335efb7abdc0f7f66ee65ec68bb21d6e10741721253bd
|
|
BLAKE2b-256 checksum How to use checksums |
c1361e5e4781e813b9bcfa4ad75b4f884f9bd72ea24b5842ed1d055fdd9bedf4
|
| 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 1, 2026.
Transparency logRelease files / enry_python-0.3.0-cp312-cp312-macosx_12_0_x86_64.whl
| Download URL | enry_python-0.3.0-cp312-cp312-macosx_12_0_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.12 macOS 12.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
32e58c72bbdfc791b8fc318d4e583bece36a21fdddfd68ffb54c3286de2c2428
|
|
BLAKE2b-256 checksum How to use checksums |
cfad4dd8c4437b1cb446e75cf7fd07ca13eaadf55361b9ab1e9c15b076f23d77
|
| 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 1, 2026.
Transparency logRelease files / enry_python-0.3.0-cp312-cp312-macosx_12_0_arm64.whl
| Download URL | enry_python-0.3.0-cp312-cp312-macosx_12_0_arm64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.12 macOS 12.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
dbe4d87df577b1f9e6713d6eef89be3c998b03c853f1ec99f4d0616ba770debf
|
|
BLAKE2b-256 checksum How to use checksums |
9c198a4d54a1cf48462fc4613b89568311109f0d0551ea60ae1b7f5bd55142ad
|
| 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 1, 2026.
Transparency logSecurity for enry-python 0.3.0
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 10 files in this release have been uploaded with provenance metadata.
Attestation for enry_python-0.3.0.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 1, 2026.
Transparency logA 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.