pykakasi - Man Page

"convert" returns result as dictionary. There are keys: 'orig', 'kana', 'hira', 'hepburn', 'kunrei', 'passport'

Example:

kks = pykakasi.kakasi()
text = 'かな漢字'
result = kks.convert(text)
for item in result:
    print("{}: kana '{}', hiragana '{}', romaji: '{}'".format(item['orig'], item['kana'], item['hira'], item['hepburn']))

かな: kana 'カナ', hiragana: 'かな', romaji: 'kana'
漢字: kana 'カンジ', hiragana: 'かんじ', romaji: 'kanji'

WARNING:

The OLD v1.2 API, wakati class, and setMode(), getConverter() and do() functions,  will be deprecated when v3.0 released. Please consider to use convert() method.

These switch alphabets are derived from original Kakasi. Now it support following options:

Each character means character sets as follows:

Character Sets
   a: ascii  j: jisroman  g: graphic  k: kana
   (j,k     defined in jisx0201)
   E: kigou  K: katakana  H: hiragana J: kanji
   (E,K,H,J defined in jisx0208)

How to Install:

pip install pykakasi

Building library, setup script build dictionary db file and generate pickled db files. Without dictionary files, a library fails to run.

Sample source code:

from pykakasi import kakasi,wakati

text = u"かな漢字交じり文"
kakasi = kakasi()
kakasi.setMode("H","a") # Hiragana to ascii, default: no conversion
kakasi.setMode("K","a") # Katakana to ascii, default: no conversion
kakasi.setMode("J","a") # Japanese to ascii, default: no conversion
kakasi.setMode("r","Hepburn") # default: use Hepburn Roman table
kakasi.setMode("s", True) # add space, default: no separator
kakasi.setMode("C", True) # capitalize, default: no capitalize
conv = kakasi.getConverter()
result = conv.do(text)
print(result)

wakati = wakati()
conv = wakati.getConverter()
result = conv.do(text)
print(result)

You can use output Mode values from "H", "K", "a" which is each means "Hiragana", "Katakana" and "Alphabet". For input, you can use "J" that means "Japanese" that is mixture of Kanji, Katakana and Hiragana. Also there is values of "H", "K" that means "Hiragana", and "Katakana". You can use  "Hepburn" , "Kunrei" or "Passport" as mode "r", Roman table switch. Also "s" used for separator switch, "C" for capitalize switch. "S" for separator storing option.

Transliterate Japanese text to rōmaji:

>>> import pykakasi
>>>
>>> text = u"かな漢字交じり文"
>>> kakasi = pykakasi.kakasi()
>>> kakasi.setMode("H","a") # Hiragana to ascii, default: no conversion
>>> kakasi.setMode("K","a") # Katakana to ascii, default: no conversion
>>> kakasi.setMode("J","a") # Japanese to ascii, default: no conversion
>>> kakasi.setMode("r","Hepburn") # default: use Hepburn Roman table
>>> kakasi.setMode("s", True) # add space, default: no separator
>>> kakasi.setMode("C", True) # capitalize, default: no capitalize
>>> conv = kakasi.getConverter()
>>> result = conv.do(text)
>>> print(result)
kana Kanji Majiri Bun

Tokenize Japanese text (split by word boundaries), equivalent to kakasi's wakati gaki option:

>>> wakati = pykakasi.wakati()
>>> conv = wakati.getConverter()
>>> result = conv.do(text)
>>> print(result)
かな 漢字 交じり 文

Add furigana (pronounciation aid) in rōmaji to text:

>>> kakasi = pykakasi.kakasi()
>>> kakasi.setMode("J","aF") # Japanese to furigana
>>> kakasi.setMode("H","aF") # Japanese to furigana
>>> conv = kakasi.getConverter()
>>> result = conv.do(text)
>>> print(result)
かな[kana] 漢字[Kanji] 交じり[Majiri] 文[Bun]

Input mode values: "J" (Japanese: kanji, hiragana and katakana), "H" (hiragana), "K" (katakana).

Output mode values: "H" (hiragana), "K" (katakana), "a" (alphabet / rōmaji), "aF" (furigana in rōmaji).

There are other setMode switches which control output:

• "r": Romanisation table: Hepburn (default), Kunrei or Passport
• "s": Separator: False adds no spaces between words (default), True adds spaces between words
• "C": Capitalize: False adds no capital letters (default), True makes each word start with a capital letter

--version,  -v

Display version

--help,  -h

Display help text

--input,  -i <filename>

input file name

--output,  -o <filename>

output file name

Command line executable return codes:

0. convert successful

--wakati,  -w

wakati gaki mode

-f

furigana mode

These switch alphabets are derived from original Kakasi.

-K

How convert Katakana to: a,H,None

-H

How convert Hiragana to: a,K,None

-J

How convert Kanji to: a,H,K,None

-a

How convert ASCII Roman to: E,None

-E

How convert JIS Roman to: a,None

Each character means character sets as follows:

 Character Sets
a: ascii  j: jisroman  g: graphic  k: kana
(j,k     defined in jisx0201)
E: kigou  K: katakana  H: hiragana J: kanji
(E,K,H,J defined in jisx0208)

-U

Output characters in uppercase

-C

Capitalize first roman character of each words

--space,  -s

Insert space character between words

--roman,  -r <h|k|p>

Roman word conversion rule it takes following keywords:

- h: hepburn
- k: kunrei
- p: passport

--separator,  -S <character>

Specify separator character for inserting between words

• Project owner: Hiroshi Miura
• Slack chat: Join to  https://pykakasi.slack.com/
• Bug Tracker:  Github issue Tracker
• Status: alpha
• Activity: low

Every report to github issue tracker should be triaged whether it is bug, question or invalid.

Here is small amount rule when you want to send patch the project;

1.

every proposal for modification should send as 'Pull Request'

1.

each pull request can consist of multiple commits.

1.

you are encourage to split modifications to individual commits that are logical subpart.

Pykakasi project configured to use AppVeyor, Travis-CI and CoverAlls for regression test. You can see test results on badge and see details in a web page linked from badge. The results are also notified in gitter channel.

To run test, you can do it as ordinary:

python setup.py test

or:

pytest

You can also run test using pyenv/tox with versions:

pyenv install 2.7.13
pyenv install 3.5.5
pyenv install 3.6.4
pyenv local 2.7.13, 3.5.5, 3.6.4
tox

• backtrack matching mechanism(#132)

• Support Latin-1 characters (#150,#152)
• Bump pytest>7
• Depend importlib_resources only for 3.8.*

• Add Zenkaku-Question(uFF1F) and other Zenkaku marks as endmark (#146)
• Configure pytest to recognize "src" project structure
• Compatibility from python 3.8 - 3.18 with importlib_resources
• Properly handle punctuation to separate it from previous string (#163, #168)

• dictionary: add noun and adjectives from UniDic(#140)

• Refactoring main loop logics for convert()(#144)

• Fix segmentation (wakati) when combination with Katakana and Hiragana(#142)

• Provide Kakasi.normalize(text) class method
• Add unidic data into data (not used yet), and add parse utility.

• Put type hint stub into package
• Copyright notifications

• Expand all cletter into dictionary (#139)
• Change primary kanwadict index from str to int
• test: gather all legacy test into test_pykakasi_legacy.py file.

• Deprecation warning when using old api(#124)
• Add type hint file(pyi) (#124)
• Benchmark test codes(#122)

• Cache internal results and improve performance about 30-40 times.(#128)
• Use standard pickle for database file(#128)
• Exceptions module is now pykakasi, not pykakasi.exceptions

• Dependency for klepto(#128)

• test: Benchmark and profiling (#122)

• Performance: avoid ord() when checking long-mark, speed up about 6%
• Reformat code by black(#121)

• Infinite loop after running for a while, handle independent HW VOICED SOUND MARK (#115, #118)

• Hiragana for Age countersa(#116,#117)

• CLI: use argparse for option parse(#113)

• Handle 思った、言った、行った properly.(#114)
• CI: fix coveralls error

• CI: drop travis-ci test and badge

• CLI: Fix -v and -h option crash on python 3.7 and before (#108).

• CLI: Fix -v and -h option crash (#108).

• Fix convert() to handle Katakana correctly.(#103)

• Update setup.py, setup.cfg, tox.ini(#102)

• Fix convert() misses last part of a text (#99, #100)
• Fix CI, coverage, and coveralls configurations(#101)

• Update test formatting.

• Update test.

• Understand more kanji variations.

• Fix IVS handling to return correct word length to consume.

• Recognize UNICODE standard Ideographic Variation Selector(IVS) and transiliterate when used.(#97)

• Add type hinting.

• Refactoring dictionary generation classes.
• call super() from wakati.__init__()
• test: detection whether tox or raw pytest by TOX_ENV environment variable. When raw pytest, generate dictionaries as fixture. Previous versions uses --runenv option for pytest.

• NewAPI: fix return value when empty input string.

• Update test cases.

• Add guard for unknown symbol code point which lead NoneType error.

• NewAPI: support kunrei and passport roman conversion rule.

• CI: test by github actions

• Support an extended kana(#77) (U0001b150-U0001b152, U0001b164-U0001b167)

• Structured interface of Kakasi class.(#21)

• Github workflows for packaging and release.(#91)

• fix data kakasidict.utf8: “本蓮沼”

• Drop python 2.7 support.

• Fix out-of-index error when kana-dash is placed on first of same character group.(#85)

• Fix Long symble issue(#58) (thanks @northernbird and @ta9ya)

• Add conversions: kya, kyu, kyo

• Rewording README document

• pytest: now run on project root without tox, by generating dictionary as a test fixture.
• tox: run tox test with installed dictionary instead of a generated fixture.
• Optimize kana conversion function.
• Move kakasidict.py to src and conftest.py to tests

• Version naming follows PEP386.
• Sometimes fails to insert space after punctuation(#79).
• Special case in kana-roman passport conversion such as 'etchu' etc.

• Threading test.
• Test with Chinese kanji.
• Test with extended kana which is out of Unicode BSC.
• t flag to specify not to change unkouwn characters to ???.

• Refactoring itaiji and kanwa class as a thread-safe borg class.

• Fix test case issue68_2 for missing characters

• Add few words(#66).

• KeyError when input unknown kanji.(#68)

• Add manual document holder.
• Test on Azure-Pipelines.
• Tox has a check test pipeline
• Add classifier to setup.py

• Drop support for python 3.4 that is end-of-line in March, 2019.
• Add suppot for pypy and tested on Travis-CI.
• Version information on __init__.py
• Use 'tox' and 'pytest' for test runner instead of 'unittest'.

• Fix keyerror for some characters(#68).
• Fix coveralls source code reference.

• Test on AppVeyor

• Implement word split feature by @oxij (#58).

• Improve setup.py build script generating pickled files when build bdist.
• Use pytest and pytest-cov for unittest.
• Use tox for CI/CD in travis-CI and appveyor.

• Kanwadict: remove entry for 市立 as ichiritsu
• Issue #59: fix 0x30f7-30fc katakana convertion to be as same as in Hiragana.
• Appveyor: twine upload credential environment variable name.

• Drop python2.6 and python 3.3 from test target.

• Add test for two type of exceptions
• Add test for Upper case flags
• Add Upper case flag with E2a mode.

• Release source distribution from appveyor.
• Refactoring how to import six

• Exception when converting Fullwidth collon uFF1A (#51)
• Fixed unworking Upper case flag ("U") which causes exception

• Drop canConvert method from itaiji.

• Release wheel binary packages for each python versions.(#50)

• Test case convert from Full-width Alphabet/symbols to Half-width (E2a).
• Convert logic from Full-width alphabet/symbols to Half-width (E2a).
• Add more words with repeat mark from SKK-JISYO.L (#46)

• Not distribute binary wheel package, because of dictionary data depends on python version.

• Conversion from ○々 become 'TypeError: must be str, not NoneType' (#46)
• Appveyor: update deployment script.

• Update release script
• Update version number for kakasi script

• Appveyor: fix twine not found error in deploy script
• setup: clean old dictionary when building

• Russian characters defined in JIS X0208(#13)

• README: fix typo and add description for Kigou conversion.
• README: update sample code to working one.
• Appveyor: generate wheel artifacts

• MANIFEST: update to specify kanwadict3.db explicitly.
• setup.py: allow reading README.rst written in UTF-8.

Here is a release candicate for v1.0

• Readme: add dependency description.

• Bump up version number.
• Readme: recommend 'pip install pykakasi'
• Replace anydbm with semidbm that is a pure dbm implementation with performance.

• Reduce test warnings.
• No platform dependency now.
• Fix dependency in wheel package that depend on gdbm in previous release.

• Binary release for windows and linux.

• wheel platform tag for linux is now manylinux1_i686 or _x86_64

• Use six for python 2 and 3 compatility code.

• Build wheel with platform names.

• Test on Python 3.5 and Python 3.6
• Test on Windows using AppVeyor
• Mesure test coverage and monitor on coveralls.io

• Move dictionary data to pykakasi/data
• Build dictionary when setup.py build
• Recoomend installation from github source not pypi. (#17)
• Converter configuration become per instance not class wide.

• kakasi.py: Fix exception class name typo of InvalidFlagValueException
• kakasi.py, h2a.py, k2a.py: Do not import all exception class.
• test_genkanwadict.py: Multi platform support for temp directory(#27).
• setup.py: change _pre_build() to pre_build() (#17).

• Support following options in kakasi command.

  • same as original kakasi:

    -J{aKH} -K{aH} -H{aK} -E{a}
    -rk -rh
    -w -s -S -C

  • additional options:

    -v --version -h --help
    -O --output: output file
    -I --input: input file

• Change default behavior as almost same as original kakasi
• Zenkaku numbers conversion
• Passport roman conversion table

• Introduced kakasi command
• Symbols support

• Wakati conversion support

• Pickled roman tables

• Work on python 2.6, 2.7, 3.3, 3.4 (Thanks @FGtatsuro)
• Kunrei and Hepburn roman table