Package: charset-normalizer
Charset Detection, for Everyone 👋The Real First Universal Charset DetectorFeatured PackagesIn other language (unofficial port - by the community)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.>>>>>👉 Try Me Online Now, Then Adopt Me 👈<<<<<This project offers you an alternative toUniversal Charset Encoding Detector, also known asChardet.FeatureChardetCharset NormalizercChardetFast❌✅✅Universal**❌✅❌Reliablewithoutdistinguishable standards❌✅✅Reliablewithdistinguishable standards✅✅✅LicenseLGPL-2.1restrictiveMITMPL-1.1restrictiveNative Python✅✅❌Detect spoken language❌✅N/AUnicodeDecodeError Safety❌✅❌Whl Size (min)193.6 kB42 kB~200 kBSupported Encoding33🎉9940** : They are clearly using specific code for a specific encoding even if covering most of used oneDid you got there because of the logs? Seehttps://charset-normalizer.readthedocs.io/en/latest/user/miscellaneous.html⚡ PerformanceThis package offer better performance than its counterpart Chardet. Here are some numbers.PackageAccuracyMean per file (ms)File per sec (est)chardet86 %200 ms5 file/seccharset-normalizer98 %10 ms100 file/secPackage99th percentile95th percentile50th percentilechardet1200 ms287 ms23 mscharset-normalizer100 ms50 ms5 msChardet'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
(eg. Supported Encoding) Challenge-them if you want.✨ InstallationUsing pip:pipinstallcharset-normalizer-U🚀 Basic UsageCLIThis 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.srtorpython-mcharset_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}PythonJust print out normalized textfromcharset_normalizerimportfrom_pathresults=from_path('./my_subtitle.srt')print(str(results.best()))Upgrade your code without effortfromcharset_normalizerimportdetectThe above code will behave the same aschardet. We ensure that we offer the best (reasonable) BC result possible.See the docs for advanced usage :readthedocs.io😇 WhyWhen 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!Idon't careabout theoriginating charsetencoding, becausetwo different tablescan
producetwo 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 packageftfywith charset-normalizer or chardet. ftfy goal is to repair unicode string whereas charset-normalizer to convert raw file in unknown encoding to unicode.🍰 HowDiscard all charset encoding table that could not fit the binary content.Measure noise, 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 noise/mess and coherence according toYOU ?Noise :I opened hundred of text files,written by humans, with the wrong encoding table.I observed, thenI establishedsome ground rules aboutwhat is obviouswhenit seems likea mess.
I know that my interpretation of what is noise is probably incomplete, 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 limitationsLanguage 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.⚠️ About Python EOLsIf you are running:Python >=2.7,<3.5: UnsupportedPython 3.5: charset-normalizer < 2.1Python 3.6: charset-normalizer < 3.1Python 3.7: charset-normalizer < 4.0Upgrade your Python interpreter as soon as possible.👤 ContributingContributions, issues and feature requests are very much welcome.Feel free to checkissues pageif you want to contribute.📝 LicenseCopyright ©Ahmed TAHRI @Ousret.This project isMITlicensed.Characters frequencies used in this project © 2012Denny Vrandečić💼 For EnterpriseProfessional support for charset-normalizer is available as part of theTidelift
Subscription. Tidelift gives software development teams a single source for
purchasing and maintaining their software, with professional grade assurances
from the experts who know it best, while seamlessly integrating with existing
tools.ChangelogAll notable changes to charset-normalizer will be documented in this file. This project adheres toSemantic Versioning.
The format is based onKeep a Changelog.3.3.2(2023-10-31)FixedUnintentional memory usage regression when using large payload that match several encoding (#376)Regression on some detection case showcased in the documentation (#371)AddedNoise (md) probe that identify malformed arabic representation due to the presence of letters in isolated form (credit to my wife)3.3.1(2023-10-22)ChangedOptional mypyc compilation upgraded to version 1.6.1 for Python >= 3.8Improved the general detection reliability based on reports from the community3.3.0(2023-09-30)AddedAllow to execute the CLI (e.g. normalizer) throughpython -m charset_normalizer.cliorpython -m charset_normalizerSupport for 9 forgotten encoding that are supported by Python but unlisted inencoding.aliasesas they have no alias (#323)Removed(internal) Redundant utils.is_ascii function and unused function is_private_use_only(internal) charset_normalizer.assets is moved inside charset_normalizer.constantChanged(internal) Unicode code blocks in constants are updated using the latest v15.0.0 definition to improve detectionOptional mypyc compilation upgraded to version 1.5.1 for Python >= 3.8FixedUnable to properly sort CharsetMatch when both chaos/noise and coherence were close due to an unreachable condition in __lt__ (#350)3.2.0(2023-06-07)ChangedTypehint for functionfrom_pathno longer enforcePathLikeas its first argumentMinor improvement over the global detection reliabilityAddedIntroduce functionis_binarythat relies on main capabilities, and optimized to detect binariesPropagateenable_fallbackargument throughoutfrom_bytes,from_path, andfrom_fpthat allow a deeper control over the detection (default True)Explicit support for Python 3.12FixedEdge case detection failure where a file would contain 'very-long' camel cased word (Issue #289)3.1.0(2023-03-06)AddedArgumentshould_rename_legacyfor legacy functiondetectand disregard any new arguments without errors (PR #262)RemovedSupport for Python 3.6 (PR #260)ChangedOptional speedup provided by mypy/c 1.0.13.0.1(2022-11-18)FixedMulti-bytes cutter/chunk generator did not always cut correctly (PR #233)ChangedSpeedup provided by mypy/c 0.990 on Python >= 3.73.0.0(2022-10-20)AddedExtend the capability of explain=True when cp_isolation contains at most two entries (min one), will log in details of the Mess-detector resultsSupport for alternative language frequency set in charset_normalizer.assets.FREQUENCIESAdd parameterlanguage_thresholdinfrom_bytes,from_pathandfrom_fpto adjust the minimum expected coherence rationormalizer --versionnow specify if current version provide extra speedup (meaning mypyc compilation whl)ChangedBuild with static metadata using 'build' frontendMake the language detection stricterOptional: Modulemd.pycan be compiled using Mypyc to provide an extra speedup up to 4x faster than v2.1FixedCLI with opt --normalize fail when using full path for filesTooManyAccentuatedPlugin induce false positive on the mess detection when too few alpha character have been fed to itSphinx warnings when generating the documentationRemovedCoherence detector no longer return 'Simple English' instead return 'English'Coherence detector no longer return 'Classical Chinese' instead return 'Chinese'Breaking: Methodfirst()andbest()from CharsetMatchUTF-7 will no longer appear as "detected" without a recognized SIG/mark (is unreliable/conflict with ASCII)Breaking: Class aliases CharsetDetector, CharsetDoctor, CharsetNormalizerMatch and CharsetNormalizerMatchesBreaking: Top-level functionnormalizeBreaking: Propertieschaos_secondary_pass,coherence_non_latinandw_counterfrom CharsetMatchSupport for the backportunicodedata23.0.0rc1(2022-10-18)AddedExtend the capability of explain=True when cp_isolation contains at most two entries (min one), will log in details of the Mess-detector resultsSupport for alternative language frequency set in charset_normalizer.assets.FREQUENCIESAdd parameterlanguage_thresholdinfrom_bytes,from_pathandfrom_fpto adjust the minimum expected coherence ratioChangedBuild with static metadata using 'build' frontendMake the language detection stricterFixedCLI with opt --normalize fail when using full path for filesTooManyAccentuatedPlugin induce false positive on the mess detection when too few alpha character have been fed to itRemovedCoherence detector no longer return 'Simple English' instead return 'English'Coherence detector no longer return 'Classical Chinese' instead return 'Chinese'3.0.0b2(2022-08-21)Addednormalizer --versionnow specify if current version provide extra speedup (meaning mypyc compilation whl)RemovedBreaking: Methodfirst()andbest()from CharsetMatchUTF-7 will no longer appear as "detected" without a recognized SIG/mark (is unreliable/conflict with ASCII)FixedSphinx warnings when generating the documentation3.0.0b1(2022-08-15)ChangedOptional: Modulemd.pycan be compiled using Mypyc to provide an extra speedup up to 4x faster than v2.1RemovedBreaking: Class aliases CharsetDetector, CharsetDoctor, CharsetNormalizerMatch and CharsetNormalizerMatchesBreaking: Top-level functionnormalizeBreaking: Propertieschaos_secondary_pass,coherence_non_latinandw_counterfrom CharsetMatchSupport for the backportunicodedata22.1.1(2022-08-19)DeprecatedFunctionnormalizescheduled for removal in 3.0ChangedRemoved useless call to decode in fn is_unprintable (#206)FixedThird-party library (i18n xgettext) crashing not recognizing utf_8 (PEP 263) with underscore from@aleksandernovikov(#204)2.1.0(2022-06-19)AddedOutput the Unicode table version when running the CLI with--version(PR #194)ChangedRe-use decoded buffer for single byte character sets from@nijel(PR #175)Fixing some performance bottlenecks from@deedy5(PR #183)FixedWorkaround potential bug in cpython with Zero Width No-Break Space located in Arabic Presentation Forms-B, Unicode 1.1 not acknowledged as space (PR #175)CLI default threshold aligned with the API threshold from@oleksandr-kuzmenko(PR #181)RemovedSupport for Python 3.5 (PR #192)DeprecatedUse of backport unicodedata fromunicodedata2as Python is quickly catching up, scheduled for removal in 3.0 (PR #194)2.0.12(2022-02-12)FixedASCII miss-detection on rare cases (PR #170)2.0.11(2022-01-30)AddedExplicit support for Python 3.11 (PR #164)ChangedThe logging behavior have been completely reviewed, now using only TRACE and DEBUG levels (PR #163 #165)2.0.10(2022-01-04)FixedFallback match entries might lead to UnicodeDecodeError for large bytes sequence (PR #154)ChangedSkipping the language-detection (CD) on ASCII (PR #155)2.0.9(2021-12-03)ChangedModerating the logging impact (since 2.0.8) for specific environments (PR #147)FixedWrong logging level applied when setting kwargexplainto True (PR #146)2.0.8(2021-11-24)ChangedImprovement over Vietnamese detection (PR #126)MD improvement on trailing data and long foreign (non-pure latin) data (PR #124)Efficiency improvements in cd/alphabet_languages from@adbar(PR #122)call sum() without an intermediary list following PEP 289 recommendations from@adbar(PR #129)Code style as refactored by Sourcery-AI (PR #131)Minor adjustment on the MD around european words (PR #133)Remove and replace SRTs from assets / tests (PR #139)Initialize the library logger with aNullHandlerby default from@nmaynes(PR #135)Setting kwargexplainto True will add provisionally (bounded to function lifespan) a specific stream handler (PR #135)FixedFix large (misleading) sequence giving UnicodeDecodeError (PR #137)Avoid using too insignificant chunk (PR #137)AddedAdd and expose functionset_logging_handlerto configure a specific StreamHandler from@nmaynes(PR #135)AddCHANGELOG.mdentries, format is based onKeep a Changelog(PR #141)2.0.7(2021-10-11)AddedAdd support for Kazakh (Cyrillic) language detection (PR #109)ChangedFurther, improve inferring the language from a given single-byte code page (PR #112)Vainly trying to leverage PEP263 when PEP3120 is not supported (PR #116)Refactoring for potential performance improvements in loops from@adbar(PR #113)Various detection improvement (MD+CD) (PR #117)RemovedRemove redundant logging entry about detected language(s) (PR #115)FixedFix a minor inconsistency between Python 3.5 and other versions regarding language detection (PR #117 #102)2.0.6(2021-09-18)FixedUnforeseen regression with the loss of the backward-compatibility with some older minor of Python 3.5.x (PR #100)Fix CLI crash when using --minimal output in certain cases (PR #103)ChangedMinor improvement to the detection efficiency (less than 1%) (PR #106 #101)2.0.5(2021-09-14)ChangedThe project now comply with: flake8, mypy, isort and black to ensure a better overall quality (PR #81)The BC-support with v1.x was improved, the old staticmethods are restored (PR #82)The Unicode detection is slightly improved (PR #93)Add syntax sugar __bool__ for results CharsetMatches list-container (PR #91)RemovedThe project no longer raise warning on tiny content given for detection, will be simply logged as warning instead (PR #92)FixedIn some rare case, the chunks extractor could cut in the middle of a multi-byte character and could mislead the mess detection (PR #95)Some rare 'space' characters could trip up the UnprintablePlugin/Mess detection (PR #96)The MANIFEST.in was not exhaustive (PR #78)2.0.4(2021-07-30)FixedThe CLI no longer raise an unexpected exception when no encoding has been found (PR #70)Fix accessing the 'alphabets' property when the payload contains surrogate characters (PR #68)The logger could mislead (explain=True) on detected languages and the impact of one MBCS match (PR #72)Submatch factoring could be wrong in rare edge cases (PR #72)Multiple files given to the CLI were ignored when publishing results to STDOUT. (After the first path) (PR #72)Fix line endings from CRLF to LF for certain project files (PR #67)ChangedAdjust the MD to lower the sensitivity, thus improving the global detection reliability (PR #69 #76)Allow fallback on specified encoding if any (PR #71)2.0.3(2021-07-16)ChangedPart of the detection mechanism has been improved to be less sensitive, resulting in more accurate detection results. Especially ASCII. (PR #63)According to the community wishes, the detection will fall back on ASCII or UTF-8 in a last-resort case. (PR #64)2.0.2(2021-07-15)FixedEmpty/Too small JSON payload miss-detection fixed. Report from@tseaver(PR #59)ChangedDon't inject unicodedata2 into sys.modules from@akx(PR #57)2.0.1(2021-07-13)FixedMake it work where there isn't a filesystem available, dropping assets frequencies.json. Report from@sethmlarson. (PR #55)Using explain=False permanently disable the verbose output in the current runtime (PR #47)One log entry (language target preemptive) was not show in logs when using explain=True (PR #47)Fix undesired exception (ValueError) on getitem of instance CharsetMatches (PR #52)ChangedPublic function normalize default args values were not aligned with from_bytes (PR #53)AddedYou may now use charset aliases in cp_isolation and cp_exclusion arguments (PR #47)2.0.0(2021-07-02)Changed4x to 5 times faster than the previous 1.4.0 release. At least 2x faster than Chardet.Accent has been made on UTF-8 detection, should perform rather instantaneous.The backward compatibility with Chardet has been greatly improved. The legacy detect function returns an identical charset name whenever possible.The detection mechanism has been slightly improved, now Turkish content is detected correctly (most of the time)The program has been rewritten to ease the readability and maintainability. (+Using static typing)+utf_7 detection has been reinstated.RemovedThis package no longer require anything when used with Python 3.5 (Dropped cached_property)Removed support for these languages: Catalan, Esperanto, Kazakh, Baque, Volapük, Azeri, Galician, Nynorsk, Macedonian, and Serbocroatian.The exception hook on UnicodeDecodeError has been removed.DeprecatedMethods coherence_non_latin, w_counter, chaos_secondary_pass of the class CharsetMatch are now deprecated and scheduled for removal in v3.0FixedThe CLI output used the relative path of the file(s). Should be absolute.1.4.1(2021-05-28)FixedLogger configuration/usage no longer conflict with others (PR #44)1.4.0(2021-05-21)RemovedUsing standard logging instead of using the package loguru.Dropping nose test framework in favor of the maintained pytest.Choose to not use dragonmapper package to help with gibberish Chinese/CJK text.Require cached_property only for Python 3.5 due to constraint. Dropping for every other interpreter version.Stop support for UTF-7 that does not contain a SIG.Dropping PrettyTable, replaced with pure JSON output in CLI.FixedBOM marker in a CharsetNormalizerMatch instance could be False in rare cases even if obviously present. Due to the sub-match factoring process.Not searching properly for the BOM when trying utf32/16 parent codec.ChangedImproving the package final size by compressing frequencies.json.Huge improvement over the larges payload.AddedCLI now produces JSON consumable output.Return ASCII if given sequences fit. Given reasonable confidence.1.3.9(2021-05-13)FixedIn some very rare cases, you may end up getting encode/decode errors due to a bad bytes payload (PR #40)1.3.8(2021-05-12)FixedEmpty given payload for detection may cause an exception if trying to access thealphabetsproperty. (PR #39)1.3.7(2021-05-12)FixedThe legacy detect function should return UTF-8-SIG if sig is present in the payload. (PR #38)1.3.6(2021-02-09)ChangedAmend the previous release to allow prettytable 2.0 (PR #35)1.3.5(2021-02-08)FixedFix error while using the package with a python pre-release interpreter (PR #33)ChangedDependencies refactoring, constraints revised.AddedAdd python 3.9 and 3.10 to the supported interpretersMIT LicenseCopyright (c) 2019 TAHRI Ahmed R.Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.