python/lib/requests/requests/packages/charade/hebrewprober.py

   1 ######################## BEGIN LICENSE BLOCK ########################
   2 # The Original Code is Mozilla Universal charset detector code.
   3 #
   4 # The Initial Developer of the Original Code is
   5 #          Shy Shalom
   6 # Portions created by the Initial Developer are Copyright (C) 2005
   7 # the Initial Developer. All Rights Reserved.
   8 #
   9 # Contributor(s):
  10 #   Mark Pilgrim - port to Python
  11 #
  12 # This library is free software; you can redistribute it and/or
  13 # modify it under the terms of the GNU Lesser General Public
  14 # License as published by the Free Software Foundation; either
  15 # version 2.1 of the License, or (at your option) any later version.
  16 #
  17 # This library is distributed in the hope that it will be useful,
  18 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20 # Lesser General Public License for more details.
  21 #
  22 # You should have received a copy of the GNU Lesser General Public
  23 # License along with this library; if not, write to the Free Software
  24 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  25 # 02110-1301  USA
  26 ######################### END LICENSE BLOCK #########################
  27
  28 from .charsetprober import CharSetProber
  29 from .constants import eNotMe, eDetecting
  30 from .compat import wrap_ord
  31
  32 # This prober doesn't actually recognize a language or a charset.
  33 # It is a helper prober for the use of the Hebrew model probers
  34
  35 ### General ideas of the Hebrew charset recognition ###
  36 #
  37 # Four main charsets exist in Hebrew:
  38 # "ISO-8859-8" - Visual Hebrew
  39 # "windows-1255" - Logical Hebrew
  40 # "ISO-8859-8-I" - Logical Hebrew
  41 # "x-mac-hebrew" - ?? Logical Hebrew ??
  42 #
  43 # Both "ISO" charsets use a completely identical set of code points, whereas
  44 # "windows-1255" and "x-mac-hebrew" are two different proper supersets of
  45 # these code points. windows-1255 defines additional characters in the range
  46 # 0x80-0x9F as some misc punctuation marks as well as some Hebrew-specific
  47 # diacritics and additional 'Yiddish' ligature letters in the range 0xc0-0xd6.
  48 # x-mac-hebrew defines similar additional code points but with a different
  49 # mapping.
  50 #
  51 # As far as an average Hebrew text with no diacritics is concerned, all four
  52 # charsets are identical with respect to code points. Meaning that for the
  53 # main Hebrew alphabet, all four map the same values to all 27 Hebrew letters
  54 # (including final letters).
  55 #
  56 # The dominant difference between these charsets is their directionality.
  57 # "Visual" directionality means that the text is ordered as if the renderer is
  58 # not aware of a BIDI rendering algorithm. The renderer sees the text and
  59 # draws it from left to right. The text itself when ordered naturally is read
  60 # backwards. A buffer of Visual Hebrew generally looks like so:
  61 # "[last word of first line spelled backwards] [whole line ordered backwards
  62 # and spelled backwards] [first word of first line spelled backwards]
  63 # [end of line] [last word of second line] ... etc' "
  64 # adding punctuation marks, numbers and English text to visual text is
  65 # naturally also "visual" and from left to right.
  66 #
  67 # "Logical" directionality means the text is ordered "naturally" according to
  68 # the order it is read. It is the responsibility of the renderer to display
  69 # the text from right to left. A BIDI algorithm is used to place general
  70 # punctuation marks, numbers and English text in the text.
  71 #
  72 # Texts in x-mac-hebrew are almost impossible to find on the Internet. From
  73 # what little evidence I could find, it seems that its general directionality
  74 # is Logical.
  75 #
  76 # To sum up all of the above, the Hebrew probing mechanism knows about two
  77 # charsets:
  78 # Visual Hebrew - "ISO-8859-8" - backwards text - Words and sentences are
  79 #    backwards while line order is natural. For charset recognition purposes
  80 #    the line order is unimportant (In fact, for this implementation, even
  81 #    word order is unimportant).
  82 # Logical Hebrew - "windows-1255" - normal, naturally ordered text.
  83 #
  84 # "ISO-8859-8-I" is a subset of windows-1255 and doesn't need to be
  85 #    specifically identified.
  86 # "x-mac-hebrew" is also identified as windows-1255. A text in x-mac-hebrew
  87 #    that contain special punctuation marks or diacritics is displayed with
  88 #    some unconverted characters showing as question marks. This problem might
  89 #    be corrected using another model prober for x-mac-hebrew. Due to the fact
  90 #    that x-mac-hebrew texts are so rare, writing another model prober isn't
  91 #    worth the effort and performance hit.
  92 #
  93 #### The Prober ####
  94 #
  95 # The prober is divided between two SBCharSetProbers and a HebrewProber,
  96 # all of which are managed, created, fed data, inquired and deleted by the
  97 # SBCSGroupProber. The two SBCharSetProbers identify that the text is in
  98 # fact some kind of Hebrew, Logical or Visual. The final decision about which
  99 # one is it is made by the HebrewProber by combining final-letter scores
 100 # with the scores of the two SBCharSetProbers to produce a final answer.
 101 #
 102 # The SBCSGroupProber is responsible for stripping the original text of HTML
 103 # tags, English characters, numbers, low-ASCII punctuation characters, spaces
 104 # and new lines. It reduces any sequence of such characters to a single space.
 105 # The buffer fed to each prober in the SBCS group prober is pure text in
 106 # high-ASCII.
 107 # The two SBCharSetProbers (model probers) share the same language model:
 108 # Win1255Model.
 109 # The first SBCharSetProber uses the model normally as any other
 110 # SBCharSetProber does, to recognize windows-1255, upon which this model was
 111 # built. The second SBCharSetProber is told to make the pair-of-letter
 112 # lookup in the language model backwards. This in practice exactly simulates
 113 # a visual Hebrew model using the windows-1255 logical Hebrew model.
 114 #
 115 # The HebrewProber is not using any language model. All it does is look for
 116 # final-letter evidence suggesting the text is either logical Hebrew or visual
 117 # Hebrew. Disjointed from the model probers, the results of the HebrewProber
 118 # alone are meaningless. HebrewProber always returns 0.00 as confidence
 119 # since it never identifies a charset by itself. Instead, the pointer to the
 120 # HebrewProber is passed to the model probers as a helper "Name Prober".
 121 # When the Group prober receives a positive identification from any prober,
 122 # it asks for the name of the charset identified. If the prober queried is a
 123 # Hebrew model prober, the model prober forwards the call to the
 124 # HebrewProber to make the final decision. In the HebrewProber, the
 125 # decision is made according to the final-letters scores maintained and Both
 126 # model probers scores. The answer is returned in the form of the name of the
 127 # charset identified, either "windows-1255" or "ISO-8859-8".
 128
 129 # windows-1255 / ISO-8859-8 code points of interest
 130 FINAL_KAF = 0xea
 131 NORMAL_KAF = 0xeb
 132 FINAL_MEM = 0xed
 133 NORMAL_MEM = 0xee
 134 FINAL_NUN = 0xef
 135 NORMAL_NUN = 0xf0
 136 FINAL_PE = 0xf3
 137 NORMAL_PE = 0xf4
 138 FINAL_TSADI = 0xf5
 139 NORMAL_TSADI = 0xf6
 140
 141 # Minimum Visual vs Logical final letter score difference.
 142 # If the difference is below this, don't rely solely on the final letter score
 143 # distance.
 144 MIN_FINAL_CHAR_DISTANCE = 5
 145
 146 # Minimum Visual vs Logical model score difference.
 147 # If the difference is below this, don't rely at all on the model score
 148 # distance.
 149 MIN_MODEL_DISTANCE = 0.01
 150
 151 VISUAL_HEBREW_NAME = "ISO-8859-8"
 152 LOGICAL_HEBREW_NAME = "windows-1255"
 153
 154
 155 class HebrewProber(CharSetProber):
 156     def __init__(self):
 157         CharSetProber.__init__(self)
 158         self._mLogicalProber = None
 159         self._mVisualProber = None
 160         self.reset()
 161
 162     def reset(self):
 163         self._mFinalCharLogicalScore = 0
 164         self._mFinalCharVisualScore = 0
 165         # The two last characters seen in the previous buffer,
 166         # mPrev and mBeforePrev are initialized to space in order to simulate
 167         # a word delimiter at the beginning of the data
 168         self._mPrev = ' '
 169         self._mBeforePrev = ' '
 170         # These probers are owned by the group prober.
 171
 172     def set_model_probers(self, logicalProber, visualProber):
 173         self._mLogicalProber = logicalProber
 174         self._mVisualProber = visualProber
 175
 176     def is_final(self, c):
 177         return wrap_ord(c) in [FINAL_KAF, FINAL_MEM, FINAL_NUN, FINAL_PE,
 178                                FINAL_TSADI]
 179
 180     def is_non_final(self, c):
 181         # The normal Tsadi is not a good Non-Final letter due to words like
 182         # 'lechotet' (to chat) containing an apostrophe after the tsadi. This
 183         # apostrophe is converted to a space in FilterWithoutEnglishLetters
 184         # causing the Non-Final tsadi to appear at an end of a word even
 185         # though this is not the case in the original text.
 186         # The letters Pe and Kaf rarely display a related behavior of not being
 187         # a good Non-Final letter. Words like 'Pop', 'Winamp' and 'Mubarak'
 188         # for example legally end with a Non-Final Pe or Kaf. However, the
 189         # benefit of these letters as Non-Final letters outweighs the damage
 190         # since these words are quite rare.
 191         return wrap_ord(c) in [NORMAL_KAF, NORMAL_MEM, NORMAL_NUN, NORMAL_PE]
 192
 193     def feed(self, aBuf):
 194         # Final letter analysis for logical-visual decision.
 195         # Look for evidence that the received buffer is either logical Hebrew
 196         # or visual Hebrew.
 197         # The following cases are checked:
 198         # 1) A word longer than 1 letter, ending with a final letter. This is
 199         #    an indication that the text is laid out "naturally" since the
 200         #    final letter really appears at the end. +1 for logical score.
 201         # 2) A word longer than 1 letter, ending with a Non-Final letter. In
 202         #    normal Hebrew, words ending with Kaf, Mem, Nun, Pe or Tsadi,
 203         #    should not end with the Non-Final form of that letter. Exceptions
 204         #    to this rule are mentioned above in isNonFinal(). This is an
 205         #    indication that the text is laid out backwards. +1 for visual
 206         #    score
 207         # 3) A word longer than 1 letter, starting with a final letter. Final
 208         #    letters should not appear at the beginning of a word. This is an
 209         #    indication that the text is laid out backwards. +1 for visual
 210         #    score.
 211         #
 212         # The visual score and logical score are accumulated throughout the
 213         # text and are finally checked against each other in GetCharSetName().
 214         # No checking for final letters in the middle of words is done since
 215         # that case is not an indication for either Logical or Visual text.
 216         #
 217         # We automatically filter out all 7-bit characters (replace them with
 218         # spaces) so the word boundary detection works properly. [MAP]
 219
 220         if self.get_state() == eNotMe:
 221             # Both model probers say it's not them. No reason to continue.
 222             return eNotMe
 223
 224         aBuf = self.filter_high_bit_only(aBuf)
 225
 226         for cur in aBuf:
 227             if cur == ' ':
 228                 # We stand on a space - a word just ended
 229                 if self._mBeforePrev != ' ':
 230                     # next-to-last char was not a space so self._mPrev is not a
 231                     # 1 letter word
 232                     if self.is_final(self._mPrev):
 233                         # case (1) [-2:not space][-1:final letter][cur:space]
 234                         self._mFinalCharLogicalScore += 1
 235                     elif self.is_non_final(self._mPrev):
 236                         # case (2) [-2:not space][-1:Non-Final letter][
 237                         #  cur:space]
 238                         self._mFinalCharVisualScore += 1
 239             else:
 240                 # Not standing on a space
 241                 if ((self._mBeforePrev == ' ') and
 242                         (self.is_final(self._mPrev)) and (cur != ' ')):
 243                     # case (3) [-2:space][-1:final letter][cur:not space]
 244                     self._mFinalCharVisualScore += 1
 245             self._mBeforePrev = self._mPrev
 246             self._mPrev = cur
 247
 248         # Forever detecting, till the end or until both model probers return
 249         # eNotMe (handled above)
 250         return eDetecting
 251
 252     def get_charset_name(self):
 253         # Make the decision: is it Logical or Visual?
 254         # If the final letter score distance is dominant enough, rely on it.
 255         finalsub = self._mFinalCharLogicalScore - self._mFinalCharVisualScore
 256         if finalsub >= MIN_FINAL_CHAR_DISTANCE:
 257             return LOGICAL_HEBREW_NAME
 258         if finalsub <= -MIN_FINAL_CHAR_DISTANCE:
 259             return VISUAL_HEBREW_NAME
 260
 261         # It's not dominant enough, try to rely on the model scores instead.
 262         modelsub = (self._mLogicalProber.get_confidence()
 263                     - self._mVisualProber.get_confidence())
 264         if modelsub > MIN_MODEL_DISTANCE:
 265             return LOGICAL_HEBREW_NAME
 266         if modelsub < -MIN_MODEL_DISTANCE:
 267             return VISUAL_HEBREW_NAME
 268
 269         # Still no good, back to final letter distance, maybe it'll save the
 270         # day.
 271         if finalsub < 0.0:
 272             return VISUAL_HEBREW_NAME
 273
 274         # (finalsub > 0 - Logical) or (don't know what to do) default to
 275         # Logical.
 276         return LOGICAL_HEBREW_NAME
 277
 278     def get_state(self):
 279         # Remain active as long as any of the model probers are active.
 280         if (self._mLogicalProber.get_state() == eNotMe) and \
 281            (self._mVisualProber.get_state() == eNotMe):
 282             return eNotMe
 283         return eDetecting