structo 0.0.8__tar.gz → 0.0.10__tar.gz

structo-0.0.10/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: structo
+Version: 0.0.10
+Summary: Structify
+Author-email: Ben Brady <benbradybusiness@gmail.com>
+Requires-Python: >=3.14
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: black>=26.1.0 ; extra == "dev"
+Requires-Dist: pytest>=9.0.2 ; extra == "dev"
+Requires-Dist: black ; extra == "docs"
+Requires-Dist: mkdocs ; extra == "docs"
+Requires-Dist: mkdocs-material ; extra == "docs"
+Requires-Dist: mkdocstrings[crystal, python] ; extra == "docs"
+Project-URL: Home, https://nnilky.site
+Provides-Extra: dev
+Provides-Extra: docs

structo-0.0.10/docs/examples/serializer.md

@@ -0,0 +1,33 @@
+## Example
+
+## Optional Int Serializer
+```py
+from
+
+NONE_TYPE_BYTE = bytes([0])
+INT_TYPE_BYTE = bytes([0])
+
+class OptionalIntSerializer(Serializer[OptionalInt]):
+    _int_type: Serializer[int]
+
+    def __init__(self, int_type: Serializer[int]):
+        self._int_type = int_type
+
+    def write(self, f, value):
+        if value is None:
+            f.write(NONE_TYPE_BYTE)
+        else:
+            assert type(value) is int, "Value was not int"
+            f.write(INT_TYPE_BYTE)
+            f.write(self._int_type.write(value))
+
+    def read(self, f):
+        type_byte = f.read(1)
+        if type_byte == NONE_TYPE_BYTE:
+            return None
+
+        if type_byte != INT_TYPE_BYTE:
+            raise ValueError(f"Invalid type byte: {type_byte}")
+
+        return self._int_type.write(f)
+```

structo-0.0.8/examples/wav.py → structo-0.0.10/docs/examples/wav.md

@@ -1,3 +1,8 @@
+# Wav File 
+
+
+```
+import io
 from typing import Annotated
 from structo import uint16_LE, uint32_LE, SerializableObject, Literal
 
@@ -22,11 +27,11 @@ class WavFormat(SerializableObject):
     bits_per_sample: Annotated[int, uint16_LE]
 
 
-with open("example.wav", "rb") as f:
+def read_wav_file(f: io.Reader) -> tuple[WavFormat, bytes]:
     WavHeader.read(f)
 
     format_header = ChunkHeader.read(f)
-    assert format_header.id == b'fmt '
+    assert format_header.id == b"fmt "
 
     format_data = f.read(format_header.size)
     format = WavFormat.from_bytes(format_data)
@@ -34,6 +39,6 @@ with open("example.wav", "rb") as f:
     data_header = ChunkHeader.read(f)
     assert data_header.id == b"data"
     wav_data = f.read(data_header.size)
+    return format, wav_data
 
-print(format)
-print(len(wav_data))
+```

structo-0.0.10/docs/index.md

@@ -0,0 +1,14 @@
+# Structo
+
+Basic
+
+## Commands
+
+* Foo
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

structo-0.0.10/docs/interfaces/serialisable.md

@@ -0,0 +1,68 @@
+# Serializable
+
+In order for classes (such as PackedInts) to be serialiable without having to annotate a serializer, they implement `Serializable`.
+
+This is just means they have a method that returns a serialiazer based on thier class.
+
+```py
+class Serializable:
+    @classmethod
+    def serializer(cls) -> Serializer[t.Self]: ...
+```
+
+For example, for Serili
+```py
+from .serializers import ObjectSerializer
+
+class SerializableObject(Serializable):
+    @classmethod
+    def serializer(cls) -> Serializer[t.Self]:
+        return ObjectSerializer(cls)
+```
+
+## Examples
+
+### Basic Serializable
+
+```py
+from structo import Serializer, Serializable, SerializableObject
+from dataclasses import dataclass
+
+@dataclass
+class UserFlags(Serializable):
+    is_alive: bool
+    is_banned: bool
+    is_admin: bool
+
+    @classmethod
+    def serializer(cls):
+        return UserFlagsSerializer()
+
+
+class UserFlagsSerializer(Serializer[UserFlags]):
+    def write(self, f, value):
+        byte = (
+            int(value.is_alive)  << 0 +
+            int(value.is_admin)  << 1 +
+            int(value.is_banned) << 2
+        )
+        f.write(bytes([byte]))
+
+    def read(self, f):
+        byte = f.read(1)[0]
+        return UserFlags(
+            is_alive  = ((byte >> 0) & 1) == 1,
+            is_admin  = ((byte >> 1) & 1) == 1,
+            is_banned = ((byte >> 2) & 1) == 1
+        )
+
+
+class User(SerializableObject):
+    name: str
+    flags: UserFlags
+
+```
+
+
+
+Note: in this example you could use a packed ints instead

structo-0.0.10/docs/interfaces/serializer.md

@@ -0,0 +1,39 @@
+## Example
+
+## Optional Int Serializer
+```py
+from
+
+NONE_TYPE_BYTE = bytes([0])
+INT_TYPE_BYTE = bytes([0])
+
+class OptionalIntSerializer(Serializer[OptionalInt]):
+    _int_type: Serializer[int]
+
+    def __init__(self, int_type: Serializer[int]):
+        self._int_type = int_type
+
+    def write(self, f, value):
+        if value is None:
+            f.write(NONE_TYPE_BYTE)
+        else:
+            assert type(value) is int, "Value was not int"
+            f.write(INT_TYPE_BYTE)
+            f.write(self._int_type.write(value))
+
+    def read(self, f):
+        type_byte = f.read(1)
+        if type_byte == NONE_TYPE_BYTE:
+            return None
+
+        if type_byte != INT_TYPE_BYTE:
+            raise ValueError(f"Invalid type byte: {type_byte}")
+
+        return self._int_type.write(f)
+```
+
+## Security
+
+You should always treat any data parsed as untrusted and validate this.
+
+If a value should be in a set of contrained values, add an assert.

structo-0.0.10/docs/security.md

@@ -0,0 +1,4 @@
+# Seucrit
+
+Basic
+

structo-0.0.10/docs/types/array.md

@@ -0,0 +1,3 @@
+# Array
+
+TODO

structo-0.0.10/docs/types/blob.md

@@ -0,0 +1,13 @@
+# Blob
+
+A dynamically set of bytes that is prefixed with it's length
+
+## Usage
+
+When creating your own system, always use a uint number. Signed intergers are allows for compatiblity with existing systems
+
+## Examples
+
+```py
+Blob(uint32_BE) # Blob with length stored as uint32bit
+```

structo-0.0.10/docs/types/buffer.md

@@ -0,0 +1,14 @@
+# Buffer
+
+A fixed length of atritrary bytes
+
+## Examples
+
+```py
+foo: Buffer(100) # The next 100 bytes
+
+class Chunk(SerializableObject):
+    chunk_id: Annotated[int, uint32_LE]
+    checksum: Annotated[bytes, Buffer(8)]
+    data: Annotated[bytes, Buffer(4096 - 8 - 4)]
+```

structo-0.0.10/docs/types/list.md

@@ -0,0 +1,13 @@
+# List
+
+A dynaimcally length list of values, prefixed with a length.
+
+You must specifiy the length type and value type
+
+## Examples
+
+```py
+List(String())
+# list[float] with max length of 65536
+List(float32, length=uint16_LE)
+```

structo-0.0.10/docs/types/literal.md

@@ -0,0 +1,13 @@
+# Byte Literal
+
+It's a common pattern to have a fixed literal in a file format, Byte Literal lets you implements this more simply.
+
+## Example
+
+```py
+from structo import Literal
+filetype: Literal(b"mp4")
+
+# You can specify multiple allowed values
+chunk_type: Literal(b"data", b"head", b"fmt ")
+```

structo-0.0.10/docs/types/numbers.md

@@ -0,0 +1,48 @@
+# Number Types
+
+## Endianness
+
+Multi-byte integers have a big endian (`_BE`) and a little endiant (`_LE`) for their different
+[endianness](https://en.wikipedia.org/wiki/Endianness). This determines the order the bytes
+are stored
+
+Modern applications should use **little endian**, however lots of file formats and network
+protocols use **big endian**. Make sure to double check when implementing a protocol.
+
+## Unsigned Integers
+
+Unsigned integers can only be positive.
+
+| Type                | Bytes | Range       | Endianness |
+| ------------------- | ----- | ----------- | ---------- |
+| `structo.uint8`     | 1     | 0 to 255    | None       |
+| `structo.uint16_LE` | 2     | 0 to 65.5k  | little     |
+| `structo.uint16_BE` | 2     | 0 to 65.5k  | big        |
+| `structo.uint32_LE` | 4     | 0 to 4.2B   | little     |
+| `structo.uint32_BE` | 4     | 0 to 4.2B   | big        |
+| `structo.uint64_LE` | 8     | 0 to 1.8e19 | little     |
+| `structo.uint64_BE` | 8     | 0 to 1.8e19 | big        |
+
+## Signed Integers
+
+Signed integers allow negative values and are stored as
+[two's compliment](https://en.wikipedia.org/wiki/Two's_complement).
+
+
+| Type               | Bytes | Range           | Endianness |
+| ------------------ | ----- | --------------- | ---------- |
+| `structo.int8`     | 1     | -128 to 127     | None       |
+| `structo.int16_LE` | 2     | -32.7k to 32.7k | little     |
+| `structo.int16_BE` | 2     | -32.7k to 32.7k | big        |
+| `structo.int32_LE` | 4     | -2.1B to 2.1B   | little     |
+| `structo.int32_BE` | 4     | -2.1B to 2.1B   | big        |
+| `structo.int64_LE` | 8     | -9e18 to 9e18   | little     |
+| `structo.int64_BE` | 8     | -9e18 to 9e18   | big        |
+
+## Floats
+
+| Type               | Bytes | Endianness |
+| ------------------ | ----- | ---------- |
+| `structo.float32`  | 4     | N/A        |
+| `structo.float64`  | 8     | N/A        |
+

structo-0.0.10/docs/types/packed-ints.md

@@ -0,0 +1,15 @@
+# PackedInts
+
+PackedInts lets you pack bits into fewer bytes.
+
+It's total
+
+
+```py
+import structo as st
+
+class Foo(st.PackedInts):
+    type: t.Annotated[int, st.PackedInt(bits=2)]
+    completed: t.Annotated[int, st.PackedInt(bits=1)]
+    b: t.Annotated[int, st.PackedInt(bits=5)]
+```

structo-0.0.10/docs/types/serializable-object.md

@@ -0,0 +1,8 @@
+# Serializable Object
+
+TODO
+## Usage
+
+## Helper Methods
+
+

structo-0.0.10/docs/types/string.md

@@ -0,0 +1,13 @@
+# String
+
+A UTF-8 encoded string with a dynamic length, the length is stored as a prefix.
+
+The length is uint32 by default, meaning a max length of 4.2M characters.
+
+## Examples
+
+```py
+String() # uint32 by default, max length 4.2GB
+String(uint16_LE) # max length 65,536
+String(uint8) # max length 255
+```

structo-0.0.10/examples/custom_serializer.py

@@ -0,0 +1,37 @@
+from typing import Annotated
+from structo import Serializer, Serializable, SerializableObject, String
+from dataclasses import dataclass
+
+
+@dataclass
+class UserFlags(Serializable):
+    is_alive: bool
+    is_banned: bool
+    is_admin: bool
+
+    @classmethod
+    def serializer(cls):
+        return UserFlagsSerializer()
+
+
+class UserFlagsSerializer(Serializer[UserFlags]):
+    def write(self, f, value):
+        byte = (
+            int(value.is_alive)  << 0 |
+            int(value.is_admin)  << 1 |
+            int(value.is_banned) << 2
+        )
+        f.write(bytes([byte]))
+
+    def read(self, f):
+        byte = f.read(1)[0]
+        return UserFlags(
+            is_alive  = ((byte >> 0) & 1) == 1,
+            is_admin  = ((byte >> 1) & 1) == 1,
+            is_banned = ((byte >> 2) & 1) == 1
+        )
+
+
+class User(SerializableObject):
+    name: Annotated[str, String()]
+    flags: UserFlags

{structo-0.0.8 → structo-0.0.10}/examples/iterable_serializer.py

@@ -21,22 +21,23 @@ NULL_TERMINATOR = bytes([0])
 
 
 class PostsSerialiser(Serializer[t.Iterable[Post]]):
-    def write(self, buf, value):
+    def write(self, f, value):
         for item in value:
-            buf.write(CONTINUE_BYTE)
-            item.write(buf)
+            f.write(CONTINUE_BYTE)
+            item.write(f)
 
-        buf.write(NULL_TERMINATOR)
+        f.write(NULL_TERMINATOR)
 
-    def read(self, buf):
+    def read(self, f):
         while True:
-            continue_byte = buf.read(1)
+            continue_byte = f.read(1)
             if continue_byte == NULL_TERMINATOR:
                 break
+
             assert continue_byte == CONTINUE_BYTE, "Continue byte was not 255"
 
             print("Loading...")  # to prove it's interspliced loading and yielding
-            yield Post.read(buf)
+            yield Post.read(f)
 
 
 type PostsIterable = t.Annotated[t.Iterable[Post], PostsSerialiser()]

structo-0.0.10/examples/wav.py

@@ -0,0 +1,39 @@
+import io
+import typing as t
+from typing import Annotated
+from structo import uint16_LE, uint32_LE, SerializableObject, Literal
+
+
+class WavHeader(SerializableObject):
+    chunk_id: Annotated[t.Literal[b"RIFF"], Literal(b"RIFF")]
+    file_size: Annotated[int, uint32_LE]
+    format: Annotated[t.Literal[b"WAVE"], Literal(b"WAVE")]
+
+
+class ChunkHeader(SerializableObject):
+    id: Annotated[t.Literal[b"fmt ", b"data"], Literal(b"fmt ", b"data")]
+    size: Annotated[int, uint32_LE]
+
+
+class WavFormat(SerializableObject):
+    audio_format: Annotated[int, uint16_LE]
+    num_channels: Annotated[int, uint16_LE]
+    sample_rate: Annotated[int, uint32_LE]
+    byte_range: Annotated[int, uint32_LE]
+    block_align: Annotated[int, uint16_LE]
+    bits_per_sample: Annotated[int, uint16_LE]
+
+
+def read_wav_file(f: io.Reader) -> tuple[WavFormat, bytes]:
+    print(WavHeader.read(f))
+
+    format_header = ChunkHeader.read(f)
+    assert format_header.id == b"fmt "
+
+    format_data = f.read(format_header.size)
+    format = WavFormat.from_bytes(format_data)
+
+    data_header = ChunkHeader.read(f)
+    assert data_header.id == b"data"
+    wav_data = f.read(data_header.size)
+    return format, wav_data

structo-0.0.10/mkdocs.yml

@@ -0,0 +1,88 @@
+site_url: https://ben-brady.github.io/structo/
+docs_dir: docs
+
+site_name: Structo
+site_description: Simplified byte serialisation and deseralisation
+site_author: Ben Brady
+repo_name: Structo
+repo_url: https://github.com/Ben-Brady/structo
+
+nav:
+- Introduction:
+  - Home: index.md
+  - Quickstart: introduction/quickstart.md
+- Data Types:
+  - Numbers: types/numbers.md
+  - Buffer: types/buffer.md
+  - Blob: types/blob.md
+  - String: types/string.md
+  - Byte Literals: types/literal.md
+- Container Types:
+  - Serializable Object: types/serializable-object.md
+  - Array: types/array.md
+  - List: types/list.md
+  - Packed Ints: types/packed-ints.md
+- Security: security.md
+
+theme:
+  name: material
+  # favicon: assets/logo-monochrome.svg
+  # logo: assets/logo.svg
+  features:
+    - content.code.copy # Add the copy to clipboard button to code blocks
+    - search # Add the search bar
+    - search.suggest # Add suggestions to search
+    - navigation.top
+    - navigation.tabs # Page tabs at the top
+    - navigation.instant # Preload pages
+    - navigation.tracking # Add anchor tag to url
+  extra:
+    social:
+      - icon: fontawesome/brands/github
+        link: https://github.com/Ben-Brady/structo
+  palette:
+  - media: '(prefers-color-scheme: light)'
+    scheme: default
+    primary: green
+    accent: amber
+    toggle:
+      icon: material/lightbulb
+      name: Switch to dark mode
+  - media: '(prefers-color-scheme: dark)'
+    scheme: slate
+    primary: green
+    accent: amber
+    toggle:
+      icon: material/lightbulb-outline
+      name: Switch to light mode
+
+
+plugins:
+  search: # Add the search bar
+  offline:
+  mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_root_heading: true
+          show_if_no_docstring: true
+          inherited_members: true
+          members_order: source
+          separate_signature: true
+          unwrap_annotated: true
+          filters:
+            - '!^_'
+          merge_init_into_class: true
+          docstring_section_style: spacy
+          signature_crossrefs: true
+          show_symbol_type_heading: true
+          show_symbol_type_toc: true
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences

structo-0.0.10/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["flit_core >=3.11,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "structo"
+authors = [{ name = "Ben Brady", email = "benbradybusiness@gmail.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+dynamic = ["version", "description"]
+requires-python = ">=3.14"
+
+[project.urls]
+Home = "https://nnilky.site"
+
+[project.optional-dependencies]
+dev = ["black>=26.1.0", "pytest>=9.0.2"]
+docs = ["black", "mkdocs", "mkdocs-material", "mkdocstrings[crystal,python]"]

{structo-0.0.8 → structo-0.0.10}/structo/__init__.py

@@ -2,13 +2,12 @@
 Structify
 """
 
-__version__ = "0.0.8"
+__version__ = "0.0.10"
 
-from .serializer import Serializer, Serializable
+from .interfaces import Serializer, Serializable
 from .serialise import get_serializer
-from .object import SerializableObject
-from .packed import PackedInts, PackedInt
-from .types import (
+from .objects import SerializableObject, PackedInt, PackedInts
+from .serializers import (
     uint64_BE,
     uint64_LE,
     uint64,
@@ -41,9 +40,5 @@ from .types import (
     String,
     Blob,
     Literal,
-    ObjectSerializer,
-)
-from .utils import (
-    StructoReader,
-    StructifyWriter,
+    Optional,
 )

structo-0.0.10/structo/interfaces.py

@@ -0,0 +1,46 @@
+import io
+import typing as t
+
+
+class Serializable:
+    @classmethod
+    def serializer(cls) -> Serializer[t.Self]: ...
+
+    @classmethod
+    def sizeof(cls) -> int | None:
+        return cls.serializer().sizeof()
+
+    def write(self, f: t.IO[bytes]):
+        return self.serializer().write(f, self)
+
+    @classmethod
+    def read(cls, f: t.IO[bytes]) -> t.Self:
+        return cls.serializer().read(f)
+
+    def to_bytes(self) -> bytes:
+        return self.serializer().to_bytes(self)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> t.Self:
+        return cls.serializer().from_bytes(data)
+
+
+class Serializer[T]:
+    def sizeof(self) -> int | None:
+        return None
+
+    def write(self, f: t.IO[bytes], value: T):
+        raise NotImplementedError(f"{type(self).__name__} can't be serialized")
+
+    def read(self, f: t.IO[bytes]) -> T:
+        raise NotImplementedError(f"{type(self).__name__} can't be deserialized")
+
+    def to_bytes(self, value: T) -> bytes:
+        buf = io.BytesIO()
+        self.write(buf, value)
+        buf.seek(0)
+        return buf.getvalue()
+
+    def from_bytes(self, data: bytes) -> T:
+        buf = io.BytesIO(data)
+        return self.read(buf)

structo-0.0.10/structo/objects/__init__.py

@@ -0,0 +1,2 @@
+from .packed import PackedInt, PackedInts
+from .serializable_object import SerializableObject