Metadata-Version: 2.4
Name: dtl-parser
Version: 1.1.0
Summary: Parser for DTL (Domain Transport Language) - Ultra-compact, cryptographic data transport format
Project-URL: Homepage, https://dtlaz.org
Project-URL: Documentation, https://dtlaz.org/docs
Project-URL: Repository, https://github.com/dtlaz/python-sdk
Project-URL: Changelog, https://github.com/dtlaz/python-sdk/blob/main/CHANGELOG.md
Author-email: Padam Sundar Kafle <padam@dtlaz.org>
Maintainer-email: AlifZetta <dev@alifzetta.com>
License: MIT
License-File: LICENSE
Keywords: ai,cryptographic,data-transport,dtl,finance,healthcare,parser,schema,serialization,web3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.8
Provides-Extra: all
Requires-Dist: blake3>=0.3.0; extra == 'all'
Requires-Dist: openpyxl>=3.0.0; extra == 'all'
Requires-Dist: pynacl>=1.5.0; extra == 'all'
Requires-Dist: pyyaml>=6.0; extra == 'all'
Provides-Extra: crypto
Requires-Dist: blake3>=0.3.0; extra == 'crypto'
Requires-Dist: pynacl>=1.5.0; extra == 'crypto'
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.0.0; extra == 'excel'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == 'yaml'
Description-Content-Type: text/markdown

# 🧬 DTL Parser

[![PyPI version](https://badge.fury.io/py/dtl-parser.svg)](https://badge.fury.io/py/dtl-parser)
[![Python](https://img.shields.io/pypi/pyversions/dtl-parser.svg)](https://pypi.org/project/dtl-parser/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Parser for DTL (Domain Transport Language)** - Ultra-compact, schema-driven, cryptographic data transport format.

📖 **Specification**: [dtlaz.org](https://dtlaz.org)

## Installation

```bash
pip install dtl-parser
```

## Quick Start

```python
import dtl

# 🧠 INTELLIGENT PARSING - Auto-detects input type!

# File path
doc = dtl.parse("data.dtl")

# Raw string
doc = dtl.parse("@dtlv1.0^dtHC^...")

# Bytes
doc = dtl.parse(b"@dtlv1.0^dtHC^...")

# URL
doc = dtl.parse("https://example.com/data.dtl")

# File handle
doc = dtl.parse(open("data.dtl"))

# StringIO / BytesIO
doc = dtl.parse(io.StringIO(content))

# Dict containing DTL
doc = dtl.parse({"_dtl": content})

# Base64 encoded
doc = dtl.parse(base64_encoded_string)

# pathlib.Path
doc = dtl.parse(Path("data.dtl"))

# Access tables
for row in doc.get_table("USERS"):
    print(row["name"])

# Get config values
region = doc.get_config("default_region")
```

## 🧠 Intelligent Input Detection

The parser automatically detects input type:

| Input | Detection | Action |
|-------|-----------|--------|
| `"data.dtl"` | File path | Read file |
| `"@dtlv1.0^..."` | DTL string | Parse directly |
| `"https://..."` | URL | Fetch & parse |
| `b"@dtlv1.0..."` | Bytes | Decode & parse |
| `open(file)` | File handle | Read & parse |
| `io.StringIO()` | Stream | Read & parse |
| `{"_dtl": ...}` | Dict | Extract & parse |
| `Path("file")` | pathlib.Path | Read file |
| Base64 string | Encoded DTL | Decode & parse |
| `None` | stdin | Read from stdin |

### Helper Functions

```python
# Check if input is valid DTL
if dtl.is_dtl(some_input):
    doc = dtl.parse(some_input)

# Detect input type
input_type = dtl.detect_input_type(some_input)
# Returns: "file", "string", "bytes", "url", "stream", "dict", "stdin"
```

## 🔄 Format Converters

Convert between DTL and other formats bidirectionally:

### JSON ↔ DTL

```python
import dtl

# JSON → DTL
doc = dtl.from_json({"users": [{"id": 1, "name": "Alice"}]})
doc = dtl.from_json('{"data": [1,2,3]}')  # String also works

# DTL → JSON
json_str = dtl.to_json(doc, pretty=True)
```

### CSV ↔ DTL

```python
# CSV → DTL
doc = dtl.from_csv("data.csv", table_name="USERS")
doc = dtl.from_csv("id,name\n1,Alice\n2,Bob")  # String content

# DTL → CSV
csv_str = dtl.to_csv(doc, table_name="USERS", delimiter=",")
```

### Excel ↔ DTL

```python
# Excel → DTL (requires openpyxl)
doc = dtl.from_excel("data.xlsx")
doc = dtl.from_excel("data.xlsx", sheet_name="Sheet1")

# DTL → Excel
dtl.to_excel(doc, "output.xlsx")
excel_bytes = dtl.to_excel(doc)  # Returns bytes
```

### XML ↔ DTL

```python
# XML → DTL
doc = dtl.from_xml("<data><user id='1'>Alice</user></data>")
doc = dtl.from_xml("data.xml")

# DTL → XML
xml_str = dtl.to_xml(doc, root_name="data")
```

### HL7 ↔ DTL (Healthcare)

```python
# HL7 → DTL (auto-sets domain to dtHC)
doc = dtl.from_hl7(hl7_message)
print(doc.header.domain)  # dtHC

# Access patient data
pid = doc.get_table("PID")[0]
print(pid["patient_name"])

# DTL → HL7
hl7_str = dtl.to_hl7(doc)
```

### JWT ↔ DTL (Auth)

```python
# JWT → DTL (auto-sets domain to dtID)
doc = dtl.from_jwt(jwt_token)
claims = doc.get_table("CLAIMS")
print(claims)

# DTL → JWT
token = dtl.to_jwt(doc, secret="optional-secret")
```

### YAML ↔ DTL

```python
# YAML → DTL (requires PyYAML)
doc = dtl.from_yaml("config.yaml")

# DTL → YAML
yaml_str = dtl.to_yaml(doc)
```

### Auto-detect Format

```python
# Auto-detects format and converts
doc = dtl.convert_to_dtl("data.json")      # Detects JSON
doc = dtl.convert_to_dtl("data.csv")       # Detects CSV
doc = dtl.convert_to_dtl("MSH|^~\\&|...")  # Detects HL7
doc = dtl.convert_to_dtl("<xml>...</xml>") # Detects XML

# Convert DTL to any format
json_str = dtl.convert_from_dtl(doc, "json")
csv_str = dtl.convert_from_dtl(doc, "csv")
xml_str = dtl.convert_from_dtl(doc, "xml")
```

### Conversion Matrix

| From → To | JSON | CSV | Excel | XML | HL7 | JWT | YAML | DTL |
|-----------|------|-----|-------|-----|-----|-----|------|-----|
| **JSON**  | -    | ✅  | ✅    | ✅  | -   | -   | ✅   | ✅  |
| **CSV**   | ✅   | -   | ✅    | ✅  | -   | -   | ✅   | ✅  |
| **Excel** | ✅   | ✅  | -     | ✅  | -   | -   | ✅   | ✅  |
| **XML**   | ✅   | ✅  | ✅    | -   | -   | -   | ✅   | ✅  |
| **HL7**   | ✅   | ✅  | ✅    | ✅  | -   | -   | ✅   | ✅  |
| **JWT**   | ✅   | -   | -     | ✅  | -   | -   | ✅   | ✅  |
| **YAML**  | ✅   | ✅  | ✅    | ✅  | -   | -   | -    | ✅  |
| **DTL**   | ✅   | ✅  | ✅    | ✅  | ✅  | ✅  | ✅   | -   |

## DTL Format

```
@dtlv1.0^dtHC^pProfile^c1^s1^w0^h0
@sec^fh0000^w0^sg0^ch0

TABLE_NAME|field:type,field:type|rowcount|S|W|C
value|value|value
value|value|value
```

### Example

```dtl
@dtlv1.0^dtHC^pMedical^c1^s1^w0^h0
@sec^fh0000^w0^sg0^chNONE

PATIENTS|id:s,name:s,dob:D|3|S1|W0|C1
P001|Ahmed Ali|1990-05-15
P002|Sara Khan|1985-03-22
P003|John Smith|1978-11-08

CONFIG|key:s,value:s|2|S0|W0|C1
region|uae
version|1.0
```

## API Reference

### Parsing

```python
import dtl

# Parse file
doc = dtl.parse_file("data.dtl")
doc = dtl.parse_file("data.dtl", strict=True)  # Raise on validation errors

# Parse string
doc = dtl.parse(content)
doc = dtl.parse(content, strict=True)
```

### Accessing Data

```python
# Get table rows as list of dicts
users = doc.get_table("USERS")

# Get table object with metadata
table = doc.get_table_obj("USERS")
print(table.schema)       # {'id': 's', 'name': 's'}
print(table.row_count)    # 3
print(table.security_mode)  # S1

# Get table as dict keyed by field
users_by_id = doc.get_table_as_dict("USERS", "id")
print(users_by_id["P001"]["name"])  # Ahmed Ali

# Filter rows
active_users = table.filter(status="active")

# Find one row
admin = table.find_one(role="admin")

# Get column values
names = table.get_column("name")  # ['Ahmed', 'Sara', 'John']
```

### Configuration

```python
# Get config from CONFIG table
region = doc.get_config("region")
region = doc.get_config("region", default="global")

# Type-safe config
enabled = doc.get_config_bool("feature_enabled")
count = doc.get_config_int("max_items", default=100)
rate = doc.get_config_float("threshold", default=0.5)
```

### Header Information

```python
# Access header
print(doc.header.domain)    # dtHC
print(doc.header.version)   # 1.0
print(doc.header.profile)   # pMedical
print(doc.header.security)  # s1
print(doc.header.web3)      # w0
```

### Writing DTL

```python
import dtl

# Write to string
content = dtl.write(doc)

# Write to file
dtl.write_file(doc, "output.dtl")
```

### Validation

```python
# Validate document
errors = doc.validate()
if errors:
    for error in errors:
        print(f"Error: {error}")

# Strict parsing (raises on error)
doc = dtl.parse_file("data.dtl", strict=True)
```

## CLI Tool

```bash
# Parse and display
dtl parse data.dtl
dtl parse data.dtl --show-data

# Validate
dtl validate data.dtl

# Convert to JSON
dtl convert data.dtl --to json
dtl convert data.dtl --to json -o output.json

# Show info
dtl info data.dtl

# List tables
dtl tables data.dtl
dtl tables data.dtl --verbose
```

## DTL Types

| Type | Description | Python Type | Example |
|------|-------------|-------------|---------|
| `s` | String | `str` | `hello` |
| `i` | Integer | `int` | `42` |
| `f` | Float | `float` | `3.14` |
| `b` | Boolean | `bool` | `1` or `0` |
| `D` | Date | `date` | `2024-01-15` |
| `T` | DateTime | `datetime` | `2024-01-15T10:30:00Z` |
| `a(s)` | Array of strings | `list[str]` | `a,b,c` |
| `a(i)` | Array of integers | `list[int]` | `1,2,3` |
| `e(M,F)` | Enum | `str` | `M` |

## Domain Codes

| Code | Domain | Use Case |
|------|--------|----------|
| `dtHC` | Healthcare | EHR, HIPAA, clinical |
| `dtFN` | Finance | Transactions, audit |
| `dtLG` | Legal | Contracts, compliance |
| `dtID` | Identity | Auth tokens, SSO |
| `dtAI` | AI/ML | Training data, models |
| `dtIOT` | IoT | Sensors, edge |

## Security Modes

| Mode | Description |
|------|-------------|
| `S0` | No security (inherits file defaults) |
| `S1` | Row-level hashing (BLAKE3-256) |
| `S2` | Row-level encryption |

## Web3 Modes

| Mode | Description |
|------|-------------|
| `W0` | No Web3 integration |
| `W1` | File-level digital signature |
| `W2` | Row-level digital signatures |

## Error Handling

```python
from dtl.exceptions import DTLError, DTLParseError, DTLValidationError

try:
    doc = dtl.parse_file("data.dtl", strict=True)
except DTLParseError as e:
    print(f"Parse error: {e}")
except DTLValidationError as e:
    print(f"Validation error: {e}")
except DTLError as e:
    print(f"DTL error: {e}")
```

## Optional Dependencies

```bash
# For cryptographic features (hashing, signatures)
pip install dtl-parser[crypto]
```

## Resources

- 📖 **Specification**: [dtlaz.org](https://dtlaz.org)
- 📚 **Documentation**: [dtlaz.org/docs](https://dtlaz.org/docs)
- 🐙 **GitHub**: [github.com/dtlaz/python-sdk](https://github.com/dtlaz/python-sdk)
- 📦 **PyPI**: [pypi.org/project/dtl-parser](https://pypi.org/project/dtl-parser/)

## License

MIT License - see [LICENSE](LICENSE) for details.

## Author

**Padam Sundar Kafle** — Commander of Superintelligence

[dtlaz.org](https://dtlaz.org) | [AlifZetta](https://alifzetta.com)
