# hexdhog/obj2bin architecture

> Architecture diagram of the GitHub repository hexdhog/obj2bin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hexdhog/obj2bin
- Repository: https://github.com/hexdhog/obj2bin

## Overview

##### Recognize the Project Type and Purpose
- This is a lightweight Python library for object serialization.
- Its goal is to allow users to define data structures using classes and an associated decorator (@pack) that automatically takes care of serializing data to bytes using Python’s struct module. The README demonstrates how constant and dynamic fields (using Field, Const, and Child) are used in serialization.

##### File Structure
- Top-level files (like setup.py, LICENSE, README.md, example.py, pypi_publish.sh) indicate that the project is a publishable library intended for distribution (for instance via PyPI).
- The main package resides in the “obj2bin” directory with its implementation (obj2bin.py) and version management (__version__.py).
- The presence of test files in the “test” directory indicates unit testing for ensuring correctness.
- There are configuration files for static analysis (mypy.ini, ruff.toml, lint.sh) which are tools for quality assurance but are less central to the runtime architecture.

##### Components and Their Roles
a. User Interface / Entry Point:
- The user's code (seen in example.py and explained in the README) interacts with the library by defining classes decorated with @pack. This is the integration point where the user defines the data structure.
b. Serialization Core:
- The core functionalities are in obj2bin.py which houses:
- The @pack decorator that registers the data class’s field serialization details.
- The functions encode and decode which handle converting objects to bytes and vice versa.
- Handling field types: Field, Const, and potentially Child, which dictate how data is processed.
c. Utility Functions and Helpers:
- Additional functions like utf8tobytes, utf8frombytes, and utf8size (likely within the module or accessible via __init__.py) handle the encoding and size computations for variable data types (like strings).
d. External Dependency:
- The Python struct module is used internally to map field definitions (provided by format strings) into actual byte conversions.
e. Testing and Quality:
- The separate test directory ensures each module function works as expected and validates behaviors like error handling in constant field matching.

##### Architectural Patterns & Design Principles
- Separation of concerns:
- The user defines the data structure.
- The library’s decorator captures and organizes the serialization schema.
- The core functions (encode/decode) operate independent of the user’s logic.
- Reliance on composition over inheritance – users’ classes are “decorated” rather than requiring them to subclass a specific base class.
- Deliberate use of established Python paradigms (e.g., dict insertion order preservation in Python ≥ 3.7) that affect behavior in serialization order.

##### Bringing It All Together
1. User Code → @pack Decorator (component that registers fields: Field, Const, Child).
2. @pack Decorator → Serialization Engine (encode/decode functions) where the metadata is consumed.
3. Serialization Engine → Utility Functions for specific data type conversions.
4. Serialization Engine → External Dependency (Python’s struct module) for actual binary conversion.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Library Workflow"
        U["User Code (Data Class Definition using @pack)"]:::user
        I["Serialization Interface (@pack Decorator & Field Definitions)"]:::interface
        E["Core Engine (encode/decode functions)"]:::core
        UT["Utility Functions (utf8tobytes, utf8frombytes, utf8size)"]:::util
        S["External Dependency (Python struct module)"]:::external
    end

    subgraph "Quality Assurance"
        T["Test Suite (Unit Tests)"]:::test
    end

    U -->|"ClassDecoration"| I
    I -->|"RegistersFields"| E
    E -->|"CallsConversion"| UT
    E -->|"UsesStruct"| S
    T -->|"ValidatesEngine"| E
    T -->|"ValidatesUtils"| UT

    click U "https://github.com/hexdhog/obj2bin/blob/master/example.py"
    click I "https://github.com/hexdhog/obj2bin/blob/master/obj2bin/obj2bin.py"
    click E "https://github.com/hexdhog/obj2bin/blob/master/obj2bin/obj2bin.py"
    click UT "https://github.com/hexdhog/obj2bin/blob/master/obj2bin/obj2bin.py"
    click T "https://github.com/hexdhog/obj2bin/blob/master/test/test_packet.py"

    classDef user fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef interface fill:#FFFFCC,stroke:#000,stroke-width:1px;
    classDef core fill:#C1E1C1,stroke:#000,stroke-width:1px;
    classDef util fill:#E2F0CB,stroke:#000,stroke-width:1px;
    classDef external fill:#FFCCCC,stroke:#000,stroke-width:1px;
    classDef test fill:#D1E0E0,stroke:#000,stroke-width:1px;
```
