Merge pull request #560 from K-dash/translate-typecheck-extension-faq-en-to-ja

Translate type-check.md, extension.md, and faq.md to Japanese

Author: yukinarit

docs/ja/extension.md

@@ -0,0 +1,97 @@
+# Extending pyserde
+
+pyserde はビルトイン型以外をサポートするために pyserde を拡張する 3 つの方法を提供しています。
+
+## カスタムフィールド（デ）シリアライザ
+
+詳細は[カスタムフィールドシリアライザ](./field-attributes.md#serializerdeserializer)を参照してください。
+
+> 💡 ヒント：`serde.field` を独自のフィールド関数でラップすると以下のようになります。
+>
+> ```python
+> import serde
+>
+> def field(*args, **kwargs):
+>     serde.field(*args, **kwargs, serializer=str)
+>
+> @serde
+> class Foo:
+>     a: int = field(default=0)  # フィールドシリアライザの設定
+> ```
+
+## カスタムクラス（デ）シリアライザ
+
+詳細は[カスタムクラスシリアライザ](./class-attributes.md#class_serializer--class_deserializer)を参照してください。
+
+## カスタムグローバル（デ）シリアライザ
+
+`add_serializer` と `add_deserializer` を使ってクラス（デ）シリアライザを登録することで、コードベース全体でカスタム（デ）シリアライザを適用できます。
+
+登録されたクラス（デ）シリアライザは pyserde のグローバル空間にスタックされ、すべての pyserde クラスで自動的に使用されます。
+
+例：[isodate](https://pypi.org/project/isodate/)パッケージを使用して `datetime.timedelta` のカスタム（デ）シリアライザを実装する。
+
+以下は、`datetime.timedelta` のためのクラス（デ）シリアライザを登録するコードです。  
+このパッケージは実際に PyPI で [pyserde-timedelta](https://pypi.org/project/pyserde-timedelta/) として公開されています。
+
+```python
+from datetime import timedelta
+from plum import dispatch
+from typing import Type, Any
+import isodate
+import serde
+
+class Serializer:
+    @dispatch
+    def serialize(self, value: timedelta) -> Any:
+        return isodate.duration_isoformat(value)
+
+class Deserializer:
+    @dispatch
+    def deserialize(self, cls: Type[timedelta], value: Any) -> timedelta:
+        return isodate.parse_duration(value)
+
+def init() -> None:
+    serde.add_serializer(Serializer())
+    serde.add_deserializer(Deserializer())
+```
+
+このパッケージの利用者は、 `serde_timedelta.init()` を呼び出すだけで `datetime.timedelta` のカスタム（デ）シリアライザの機能を再利用できます。
+
+```python
+import serde_timedelta
+from serde import serde
+from serde.json import to_json, from_json
+from datetime import timedelta
+
+serde_timedelta.init()
+
+@serde
+class Foo:
+    a: timedelta
+
+f = Foo(timedelta(hours=10))
+json = to_json(f)
+print(json)
+print(from_json(Foo, json))
+```
+
+以下のように `datetime.timedelta` がISO 8601 形式でシリアライズされます！
+
+```bash
+{"a":"PT10H"}
+Foo(a=datetime.timedelta(seconds=36000))
+```
+
+> 💡 ヒント：クラス（デ）シリアライザはいくつでも登録できます。これは、好きなだけpyserde拡張を使用できることを意味します。
+> 登録された（デ）シリアライザはメモリにスタックされます。
+>
+> なお、1つの（デ）シリアライザは他の（デ）シリアライザによってオーバーライドされる可能性があります。
+>
+> 例：次の順序で3つのカスタムシリアライザを登録すると、最初のシリアライザは3番目によって完全に上書きされます。2番目は異なる型用に実装されているため機能します。
+>
+> 1. `int` 用のシリアライザを登録
+> 2. `float` 用のシリアライザを登録
+> 3. `int` 用のシリアライザを登録
+
+こちらは、v0.13.0 で新しく追加されました。

docs/ja/faq.md

@@ -0,0 +1,45 @@
+# FAQ
+
+## pyserdeによって生成されたコードをどのように確認できますか？
+
+pyserdeはコマンドラインとして動作する `inspect` サブモジュールを提供しています。
+```
+python -m serde.inspect <PATH_TO_FILE> <CLASS>
+```
+
+例：pyserdeプロジェクト内で以下を実行します。
+
+```
+cd pyserde
+poetry shell
+python -m serde.inspect examples/simple.py Foo
+```
+
+出力
+```python
+Loading simple.Foo from examples.
+
+==================================================
+                       Foo
+==================================================
+
+--------------------------------------------------
+          Functions generated by pyserde
+--------------------------------------------------
+def to_iter(obj, reuse_instances=True, convert_sets=False):
+    if reuse_instances is Ellipsis:
+        reuse_instances = True
+    if convert_sets is Ellipsis:
+        convert_sets = False
+    if not is_dataclass(obj):
+        return copy.deepcopy(obj)
+
+    Foo = serde_scope.types["Foo"]
+    res = []
+    res.append(obj.i)
+    res.append(obj.s)
+    res.append(obj.f)
+    res.append(obj.b)
+    return tuple(res)
+...
+```

docs/ja/type-check.md

@@ -0,0 +1,92 @@
+# Type Checking
+
+pyserdeはv0.9からランタイム型チェックを提供しています。  
+v0.14で完全に作り直され、[beartype](https://github.com/beartype/beartype)を使用してより洗練され信頼性の高いものとなりました。  
+型安全で堅牢なプログラムを書くためには、型チェックを常に有効にすることを強く推奨します。
+
+## `strict`
+
+厳格な型チェック `strict` は、（デ）シリアライズとオブジェクト構築の際にすべてのフィールド値を宣言された型と照合します。  
+これはv0.14以降のデフォルトの型チェックモードです。
+
+このモードでは、クラス属性を指定せずに `@serde` デコレータを使用してクラスを宣言した場合、`@serde(type_check=strict)` と見なされ、厳格な型チェックが有効になります。
+
+```python
+@serde
+class Foo:
+    s: str
+```
+
+例えば、以下のように間違った型のオブジェクトで`Foo`を呼び出すと、
+```python
+foo = Foo(10)
+```
+
+以下のエラーが発生します。
+```python
+beartype.roar.BeartypeCallHintParamViolation: Method __main__.Foo.__init__() parameter s=10 violates type hint <class 'str'>, as int 10 not instance of str.
+```
+
+> **注記:** 2024年2月時点でbeartypeは検証フックを提供していないため、コンストラクターからはSerdeErrorではなくbeartypeの例外が発生します。
+
+同様に、間違った型のオブジェクトで（デ）シリアライズAPIを呼び出すと、
+
+```python
+print(to_json(foo))
+```
+
+再びエラーが発生します。
+
+```python
+serde.compat.SerdeError: Method __main__.Foo.__init__() parameter s=10 violates type hint <class 'str'>, as int 10 not instance of str.
+```
+
+> **注記:** beartypeによる型チェックにはいくつかの注意点があります。
+>
+> 1. beartypeは変更されたプロパティを検証できません。
+>
+>   以下のコードでは、プロパティ `s` が最後に変更されていますが、beartypeはこのケースを検出できません。
+>   ```python
+>   @serde
+>   class Foo:
+>       s: str
+>
+>   f = Foo("foo")
+>   f.s = 100
+>   ```
+>
+> 2. beartypeはコンテナ内の各要素を検証することはできません。これはバグではなく、beartypeの設計原則です。[Does beartype actually do anything?](https://beartype.readthedocs.io/en/latest/faq/#faq-o1)を参照してください。
+
+## `coerce`
+
+型強制 `coerce` は、（デ）シリアライズ中に値を宣言された型に自動的に変換します。
+
+```python
+@serde(type_check=Coerce)
+class Foo:
+    s: str
+
+foo = Foo(10)
+# pyserdeは自動的に int 値の 10 を str の "10" に変換します
+# {"s": "10"}が出力されます
+print(to_json(foo))
+```
+
+しかし、値が宣言された型に変換できない場合（例えば、値が `foo` で型が `int` の場合）、pyserde は`SerdeError` を発生させます。
+
+## `disabled`
+
+これはpyserde v0.8.3およびv0.9.xまでのデフォルトの挙動です。  
+型強制またはチェックは実行されません。
+
+利用者が間違った値を入力しても、pyserdeは型の不整合を無視して処理を続行します。
+
+```python
+@serde
+class Foo:
+    s: str
+
+foo = Foo(10)
+# pyserdeは型の整合性を確認しないため、{"s": 10} が出力されます
+print(to_json(foo))
+```