tsrkit-types 0.1.0__tar.gz → 0.1.2__tar.gz

{tsrkit_types-0.1.0 → tsrkit_types-0.1.2}/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2024-12-19
+## [0.1.0] - 2025-06-03
 
 ### Added
 - Initial release of tsrkit-types library
@@ -20,7 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Dictionary type: `Dictionary[K, V]` with typed keys and values
 - Bytes types: `Bytes` for raw binary data and `BitArray` for bit sequences
 - Enumeration type: `Enum` with integer backing and string names
-- Structured types: `@struct` decorator for automatic `Codable` implementation
+- Structured types: `@structure` decorator for automatic `Codable` implementation
 - Binary serialization with efficient encoding formats
 - JSON serialization with customizable field mapping
 - Type safety with runtime validation
@@ -35,7 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Type validation at construction and assignment time
 - Support for nested and complex type compositions
 - Zero-dependency core library
-- Python 3.12+ support
+- Python 3.11+ support
 
 ## [Unreleased]
 

{tsrkit_types-0.1.0 → tsrkit_types-0.1.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tsrkit-types
-Version: 0.1.0
-Summary: High-performance Python library for type-safe binary serialization, JSON encoding, and data validation with zero dependencies
+Version: 0.1.2
+Summary: Performant Python Typings library for type-safe binary serialization, JSON encoding, and data validation with zero dependencies
 Author-email: chainscore-labs <hello@chainscore.finance>, prasad-kumkar <prasad@chainscore.finance>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/chainscore/tsrkit-types
@@ -15,6 +15,7 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -26,7 +27,7 @@ Classifier: Topic :: Utilities
 Classifier: Topic :: System :: Archiving
 Classifier: Topic :: Communications
 Classifier: Typing :: Typed
-Requires-Python: >=3.12
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
@@ -40,7 +41,7 @@ Dynamic: license-file
 
 # TSRKit Types
 
-Performant Python library for type-safe binary serialization, JSON encoding, and data validation with zero dependencies.
+Performant Python Typings library for type-safe binary serialization, JSON encoding, and data validation with zero dependencies.
 
 Perfect for network protocols, game state serialization, configuration files, and any application requiring efficient, validated data handling.
 
@@ -62,7 +63,7 @@ pip install tsrkit-types
 
 ## Type Categories
 
-### Integer Types
+### Integer Types (extension of Python int)
 
 #### Unsigned Integers (`Uint`)
 
@@ -70,13 +71,13 @@ The `Uint` class provides both fixed-size and variable-size unsigned integers.
 
 **Fixed-Size Integers:**
 ```python
-from tsrkit_types.integers import Uint, U8, U16, U32, U64
+from tsrkit_types.integers import Uint
 
 # Pre-defined types
-value = U8(255)        # 8-bit unsigned integer (0-255)
-value = U16(65535)     # 16-bit unsigned integer (0-65535) 
-value = U32(42949)     # 32-bit unsigned integer
-value = U64(1844674)   # 64-bit unsigned integer
+value = Uint[8](255)        # 8-bit unsigned integer (0-255)
+value = Uint[16](65535)     # 16-bit unsigned integer (0-65535) 
+value = Uint[32](42949)     # 32-bit unsigned integer
+value = Uint[64](1844674)   # 64-bit unsigned integer
 
 # Dynamic size specification
 U128 = Uint[128]       # 128-bit unsigned integer
@@ -96,9 +97,9 @@ encoded = num.encode()
 decoded = Uint.decode(encoded)
 
 # Arithmetic operations preserve type
-a = U8(10)
-b = U8(20)
-result = a + b         # result is U8(30)
+a = Uint[8](10)
+b = Uint[8](20)
+result = a + b         # result is Uint[8](30)
 ```
 
 **Encoding Details:**
@@ -107,7 +108,7 @@ result = a + b         # result is U8(30)
 - Values < 2^7 are encoded in 1 byte
 - Larger values use a variable-length prefix encoding
 
-### String Types
+### String Types (extension of Python str)
 
 #### UTF-8 Strings (`String`)
 
@@ -161,27 +162,11 @@ restored = Bool.from_json("true")
 
 ### Null Types
 
-#### Null and Nullable
-
 ```python
-from tsrkit_types.null import Null, Nullable
+from tsrkit_types.null import Null
 
 # Null type
 null_val = Null                  # Singleton null value
-
-# Nullable wrapper for optional values
-maybe_string = Nullable[String](String("hello"))
-empty_val = Nullable[String]()   # Contains null
-
-# Check for null
-if maybe_string.is_null():
-    print("Value is null")
-else:
-    value = maybe_string.unwrap()  # Get the wrapped value
-
-# Encoding
-encoded = maybe_string.encode()  # 1 byte flag + optional value
-decoded = Nullable[String].decode(encoded)
 ```
 
 ### Choice and Option Types
@@ -219,7 +204,7 @@ encoded = result.encode()        # [variant_index][value]
 decoded = Result.decode(encoded)
 ```
 
-#### Option (Optional Values)
+#### Option (Optional Value - T | Null)
 
 ```python
 from tsrkit_types.option import Option
@@ -240,7 +225,7 @@ decoded = Option[U32].decode(encoded)
 
 ### Container Types
 
-#### Sequences (Arrays and Vectors)
+#### Sequences (Extension of Python list)
 
 ```python
 from tsrkit_types.sequences import Array, Vector, TypedArray, TypedVector
@@ -274,7 +259,7 @@ decoded = TypedDynamicVector.decode(encoded)
 
 **Sequence Types:**
 - `Array[N]`: Fixed size, any element type
-- `Vector[max]`: Variable size up to max, any element type  
+- `Vector`: Variable size, any element type  
 - `TypedArray[T, N]`: Fixed size with typed elements
 - `TypedVector[T]`: Variable size with typed elements
 - `BoundedVector[min, max]`: Size constrained vector
@@ -314,7 +299,7 @@ restored = StringToInt.from_json(json_data)
 
 ### Bytes Types
 
-#### Raw Bytes
+#### Bytes (extension of Python in-built bytes)
 
 ```python
 from tsrkit_types.bytes import Bytes
@@ -323,6 +308,10 @@ from tsrkit_types.bytes import Bytes
 data = Bytes(b"Hello, binary world!")
 data = Bytes([0x01, 0x02, 0x03, 0x04])
 
+# Bytes <-> Bits Operations
+data.to_bits()          # [True, False, True, ...]
+Bytes.from_bits([True, False, True, ...])
+
 # Operations
 length = len(data)               # Byte length
 raw_bytes = bytes(data)         # Convert to Python bytes
@@ -336,7 +325,7 @@ json_str = data.to_json()        # "48656c6c6f2c2062696e61727920776f726c6421"
 restored = Bytes.from_json(json_str)
 ```
 
-#### Bit Arrays
+#### Bit Arrays (Sequence of bool)
 
 ```python
 from tsrkit_types.bits import BitArray
@@ -361,7 +350,7 @@ encoded = bits.encode()          # [length][packed_bits]
 decoded = BitArray.decode(encoded)
 ```
 
-### Enumeration Types
+### Enum (Extension of Python Enum, with Codable + JSON support)
 
 ```python
 from tsrkit_types.enum import Enum
@@ -391,7 +380,7 @@ restored = Color.from_json("GREEN")
 
 ### Structured Types
 
-#### Struct Decorator
+#### Struct Decorator (Extension of dataclasses)
 
 ```python
 from tsrkit_types.struct import struct
@@ -399,12 +388,12 @@ from tsrkit_types.string import String
 from tsrkit_types.integers import U8, U32
 from dataclasses import field
 
-@struct
+@structure
 class Person:
     name: String
     age: U8
     
-@struct  
+@structure  
 class Employee:
     person: Person
     employee_id: U32
@@ -427,7 +416,7 @@ encoded = employee.encode()      # Concatenated field encodings
 decoded = Employee.decode(encoded)
 
 # JSON serialization with custom field names
-@struct
+@structure
 class CustomPerson:
     name: String = field(metadata={"name": "full_name"})
     age: U8
@@ -479,7 +468,7 @@ class Point3D(Codable):
 
 ```python
 # Optimize for specific use cases
-@struct(frozen=True)             # Immutable structs
+@structure(frozen=True)             # Immutable structs
 class ImmutableData:
     value: U64
 
@@ -575,8 +564,8 @@ offset += value2.encode_into(buffer, offset)
 
 ### Network Protocol
 
-```python
-@struct
+```**python**
+@structure
 class NetworkPacket:
     packet_type: U8
     session_id: U32
@@ -601,7 +590,7 @@ received_packet = NetworkPacket.decode(wire_data)
 ### Configuration File
 
 ```python
-@struct
+@structure
 class DatabaseConfig:
     host: String
     port: U16
@@ -637,19 +626,19 @@ class GameEntityType(Enum):
     ENEMY = 1
     ITEM = 2
 
-@struct
+@structure
 class Position:
     x: U16
     y: U16
 
-@struct  
+@structure  
 class GameEntity:
     entity_type: GameEntityType
     position: Position
     health: U8
     name: String
 
-@struct
+@structure
 class GameState:
     level: U8
     score: U32
@@ -745,6 +734,6 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gui
 
 ## Requirements
 
-- **Python**: >= 3.12
+- **Python**: >= 3.11
 - **Runtime Dependencies**: None (zero dependencies!)
 - **Development Dependencies**: pytest and plugins (see `pyproject.toml`) 

{tsrkit_types-0.1.0 → tsrkit_types-0.1.2}/README.md

@@ -1,6 +1,6 @@
 # TSRKit Types
 
-Performant Python library for type-safe binary serialization, JSON encoding, and data validation with zero dependencies.
+Performant Python Typings library for type-safe binary serialization, JSON encoding, and data validation with zero dependencies.
 
 Perfect for network protocols, game state serialization, configuration files, and any application requiring efficient, validated data handling.
 
@@ -22,7 +22,7 @@ pip install tsrkit-types
 
 ## Type Categories
 
-### Integer Types
+### Integer Types (extension of Python int)
 
 #### Unsigned Integers (`Uint`)
 
@@ -30,13 +30,13 @@ The `Uint` class provides both fixed-size and variable-size unsigned integers.
 
 **Fixed-Size Integers:**
 ```python
-from tsrkit_types.integers import Uint, U8, U16, U32, U64
+from tsrkit_types.integers import Uint
 
 # Pre-defined types
-value = U8(255)        # 8-bit unsigned integer (0-255)
-value = U16(65535)     # 16-bit unsigned integer (0-65535) 
-value = U32(42949)     # 32-bit unsigned integer
-value = U64(1844674)   # 64-bit unsigned integer
+value = Uint[8](255)        # 8-bit unsigned integer (0-255)
+value = Uint[16](65535)     # 16-bit unsigned integer (0-65535) 
+value = Uint[32](42949)     # 32-bit unsigned integer
+value = Uint[64](1844674)   # 64-bit unsigned integer
 
 # Dynamic size specification
 U128 = Uint[128]       # 128-bit unsigned integer
@@ -56,9 +56,9 @@ encoded = num.encode()
 decoded = Uint.decode(encoded)
 
 # Arithmetic operations preserve type
-a = U8(10)
-b = U8(20)
-result = a + b         # result is U8(30)
+a = Uint[8](10)
+b = Uint[8](20)
+result = a + b         # result is Uint[8](30)
 ```
 
 **Encoding Details:**
@@ -67,7 +67,7 @@ result = a + b         # result is U8(30)
 - Values < 2^7 are encoded in 1 byte
 - Larger values use a variable-length prefix encoding
 
-### String Types
+### String Types (extension of Python str)
 
 #### UTF-8 Strings (`String`)
 
@@ -121,27 +121,11 @@ restored = Bool.from_json("true")
 
 ### Null Types
 
-#### Null and Nullable
-
 ```python
-from tsrkit_types.null import Null, Nullable
+from tsrkit_types.null import Null
 
 # Null type
 null_val = Null                  # Singleton null value
-
-# Nullable wrapper for optional values
-maybe_string = Nullable[String](String("hello"))
-empty_val = Nullable[String]()   # Contains null
-
-# Check for null
-if maybe_string.is_null():
-    print("Value is null")
-else:
-    value = maybe_string.unwrap()  # Get the wrapped value
-
-# Encoding
-encoded = maybe_string.encode()  # 1 byte flag + optional value
-decoded = Nullable[String].decode(encoded)
 ```
 
 ### Choice and Option Types
@@ -179,7 +163,7 @@ encoded = result.encode()        # [variant_index][value]
 decoded = Result.decode(encoded)
 ```
 
-#### Option (Optional Values)
+#### Option (Optional Value - T | Null)
 
 ```python
 from tsrkit_types.option import Option
@@ -200,7 +184,7 @@ decoded = Option[U32].decode(encoded)
 
 ### Container Types
 
-#### Sequences (Arrays and Vectors)
+#### Sequences (Extension of Python list)
 
 ```python
 from tsrkit_types.sequences import Array, Vector, TypedArray, TypedVector
@@ -234,7 +218,7 @@ decoded = TypedDynamicVector.decode(encoded)
 
 **Sequence Types:**
 - `Array[N]`: Fixed size, any element type
-- `Vector[max]`: Variable size up to max, any element type  
+- `Vector`: Variable size, any element type  
 - `TypedArray[T, N]`: Fixed size with typed elements
 - `TypedVector[T]`: Variable size with typed elements
 - `BoundedVector[min, max]`: Size constrained vector
@@ -274,7 +258,7 @@ restored = StringToInt.from_json(json_data)
 
 ### Bytes Types
 
-#### Raw Bytes
+#### Bytes (extension of Python in-built bytes)
 
 ```python
 from tsrkit_types.bytes import Bytes
@@ -283,6 +267,10 @@ from tsrkit_types.bytes import Bytes
 data = Bytes(b"Hello, binary world!")
 data = Bytes([0x01, 0x02, 0x03, 0x04])
 
+# Bytes <-> Bits Operations
+data.to_bits()          # [True, False, True, ...]
+Bytes.from_bits([True, False, True, ...])
+
 # Operations
 length = len(data)               # Byte length
 raw_bytes = bytes(data)         # Convert to Python bytes
@@ -296,7 +284,7 @@ json_str = data.to_json()        # "48656c6c6f2c2062696e61727920776f726c6421"
 restored = Bytes.from_json(json_str)
 ```
 
-#### Bit Arrays
+#### Bit Arrays (Sequence of bool)
 
 ```python
 from tsrkit_types.bits import BitArray
@@ -321,7 +309,7 @@ encoded = bits.encode()          # [length][packed_bits]
 decoded = BitArray.decode(encoded)
 ```
 
-### Enumeration Types
+### Enum (Extension of Python Enum, with Codable + JSON support)
 
 ```python
 from tsrkit_types.enum import Enum
@@ -351,7 +339,7 @@ restored = Color.from_json("GREEN")
 
 ### Structured Types
 
-#### Struct Decorator
+#### Struct Decorator (Extension of dataclasses)
 
 ```python
 from tsrkit_types.struct import struct
@@ -359,12 +347,12 @@ from tsrkit_types.string import String
 from tsrkit_types.integers import U8, U32
 from dataclasses import field
 
-@struct
+@structure
 class Person:
     name: String
     age: U8
     
-@struct  
+@structure  
 class Employee:
     person: Person
     employee_id: U32
@@ -387,7 +375,7 @@ encoded = employee.encode()      # Concatenated field encodings
 decoded = Employee.decode(encoded)
 
 # JSON serialization with custom field names
-@struct
+@structure
 class CustomPerson:
     name: String = field(metadata={"name": "full_name"})
     age: U8
@@ -439,7 +427,7 @@ class Point3D(Codable):
 
 ```python
 # Optimize for specific use cases
-@struct(frozen=True)             # Immutable structs
+@structure(frozen=True)             # Immutable structs
 class ImmutableData:
     value: U64
 
@@ -535,8 +523,8 @@ offset += value2.encode_into(buffer, offset)
 
 ### Network Protocol
 
-```python
-@struct
+```**python**
+@structure
 class NetworkPacket:
     packet_type: U8
     session_id: U32
@@ -561,7 +549,7 @@ received_packet = NetworkPacket.decode(wire_data)
 ### Configuration File
 
 ```python
-@struct
+@structure
 class DatabaseConfig:
     host: String
     port: U16
@@ -597,19 +585,19 @@ class GameEntityType(Enum):
     ENEMY = 1
     ITEM = 2
 
-@struct
+@structure
 class Position:
     x: U16
     y: U16
 
-@struct  
+@structure  
 class GameEntity:
     entity_type: GameEntityType
     position: Position
     health: U8
     name: String
 
-@struct
+@structure
 class GameState:
     level: U8
     score: U32
@@ -705,6 +693,6 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gui
 
 ## Requirements
 
-- **Python**: >= 3.12
+- **Python**: >= 3.11
 - **Runtime Dependencies**: None (zero dependencies!)
 - **Development Dependencies**: pytest and plugins (see `pyproject.toml`) 

{tsrkit_types-0.1.0 → tsrkit_types-0.1.2}/pyproject.toml

@@ -1,14 +1,14 @@
 [project]
 name = "tsrkit-types"
-version = "0.1.0"
-description = "High-performance Python library for type-safe binary serialization, JSON encoding, and data validation with zero dependencies"
+version = "0.1.2"
+description = "Performant Python Typings library for type-safe binary serialization, JSON encoding, and data validation with zero dependencies"
 authors = [
     {name = "chainscore-labs", email = "hello@chainscore.finance"},
     {name = "prasad-kumkar", email = "prasad@chainscore.finance"}
 ]
 readme = "README.md"
 license = "MIT"
-requires-python = ">=3.12"
+requires-python = ">=3.11"
 keywords = [
     "serialization", "binary", "encoding", "types", "codable", "json", 
     "validation", "data-types", "type-safety", "zero-copy", "protocol",
@@ -20,6 +20,7 @@ classifiers = [
     "Intended Audience :: System Administrators",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3 :: Only",
     "Topic :: Software Development :: Libraries :: Python Modules",