About this library

jchars is a Python library developed as a personal project and may contain errors.

This library was created alongside Gokan. The main purpose for which it was created was to automatically match each character of a kanji word to its reading and to verify that the characters in the input words are of the correct type. These functions are used in Gokan.

I am considering adding more features in the future that can be useful for Gokan.

If you would like to contact me for any reason, feel free to email me at mariomoratilla@gmail.com

View the project on GitHub

View the project on PyPi

Installation:


            pip install jchars
Functions
  1. match_kanji_to_hiragana 
    
                  match_kanji_to_hiragana(kanji_string: str, hiragana_string: str) -> tuple[bool, str, list]

    This is the main function of this library. It tries to match the input kanji and hiragana strings and returns the following three elements:

    • Boolean: True if a correct combinations has been found, False otherwise.
    • String: Empty if the boolean is True. If it is False, the string contains the reason why the correct combination could not be found. That reason will be one of the following: 'irregular reading', 'not valid combination found' or 'more than one possible combination'.
    • List: If the boolean is True, this will be a list containing the correct combination. For 'irregular reading' or 'not valid combination found' this will be an empty list. For 'more than one possible combination' it will be a list of lists containing all possible combinations.

    Input where the solution can be found

    
                  match_kanji_to_hiragana("食べ物", "たべもの")
                  (True, '', [['食', 'た'], ['べ', 'べ'], ['物', 'もの']])

    Input with an irregular reading

    
                  match_kanji_to_hiragana("今日", "きょう")
                  (False, 'irregular reading', [])

    Input where no solution can be found because the reading is incorrect. (つき is not a reading of 日)

    
                  match_kanji_to_hiragana("日", "つき")
                  (False, 'not valid combination found', [])

    There could, in theory, be a word where the same hiragana can match the kanji in two different ways. For example, supposing the following:

    • Kanji X has two possible readings: あ and あか.
    • Kanji Y has two possible readings: かさ and さ.
    • The word XY is read あかさ.

    In this case, this function would not be able to determine whether the correct combination is [['X', 'あか'], ['Y', 'さ']] or [['X', 'あ'], ['Y', 'かさ']] and it would therefore return 'more than one possible combination'. I have not found any real examples of such a case, but it may theoretically be possible.

    
                  match_kanji_to_hiragana("XY","あかさ")
                  (False, 'more than one possible combination', [[['X', 'あか'], ['Y', 'さ']], [['X', 'あ'], ['Y', 'かさ']]])
  2. has_irregular_reading 
    
                  has_irregular_reading(kanji_string: str) -> tuple[bool, str | None]

    It returns a boolean indicating whether a kanji word has an irregular reading and, if so, what that irregular reading is.

    
                  has_irregular_reading("大人")
                  (True, 'おとな')
                
    
                  has_irregular_reading("食べ物")
                  (False, None)
  3. is_irregular_reading 
    
                  is_irregular_reading(kanji_string: str, hiragana_string: str) -> bool

    It returns a boolean indicating whether a hiragana word is the irregular reading of a kanji word.

    
                  is_irregular_reading("紅葉", "もみじ")
                  True
                
    
                  is_irregular_reading("紅葉", "こうよう")
                  False
  4. type_of_char 
    
                  type_of_char(char: str, multiple_results: bool = False) -> str | list[str]

    If multiple results is False, this function returns a string indicating the type of a one-character string. Only the first (the most restrictive) category is returned. If it is True, it returns a list of strings with all the types that include that character.

    The possible return values are those listed under Sets.

    
                  type_of_char("あ")
                  "hiragana"
                
    
                  type_of_char("あ", True)
                  ['hiragana', 'kana', 'japanese', 'hiragana_wsym', 'kana_wsym', 'japanese_wsym']
                
    
                  type_of_char("月")
                  'jouyou_kanji'
                
    
                  type_of_char("a", True)
                  ['english', 'english_wsym', 'spanish', 'spanish_wsym']
                
    
                  type_of_char("π")
                  'unknown'
  5. type_of_string 
    
                  type_of_string(string: str, multiple_results: bool = False) -> str | list[str]

    If multiple results is False, this function returns a string indicating the type of the input string. Only the first (the most restrictive) category is returned. If it is True, it returns a list of strings with all the types where the input string is included.

    The possible return values are those listed under Sets.

    
                  type_of_string("たべもの")
                  "hiragana"
                
    
                  type_of_string("たべもの", True)
                  ['hiragana', 'kana', 'japanese', 'hiragana_wsym', 'kana_wsym', 'japanese_wsym']
                
    
                  type_of_string("自動車")
                  'jouyou_kanji'
                
    
                  type_of_string("自動車", True)
                  ['jouyou_kanji', 'kanji', 'japanese', 'japanese_wsym']
  6. char_in_set 
    
                  char_in_set(char: str, set_name: str) -> bool

    It returns whether a character is included in a given set.

    The possible return values are those listed under Sets.

    
                  char_in_set("山", "kanji")
                  True
                
    
                  char_in_set("川", "hiragana")
                  False
  7. string_in_set 
    
                  string_in_set(string: str, set_name: str) -> bool

    It returns whether a string is included in a given set.

    The possible return values are those listed under Sets.

    
                  string_in_set("火曜日", "kanji")
                  True
                
    
                  string_in_set("カラオケ", "hiragana")
                  False
  8. type_of_kanji 
    
                  type_of_kanji(char: str) -> str

    This function checks the category of a kanji character.

    
                  type_of_kanji("田")
                  'jouyou_kanji'
                
    
                  type_of_kanji("杏")
                  'jinmeiyou_kanji'
                
    
                  type_of_kanji("炒")
                  'hyougaiji'
Variables
  1. jouyou_kanji 
    
                  jouyou_kanji
                  ('亜', '哀', '挨', '愛', '曖', '悪', '握', '圧', '扱', '宛', '嵐', '安', '案', '暗', '以', '衣', '位', '囲', '医', '依', ...)

    A tuple containing the complete set of 2136 jōyō kanji (常用漢字).

    All data of this dictionary is taken from the official jōyō kanji list published by the Ministry of Education of Japan.

  2. jinmeiyou_kanji 
    
                  jinmeiyou_kanji
                  ('丑', '丞', '乃', '之', '乎', '乘', '也', '云', '亙', '亘', '些', '亞', '亥', '亦', '亨', '亮', '來', '仔', '伊', '伍', ...)

    A tuple containing the complete set of 861 jinmeiyō kanji (人名用漢字).

  3. hyougaiji 
    
                  hyougaiji
                  ('椶', '㐮', '蠐', '棆', '攴', '篗', '髞', '㝢', '攸', '桗', '釭', '沮', '甜', '臘', '噎', '瘜', '𥻂', '蝣', '翏', '瓺', ...)

    A tuple containing 7053 hyōgaiji (表外字). These are not all the hyōgaiji, as there is no official, comprehensive list of them.

  4. jouyou_kanji_dict 
    
                  jouyou_kanji_dict["今"]
                  {
                    "onyomi": [
                        "コン",
                        "キン"
                    ],
                    "kunyomi": [
                        "いま"
                    ],
                    "grade": 2,
                    "irregular": {
                        "今日": "きょう",
                        "今朝": "けさ",
                        "今年": "ことし"
                  }

    A dictionary where every jōyō kanji is a key, and its value is another dictionary containing the following data:

    • "onyomi": a tuple containing the onyomi readings
    • "kunyomi": a tuple containing the kunyomi readings
    • "grade": the grade of the kanji as specified in the official jōyō kanji list. This is different from the JLPT level.
    • "irregular": a dictionary where the keys are words that use that kanji that have an irregular reading, and the values are the readings of those words.

    All data of this dictionary is taken from the official jōyō kanji list published by the Ministry of Education of Japan.

  5. kanji_dict 
    
                  kanji_dict["学"]
                  {
                    "onyomi": [
                        "ガク"
                    ],
                    "kunyomi": [
                        "まなぶ"
                    ],
                    "grade": 1,
                    "irregular": {},
                    "readings": {
                      "がく": ["ガク"],
                      "がっ": ["ガク"],
                      "ま": ["まなぶ"],
                      "まな": ["まなぶ"],
                      "まなぶ": ["まなぶ"],
                      "まなび": ["まなぶ"]
                    }
                  }

    At present, this dictionary is similar to "jouyou_kanji_dictionary", but it adds the key "readings" to the dictionary of each kanji. This dictionary will be updated in the future to include jinmeiyō kanji and hyōgaiji.

    • "onyomi": a tuple containing the onyomi readings.
    • "kunyomi": a tuple containing the kunyomi readings
    • "grade": the grade of the kanji as specified in the official jōyō kanji list. This is different from the JLPT level.
    • "irregular": a dictionary where the keys are words that use that kanji that have an irregular reading, and the values are the readings of those words.
    • "readings": a dictionary in which the keys are potential readings in hiragana and the values are lists of the original onyomi or kunyomi readings. The keys are just potential readings; that is, they may not actually be the real readings of the kanji.

  6. irregular_readings_dict 
    
                  irregular_readings_dict['大人']
                  'おとな'

    A dictionary where the keys are words with irregular readings, and the values are the irregular readings in hiragana.

    All data of this dictionary is taken from the official jōyō kanji list published by the Ministry of Education of Japan.

Other
  1. Sets

    The following sets are used in the functions 'type_of_char', 'type_of_string', 'char_in_set', 'string_in_set' and 'type_of_kanji'.

    • "hiragana"
    • "katakana"
    • "kana": hiragana + katakana
    • "jouyou_kanji"
    • "jinmeiyou_kanji"
    • "hyougaiji"
    • "kanji": jouyou_kanji + jinmeiyou_kanji + hyougaiji
    • "other_ja": 々, ゝ, ゞ, ヽ, ヾ, ヶ, 〆
    • "symbol_ja": ・,（, ）, ～
    • "japanese": kana + kanji + other_ja
    • "hiragana_wsym": hiragana + symbol_ja
    • "katakana_wsym": katakana + symbol_ja
    • "kana_wsym": kana + symbol_ja
    • "japanese_wsym": japanese + symbol_ja
    • "english": english alphabet
    • "symbol_en": ' , . ( ) - ’ /
    • "english_wsym": english + symbol_en
    • "spanish": spanish alphabet
    • "symbol_sp": currently it is the same set as symbol_en
    • "spanish_wsym": spanish + symbol_es
    • "number": 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
    • "unknown": if it is not included in any of the previous categories