fix return types; add user defined kanji function

examples/kanji.py

@@ -45,9 +45,7 @@ p.kanji_text("こんにちは世界！\n")
 p.ln()
 
 p.define_user_defined_kanji(b"\x77\x7e", checkerboard_kanji)
-p._enter_kanji_mode()
-p._raw(b"\x77\x7e")
-p._exit_kanji_mode()
+p.write_user_defined_kanji(b"\x77\x7e")
 p.kanji_text("←外字\n")
 p.delete_user_defined_kanji(b"\x77\x7e")
 p.cut()

setup.cfg

@@ -75,6 +75,6 @@ all =
     pywin32; platform_system=='Windows'
 
 [flake8]
-exclude = .git,.venv,.tox,.github,.eggs,__pycache__,doc/conf.py,build,dist,capabilities-data,test,src/escpos/constants.py
+exclude = .git,venv,.venv,.tox,.github,.eggs,__pycache__,doc/conf.py,build,dist,capabilities-data,test,src/escpos/constants.py
 max-line-length = 120
 extend-ignore = E203, W503

src/escpos/escpos.py

@@ -1507,11 +1507,11 @@ class Escpos(object, metaclass=ABCMeta):
 
         self._raw(BUZZER + six.int2byte(times) + six.int2byte(duration))
 
-    def _enter_kanji_mode(self):
+    def _enter_kanji_mode(self) -> None:
         """Enter Kanji mode."""
         self._raw(KANJI_ENTER_KANJI_MODE)
 
-    def _exit_kanji_mode(self):
+    def _exit_kanji_mode(self) -> None:
         """Exit Kanji mode."""
         self._raw(KANJI_EXIT_KANJI_MODE)
 
@@ -1574,7 +1574,7 @@ class Escpos(object, metaclass=ABCMeta):
         double_width: bool = False,
         double_height: bool = False,
         underline: Literal[0, 1, 2] = 0,
-    ):
+    ) -> None:
         """Set the Kanji print mode.
 
         :param double_width: Doubles the width of the text.
@@ -1592,7 +1592,7 @@ class Escpos(object, metaclass=ABCMeta):
     def set_kanji_underline(
         self,
         underline: Literal[0, 1, 2] = 0,
-    ):
+    ) -> None:
         """Set the Kanji underline mode.
 
         Some printers may only support 1 dot width underline.
@@ -1609,7 +1609,7 @@ class Escpos(object, metaclass=ABCMeta):
         self,
         code: bytes,
         data: bytes,
-    ):
+    ) -> None:
         """Set a user defined Kanji character.
 
         :param code: The Kanji code.
@@ -1620,13 +1620,25 @@ class Escpos(object, metaclass=ABCMeta):
     def delete_user_defined_kanji(
         self,
         code: bytes,
-    ):
+    ) -> None:
         """Delete a user defined Kanji character.
 
         :param code: The Kanji code.
         """
         self._raw(KANJI_DELETE_USER_DEFINED + code)
 
+    def write_user_defined_kanji(
+        self,
+        code: bytes,
+    ) -> None:
+        """Write a user defined Kanji character.
+
+        :param code: The Kanji code.
+        """
+        self._enter_kanji_mode()
+        self._raw(code)
+        self._exit_kanji_mode()
+
     def set_kanji_encoding(
         self,
         encoding: Literal[
@@ -1638,13 +1650,15 @@ class Escpos(object, metaclass=ABCMeta):
             "gb2312",  # FIXME test with real device,
             "gb18030",  # FIXME test with real device,
         ],
-    ):
+    ) -> None:
         """Select the Kanji encoding.
 
         This command is available only for Japanese model printers.
 
         :param code: Encoding.
         :raises ValueError: If the encoding is invalid.
+
+        .. todo:: Test the encodings marked above with `FIXME` with a real device.
         """
         # Japanese model printer have several Kanji encoding modes.
         if (
@@ -1669,7 +1683,7 @@ class Escpos(object, metaclass=ABCMeta):
         self,
         left_spacing: int,
         right_spacing: int,
-    ):
+    ) -> None:
         """Set the Kanji spacing.
 
         Spacing is either 0-255 or 0-32 according to the printer model.
@@ -1684,7 +1698,7 @@ class Escpos(object, metaclass=ABCMeta):
     def set_kanji_quadruple_size(
         self,
         enable: bool,
-    ):
+    ) -> None:
         """Set the Kanji quadruple size.
 
         :param enable: Enable quadruple size.
@@ -1694,7 +1708,7 @@ class Escpos(object, metaclass=ABCMeta):
     def set_kanji_font(
         self,
         font: Literal[0, 1, 2],
-    ):
+    ) -> None:
         """Set the Kanji font.
 
         :param font: The Kanji font.

test/test_functions/test_function_kanji.py

@@ -88,6 +88,13 @@ def test_kanji_text_shift_jis() -> None:
     )
 
 
+def test_kanji_text_without_encoding() -> None:
+    """Test behavior when no encoding is set."""
+    instance = printer.Dummy()
+    with pytest.raises(ValueError):
+        instance.kanji_text("Hello世界Hello")
+
+
 def test_set_kanji_decoration() -> None:
     """should set kanji decoration."""
     instance = printer.Dummy()
@@ -96,7 +103,7 @@ def test_set_kanji_decoration() -> None:
 
     instance = printer.Dummy()
     instance.set_kanji_decoration(double_width=True, double_height=True, underline=1)
-    assert instance.output == KANJI_PRINT_MODE + b"\x0C" + KANJI_UNDERLINE + b"\x01"
+    assert instance.output == KANJI_PRINT_MODE + b"\x0c" + KANJI_UNDERLINE + b"\x01"
 
 
 def test_define_user_defined_kanji() -> None:

tox.ini

@@ -30,6 +30,7 @@ setenv = PY_IGNORE_IMPORTMISMATCH=1
 [testenv:docs]
 basepython = python
 changedir = doc
+passenv = PYENCHANT_LIBRARY_PATH
 deps = sphinx>=7.2.3
        setuptools_scm
        python-barcode>=0.15.0,<1