# `collation` – Tools for working with collations.

Tools for working with collations.

See also

This module is compatible with both the synchronous and asynchronous PyMongo APIs.

class pymongo.collation.Collation(locale, caseLevel=None, caseFirst=None, strength=None, numericOrdering=None, alternate=None, maxVariable=None, normalization=None, backwards=None, **kwargs)
  Parameters:

    - locale (str) – (string) The locale of the collation. This should be a string that identifies an ICU locale ID exactly. For example, `en_US` is valid, but `en_us` and `en-US` are not. Consult the MongoDB documentation for a list of supported locales.

    - caseLevel (Optional[bool]) – (optional) If `True`, turn on case sensitivity if strength is 1 or 2 (case sensitivity is implied if strength is greater than 2). Defaults to `False`.

    - caseFirst (Optional[str]) –

      (optional) Specify that either uppercase or lowercase characters take precedence. Must be one of the following values:

      > - `UPPER`

      > - `LOWER`

      > - `OFF` (the default)

    - strength (Optional[int]) –

      Specify the comparison strength. This is also known as the ICU comparison level. This must be one of the following values:

      > - `PRIMARY`

      > - `SECONDARY`

      > - `TERTIARY` (the default)

      > - `QUATERNARY`

      > - `IDENTICAL`

      Each successive level builds upon the previous. For example, a strength of `SECONDARY` differentiates characters based both on the unadorned base character and its accents.

    - numericOrdering (Optional[bool]) – If `True`, order numbers numerically instead of in collation order (defaults to `False`).

    - alternate (Optional[str]) –

      Specify whether spaces and punctuation are considered base characters. This must be one of the following values:

      > - `NON_IGNORABLE` (the default)

      > - `SHIFTED`

    - maxVariable (Optional[str]) –

      When alternate is `SHIFTED`, this option specifies what characters may be ignored. This must be one of the following values:

      > - `PUNCT` (the default)

      > - `SPACE`

    - normalization (Optional[bool]) – If `True`, normalizes text into Unicode NFD. Defaults to `False`.

    - backwards (Optional[bool]) – If `True`, accents on characters are considered from the back of the word to the front, as it is done in some French dictionary ordering traditions. Defaults to `False`.

    - kwargs (Any) – Keyword arguments supplying any additional options to be sent with this Collation object.

class pymongo.collation.CollationStrength

  An enum that defines values for strength on a `Collation`.

  PRIMARY = 1

    Differentiate base (unadorned) characters.

  SECONDARY = 2

    Differentiate character accents.

  TERTIARY = 3

    Differentiate character case.

  QUATERNARY = 4

    Differentiate words with and without punctuation.

  IDENTICAL = 5

    Differentiate unicode code point (characters are exactly identical).

class pymongo.collation.CollationAlternate

  An enum that defines values for alternate on a `Collation`.

  NON_IGNORABLE = 'non-ignorable'

    Spaces and punctuation are treated as base characters.

  SHIFTED = 'shifted'

    Spaces and punctuation are not considered base characters.

    Spaces and punctuation are distinguished regardless when the `Collation` strength is at least `QUATERNARY`.

class pymongo.collation.CollationCaseFirst

  An enum that defines values for case_first on a `Collation`.

  UPPER = 'upper'

    Sort uppercase characters first.

  LOWER = 'lower'

    Sort lowercase characters first.

  OFF = 'off'

    Default for locale or collation strength.

class pymongo.collation.CollationMaxVariable

  An enum that defines values for max_variable on a `Collation`.

  PUNCT = 'punct'

    Both punctuation and spaces are ignored.

  SPACE = 'space'

    Spaces alone are ignored.