Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Advanced Search

Charset Normalizer method `from_bytes`, `from_fp` and `from_path` provide some optional parameters that can be tweaked.

As follow

    from charset_normalizer import from_bytes

    my_byte_str = 'Bсеки човек има право на образование.'.encode('cp1251')

    results = from_bytes(
        my_byte_str,
        steps=10,  # Number of steps/block to extract from my_byte_str
        chunk_size=512,  # Set block size of each extraction
        threshold=0.2,  # Maximum amount of chaos allowed on first pass
        cp_isolation=None,  # Finite list of encoding to use when searching for a match
        cp_exclusion=None,  # Finite list of encoding to avoid when searching for a match
        preemptive_behaviour=True,  # Determine if we should look into my_byte_str (ASCII-Mode) for pre-defined encoding
        explain=False,  # Print on screen what is happening when searching for a match
        language_threshold=0.1  # Minimum coherence ratio / language ratio match accepted
    )

## Using CharsetMatches

Here, `results` is a `CharsetMatches` object. It behave like a list but does not implements all related methods. Initially, it is sorted. Calling `best()` is sufficient to extract the most probable result.

class charset_normalizer.CharsetMatches(results: list[CharsetMatch] | None = None)

  Container with every CharsetMatch items ordered by default from most probable to the less one. Act like a list(iterable) but does not implements all related methods.

  append(item: CharsetMatch) → None

    Insert a single match. Will be inserted accordingly to preserve sort. Can be inserted as a submatch.

  best() → CharsetMatch | None

    Simply return the first match. Strict equivalent to matches[0].

  first() → CharsetMatch | None

    Redundant method, call the method best(). Kept for BC reasons.

## List behaviour

Like said earlier, `CharsetMatches` object behave like a list.

>     # Call len on results also work
>     if not results:
>         print('No match for your sequence')

>     # Iterate over results like a list
>     for match in results:
>         print(match.encoding, 'can decode properly your sequence using', match.alphabets, 'and language', match.language)

>     # Using index to access results
>     if results:
>         print(str(results[0]))

## Using best()

Like said above, `CharsetMatches` object behave like a list and it is sorted by default after getting results from `from_bytes`, `from_fp` or `from_path`.

Using `best()` return the most probable result, the first entry of the list. Eg. idx 0. It return a `CharsetMatch` object as return value or None if there is not results inside it.

>     result = results.best()

## Calling first()

The very same thing than calling the method `best()`.

## Class aliases

`CharsetMatches` is also known as `CharsetDetector`, `CharsetDoctor` and `CharsetNormalizerMatches`. It is useful if you prefer short class name.

## Verbose output

You may want to understand why a specific encoding was not picked by charset_normalizer. All you have to do is passing `explain` to True when using methods `from_bytes`, `from_fp` or `from_path`.