charset-normalizer
The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet.
Description
<p align="center"> >>>>> <a href="https://charsetnormalizerweb.ousret.now.sh" target="_blank">👉 Try Me Online Now, Then Adopt Me 👈 </a> <<<<< </p>A library that helps you read text from an unknown charset encoding.<br /> Motivated by
chardet, I'm trying to resolve the issue by taking a new approach. All IANA character set names for which the Python core library provides codecs are supported.
This project offers you an alternative to Universal Charset Encoding Detector, also known as Chardet.
| Feature | Chardet | Charset Normalizer | cChardet |
|---|---|---|---|
Fast | ❌ | ✅ | ✅ |
Universal** | ❌ | ✅ | ❌ |
Reliable without distinguishable standards | ❌ | ✅ | ✅ |
Reliable with distinguishable standards | ✅ | ✅ | ✅ |
License | LGPL-2.1<br>restrictive | MIT | MPL-1.1<br>restrictive |
Native Python | ✅ | ✅ | ❌ |
Detect spoken language | ❌ | ✅ | N/A |
UnicodeDecodeError Safety | ❌ | ✅ | ❌ |
Whl Size (min) | 193.6 kB | 42 kB | ~200 kB |
Supported Encoding | 33 | 🎉 99 | 40 |
** : They are clearly using specific code for a specific encoding even if covering most of used one<br>
⚡ Performance
This package offer better performance than its counterpart Chardet. Here are some numbers.
| Package | Accuracy | Mean per file (ms) | File per sec (est) |
|---|---|---|---|
| chardet | 86 % | 63 ms | 16 file/sec |
| charset-normalizer | 98 % | 10 ms | 100 file/sec |
| Package | 99th percentile | 95th percentile | 50th percentile |
|---|---|---|---|
| chardet | 265 ms | 71 ms | 7 ms |
| charset-normalizer | 100 ms | 50 ms | 5 ms |
updated as of december 2024 using CPython 3.12
Chardet's performance on larger file (1MB+) are very poor. Expect huge difference on large payload.
Stats are generated using 400+ files using default parameters. More details on used files, see GHA workflows. And yes, these results might change at any time. The dataset can be updated to include more files. The actual delays heavily depends on your CPU capabilities. The factors should remain the same. Keep in mind that the stats are generous and that Chardet accuracy vs our is measured using Chardet initial capability (e.g. Supported Encoding) Challenge-them if you want.
✨ Installation
Using pip:
pip install charset-normalizer -U
🚀 Basic Usage
CLI
This package comes with a CLI.
usage: normalizer [-h] [-v] [-a] [-n] [-m] [-r] [-f] [-t THRESHOLD]
file [file ...]
The Real First Universal Charset Detector. Discover originating encoding used
on text file. Normalize text to unicode.
positional arguments:
files File(s) to be analysed
optional arguments:
-h, --help show this help message and exit
-v, --verbose Display complementary information about file if any.
Stdout will contain logs about the detection process.
-a, --with-alternative
Output complementary possibilities if any. Top-level
JSON WILL be a list.
-n, --normalize Permit to normalize input file. If not set, program
does not write anything.
-m, --minimal Only output the charset detected to STDOUT. Disabling
JSON output.
-r, --replace Replace file when trying to normalize it instead of
creating a new one.
-f, --force Replace file without asking if you are sure, use this
flag with caution.
-t THRESHOLD, --threshold THRESHOLD
Define a custom maximum amount of chaos allowed in
decoded content. 0. <= chaos <= 1.
--version Show version information and exit.
normalizer ./data/sample.1.fr.srt
or
python -m charset_normalizer ./data/sample.1.fr.srt
🎉 Since version 1.4.0 the CLI produce easily usable stdout result in JSON format.
{
"path": "/home/default/projects/charset_normalizer/data/sample.1.fr.srt",
"encoding": "cp1252",
"encoding_aliases": [
"1252",
"windows_1252"
],
"alternative_encodings": [
"cp1254",
"cp1256",
"cp1258",
"iso8859_14",
"iso8859_15",
"iso8859_16",
"iso8859_3",
"iso8859_9",
"latin_1",
"mbcs"
],
"language": "French",
"alphabets": [
"Basic Latin",
"Latin-1 Supplement"
],
"has_sig_or_bom": false,
"chaos": 0.149,
"coherence": 97.152,
"unicode_path": null,
"is_preferred": true
}
Python
Just print out normalized text
from charset_normalizer import from_path
results = from_path('./my_subtitle.srt')
print(str(results.best()))
Upgrade your code without effort
from charset_normalizer import detect
The above code will behave the same as chardet. We ensure that we offer the best (reasonable) BC result possible.
See the docs for advanced usage : readthedocs.io
😇 Why
When I started using Chardet, I noticed that it was not suited to my expectations, and I wanted to propose a reliable alternative using a completely different method. Also! I never back down on a good challenge!
I don't care about the originating charset encoding, because two different tables can produce two identical rendered string. What I want is to get readable text, the best I can.