semvec/pypi-packages huggingface dataset:
ZENTCH-Q 0.1.0
qlcontracts defines the shared, versioned data contracts and precision/time rules for instruments, market data, orders, fills, and risk results used across the QL trading stack.
License: MIT
Requires Python: >=3.9

`qlcontracts`

[![PyPI version](https://badge.fury.io/py/qlcontracts.svg)](https://badge.fury.io/py/qlcontracts)
[![Python Versions](https://img.shields.io/pypi/pyversions/qlcontracts.svg)](https://pypi.org/project/qlcontracts/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Professional Data Contracts for High-Frequency Trading Systems.**

`qlcontracts` defines the shared, versioned data contracts, precision rules, and time handling logic for instruments, market data, orders, fills, and risk checks used across the QL trading stack. It serves as the "source of truth" for data structures, ensuring compile-time correctness and runtime validation.

---

## 🚀 Key Features

- **Type Safety**: Heavy use of `NewType` and Pydantic-compatible dataclasses to prevent category errors (e.g., confusing an `InstrumentId` with a `Symbol`).
- **Precision Handling**: Native `Decimal` support for prices and quantities, with strict helpers for tick-size rounding and quantization.
- **Unified Taxonomy**: Standardized enums for `OrderType`, `TimeInForce`, `AssetType`, etc.
- **Zero-Copy Validation**: Lightweight `ensure_*` helpers for hot paths where full schema validation is too slow.
- **Serialization**: Canonical JSON serialization helpers ensuring consistent representation of dates and decimals.

## 📦 Installation

```bash
pip install qlcontracts
```

Or with optional dependencies for development:

```bash
pip install "qlcontracts[dev]"
```

## ⚡ Quick Example

```python
from decimal import Decimal
from qlcontracts import (
    OrderRequest, InstrumentId, OrderSide, OrderType, Quantity, Price,
    make_instrument_id
)

# 1. Define distinct types
btc_usd = make_instrument_id("BINANCE", "BTC-USDT")

# 2. Create an order with validation
order = OrderRequest(
    instrument_id=btc_usd,
    side=OrderSide.BUY,
    type=OrderType.LIMIT,
    quantity=Quantity(Decimal("0.5")),
    price=Price(Decimal("95000.00")),
    client_order_id="strategy-algo-001"
)

print(f"Placing {order.side} for {order.quantity} of {order.instrument_id}")
```

## 📚 Documentation

Full documentation is available at **[Docs URL]** (or locally via `mkdocs serve`).

- [Getting Started](docs/getting-started/quickstart.md)
- [User Guide](docs/user-guide/identifiers.md)
- [API Reference](docs/reference/api.md)

## 🤝 Contributing

We welcome contributions! Please see `CONTRIBUTING.md` for details (if applicable).

## 📄 License

This project is licensed under the terms of the MIT license.