tsrkit-types 0.1.9__tar.gz → 0.2.0__tar.gz

{tsrkit_types-0.1.9 → tsrkit_types-0.2.0}/MANIFEST.in

@@ -2,11 +2,13 @@ include README.md
 include LICENSE
 include CHANGELOG.md
 include CONTRIBUTING.md
+include benchmark.md
 include pytest.ini
 include pyproject.toml
 include setup.py
 
 recursive-include tsrkit_types *.py
+recursive-include tsrkit_types *.c
 recursive-include tests *.py
 
 exclude .gitignore
@@ -16,4 +18,4 @@ exclude .pytest_cache/*
 exclude __pycache__/*
 exclude *.pyc
 exclude .coverage
-exclude htmlcov/* 
+exclude htmlcov/* 

tsrkit_types-0.2.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: tsrkit-types
+Version: 0.2.0
+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
+Project-URL: Repository, https://github.com/chainscore/tsrkit-types
+Project-URL: Issues, https://github.com/chainscore/tsrkit-types/issues
+Project-URL: Documentation, https://github.com/chainscore/tsrkit-types#readme
+Project-URL: Changelog, https://github.com/chainscore/tsrkit-types/blob/main/CHANGELOG.md
+Keywords: serialization,binary,encoding,types,codable,json,validation,data-types,type-safety,zero-copy,protocol,struct,networking,performance,bytes,integers,strings
+Classifier: Development Status :: 4 - Beta
+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
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Database
+Classifier: Topic :: Utilities
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: Communications
+Classifier: Typing :: Typed
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Dynamic: license-file
+
+# TSRKit Types
+
+[![PyPI](https://img.shields.io/pypi/v/tsrkit-types.svg)](https://pypi.org/project/tsrkit-types/)
+[![Python](https://img.shields.io/pypi/pyversions/tsrkit-types.svg)](https://pypi.org/project/tsrkit-types/)
+[![CI](https://github.com/Chainscore/tsrkit-types/actions/workflows/ci.yml/badge.svg)](https://github.com/Chainscore/tsrkit-types/actions/workflows/ci.yml)
+[![Release](https://github.com/Chainscore/tsrkit-types/actions/workflows/release.yml/badge.svg)](https://github.com/Chainscore/tsrkit-types/actions/workflows/release.yml)
+[![License](https://img.shields.io/github/license/Chainscore/tsrkit-types.svg)](https://github.com/Chainscore/tsrkit-types/blob/main/LICENSE)
+
+A high‑performance, strongly‑typed Python serialization library with built‑in JSON support. TSRKit Types provides a concise type system for integers, bytes, strings, bits, sequences, dictionaries, enums, and structs with deterministic, validated encoding.
+
+## Highlights
+
+- Native C extension for performance‑critical encode/decode paths
+- Deterministic binary encoding and JSON serialization
+- Strong runtime validation with type‑safe containers
+- Clean, small API designed for application‑level data modeling
+
+## Installation
+
+### Wheels (recommended)
+
+```bash
+pip install tsrkit-types
+```
+
+### Build from source
+
+```bash
+pip install .
+```
+
+The native extension is required. Wheels are provided for macOS and Linux.
+
+## Quickstart
+
+```python
+from tsrkit_types import Uint, U16, String, Bytes, Bits, TypedVector, Dictionary, structure
+
+# Integers
+value = Uint(1000)
+encoded = value.encode()
+decoded = Uint.decode(encoded)
+
+# Fixed-width integer
+port = U16(8080)
+
+# Strings and bytes
+name = String("alice")
+blob = Bytes(b"payload")
+
+# Bits
+flags = Bits([True, False, True, True])
+
+# Typed container
+VecU16 = TypedVector[U16]
+ports = VecU16([U16(80), U16(443)])
+
+# Dictionary with typed keys/values
+Config = Dictionary[String, U16]
+config = Config({String("port"): U16(8080)})
+
+# Structs
+@structure
+class Person:
+    name: String
+    age: U16
+
+p = Person(name=String("bob"), age=U16(42))
+
+# Binary + JSON
+binary = p.encode()
+json_data = p.to_json()
+```
+
+## Type Overview
+
+- **Integers**: `Uint`, `U8`, `U16`, `U32`, `U64`
+- **Strings**: `String`
+- **Bytes**: `Bytes`, `Bytes16`, `Bytes32`, `Bytes64`, `Bytes128`, `Bytes256`, `Bytes512`, `Bytes1024`, `ByteArray`
+- **Bits**: `Bits`
+- **Sequences**: `Seq`, `Vector`, `Array`, `TypedVector`, `TypedArray`, `BoundedVector`, `TypedBoundedVector`
+- **Dictionary**: `Dictionary`
+- **Enums**: `Enum`
+- **Structs**: `structure`
+- **Choice/Option**: `Choice`, `Option`
+
+## Encoding Notes
+
+- Fixed‑width integers are little‑endian.
+- Variable‑length integers use a compact prefix encoding optimized for smaller values.
+- Dictionaries encode in sorted key order for determinism.
+
+## Benchmarks
+
+See `benchmark.md` for current results and Python/stdlib baselines. Raw benchmark outputs are written to:
+
+- `benchmarks/out/bench_results.json`
+- `benchmarks/out/bench_profiles.json`
+
+## Development
+
+### Tests
+
+```bash
+uv run pytest
+```
+
+### Linting
+
+```bash
+uv run ruff check .
+```

tsrkit_types-0.2.0/README.md

@@ -0,0 +1,112 @@
+# TSRKit Types
+
+[![PyPI](https://img.shields.io/pypi/v/tsrkit-types.svg)](https://pypi.org/project/tsrkit-types/)
+[![Python](https://img.shields.io/pypi/pyversions/tsrkit-types.svg)](https://pypi.org/project/tsrkit-types/)
+[![CI](https://github.com/Chainscore/tsrkit-types/actions/workflows/ci.yml/badge.svg)](https://github.com/Chainscore/tsrkit-types/actions/workflows/ci.yml)
+[![Release](https://github.com/Chainscore/tsrkit-types/actions/workflows/release.yml/badge.svg)](https://github.com/Chainscore/tsrkit-types/actions/workflows/release.yml)
+[![License](https://img.shields.io/github/license/Chainscore/tsrkit-types.svg)](https://github.com/Chainscore/tsrkit-types/blob/main/LICENSE)
+
+A high‑performance, strongly‑typed Python serialization library with built‑in JSON support. TSRKit Types provides a concise type system for integers, bytes, strings, bits, sequences, dictionaries, enums, and structs with deterministic, validated encoding.
+
+## Highlights
+
+- Native C extension for performance‑critical encode/decode paths
+- Deterministic binary encoding and JSON serialization
+- Strong runtime validation with type‑safe containers
+- Clean, small API designed for application‑level data modeling
+
+## Installation
+
+### Wheels (recommended)
+
+```bash
+pip install tsrkit-types
+```
+
+### Build from source
+
+```bash
+pip install .
+```
+
+The native extension is required. Wheels are provided for macOS and Linux.
+
+## Quickstart
+
+```python
+from tsrkit_types import Uint, U16, String, Bytes, Bits, TypedVector, Dictionary, structure
+
+# Integers
+value = Uint(1000)
+encoded = value.encode()
+decoded = Uint.decode(encoded)
+
+# Fixed-width integer
+port = U16(8080)
+
+# Strings and bytes
+name = String("alice")
+blob = Bytes(b"payload")
+
+# Bits
+flags = Bits([True, False, True, True])
+
+# Typed container
+VecU16 = TypedVector[U16]
+ports = VecU16([U16(80), U16(443)])
+
+# Dictionary with typed keys/values
+Config = Dictionary[String, U16]
+config = Config({String("port"): U16(8080)})
+
+# Structs
+@structure
+class Person:
+    name: String
+    age: U16
+
+p = Person(name=String("bob"), age=U16(42))
+
+# Binary + JSON
+binary = p.encode()
+json_data = p.to_json()
+```
+
+## Type Overview
+
+- **Integers**: `Uint`, `U8`, `U16`, `U32`, `U64`
+- **Strings**: `String`
+- **Bytes**: `Bytes`, `Bytes16`, `Bytes32`, `Bytes64`, `Bytes128`, `Bytes256`, `Bytes512`, `Bytes1024`, `ByteArray`
+- **Bits**: `Bits`
+- **Sequences**: `Seq`, `Vector`, `Array`, `TypedVector`, `TypedArray`, `BoundedVector`, `TypedBoundedVector`
+- **Dictionary**: `Dictionary`
+- **Enums**: `Enum`
+- **Structs**: `structure`
+- **Choice/Option**: `Choice`, `Option`
+
+## Encoding Notes
+
+- Fixed‑width integers are little‑endian.
+- Variable‑length integers use a compact prefix encoding optimized for smaller values.
+- Dictionaries encode in sorted key order for determinism.
+
+## Benchmarks
+
+See `benchmark.md` for current results and Python/stdlib baselines. Raw benchmark outputs are written to:
+
+- `benchmarks/out/bench_results.json`
+- `benchmarks/out/bench_profiles.json`
+
+## Development
+
+### Tests
+
+```bash
+uv run pytest
+```
+
+### Linting
+
+```bash
+uv run ruff check .
+```

tsrkit_types-0.2.0/benchmark.md

@@ -0,0 +1,53 @@
+# Benchmarks
+
+This document records the latest benchmark run and the Python/stdlib baselines used for comparison.
+All timings are **seconds for 20,000 runs** on the local machine; results are not directly comparable across hardware or Python versions.
+
+## How To Run
+
+```bash
+PYTHONPATH=. python3.12 benchmarks/bench_types.py
+```
+
+Raw data is written to:
+- `benchmarks/out/bench_results.json`
+- `benchmarks/out/bench_profiles.json`
+
+## Latest Results (Local)
+
+**Run date:** 2026-02-04  
+**Python:** 3.12.11  
+**Runs:** 20,000
+
+### TSRKit Types (selected)
+
+| Case | init_s | encode_s | decode_s | json_encode_s | json_decode_s |
+| --- | --- | --- | --- | --- | --- |
+| Uint | 0.008567 | 0.004479 | 0.014276 | 0.002534 | 0.008913 |
+| U16 | 0.008530 | 0.004632 | 0.014242 | 0.002791 | 0.009892 |
+| Bytes(var,64B) | 0.004458 | 0.010630 | 0.008252 | 0.003609 | 0.010214 |
+| ByteArray | 0.003199 | 0.006915 | 0.006440 | 0.003522 | 0.009588 |
+| Bits(var,64b) | 0.011615 | 0.011080 | 0.016224 | 0.007608 | 0.024439 |
+| TypedArray[U16,10] | 0.014253 | 0.006967 | 0.017195 | 0.003189 | 0.152636 |
+| Dictionary[String,U16] | 0.023382 | 0.061991 | 0.149705 | 0.068052 | 0.179980 |
+
+### Python/Stdlib Baselines (selected)
+
+| Case | init_s | encode_s | decode_s |
+| --- | --- | --- | --- |
+| PyInt(varint) | 0.002778 | 0.006405 | 0.007207 |
+| PyU16(to_bytes) | 0.004112 | 0.003861 | 0.006797 |
+| PyBytes(var,64B) | 0.003516 | 0.005396 | 0.005538 |
+| PyByteArray(var,64B) | 0.003091 | 0.006694 | 0.006594 |
+| PyBits(var,64b) | 0.006438 | 0.088161 | 0.150918 |
+| PyArray('H',10) | 0.006611 | 0.008616 | 0.006599 |
+| PyDict[str,U16] | 0.003587 | 0.095823 | 0.077303 |
+
+## Notes On Baselines
+
+- `PyInt(varint)`: pure-Python varint encoder/decoder (same scheme as `Uint`).
+- `PyU16(to_bytes)`: `int.to_bytes` / `int.from_bytes` for fixed-width integers.
+- `PyBytes(var,64B)` / `PyByteArray(var,64B)`: length-prefixed bytes (varint length).
+- `PyBits(var,64b)`: list[bool] packed/unpacked to bytes in Python.
+- `PyArray('H',10)`: stdlib `array('H')` with `.tobytes()` / `.frombytes()`.
+- `PyDict[str,U16]`: sorted key encode; keys length-prefixed; values fixed 2-byte little-endian.

{tsrkit_types-0.1.9 → tsrkit_types-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tsrkit-types"
-version = "0.1.9"
+version = "0.2.0"
 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"},
@@ -43,6 +43,7 @@ dev = [
     "pytest-asyncio>=0.21.0",
     "pytest-timeout>=2.1.0",
     "pytest-xdist>=3.0.0",
+    "ruff>=0.6.0",
 ]
 
 [project.urls]
@@ -55,3 +56,11 @@ Changelog = "https://github.com/chainscore/tsrkit-types/blob/main/CHANGELOG.md"
 [build-system]
 requires = ["setuptools>=65.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = { find = { include = ["tsrkit_types*"], exclude = ["wheelhouse*"] } }
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+select = ["E9", "F63", "F7", "F82"]

{tsrkit_types-0.1.9 → tsrkit_types-0.2.0}/pytest.ini

@@ -12,4 +12,5 @@ addopts =
 markers =
     slow: marks tests as slow (deselect with '-m "not slow"')
     integration: marks tests as integration tests
-    unit: marks tests as unit tests 
+    unit: marks tests as unit tests
+    perf: marks performance benchmarks

tsrkit_types-0.2.0/setup.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""Setup script for tsrkit-types package."""
+
+from setuptools import Extension, setup
+
+extensions = [Extension("tsrkit_types._native", sources=["tsrkit_types/_native.c"])]
+
+# Use pyproject.toml for configuration
+setup(ext_modules=extensions)

tsrkit_types-0.2.0/tests/test_native_optional.py

@@ -0,0 +1,43 @@
+import pytest
+
+_native = pytest.importorskip("tsrkit_types._native")
+
+from tsrkit_types import Uint, U16, TypedArray
+
+
+def test_native_uint_roundtrip():
+    values = [0, 1, 127, 128, 255, 1000, 2**32]
+    for value in values:
+        encoded = _native.uint_encode(value, 0, False)
+        assert encoded == Uint(value).encode()
+        decoded, size = _native.uint_decode(encoded, 0, 0, False)
+        assert decoded == value
+        assert size == len(encoded)
+
+
+def test_native_uint_fixed_roundtrip():
+    value = 500
+    encoded = _native.uint_encode(value, 2, False)
+    assert encoded == U16(value).encode()
+    decoded, size = _native.uint_decode(encoded, 0, 2, False)
+    assert decoded == value
+    assert size == 2
+
+
+def test_native_bits_pack_unpack():
+    bits = [True, False, True, False, True, False, True, False, True]
+    packed = _native.pack_bits(bits, len(bits), "msb")
+    unpacked = _native.unpack_bits(packed, len(bits), "msb")
+    assert unpacked == bits
+
+
+def test_native_fixed_array_roundtrip():
+    arr_cls = TypedArray[U16, 4]
+    values = [U16(1), U16(2), U16(3), U16(4)]
+    encoded = _native.encode_fixed_array(values, U16.byte_size)
+    assert encoded == arr_cls(values).encode()
+
+    items, size = _native.decode_fixed_array(encoded, 0, 4, U16.byte_size, U16)
+    assert size == 4 * U16.byte_size
+    assert [int(x) for x in items] == [1, 2, 3, 4]
+    assert all(isinstance(x, U16) for x in items)

{tsrkit_types-0.1.9 → tsrkit_types-0.2.0}/tsrkit_types/__init__.py

@@ -8,6 +8,7 @@ serialization capabilities, including integers, strings, containers, and more.
 # Core interfaces
 from .itf.codable import Codable
 
+
 # Integer types
 from .integers import Uint, U8, U16, U32, U64
 
@@ -87,9 +88,10 @@ __all__ = [
     
     # Structure decorator
     "structure", "struct",
+
 ]
 
 # Version information
-__version__ = "0.1.9"
+__version__ = "0.2.0"
 __author__ = "TSRKit Team"
 __license__ = "MIT"