Charset Detection, for Everyone
👋
The Real First Universal Charset Detector
A library that helps you read text from an unknown charset encoding.
Motivated bychardet, 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 |
|
|
|
Free & Open |
|
|
|
License |
LGPL-2.1 | MIT | MPL-1.1 |
Native Python |
|
|
|
Detect spoken language |
|
|
N/A |
Supported Encoding |
30 | |
40 |
** : They are clearly using specific code for a specific encoding even if covering most of used one
⭐
Your support
Fork, test-it, star-it, submit your ideas! We do listen.
⚡
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 | 92 % | 220 ms | 5 file/sec |
| charset-normalizer | 98 % | 40 ms | 25 file/sec |
| Package | 99th percentile | 95th percentile | 50th percentile |
|---|---|---|---|
| chardet | 1115 ms | 300 ms | 27 ms |
| charset-normalizer | 460 ms | 240 ms | 18 ms |
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.
cchardet is a non-native (cpp binding) and unmaintained faster alternative with a better accuracy than chardet but lower than this package. If speed is the most important factor, you should try it.
✨
Installation
Using PyPi for latest stable
pip install charset-normalizer -U
If you want a more up-to-date unicodedata than the one available in your Python setup.
pip install charset-normalizer[unicode_backport] -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
{
"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()))
Normalize any text file
from charset_normalizer import normalize
try:
normalize('./my_subtitle.srt') # should write to disk my_subtitle-***.srt
except IOError as e:
print('Sadly, we are unable to perform charset normalization.', str(e))
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.
In a way, I'm brute forcing text decoding. How cool is that ?
Don't confuse package ftfy with charset-normalizer or chardet. ftfy goal is to repair unicode string whereas charset-normalizer to convert raw file in unknown encoding to unicode.
🍰
How
- Discard all charset encoding table that could not fit the binary content.
- Measure chaos, or the mess once opened (by chunks) with a corresponding charset encoding.
- Extract matches with the lowest mess detected.
- Additionally, we measure coherence / probe for a language.
Wait a minute, what is chaos/mess and coherence according to YOU ?
Chaos : I opened hundred of text files, written by humans, with the wrong encoding table. I observed, then I established some ground rules about what is obvious when it seems like a mess. I know that my interpretation of what is chaotic is very subjective, feel free to contribute in order to improve or rewrite it.
Coherence : For each language there is on earth, we have computed ranked letter appearance occurrences (the best we can). So I thought that intel is worth something here. So I use those records against decoded text to check if I can detect intelligent design.
⚡
Known limitations
- Language detection is unreliable when text contains two or more languages sharing identical letters. (eg. HTML (english tags) + Turkish content (Sharing Latin characters))
- Every charset detector heavily depends on sufficient content. In common cases, do not bother run detection on very tiny content.
👤
Contributing
Contributions, issues and feature requests are very much welcome.
Feel free to check issues page if you want to contribute.
📝
License
Copyright © 2019 Ahmed TAHRI @Ousret.
This project is MIT licensed.
Characters frequencies used in this project © 2012 Denny Vrandečić
![[Proposal] Add module creation with mypyc to speed up](https://avatars.githubusercontent.com/u/65482418?v=4)
![[Proposal] Incrase language coverage](https://avatars.githubusercontent.com/u/10583082?v=4)
![[BUG] Support for custom Python environment that ignore PEP 3120](https://avatars.githubusercontent.com/u/73003277?v=4)
3 Feb 22, 2022
101 Dec 12, 2022
4 Sep 29, 2022
952 Dec 31, 2022
4 Apr 24, 2022
2.2k Jan 04, 2023
87 Dec 26, 2022
20 Oct 25, 2022
1 Jan 01, 2022
6 Dec 09, 2022
17 Nov 03, 2022
18 Jul 19, 2022
117 Dec 28, 2022
9 Oct 14, 2022
157 Aug 23, 2022
2.2k Jan 02, 2023
24 Apr 28, 2022
2 Nov 21, 2021
26 Jun 17, 2021
4 Jun 30, 2022