1 """collate - Sort strings intelligently.
3 This module provides tools to sort strings in a 'human-expected' order.
5 Because human expectations are fuzzy and often self-contradictory, the
6 sort order is not guaranteed to be stable between versions of this
7 module (rather the opposite - the primary reason to update it will
8 probably be changed sort results).
10 If available, this module uses the ICU localization library.
11 Otherwise, it uses the system's locale database (and produces
12 significantly worse results).
16 strings = read_strings(...)
17 strings.sort(key=collate.key)
21 backend - The default collation backend. If available, this is
22 collate.icu; otherwise, it is collate.syslocale. In special
23 situations, it may be collate.codepoint.
25 collate - The default collator. This is the collator of the default
26 backend instantiated with the default system locale and encoding.
30 __all__
= ["collator", "set_collator", "cmp", "key", "default",
31 "VERSION", "VERSION_STRING"]
34 import collate
._locale
37 import collate
.codepoint
as default
41 import collate
.syslocale
as default
45 import collate
.icu
as default
50 VERSION_STRING
= ".".join(map(str, VERSION
))
54 def set_collator(backend
=None, locale
=None, encoding
=None):
55 """Set the default collation backend.
57 This function tries very hard not to fail; the resulting Collator
58 may not have the locale or encoding you specified (at the very
59 least, they will be normalized). Remember to check
60 collator.locale and collator.encoding.
63 backend - 'icu', 'syslocale', or 'codepoint'; None to not change.
64 locale - e.g. 'en_US', or None for the system locale.
65 encoding - e.g. 'utf-8', or None for the system locale encoding
68 The new default Collator instance, or None if no collator could be
69 created; if None is returned, the existing default Collator is
78 locales
= collate
._locale
.localelist(locale
)
80 for locale
in locales
:
81 locale
, encoding_
= collate
._locale
.getpair(locale
, encoding
)
83 possible
= backend
.Collator(locale
, encoding_
)
84 except collate
.errors
.InvalidLocaleError
:
88 if possible
is not None:
95 """Return a good sorting key for the string.
97 The sort key should be considered an opaque value which is only
98 meaningful when compared to other sort keys from the same
101 This is the same as collate.collator.sortemekey(string).
103 return collator
.sortemekey(string
)
106 """Return negative if a < b, zero if a == b, positive if a > b.
108 This is the same as collate.collator.cmp(a, b).
110 return collator
.cmp(a
, b
)
115 raise collate
.errors
.InvalidLocaleError("C")