dtl-parser 1.2.0

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

🧬 DTL Parser

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

📖 Specification: dtlaz.org

Installation

pip install dtl-parser

Quick Start

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

# 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"

🔐 Security Features

DTL supports cryptographic security for sensitive data:

Security Modes

Mode	Description	Use Case
S0	No security (plaintext)	Public data
S1	Row-level hashing (BLAKE3)	Integrity verification
S2	Row-level encryption (AES-256-GCM)	Confidential data

Web3 Modes

Mode	Description	Use Case
W0	No signatures	Standard files
W1	File-level Ed25519 signature	Document signing
W2	Row-level signatures	Audit trails

Secure Writing

from dtl import SecureDTLWriter, DTLSecurity

# Generate encryption key
key = DTLSecurity.generate_key()

# Create secure writer (S2 = encrypted)
writer = SecureDTLWriter(
    security_mode="S2",
    encryption_key=key
)

# Write encrypted table
content = writer.create_file(
    domain="dtHC",
    profile="pPatients",
    tables={
        "PATIENTS": {
            "schema": {"id": "s", "name": "s", "ssn": "s"},
            "rows": [
                {"id": "P001", "name": "John Doe", "ssn": "123-45-6789"}
            ]
        }
    }
)

Integrity Verification

from dtl import DTLSecurity

# Hash a row
row_hash = DTLSecurity.hash_row("P001|John Doe|active")

# Verify file integrity
is_valid, message = DTLSecurity.verify_file_integrity(content)

# Check available crypto
crypto = DTLSecurity.is_crypto_available()
# {'blake3': True, 'encryption': True, 'signatures': True}

Digital Signatures

from dtl import DTLSecurity

# Generate keypair
private_key, public_key = DTLSecurity.generate_signing_keypair()

# Sign content
signature = DTLSecurity.sign_content(content, private_key)

# Verify signature
is_valid = DTLSecurity.verify_signature(content, signature, public_key)

Install Security Dependencies

pip install dtl-parser[security]

🔄 Format Converters

Convert between DTL and other formats bidirectionally:

JSON ↔ DTL

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

# 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

# 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

# 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)

# 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)

# 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

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

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

Auto-detect Format

# 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

@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

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

# 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

# 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

# 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

import dtl

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

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

Validation

# 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

# 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

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

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

Resources

• 📖 Specification: dtlaz.org
• 📚 Documentation: dtlaz.org/docs
• 🐙 GitHub: github.com/dtlaz/python-sdk
• 📦 PyPI: pypi.org/project/dtl-parser

License

MIT License - see LICENSE for details.

Author

Padam Sundar Kafle — Commander of Superintelligence

dtlaz.org | AlifZetta