add support for Japanese (JA)

README.rst

@@ -48,7 +48,7 @@ There's only one function to use::
     >>> num2words(42, lang='fr')
     quarante-deux
 
-Besides the numerical argument, there's two optional arguments.
+Besides the numerical argument, there are two main optional arguments.
 
 **to:** The converter to use. Supported values are:
 
@@ -78,6 +78,7 @@ Besides the numerical argument, there's two optional arguments.
 * ``he`` (Hebrew)
 * ``id`` (Indonesian)
 * ``it`` (Italian)
+* ``ja`` (Japanese)
 * ``lt`` (Lithuanian)
 * ``lv`` (Latvian)
 * ``no`` (Norwegian)
@@ -101,6 +102,58 @@ Therefore, if you want to call ``num2words`` with a fallback, you can do::
     except NotImplementedError:
         return num2words(42, lang='en')
 
+Additionally, some converters and languages support other optional arguments
+that are needed to make the converter useful in practice.
+
+**ja (Japanese)**
+
+**reading:** whether or not to return the reading of the converted number.
+Also has the special value ``"arabic"`` when used with ``year``::
+
+    >>> num2words(42, lang='ja', reading=True)
+    よんじゅうに
+    >>> num2words(2017, lang='ja', to='year', reading='arabic')
+    平成29年
+
+**prefer:** when there are multiple readings or (kanji) words available,
+prefer those in the sequence ``prefer``::
+
+    >>> num2words(0, lang='ja')
+    零
+    >>> num2words(0, lang='ja', prefer=['〇'])
+    〇
+    >>> num2words(42, lang='ja', reading=True, prefer=['し'])
+    しじゅうに
+    >>> num2words(74, lang='ja', reading=True)
+    ななじゅうよん
+    >>> num2words(74, lang='ja', reading=True, prefer=['し', 'しち'])
+    しちじゅうし
+    >>> num2words(1375, lang='ja', to="year")
+    天授元年
+    >>> num2words(1375, lang='ja', to="year", prefer=['えいわ'])
+    永和元年
+
+**era:** (``year`` only) whether or not to convert the year to the era
+calendar format. Defaults to ``True``::
+
+    >>> num2words(2017, lang='ja', to='year', era=True)
+    平成二十九年
+    >>> num2words(2017, lang='ja', to='year', reading=True, era=True)
+    へいせいにじゅうくねん
+    >>> num2words(2017, lang='ja', to='year', era=False)
+    二千十七年
+
+**counter:** (``ordinal`` and ``ordinal_num`` only) which counter to use with
+the ordinal number. Defaults to ``番`` and only supports ``reading`` with
+it::
+
+    >>> num2words(0, lang='ja', to='ordinal')
+    零番目
+    >>> num2words(1, lang='ja', to='ordinal', counter='人')
+    一人目
+    >>> num2words(1, lang='ja', to='ordinal', reading=True, counter='人')
+    NotImplementedError: Reading not implemented for 人
+
 History
 -------
 

num2words/__init__.py

@@ -31,6 +31,7 @@
 from . import lang_PL
 from . import lang_RU
 from . import lang_ID
+from . import lang_JA
 from . import lang_NO
 from . import lang_DK
 from . import lang_PT_BR
@@ -59,6 +60,7 @@
     'es_CO': lang_ES_CO.Num2Word_ES_CO(),
     'es_VE': lang_ES_VE.Num2Word_ES_VE(),
     'id': lang_ID.Num2Word_ID(),
+    'ja': lang_JA.Num2Word_JA(),
     'lt': lang_LT.Num2Word_LT(),
     'lv': lang_LV.Num2Word_LV(),
     'pl': lang_PL.Num2Word_PL(),

num2words/compat.py

@@ -15,6 +15,12 @@
 # MA 02110-1301 USA
 
 
+try:
+    strtype = basestring
+except NameError:
+    strtype = str
+
+
 def to_s(val):
     try:
         return unicode(val)