Update docs

Author: yukinarit

Makefile

@@ -1,6 +1,6 @@
 .PHONY: all setup build test coverage pep8 mypy fmt docs open-docs bench
 
-all: setup test pep8 mypy
+all: setup test pep8 mypy docs
 
 setup:
 	pipenv install --dev

docs/de.html

@@ -45,9 +45,11 @@ <h1 class="title">Module <code>serde.de</code></h1>
 parts of pyserde.
 &#34;&#34;&#34;
 import abc
+import functools
 from dataclasses import dataclass, fields, is_dataclass
 from typing import Any, Dict, List, Optional, Tuple, Type, Union
 
+import jinja2
 import stringcase
 
 from .compat import assert_type, is_dict, is_list, is_opt, is_tuple, is_union, iter_types, type_args, typename
@@ -95,8 +97,8 @@ <h1 class="title">Module <code>serde.de</code></h1>
     def wrap(cls) -&gt; Type:
         if not hasattr(cls, HIDDEN_NAME):
             setattr(cls, HIDDEN_NAME, Hidden())
-        cls = de_func(cls, FROM_ITER, args_from_iter(cls))
-        cls = de_func(cls, FROM_DICT, args_from_dict(cls, case=rename_all))
+        cls = de_func(cls, FROM_ITER, render_from_iter(cls))
+        cls = de_func(cls, FROM_DICT, render_from_dict(cls, case=rename_all))
         return cls
 
     if _cls is None:
@@ -131,7 +133,7 @@ <h1 class="title">Module <code>serde.de</code></h1>
     &#34;&#34;&#34;
 
     @abc.abstractclassmethod
-    def deserialize(self, data, **opts):
+    def deserialize(cls, data, **opts):
         &#34;&#34;&#34;
         deserialize `data` into an object typically `dict`, `list` or `tuple`.
 
@@ -180,7 +182,7 @@ <h1 class="title">Module <code>serde.de</code></h1>
     &gt;&gt;&gt;
     &#34;&#34;&#34;
     if de:
-        o = de().deserialize(o, **opts)
+        o = de.deserialize(o, **opts)
     if o is None:
         v = None
     if is_deserializable(c):
@@ -439,12 +441,32 @@ <h1 class="title">Module <code>serde.de</code></h1>
     return s
 
 
-def de_func(cls: Type[T], funcname: str, params: str) -&gt; Type[T]:
+def render_from_iter(cls: Type) -&gt; str:
+    template = &#34;&#34;&#34;
+def {{func}}(data):
+  return cls({{cls|args}})
     &#34;&#34;&#34;
-    Generate function to deserialize into an instance of `deserialize` class.
+
+    env = jinja2.Environment(loader=jinja2.DictLoader({&#39;iter&#39;: template}))
+    env.filters.update({&#39;args&#39;: args_from_iter})
+    return env.get_template(&#39;iter&#39;).render(func=FROM_ITER, cls=cls)
+
+
+def render_from_dict(cls: Type, case: Optional[str] = None) -&gt; str:
+    template = &#34;&#34;&#34;
+def {{func}}(data):
+  return cls({{cls|args}})
     &#34;&#34;&#34;
-    body = f&#39;def {funcname}(data):\n&#39; f&#39;  return cls({params})&#39;
 
+    env = jinja2.Environment(loader=jinja2.DictLoader({&#39;dict&#39;: template}))
+    env.filters.update({&#39;args&#39;: functools.partial(args_from_dict, case=case)})
+    return env.get_template(&#39;dict&#39;).render(func=FROM_DICT, cls=cls)
+
+
+def de_func(cls: Type[T], func: str, code: str) -&gt; Type[T]:
+    &#34;&#34;&#34;
+    Generate function to deserialize into an instance of `deserialize` class.
+    &#34;&#34;&#34;
     # Collect types to be used in the `exec` scope.
     g: Dict[str, Any] = globals().copy()
     for typ in iter_types(cls):
@@ -458,11 +480,11 @@ <h1 class="title">Module <code>serde.de</code></h1>
     g[&#39;NoneType&#39;] = type(None)
 
     # Generate deserialize function.
-    code = gen(body, g, cls=cls)
-    setattr(cls, funcname, staticmethod(g[funcname]))
+    code = gen(code, g, cls=cls)
+    setattr(cls, func, staticmethod(g[func]))
     if SETTINGS[&#39;debug&#39;]:
         hidden = getattr(cls, HIDDEN_NAME)
-        hidden.code[funcname] = code
+        hidden.code[func] = code
 
     return cls</code></pre>
 </details>
@@ -690,8 +712,8 @@ <h2 class="section-title" id="header-functions">Functions</h2>
     def wrap(cls) -&gt; Type:
         if not hasattr(cls, HIDDEN_NAME):
             setattr(cls, HIDDEN_NAME, Hidden())
-        cls = de_func(cls, FROM_ITER, args_from_iter(cls))
-        cls = de_func(cls, FROM_DICT, args_from_dict(cls, case=rename_all))
+        cls = de_func(cls, FROM_ITER, render_from_iter(cls))
+        cls = de_func(cls, FROM_DICT, render_from_dict(cls, case=rename_all))
         return cls
 
     if _cls is None:
@@ -778,7 +800,7 @@ <h3 id="containers">Containers</h3>
     &gt;&gt;&gt;
     &#34;&#34;&#34;
     if de:
-        o = de().deserialize(o, **opts)
+        o = de.deserialize(o, **opts)
     if o is None:
         v = None
     if is_deserializable(c):
@@ -872,7 +894,7 @@ <h2 class="section-title" id="header-classes">Classes</h2>
     &#34;&#34;&#34;
 
     @abc.abstractclassmethod
-    def deserialize(self, data, **opts):
+    def deserialize(cls, data, **opts):
         &#34;&#34;&#34;
         deserialize `data` into an object typically `dict`, `list` or `tuple`.
 
@@ -883,10 +905,10 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 </details>
 <h3>Subclasses</h3>
 <ul class="hlist">
+<li><a title="serde.toml.TomlDeserializer" href="toml.html#serde.toml.TomlDeserializer">TomlDeserializer</a></li>
 <li><a title="serde.msgpack.MsgPackDeserializer" href="msgpack.html#serde.msgpack.MsgPackDeserializer">MsgPackDeserializer</a></li>
 <li><a title="serde.yaml.YamlDeserializer" href="yaml.html#serde.yaml.YamlDeserializer">YamlDeserializer</a></li>
 <li><a title="serde.json.JsonDeserializer" href="json.html#serde.json.JsonDeserializer">JsonDeserializer</a></li>
-<li><a title="serde.toml.TomlDeserializer" href="toml.html#serde.toml.TomlDeserializer">TomlDeserializer</a></li>
 </ul>
 <h3>Static methods</h3>
 <dl>
@@ -901,7 +923,7 @@ <h3>Static methods</h3>
 <details class="source">
 <summary>Source code</summary>
 <pre><code class="python">@abc.abstractclassmethod
-def deserialize(self, data, **opts):
+def deserialize(cls, data, **opts):
     &#34;&#34;&#34;
     deserialize `data` into an object typically `dict`, `list` or `tuple`.
 

docs/index.html

@@ -70,10 +70,67 @@ <h2 id="features">Features</h2>
 </ul>
 </li>
 <li>Class attributes<ul>
-<li>Case conversion e.g. camelCase, kebab-case</li>
+<li><a href="#case-conversion">Case conversion</a> e.g. camelCase, kebab-case</li>
 </ul>
 </li>
+<li>Field attributes<ul>
+<li><a href="#rename-field">Rename</a></li>
+<li><a href="#skip-field">Skip</a></li>
+<li><a href="#skip-if-value-is-evaluated-as-false">Skip if value is evaluated as False</a></li>
 </ul>
+</li>
+</ul>
+<h3 id="case-conversion">Case conversion</h3>
+<pre><code class="python">&gt;&gt;&gt; @serialize(rename_all = 'camelcase')
+... @dataclass
+... class Hoge:
+...     int_field: int
+...     str_field: str
+&gt;&gt;&gt;
+&gt;&gt;&gt; to_json(Hoge(int_field=10, str_field='hoge'))
+'{&quot;intField&quot;: 10, &quot;strField&quot;: &quot;hoge&quot;}'
+</code></pre>
+<h3 id="rename-field">Rename field</h3>
+<pre><code class="python">&gt;&gt;&gt; @serialize
+... @dataclass
+... class Hoge:
+...     # Use 'class_name' because 'class' is a keyword.
+...     class_name: str = field(metadata={'serde_rename': 'class'})
+&gt;&gt;&gt; to_json(Hoge(class_name='Hoge'))
+'{&quot;class&quot;: &quot;Hoge&quot;}'
+</code></pre>
+<p>For complete example, please see <a href="./examples/rename.py">./examples/rename.py</a></p>
+<h3 id="skip-field">Skip field</h3>
+<pre><code class="python">&gt;&gt;&gt; @serialize
+... @dataclass
+... class Resource:
+...     name: str
+...     hash: str
+...     metadata: Dict[str, str] = field(default_factory=dict, metadata={'serde_skip': True})
+
+&gt;&gt;&gt; resources = [
+...     Resource(&quot;Stack Overflow&quot;, &quot;b6469c3f31653d281bbbfa6f94d60fea130abe38&quot;),
+...     Resource(&quot;GitHub&quot;, &quot;5cb7a0c47e53854cd00e1a968de5abce1c124601&quot;, metadata={&quot;headquarters&quot;: &quot;San Francisco&quot;}) ]
+&gt;&gt;&gt; to_json(resources)
+'[{&quot;name&quot;: &quot;Stack Overflow&quot;, &quot;hash&quot;: &quot;b6469c3f31653d281bbbfa6f94d60fea130abe38&quot;}, {&quot;name&quot;: &quot;GitHub&quot;, &quot;hash&quot;: &quot;5cb7a0c47e53854cd00e1a968de5abce1c124601&quot;}]'
+</code></pre>
+<p>For complete example, please see <a href="./examples/skip.py">./examples/skip.py</a></p>
+<h3 id="skip-if-value-is-evaluated-as-false">Skip if value is evaluated as False</h3>
+<pre><code class="python">&gt;&gt;&gt; @serialize
+... @dataclass
+... class World:
+...     player: str
+...     enemies: List[str] = field(default_factory=list, metadata={'serde_skip_if_false': True})
+
+&gt;&gt;&gt; world = World('satoshi', ['Rattata', 'Pidgey'])
+&gt;&gt;&gt; to_json(world)
+'{&quot;player&quot;: &quot;satoshi&quot;, &quot;enemies&quot;: [&quot;Rattata&quot;, &quot;Pidgey&quot;]}'
+
+&gt;&gt;&gt; world = World('green', [])
+&gt;&gt;&gt; print(to_json(world))
+'{&quot;player&quot;: &quot;green&quot;}'
+</code></pre>
+<p>For complete example, please see <a href="./examples/skip.py">./examples/skip.py</a></p>
 <h2 id="documentation">Documentation</h2>
 <p><a href="https://yukinarit.github.io/pyserde/">https://yukinarit.github.io/pyserde/</a></p>
 <details class="source">
@@ -144,7 +201,13 @@ <h1>Index</h1>
 <li><a href="#pyserde">pyserde</a><ul>
 <li><a href="#installation">Installation</a></li>
 <li><a href="#quickstart">QuickStart</a></li>
-<li><a href="#features">Features</a></li>
+<li><a href="#features">Features</a><ul>
+<li><a href="#case-conversion">Case conversion</a></li>
+<li><a href="#rename-field">Rename field</a></li>
+<li><a href="#skip-field">Skip field</a></li>
+<li><a href="#skip-if-value-is-evaluated-as-false">Skip if value is evaluated as False</a></li>
+</ul>
+</li>
 <li><a href="#documentation">Documentation</a></li>
 </ul>
 </li>

docs/json.html

@@ -27,24 +27,23 @@ <h1 class="title">Module <code>serde.json</code></h1>
 
 from .core import T
 from .de import Deserializer, from_obj
-from .se import Serializer, is_serializable, asdict
+from .se import Serializer, asdict, is_serializable
 
 
 class JsonSerializer(Serializer):
-    def serialize(self, obj: Any, **opts) -&gt; str:
+    @classmethod
+    def serialize(cls, obj: Any, **opts) -&gt; str:
         return json.dumps(asdict(obj), **opts)
 
 
 class JsonDeserializer(Deserializer):
-    def deserialize(self, s, **opts):
+    @classmethod
+    def deserialize(cls, s, **opts):
         return json.loads(s, **opts)
 
 
-def to_json(obj: Any, serializer=JsonSerializer) -&gt; str:
-    if is_serializable(obj):
-        return obj.__serde_serialize__(serializer)
-    else:
-        return json.dumps(obj)
+def to_json(obj: Any, cls: Type[JsonSerializer] = JsonSerializer) -&gt; str:
+    return cls.serialize(obj)
 
 
 def from_json(c: Type[T], s: str, de: Type[Deserializer] = JsonDeserializer, **opts) -&gt; T:
@@ -70,17 +69,14 @@ <h2 class="section-title" id="header-functions">Functions</h2>
 </details>
 </dd>
 <dt id="serde.json.to_json"><code class="name flex">
-<span>def <span class="ident">to_json</span></span>(<span>obj, serializer=<class 'serde.json.JsonSerializer'>)</span>
+<span>def <span class="ident">to_json</span></span>(<span>obj, cls=<class 'serde.json.JsonSerializer'>)</span>
 </code></dt>
 <dd>
 <section class="desc"></section>
 <details class="source">
 <summary>Source code</summary>
-<pre><code class="python">def to_json(obj: Any, serializer=JsonSerializer) -&gt; str:
-    if is_serializable(obj):
-        return obj.__serde_serialize__(serializer)
-    else:
-        return json.dumps(obj)</code></pre>
+<pre><code class="python">def to_json(obj: Any, cls: Type[JsonSerializer] = JsonSerializer) -&gt; str:
+    return cls.serialize(obj)</code></pre>
 </details>
 </dd>
 </dl>
@@ -98,7 +94,8 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <details class="source">
 <summary>Source code</summary>
 <pre><code class="python">class JsonDeserializer(Deserializer):
-    def deserialize(self, s, **opts):
+    @classmethod
+    def deserialize(cls, s, **opts):
         return json.loads(s, **opts)</code></pre>
 </details>
 <h3>Ancestors</h3>
@@ -124,23 +121,25 @@ <h3>Inherited members</h3>
 <details class="source">
 <summary>Source code</summary>
 <pre><code class="python">class JsonSerializer(Serializer):
-    def serialize(self, obj: Any, **opts) -&gt; str:
+    @classmethod
+    def serialize(cls, obj: Any, **opts) -&gt; str:
         return json.dumps(asdict(obj), **opts)</code></pre>
 </details>
 <h3>Ancestors</h3>
 <ul class="hlist">
 <li><a title="serde.se.Serializer" href="se.html#serde.se.Serializer">Serializer</a></li>
 </ul>
-<h3>Methods</h3>
+<h3>Static methods</h3>
 <dl>
 <dt id="serde.json.JsonSerializer.serialize"><code class="name flex">
-<span>def <span class="ident">serialize</span></span>(<span>self, obj, **opts)</span>
+<span>def <span class="ident">serialize</span></span>(<span>obj, **opts)</span>
 </code></dt>
 <dd>
 <section class="desc"></section>
 <details class="source">
 <summary>Source code</summary>
-<pre><code class="python">def serialize(self, obj: Any, **opts) -&gt; str:
+<pre><code class="python">@classmethod
+def serialize(cls, obj: Any, **opts) -&gt; str:
     return json.dumps(asdict(obj), **opts)</code></pre>
 </details>
 </dd>

docs/msgpack.html

@@ -33,12 +33,14 @@ <h1 class="title">Module <code>serde.msgpack</code></h1>
 
 
 class MsgPackSerializer(Serializer):
-    def serialize(self, obj: Any, **opts) -&gt; str:
+    @classmethod
+    def serialize(cls, obj: Any, **opts) -&gt; str:
         return msgpack.packb(astuple(obj), **opts)
 
 
 class MsgPackDeserializer(Deserializer):
-    def deserialize(self, s, **opts):
+    @classmethod
+    def deserialize(cls, s, **opts):
         unp = msgpack.unpackb(s, raw=False, use_list=False, **opts)
         logger.debug(&#39;unpack from msgpack: {unp}&#39;)
         return unp
@@ -96,7 +98,8 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <details class="source">
 <summary>Source code</summary>
 <pre><code class="python">class MsgPackDeserializer(Deserializer):
-    def deserialize(self, s, **opts):
+    @classmethod
+    def deserialize(cls, s, **opts):
         unp = msgpack.unpackb(s, raw=False, use_list=False, **opts)
         logger.debug(&#39;unpack from msgpack: {unp}&#39;)
         return unp</code></pre>
@@ -124,23 +127,25 @@ <h3>Inherited members</h3>
 <details class="source">
 <summary>Source code</summary>
 <pre><code class="python">class MsgPackSerializer(Serializer):
-    def serialize(self, obj: Any, **opts) -&gt; str:
+    @classmethod
+    def serialize(cls, obj: Any, **opts) -&gt; str:
         return msgpack.packb(astuple(obj), **opts)</code></pre>
 </details>
 <h3>Ancestors</h3>
 <ul class="hlist">
 <li><a title="serde.se.Serializer" href="se.html#serde.se.Serializer">Serializer</a></li>
 </ul>
-<h3>Methods</h3>
+<h3>Static methods</h3>
 <dl>
 <dt id="serde.msgpack.MsgPackSerializer.serialize"><code class="name flex">
-<span>def <span class="ident">serialize</span></span>(<span>self, obj, **opts)</span>
+<span>def <span class="ident">serialize</span></span>(<span>obj, **opts)</span>
 </code></dt>
 <dd>
 <section class="desc"></section>
 <details class="source">
 <summary>Source code</summary>
-<pre><code class="python">def serialize(self, obj: Any, **opts) -&gt; str:
+<pre><code class="python">@classmethod
+def serialize(cls, obj: Any, **opts) -&gt; str:
     return msgpack.packb(astuple(obj), **opts)</code></pre>
 </details>
 </dd>