CodecCat
Detect the encoding. Read the text.
A Python library for opening text when you don't know its character encoding.
Install
Download the wheel for your operating system from CodecCat v0.1.0, then install it:
python -m pip install ./codeccat-0.1.0-*.whl
Supports Python 3.10+ on Linux, macOS and Windows. On Windows, use the exact downloaded wheel filename instead of the * wildcard. Native detection doesn't require NumPy or scikit-learn. GitHub Wheels; PyPI publishing is a separate distribution step.
Use it
import codeccat
data = "こんにちは".encode("shift_jis")
result = codeccat.detect(data)
print(result.encoding) # detected encoding
print(result.text) # decoded text
Only need the text? Use codeccat.decode(data).
From the command line:
codeccat file.txt
codeccat --decode file.txt > readable.txt
Comparison
CodecCat v0.1.0 stable candidate, using the same frozen model and decoder code as the verified v0.1.0a5 baseline, compared with chardet and charset-normalizer on the same 843 text samples across five fixed test sets (Ubuntu 24.04 / Python 3.12).
| CodecCat | chardet | charset-normalizer | |
|---|---|---|---|
| Correctly decoded text | 97.98% | 98.34% | 82.80% |
| Exact encoding name | 93.36% | 84.46% | 69.16% |
| Total CPU time | 660 ms | 861 ms | 1,073 ms |
| Typical latency (p50 range) | 0.78–0.89 ms | 0.46–0.75 ms | 0.74–1.02 ms |
| Slower-case latency (p95 range) | 1.20–1.32 ms | 2.69–3.01 ms | 3.10–4.64 ms |
| Peak RAM (range) | 66–69 MiB | 61–64 MiB | 40–44 MiB |
chardet still decoded slightly more of these samples correctly. CodecCat used less measured CPU time and had lower p95 latency, but used more RAM.
Limits: These test sets include model training and development sources; 97.98% is not a general real-world accuracy estimate. CPU and timing values come from one hosted CI run. A separately pinned GNOME Software source showed 198/225 → 216/225 correct decodes versus v0.1.0a4, using the identical model and with no observed regressions. Full methods and caveats.
Notes
Public API compatibility contract: the 0.1.x stable line preserves the documented public calls and result fields. Encoding inference remains probabilistic and is not guaranteed for arbitrary bytes.
Encoding isn't always identifiable from bytes alone. Check result.ambiguous when the exact encoding matters. Decoding is strict: invalid text is not silently replaced. CodecCat v0.1.0 is a stable release.
Releases · Issues · Benchmarks · MIT License · Rights inquiries
1 maintainer
Metadata
1 maintainer
Release files for codeccat 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| codeccat-0.1.0-cp310-abi3-win_arm64.whl | CPython 3.10 | abi3 | Windows ARM64 | Details for codeccat-0.1.0-cp310-abi3-win_arm64.whl |
| codeccat-0.1.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details for codeccat-0.1.0-cp310-abi3-win_amd64.whl |
| codeccat-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ x86-64 | Details for codeccat-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl |
| codeccat-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ ARM64 | Details for codeccat-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl |
| codeccat-0.1.0-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details for codeccat-0.1.0-cp310-abi3-macosx_11_0_arm64.whl |
| codeccat-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details for codeccat-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl |
Total release size: 45.7 MB
Release files / codeccat-0.1.0-cp310-abi3-win_arm64.whl
| Download URL | codeccat-0.1.0-cp310-abi3-win_arm64.whl |
|---|---|
| Size | 7.5 MB |
| Tags | CPython 3.10 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
60e81680a88c35f1284171efee65737d3d0257e4a4a0bba167fc37c895ea246c
|
|
BLAKE2b-256 checksum How to use checksums |
8f2d351242b3181a7b5d010ab68e88770f99d5ead04d242f1591b026677f4788
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 6, 2026.
Transparency logRelease files / codeccat-0.1.0-cp310-abi3-win_amd64.whl
| Download URL | codeccat-0.1.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 7.6 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
5411cd96359b4c36298de0917ec296b157ecf927165b02175aa2b7ad7edbf5d9
|
|
BLAKE2b-256 checksum How to use checksums |
f25cdf3161b02673a34d34df132c2b2f73f55e9d2d7c6e44583eea842efddf0e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 6, 2026.
Transparency logRelease files / codeccat-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl
| Download URL | codeccat-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 7.6 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
dd33b809e8203496f54dc3b5bc614371b051a68472904ef045a58f32b4f451d6
|
|
BLAKE2b-256 checksum How to use checksums |
93aba1429df1337722273f733e3e5021196635544a6477bee3640fef472454d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 6, 2026.
Transparency logRelease files / codeccat-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl
| Download URL | codeccat-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 7.6 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
47839b3f8e57fa8337532e6ba01055d54efca7770924e13aab63d0b65937a068
|
|
BLAKE2b-256 checksum How to use checksums |
8091cab8bd46b0f2cd57d1b49572681106a564f2783b99724b50e7a8a9e63d62
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 6, 2026.
Transparency logRelease files / codeccat-0.1.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | codeccat-0.1.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 7.6 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
414719b098bfad68cc3d692be78ac7f3e4dcf69979e22859df16b1aa61c75d8a
|
|
BLAKE2b-256 checksum How to use checksums |
158ce9a1912c958ea88691b86c9b0fe0f5f123fa8dd6eb83fe34e5cfbc69d117
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 6, 2026.
Transparency logRelease files / codeccat-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | codeccat-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 7.6 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
4088b22a329b7310d08d06481a85c15990f53d1b466dda067700942c699d5523
|
|
BLAKE2b-256 checksum How to use checksums |
86f17793c0c67b6ba2070b075dc17e63ea1dca24eeea62974a3c7a4023c12ff8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 6, 2026.
Transparency logSecurity for codeccat 0.1.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 6 files in this release have been uploaded with provenance metadata.
Attestation for codeccat-0.1.0-cp310-abi3-win_arm64.whl
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 Nov 6, 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.
