Doc/library/stringprep.rst

   1
   2 :mod:`stringprep` --- Internet String Preparation
   3 =================================================
   4
   5 .. module:: stringprep
   6    :synopsis: String preparation, as per RFC 3453
   7    :deprecated:
   8 .. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
   9 .. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
  10
  11
  12 .. versionadded:: 2.3
  13
  14 When identifying things (such as host names) in the internet, it is often
  15 necessary to compare such identifications for "equality". Exactly how this
  16 comparison is executed may depend on the application domain, e.g. whether it
  17 should be case-insensitive or not. It may be also necessary to restrict the
  18 possible identifications, to allow only identifications consisting of
  19 "printable" characters.
  20
  21 :rfc:`3454` defines a procedure for "preparing" Unicode strings in internet
  22 protocols. Before passing strings onto the wire, they are processed with the
  23 preparation procedure, after which they have a certain normalized form. The RFC
  24 defines a set of tables, which can be combined into profiles. Each profile must
  25 define which tables it uses, and what other optional parts of the ``stringprep``
  26 procedure are part of the profile. One example of a ``stringprep`` profile is
  27 ``nameprep``, which is used for internationalized domain names.
  28
  29 The module :mod:`stringprep` only exposes the tables from RFC 3454. As these
  30 tables would be very large to represent them as dictionaries or lists, the
  31 module uses the Unicode character database internally. The module source code
  32 itself was generated using the ``mkstringprep.py`` utility.
  33
  34 As a result, these tables are exposed as functions, not as data structures.
  35 There are two kinds of tables in the RFC: sets and mappings. For a set,
  36 :mod:`stringprep` provides the "characteristic function", i.e. a function that
  37 returns true if the parameter is part of the set. For mappings, it provides the
  38 mapping function: given the key, it returns the associated value. Below is a
  39 list of all functions available in the module.
  40
  41
  42 .. function:: in_table_a1(code)
  43
  44    Determine whether *code* is in tableA.1 (Unassigned code points in Unicode 3.2).
  45
  46
  47 .. function:: in_table_b1(code)
  48
  49    Determine whether *code* is in tableB.1 (Commonly mapped to nothing).
  50
  51
  52 .. function:: map_table_b2(code)
  53
  54    Return the mapped value for *code* according to tableB.2 (Mapping for
  55    case-folding used with NFKC).
  56
  57
  58 .. function:: map_table_b3(code)
  59
  60    Return the mapped value for *code* according to tableB.3 (Mapping for
  61    case-folding used with no normalization).
  62
  63
  64 .. function:: in_table_c11(code)
  65
  66    Determine whether *code* is in tableC.1.1  (ASCII space characters).
  67
  68
  69 .. function:: in_table_c12(code)
  70
  71    Determine whether *code* is in tableC.1.2  (Non-ASCII space characters).
  72
  73
  74 .. function:: in_table_c11_c12(code)
  75
  76    Determine whether *code* is in tableC.1  (Space characters, union of C.1.1 and
  77    C.1.2).
  78
  79
  80 .. function:: in_table_c21(code)
  81
  82    Determine whether *code* is in tableC.2.1  (ASCII control characters).
  83
  84
  85 .. function:: in_table_c22(code)
  86
  87    Determine whether *code* is in tableC.2.2  (Non-ASCII control characters).
  88
  89
  90 .. function:: in_table_c21_c22(code)
  91
  92    Determine whether *code* is in tableC.2  (Control characters, union of C.2.1 and
  93    C.2.2).
  94
  95
  96 .. function:: in_table_c3(code)
  97
  98    Determine whether *code* is in tableC.3  (Private use).
  99
 100
 101 .. function:: in_table_c4(code)
 102
 103    Determine whether *code* is in tableC.4  (Non-character code points).
 104
 105
 106 .. function:: in_table_c5(code)
 107
 108    Determine whether *code* is in tableC.5  (Surrogate codes).
 109
 110
 111 .. function:: in_table_c6(code)
 112
 113    Determine whether *code* is in tableC.6  (Inappropriate for plain text).
 114
 115
 116 .. function:: in_table_c7(code)
 117
 118    Determine whether *code* is in tableC.7  (Inappropriate for canonical
 119    representation).
 120
 121
 122 .. function:: in_table_c8(code)
 123
 124    Determine whether *code* is in tableC.8  (Change display properties or are
 125    deprecated).
 126
 127
 128 .. function:: in_table_c9(code)
 129
 130    Determine whether *code* is in tableC.9  (Tagging characters).
 131
 132
 133 .. function:: in_table_d1(code)
 134
 135    Determine whether *code* is in tableD.1  (Characters with bidirectional property
 136    "R" or "AL").
 137
 138
 139 .. function:: in_table_d2(code)
 140
 141    Determine whether *code* is in tableD.2  (Characters with bidirectional property
 142    "L").
 143