Merge pull request #17 from MatrixEditor/dev/py-docs

[DEV] Actions, Message Digests, Documentation Updates
MatrixEditor · Dec 30, 2024 · 21f3d85 · 21f3d85
2 parents 294fd10 + f8cc109
commit 21f3d85
Show file tree

Hide file tree

Showing 63 changed files with 4,216 additions and 871 deletions.
diff --git a/README.md b/README.md
@@ -40,15 +40,20 @@ class Format:
     b: int32
     length: uint8             # String fields with computed lengths
     name: String(this.length) #  -> you can also use Prefixed(uint8)
-    names: CString[uint8::]   # Sequences with prefixed, computed lengths
+    with Md5(name="hash", verify=True): # wraps all following fields and creates a new attr
+        names: CString[uint8::]    # Sequences with prefixed, computed lengths
+
 
 # Instantiation (keyword-only arguments, magic is auto-inferred):
 obj = Format(a=1, b=2, length=3, name="foo", names=["a", "b"])
-# Packing the object:
-blob = pack(obj) # objects of struct classes can be packed right away
-# results in: b'ITS MAGIC\x01\x02\x00\x00\x00\x03foo\x02a\x00b\x00'
-# Unpacking the binary data:
-obj2 = unpack(blob, Format)
+# Packing the object, reads as 'PACK obj FROM Format'
+# objects of struct classes can be packed right away
+blob = pack(obj, Format)
+# results in: b'ITS MAGIC\x01\x02\x00\x00\x00\x03foo\x02a\x00b\x00\xf55...
+
+# Unpacking the binary data, reads as 'UNPACK Format FROM blob'
+obj2 = unpack(Format, blob)
+assert obj2.hash == obj.hash
 ```
 
 This library offers extensive functionality beyond basic struct handling. For further details

diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
@@ -6,6 +6,7 @@
 import os
 
 sys.path.insert(0, os.path.abspath("./extensions/"))
+sys.path.insert(0, os.path.abspath("../../../examples/"))
 sys.path.insert(0, os.path.abspath("../../.."))
 
 # -- Project information -----------------------------------------------------
@@ -63,6 +64,7 @@
 todo_include_todos = False
 
 refcount_file = '../../../src/capi.dat'
+autodoc_member_order = 'bysource'
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst
@@ -117,7 +117,7 @@ what configuration options can be used. Alternatively you can follow the :ref:`t
       Changelog and contributing information.
 
    .. grid-item-card:: C Reference
-      :link: reference/capi/index.html
+      :link: reference/capi/extension.html
 
       Caterpillar C API Reference and extension development.
 

diff --git a/docs/sphinx/source/library/fields/common.rst b/docs/sphinx/source/library/fields/common.rst
@@ -7,9 +7,12 @@ Common Structs
 Numeric Structs
 ---------------
 
-.. autoclass:: caterpillar.py.FormatField
+.. autoclass:: caterpillar.py.PyStructFormattedField
     :members:
 
+    .. versionchanged:: 2.4.0
+        :code:`FormatField` renamed to :code:`PyStructFormattedField`
+
 .. autoattribute:: caterpillar.py.uint8
 
 .. autoattribute:: caterpillar.py.int8
@@ -61,6 +64,9 @@ Bytes, Strings
 .. autoclass:: caterpillar.py.Memory
     :members:
 
+    .. versionchanged:: 2.4.0
+        Removed :code:`encoding` argument
+
 .. autoclass:: caterpillar.py.Bytes
     :members:
 
@@ -70,6 +76,9 @@ Bytes, Strings
 .. autoclass:: caterpillar.py.Prefixed
     :members:
 
+    .. versionadded:: 2.4.0
+        Added support for arbitrary structs
+
 .. autoclass:: caterpillar.py.CString
     :members:
 
@@ -85,6 +94,17 @@ Special Structs
 
 .. autoattribute:: caterpillar.py.Pass
 
+    See source code for details
+
+
+.. autoclass:: caterpillar.py.Aligned
+    :members:
+
+    .. versionadded:: 2.4.0
+
+.. autofunction:: caterpillar.py.align
+
+    .. versionadded:: 2.4.0
 
 .. autoclass:: caterpillar.py.Computed
     :members:
@@ -96,4 +116,13 @@ Special Structs
     :members:
 
 .. autoclass:: caterpillar.py.Const
-    :members:
+    :members:
+
+.. autoclass:: caterpillar.py.Lazy
+    :members:
+
+.. autoclass:: caterpillar.py.Uuid
+    :members:
+
+    .. versionchanged:: 2.4.0
+        :code:`uuid` renamed to :code:`Uuid`
diff --git a/docs/sphinx/source/library/fields/crypto.rst b/docs/sphinx/source/library/fields/crypto.rst
@@ -4,8 +4,16 @@
 Cryptographic Structs
 *********************
 
-Core structs
-------------
+
+Hashes
+------
+
+.. autoclass:: caterpillar.py.Algorithm
+
+.. autoclass:: caterpillar.py.Digest
+
+Ciphers
+-------
 
 .. autoclass:: caterpillar.fields.Encrypted
     :members: