From f1909cdf32198e076ab2dd2780af0f243c26e6b7 Mon Sep 17 00:00:00 2001
From: Animenosekai <40539549+Animenosekai@users.noreply.github.com>
Date: Tue, 15 Aug 2023 18:45:53 +0200
Subject: [PATCH] [update] add examples in datatype docstring

---
 cain/types/arrays.py     |  7 +++++++
 cain/types/binary.py     |  4 ++++
 cain/types/booleans.py   | 13 ++++++++++++-
 cain/types/characters.py | 12 +++++++++++-
 cain/types/enums.py      |  7 +++++++
 cain/types/nonetype.py   | 10 ++++++++++
 cain/types/numbers.py    | 25 +++++++++++++++++++++++++
 cain/types/objects.py    | 24 +++++++++++++++++++++++-
 cain/types/optionals.py  | 11 +++++++++++
 cain/types/ranges.py     | 14 ++++++++++++++
 cain/types/sets.py       | 11 +++++++++++
 cain/types/strings.py    | 12 +++++++++++-
 cain/types/tuples.py     | 11 +++++++++++
 cain/types/types.py      |  9 +++++++++
 cain/types/unions.py     | 12 ++++++++++++
 15 files changed, 178 insertions(+), 4 deletions(-)

diff --git a/cain/types/arrays.py b/cain/types/arrays.py
index fb22c09..b251da6 100644
--- a/cain/types/arrays.py
+++ b/cain/types/arrays.py
@@ -55,6 +55,13 @@
 class Array(Datatype, typing.Generic[typing_extensions.Unpack[T]]):
     """
     Handles the encoding and decoding of arrays.
+
+    Example
+    -------
+    >>> Array[int].encode([1, 2, 3])
+    b'\x00\x03\x00\x00\x00\x01\x00\x02\x00\x03'
+    >>> Array.decode(b'\x00\x03\x00\x00\x00\x01\x00\x02\x00\x03', int)
+    [1, 2, 3]
     """
 
     @staticmethod
diff --git a/cain/types/binary.py b/cain/types/binary.py
index 2a572cf..4d2a5f7 100644
--- a/cain/types/binary.py
+++ b/cain/types/binary.py
@@ -54,6 +54,10 @@ class Binary(Datatype, typing.Generic[typing_extensions.Unpack[T]]):
     >>> class A(Object):
     ...     a: Binary[LONG] # Will be able to take binary blobs as big as 1,099,511,627,776 bytes (~1100 GB) long.
     ...     b: Binary[SHORT] # Will be able to take binary blobs as big as 16,777,216 bytes (~17 MB) long.
+    >>> Binary.encode(b"Hello world")
+    b'\x00\x00\x00\x0bHello world'
+    >>> Binary.decode(b"\x00\x00\x00\x0bHello world")
+    b'Hello world'
     """
 
     @staticmethod
diff --git a/cain/types/booleans.py b/cain/types/booleans.py
index da33526..0e932f9 100644
--- a/cain/types/booleans.py
+++ b/cain/types/booleans.py
@@ -26,6 +26,16 @@
 class Boolean(Datatype):
     """
     Handles the encoding and decoding of booleans.
+
+    Example
+    -------
+    >>> b = Boolean(True)
+    >>> b.encoded
+    b'\x01'
+    >>> Boolean.encode(False)
+    b'\x00'
+    >>> Binary.decode(b'\x01')
+    True
     """
 
     @classmethod
@@ -41,4 +51,5 @@ def _decode(cls, value: bytes, *args):
             return True, value[1:]
         raise errors.DecodingError(cls, "The given value does not seem to be a boolean")
 
-Bool = Boolean
\ No newline at end of file
+
+Bool = Boolean
diff --git a/cain/types/characters.py b/cain/types/characters.py
index a01e198..3d50d12 100644
--- a/cain/types/characters.py
+++ b/cain/types/characters.py
@@ -39,6 +39,16 @@
 class Character(Datatype):
     """
     Handles the encoding and decoding of binary blob.
+
+    Example
+    -------
+    >>> c = Character("a")
+    >>> c.encoded
+    b'a'
+    >>> Character.encode("夏")
+    b'\xe5\xa4\x8f'
+    >>> Character.decode(b'\xe5\xa4\x8f')
+    '夏'
     """
 
     @classmethod
@@ -52,7 +62,7 @@ def _decode(cls, value: bytes, *args):
                 return value[:i].decode("utf-8"), value[i:]
             except UnicodeDecodeError:
                 continue
-        
+
         # In theory, it should never come here
         # Falling back to manual decoding
         # Removing 3 bits at the right of the byte, then checking if it starts with four `1`.
diff --git a/cain/types/enums.py b/cain/types/enums.py
index d2baf5a..e3fe602 100644
--- a/cain/types/enums.py
+++ b/cain/types/enums.py
@@ -25,6 +25,13 @@
 class Enum(Datatype):
     """
     Handles the encoding and decoding of enums.
+
+    Example
+    -------
+    >>> Enum["hello", "world"].encode("hello")
+    b'\x00'
+    >>> Enum["hello", "world"].decode(b"\x00")
+    "hello"
     """
 
     @classmethod
diff --git a/cain/types/nonetype.py b/cain/types/nonetype.py
index 817b065..f5c0cb2 100644
--- a/cain/types/nonetype.py
+++ b/cain/types/nonetype.py
@@ -27,6 +27,16 @@
 class NoneType(Datatype):
     """
     Handles the encoding and decoding of arrays.
+
+    Example
+    -------
+    >>> n = NoneType(None)
+    >>> n.encoded
+    b''
+    >>> NoneType.encode(None)
+    b''
+    >>> NoneType.decode(b'')
+    None
     """
 
     @classmethod
diff --git a/cain/types/numbers.py b/cain/types/numbers.py
index bd86533..8a0fe95 100644
--- a/cain/types/numbers.py
+++ b/cain/types/numbers.py
@@ -72,6 +72,16 @@ class Number(Datatype):
 
     Represents a double precision floating point number, encoded with 64 bits (8 bytes).
     The numbers can range from -1.7e308 to +1.7e308
+
+    Example
+    -------
+    >>> n = Number(3.14)
+    >>> n.encoded
+    b'\x1f\x85\xebQ\xb8\x1e\t@'
+    >>> Number.encode(3.14)
+    b'\x1f\x85\xebQ\xb8\x1e\t@'
+    >>> Number.decode(b'\x1f\x85\xebQ\xb8\x1e\t@')
+    3.14
     """
 
     @classmethod
@@ -91,6 +101,12 @@ class Float(Number):
     Represents a single precision floating point number, encoded with 32 bits (4 bytes).
 
     The numbers can range from -3.4e38 to 3.4e38
+
+    Example
+    -------
+    >>> from cain.types import Int, Float
+    >>> Float.encode(3.14)
+    b'\xc3\xf5H@'
     """
 
     @classmethod
@@ -175,6 +191,15 @@ class Int(Number, typing.Generic[typing_extensions.Unpack[T]]):
         Adds 1 byte to the size of the integer, allowing for greater ranges (can be used multiple times)
     short
         Removes 1 byte from the size of the integer, allowing for smaller ranges (can be used multiple times)
+
+    Example
+    -------
+    >>> Int.encode(3)
+    b'\x00\x03'
+    >>> Int.encode(3, "short")
+    b'\x03'
+    >>> Int[long].encode(3)
+    b'\x00\x00\x03'
     """
 
     @staticmethod
diff --git a/cain/types/objects.py b/cain/types/objects.py
index 11d8c18..3774037 100644
--- a/cain/types/objects.py
+++ b/cain/types/objects.py
@@ -57,7 +57,29 @@
 
 class Object(Datatype):
     """
-    An object which handles the encoding and use of dictionaries
+    An object which handles the encoding and use of dictionaries.
+
+    Example
+    -------
+    >>> class TestObject(Object):
+    ...     username: str
+    ...     favorite_number: int
+    >>> TestObject(username="Anise", favorite_number=2)
+    TestObject({'username': 'Anise', 'favorite_number': 2})
+    >>> TestObject({"username": "Anise", "favorite_number": 2})
+    TestObject({'username': 'Anise', 'favorite_number': 2})
+    >>> TestObject({"username": "Anise"}, favorite_number=2)
+    TestObject({'username': 'Anise', 'favorite_number': 2})
+    >>> TestObject.encode({"username": "Anise", "favorite_number": 2})
+    b'\x00\x00\x00\x02Anise\x00'
+    >>> TestObject.decode(b'\x00\x00\x00\x02Anise\x00')
+    {'favorite_number': 2, 'username': 'Anise'}
+    >>> class TestObject2(Object):
+    ...     name: str
+    ...     username: str
+    ...     favorite_number: int
+    >>> TestObject2.encode({"name": "Anise", "username": "Anise", "favorite_number": 2})
+    b'\x00\x01\x00\x02\x00\x01\x00\x02Anise\x00\x00\x02'
     """
 
     def __init__(self, value: typing.Optional[dict] = None, *args, **kwargs) -> None:
diff --git a/cain/types/optionals.py b/cain/types/optionals.py
index dbc93cc..6094d5e 100644
--- a/cain/types/optionals.py
+++ b/cain/types/optionals.py
@@ -33,6 +33,17 @@
 class Optional(Datatype, typing.Generic[typing_extensions.Unpack[T]]):
     """
     Handles the encoding and decoding of optional elements.
+
+    Example
+    -------
+    >>> Optional.encode("Hello world", str)
+    b'\x01Hello world\x00'
+    >>> Optional.decode(b'\x01Hello world\x00', str)
+    'Hello world'
+    >>> Optional.encode(None, str)
+    b'\x00'
+    >>> Optional.decode(b'\x00', str)
+    None
     """
 
     @classmethod
diff --git a/cain/types/ranges.py b/cain/types/ranges.py
index 652c839..20d619a 100644
--- a/cain/types/ranges.py
+++ b/cain/types/ranges.py
@@ -46,6 +46,20 @@
 class Range(Datatype, typing.Generic[typing_extensions.Unpack[T]]):
     """
     Handles the encoding and decoding of ranges.
+
+    Example
+    -------
+    >>> r = Range(range(0, 4, 2))
+    >>> r.encoded
+    b'\x00\x04\x02'
+    >>> Range.encode(range(0, 4, 2))
+    b'\x00\x04\x02'
+    >>> Range.decode(b'\x00\x04\x02')
+    range(0, 4, 2)
+    >>> for i in Range.decode(b'\x00\x04\x02'):
+    ...     print(i)
+    0
+    2
     """
 
     @classmethod
diff --git a/cain/types/sets.py b/cain/types/sets.py
index 877970f..f492444 100644
--- a/cain/types/sets.py
+++ b/cain/types/sets.py
@@ -35,6 +35,17 @@
 class Set(Datatype, typing.Generic[typing_extensions.Unpack[T]]):
     """
     Handles the encoding and decoding of arrays.
+
+    Example
+    -------
+    >>> Set.encode({"Hello", "world"}, str)
+    b'\x00\x02\x00\x00Hello\x00world\x00'
+    >>> Set.encode({"Hello", 1}, str, int)
+    b'\x00Hello\x00\x00\x01'
+    >>> Set.decode(b'\x00\x02\x00\x00Hello\x00world\x00', str)
+    {'Hello', 'world'}
+    >>> Set[str, int].decode(b'\x00Hello\x00\x00\x01')
+    {'Hello', 1}
     """
 
     @staticmethod
diff --git a/cain/types/strings.py b/cain/types/strings.py
index fd843e9..0129c7a 100644
--- a/cain/types/strings.py
+++ b/cain/types/strings.py
@@ -27,7 +27,17 @@
 
 class String(Datatype):
     """
-    Handles the encoding and decoding of binary blob.
+    Handles the encoding and decoding of strings.
+
+    Example
+    -------
+    >>> s = String("Hello world")
+    >>> s.encoded
+    b'Hello world\x00'
+    >>> String.encode("夏祭り")
+    b'\xe5\xa4\x8f\xe7\xa5\xad\xe3\x82\x8a\x00'
+    >>> String.decode(b'\xe5\xa4\x8f\xe7\xa5\xad\xe3\x82\x8a\x00')
+    '夏祭り'
     """
 
     @classmethod
diff --git a/cain/types/tuples.py b/cain/types/tuples.py
index 24b89ed..7f6b408 100644
--- a/cain/types/tuples.py
+++ b/cain/types/tuples.py
@@ -32,6 +32,17 @@
 class Tuple(Datatype, typing.Generic[typing_extensions.Unpack[T]]):
     """
     Handles the encoding and decoding of tuples.
+
+    Example
+    -------
+    >>> Tuple.encode(("Hello", "world"), str)
+    b'\x00\x02\x00\x00Hello\x00world\x00'
+    >>> Tuple.encode(("Hello", 1), str, int)
+    b'\x00Hello\x00\x00\x01'
+    >>> Tuple.decode(b'\x00\x02\x00\x00Hello\x00world\x00', str)
+    ('Hello', 'world')
+    >>> Tuple[str, int].decode(b'\x00Hello\x00\x00\x01')
+    ('Hello', 1)
     """
 
     @classmethod
diff --git a/cain/types/types.py b/cain/types/types.py
index e8927a0..cd8c976 100644
--- a/cain/types/types.py
+++ b/cain/types/types.py
@@ -26,7 +26,16 @@
 class Type(cain.types.Object):
     """
     Handles the encoding and decoding of types elements.
+
+    Example
+    -------
+    >>> from cain.types.types import Type
+    >>> Type.encode(str)
+    b'\x01\x03\x00\x01\x02\x00\x00\x00\x00\x1a'
+    >>> Type.decode(b'\x01\x03\x00\x01\x02\x00\x00\x00\x00\x1a')
+    String
     """
+
     index: cain.types.UInt8
     """The index of the Datatype in `TYPES_REGISTRY`"""
     name: typing.Optional[str] = None
diff --git a/cain/types/unions.py b/cain/types/unions.py
index a86af1a..54efd4e 100644
--- a/cain/types/unions.py
+++ b/cain/types/unions.py
@@ -44,6 +44,18 @@
 class Union(Datatype, typing.Generic[typing_extensions.Unpack[T]]):
     """
     Handles the encoding and decoding of union elements (elements which can be of different types)
+
+    Example
+    -------
+    >>> Union.encode("Hello world", str)
+    b'Hello world\x00'
+    >>> Union.encode("Hello world", str, int)
+    b'\x00Hello world\x00'
+    >>> Union[str, int].encode(2)
+    b'\x01\x00\x02'
+    >>> from cain.types.numbers import Int, short
+    >>> Union.encode(2, str, Int[short])
+    b'\x01\x02'
     """
 
     @classmethod