Skip to content
๐Ÿ”Ž Like Chardet. ๐Ÿš€ Package for encoding & language detection. Charset detection.
Branch: master
Clone or download
Fetching latest commitโ€ฆ
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
charset_normalizer Improvement on probe chaos (#31) Dec 16, 2019
data Add file (test purpose) utf_8 with sig Sep 6, 2019
docs Docs update (#21) Oct 7, 2019
paper Improvement on probe chaos (#31) Dec 16, 2019
test Improvement on probe chaos (#31) Dec 16, 2019
.gitignore Initial commit ๐Ÿ”ฎ Aug 2, 2019
.travis.yml travis build change Sep 6, 2019 Create Sep 20, 2019
LICENSE Add LICENSE and data to sdist Aug 28, 2019 Include in manifest Aug 31, 2019 replace github checkmark to unicode checkmark in Oct 11, 2019

Welcome to Charset Detection for Humans ๐Ÿ‘‹

The Real First Universal Charset Detector
Download Count /Month License: MIT Code Quality Badge Documentation Status Download Count Total

A library that helps you read text from an unknown charset encoding.
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.

>>>>> โค๏ธ Try Me Online Now, Then Adopt Me โค๏ธ <<<<<

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 ๐ŸŽ‰ 90 40
Package Accuracy Mean per file (ns) File per sec (est)
chardet 93.5 % 126 081 168 ns 7.931 file/sec
cchardet 97.0 % 1 668 145 ns 599.468 file/sec
charset-normalizer 97.25 % 209 503 253 ns 4.773 file/sec

Reading Normalized TextCat Reading Text

** : They are clearly using specific code for a specific encoding even if covering most of used one

Your support

Please โญ this repository if this project helped you!

โœจ Installation

Using PyPi

pip install charset_normalizer

๐Ÿš€ Basic Usage


This package comes with a CLI

usage: normalizer [-h] [--verbose] [--normalize] [--replace] [--force]
                  file [file ...]
normalizer ./data/
|       Filename       | Encoding | Language |             Alphabets              | Chaos | Coherence |
| data/ |  cp1252  |  French  | Basic Latin and Latin-1 Supplement | 0.0 % |  84.924 % |


Just print out normalized text

from charset_normalizer import CharsetNormalizerMatches as CnM

Normalize any text file

from charset_normalizer import CharsetNormalizerMatches as CnM
    CnM.normalize('./') # 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.

See the docs for advanced usage :

๐Ÿ˜‡ Why

When I started using Chardet, I noticed that it was unreliable nowadays and also it's unmaintained, and most likely will never be.

I don't care about the originating charset encoding, because two different tables can produce two identical files. 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 with a corresponding charset encoding.
  • Extract matches with the lowest mess detected.
  • Finally, if there is too much match left, we measure coherence.

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

  • Not intended to work on non (human) speakable language text content. eg. crypted text.
  • Language detection is unreliable when text contains two or more languages sharing identical letters.
  • Not well tested with 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.

Letter appearances frequencies used in this project ยฉ 2012 Denny Vrandeฤiฤ‡

You canโ€™t perform that action at this time.