cdxf 0.1.0__tar.gz

cdxf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muntaser Syed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cdxf-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: cdxf
+Version: 0.1.0
+Summary: Compact Data Exchange Format -- universal binary interchange for JSON, YAML, XML, and TOML
+Author-email: Muntaser Syed <jemsbhai@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/jemsbhai/cdxf
+Project-URL: Repository, https://github.com/jemsbhai/cdxf
+Project-URL: Issues, https://github.com/jemsbhai/cdxf/issues
+Keywords: serialization,binary,interchange,json,yaml,xml,toml,cbor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: File Formats
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cbor2>=5.4
+Requires-Dist: ruamel.yaml>=0.17
+Requires-Dist: tomlkit>=0.11
+Dynamic: license-file
+
+# CDXF — Compact Data Exchange Format
+
+A universal binary interchange format whose information model is a provable superset of JSON, YAML, XML, and TOML, enabling lossless round-trip encoding of documents from any of these format families.
+
+## Status
+
+**Alpha.** The specification and reference implementation are functional with 408 tests passing. All four format bridges (JSON, YAML, XML, TOML) are complete with full round-trip fidelity verified on a 43-file benchmark corpus.
+
+## Motivation
+
+Every existing binary serialization format is anchored to a single text format's information model. CBOR and MessagePack encode the JSON data model. EXI and Fast Infoset encode the XML Information Set. Nothing encodes YAML's graph-structured representation or TOML's typed configuration model. And critically, no binary format preserves all of them through a single unified information model.
+
+CDXF fills that gap.
+
+## What CDXF preserves that others lose
+
+Empirically verified via automated tests (EXP-001 Feature Preservation Matrix):
+
+| Construct | CDXF | CBOR | MsgPack | BSON | Ion |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Map key order | ✓ | ✓ | ✓ | ✓ | ✗ |
+| Non-string map keys | ✓ | ✓ | ✗ | ✗ | ✗ |
+| Comments | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Anchors/Aliases (graph) | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Merge keys | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Multi-document streams | ✓ | ✗ | ✗ | ✗ | ✗ |
+| XML elements/attributes | ✓ | ✗ | ✗ | ✗ | ✗ |
+| XML namespaces | ✓ | ✗ | ✗ | ✗ | ✗ |
+| XML mixed content | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Processing instructions | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Typed timestamps | ✓ | ✓ | ✗ | ✓ | ✗ |
+| Typed date/time (local) | ✓ | ✗ | ✗ | ✗ | ✗ |
+| **Total** | **12/12** | **3/12** | **1/12** | **2/12** | **0/12** |
+
+## Installation
+
+```bash
+pip install cdxf
+```
+
+## CLI Usage
+
+```bash
+# Encode a JSON file to CDXF binary
+cdxf encode config.json                   # -> config.cdxf
+
+# Decode back to text (auto-detects source format)
+cdxf decode config.cdxf                   # -> config.json
+
+# Convert between formats via CDXF
+cdxf convert data.yaml --to json          # -> data.json
+cdxf convert config.json --to toml        # -> config.toml
+
+# Inspect a file
+cdxf info config.json
+# File:          config.json
+# Type:          JSON text
+# Text size:     2,946 bytes
+# CDXF size:     2,001 bytes
+# Ratio:         0.679
+# Node counts:   {'Map': 9, 'Scalar': 114, 'Sequence': 2}
+```
+
+## Python API
+
+```python
+from cdxf.bridges import from_json, to_json, from_yaml, to_yaml
+from cdxf.bridges import from_xml, to_xml, from_toml, to_toml
+from cdxf.codec import encode, decode
+
+# JSON round-trip through binary
+stream = from_json('{"name": "Alice", "age": 30}')
+binary = encode(stream)          # compact CBOR-based binary
+restored = decode(binary)
+print(to_json(restored))         # '{"name": "Alice", "age": 30}'
+
+# Cross-format conversion: YAML → CDXF → JSON
+stream = from_yaml("name: Alice\nage: 30\n")
+print(to_json(stream))           # '{"name": "Alice", "age": 30}'
+
+# YAML with anchors and comments — preserved through binary
+yaml_doc = """
+# Server defaults
+defaults: &defaults
+  timeout: 30
+  retries: 3
+production:
+  <<: *defaults
+  timeout: 60
+"""
+stream = from_yaml(yaml_doc)
+binary = encode(stream)          # anchors, comments, merge keys preserved
+restored = decode(binary)
+print(to_yaml(restored))         # anchors and comments survive
+
+# XML with namespaces and mixed content
+xml_doc = '<p xmlns="http://www.w3.org/1999/xhtml">Hello <b>world</b>!</p>'
+stream = from_xml(xml_doc)
+binary = encode(stream)          # namespaces, mixed content preserved
+restored = decode(binary)
+print(to_xml(restored))          # faithful reconstruction
+```
+
+## Size Efficiency
+
+Median CDXF/text size ratios on a 43-file benchmark corpus:
+
+| Format | Median | Interpretation |
+|---|---|---|
+| JSON | 0.66 | 34% smaller than text |
+| TOML | 0.75 | 25% smaller |
+| YAML | 0.82 | 18% smaller |
+| XML | 1.26 | 26% larger (namespace URIs stored explicitly) |
+
+For JSON data, CDXF shorthand mode produces byte-identical output to standard CBOR — zero overhead.
+
+## Documentation
+
+- [`docs/information_model.md`](docs/information_model.md) — Formal specification: 9 node kinds, 2 conformance levels, format mapping proofs
+- [`docs/binary_encoding.md`](docs/binary_encoding.md) — CBOR-based wire format with 16 semantic tags
+- [`docs/literature_survey_universal_binary_interchange.md`](docs/literature_survey_universal_binary_interchange.md) — Comprehensive gap analysis of existing binary formats
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Author
+
+Muntaser Syed ([@jemsbhai](https://github.com/jemsbhai)) — Florida Institute of Technology

cdxf-0.1.0/README.md

@@ -0,0 +1,129 @@
+# CDXF — Compact Data Exchange Format
+
+A universal binary interchange format whose information model is a provable superset of JSON, YAML, XML, and TOML, enabling lossless round-trip encoding of documents from any of these format families.
+
+## Status
+
+**Alpha.** The specification and reference implementation are functional with 408 tests passing. All four format bridges (JSON, YAML, XML, TOML) are complete with full round-trip fidelity verified on a 43-file benchmark corpus.
+
+## Motivation
+
+Every existing binary serialization format is anchored to a single text format's information model. CBOR and MessagePack encode the JSON data model. EXI and Fast Infoset encode the XML Information Set. Nothing encodes YAML's graph-structured representation or TOML's typed configuration model. And critically, no binary format preserves all of them through a single unified information model.
+
+CDXF fills that gap.
+
+## What CDXF preserves that others lose
+
+Empirically verified via automated tests (EXP-001 Feature Preservation Matrix):
+
+| Construct | CDXF | CBOR | MsgPack | BSON | Ion |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Map key order | ✓ | ✓ | ✓ | ✓ | ✗ |
+| Non-string map keys | ✓ | ✓ | ✗ | ✗ | ✗ |
+| Comments | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Anchors/Aliases (graph) | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Merge keys | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Multi-document streams | ✓ | ✗ | ✗ | ✗ | ✗ |
+| XML elements/attributes | ✓ | ✗ | ✗ | ✗ | ✗ |
+| XML namespaces | ✓ | ✗ | ✗ | ✗ | ✗ |
+| XML mixed content | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Processing instructions | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Typed timestamps | ✓ | ✓ | ✗ | ✓ | ✗ |
+| Typed date/time (local) | ✓ | ✗ | ✗ | ✗ | ✗ |
+| **Total** | **12/12** | **3/12** | **1/12** | **2/12** | **0/12** |
+
+## Installation
+
+```bash
+pip install cdxf
+```
+
+## CLI Usage
+
+```bash
+# Encode a JSON file to CDXF binary
+cdxf encode config.json                   # -> config.cdxf
+
+# Decode back to text (auto-detects source format)
+cdxf decode config.cdxf                   # -> config.json
+
+# Convert between formats via CDXF
+cdxf convert data.yaml --to json          # -> data.json
+cdxf convert config.json --to toml        # -> config.toml
+
+# Inspect a file
+cdxf info config.json
+# File:          config.json
+# Type:          JSON text
+# Text size:     2,946 bytes
+# CDXF size:     2,001 bytes
+# Ratio:         0.679
+# Node counts:   {'Map': 9, 'Scalar': 114, 'Sequence': 2}
+```
+
+## Python API
+
+```python
+from cdxf.bridges import from_json, to_json, from_yaml, to_yaml
+from cdxf.bridges import from_xml, to_xml, from_toml, to_toml
+from cdxf.codec import encode, decode
+
+# JSON round-trip through binary
+stream = from_json('{"name": "Alice", "age": 30}')
+binary = encode(stream)          # compact CBOR-based binary
+restored = decode(binary)
+print(to_json(restored))         # '{"name": "Alice", "age": 30}'
+
+# Cross-format conversion: YAML → CDXF → JSON
+stream = from_yaml("name: Alice\nage: 30\n")
+print(to_json(stream))           # '{"name": "Alice", "age": 30}'
+
+# YAML with anchors and comments — preserved through binary
+yaml_doc = """
+# Server defaults
+defaults: &defaults
+  timeout: 30
+  retries: 3
+production:
+  <<: *defaults
+  timeout: 60
+"""
+stream = from_yaml(yaml_doc)
+binary = encode(stream)          # anchors, comments, merge keys preserved
+restored = decode(binary)
+print(to_yaml(restored))         # anchors and comments survive
+
+# XML with namespaces and mixed content
+xml_doc = '<p xmlns="http://www.w3.org/1999/xhtml">Hello <b>world</b>!</p>'
+stream = from_xml(xml_doc)
+binary = encode(stream)          # namespaces, mixed content preserved
+restored = decode(binary)
+print(to_xml(restored))          # faithful reconstruction
+```
+
+## Size Efficiency
+
+Median CDXF/text size ratios on a 43-file benchmark corpus:
+
+| Format | Median | Interpretation |
+|---|---|---|
+| JSON | 0.66 | 34% smaller than text |
+| TOML | 0.75 | 25% smaller |
+| YAML | 0.82 | 18% smaller |
+| XML | 1.26 | 26% larger (namespace URIs stored explicitly) |
+
+For JSON data, CDXF shorthand mode produces byte-identical output to standard CBOR — zero overhead.
+
+## Documentation
+
+- [`docs/information_model.md`](docs/information_model.md) — Formal specification: 9 node kinds, 2 conformance levels, format mapping proofs
+- [`docs/binary_encoding.md`](docs/binary_encoding.md) — CBOR-based wire format with 16 semantic tags
+- [`docs/literature_survey_universal_binary_interchange.md`](docs/literature_survey_universal_binary_interchange.md) — Comprehensive gap analysis of existing binary formats
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Author
+
+Muntaser Syed ([@jemsbhai](https://github.com/jemsbhai)) — Florida Institute of Technology

cdxf-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cdxf"
+version = "0.1.0"
+description = "Compact Data Exchange Format -- universal binary interchange for JSON, YAML, XML, and TOML"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Muntaser Syed", email = "jemsbhai@gmail.com"},
+]
+keywords = ["serialization", "binary", "interchange", "json", "yaml", "xml", "toml", "cbor"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: File Formats",
+]
+dependencies = [
+    "cbor2>=5.4",
+    "ruamel.yaml>=0.17",
+    "tomlkit>=0.11",
+]
+
+[project.scripts]
+cdxf = "cdxf.cli:entry_point"
+
+[project.urls]
+Homepage = "https://github.com/jemsbhai/cdxf"
+Repository = "https://github.com/jemsbhai/cdxf"
+Issues = "https://github.com/jemsbhai/cdxf/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"

cdxf-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cdxf-0.1.0/src/cdxf/__init__.py

@@ -0,0 +1,51 @@
+"""CDXF -- Compact Data Exchange Format.
+
+A universal binary interchange format whose information model is a provable
+superset of JSON, YAML, XML, and TOML.
+"""
+
+__version__ = "0.1.0"
+
+from cdxf.model import (
+    Stream,
+    Document,
+    Map,
+    Sequence,
+    Scalar,
+    Element,
+    Attribute,
+    Comment,
+    ProcessingInstruction,
+    Directive,
+    TagAnnotation,
+    Anchor,
+    Alias,
+    ScalarType,
+    SourceFormat,
+)
+
+from cdxf.codec import encode, decode, Encoder, Decoder
+
+__all__ = [
+    # Model
+    "Stream",
+    "Document",
+    "Map",
+    "Sequence",
+    "Scalar",
+    "Element",
+    "Attribute",
+    "Comment",
+    "ProcessingInstruction",
+    "Directive",
+    "TagAnnotation",
+    "Anchor",
+    "Alias",
+    "ScalarType",
+    "SourceFormat",
+    # Codec
+    "encode",
+    "decode",
+    "Encoder",
+    "Decoder",
+]

cdxf-0.1.0/src/cdxf/bridges/__init__.py

@@ -0,0 +1,13 @@
+"""CDXF format bridges — convert between text formats and CDXF model."""
+
+from cdxf.bridges.json_bridge import from_json, to_json
+from cdxf.bridges.yaml_bridge import from_yaml, to_yaml
+from cdxf.bridges.xml_bridge import from_xml, to_xml
+from cdxf.bridges.toml_bridge import from_toml, to_toml
+
+__all__ = [
+    "from_json", "to_json",
+    "from_yaml", "to_yaml",
+    "from_xml", "to_xml",
+    "from_toml", "to_toml",
+]

cdxf-0.1.0/src/cdxf/bridges/json_bridge.py

@@ -0,0 +1,122 @@
+"""JSON bridge — convert between JSON text and CDXF model.
+
+Functions:
+    from_json(text) -> Stream
+    to_json(stream, indent=None) -> str
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from cdxf.model import (
+    Comment,
+    Document,
+    Map,
+    Scalar,
+    ScalarType,
+    Sequence,
+    SourceFormat,
+    Stream,
+)
+
+
+def from_json(text: str) -> Stream:
+    """Parse JSON text into a CDXF Stream.
+
+    Parameters
+    ----------
+    text : str
+        Valid JSON text.
+
+    Returns
+    -------
+    Stream
+        A single-document CDXF Stream with source_format_hint=JSON.
+    """
+    raw = json.loads(text)
+    root = _from_native(raw)
+    doc = Document(root=root, source_format_hint=SourceFormat.JSON)
+    return Stream(documents=[doc])
+
+
+def to_json(stream: Stream, *, indent: int | None = None) -> str:
+    """Convert a CDXF Stream to JSON text.
+
+    Uses the first document in the stream. Comments and CDXF-specific
+    annotations are silently dropped (JSON cannot represent them).
+
+    Parameters
+    ----------
+    stream : Stream
+        A CDXF Stream.
+    indent : int or None
+        If set, pretty-print with this indentation level.
+
+    Returns
+    -------
+    str
+        Valid JSON text.
+    """
+    if not stream.documents:
+        return "null"
+    root = stream.documents[0].root
+    native = _to_native(root)
+    return json.dumps(native, indent=indent, ensure_ascii=False)
+
+
+# -------------------------------------------------------------------
+# Internal: Python native types ↔ CDXF model
+# -------------------------------------------------------------------
+
+def _from_native(value: Any) -> Scalar | Map | Sequence:
+    """Convert a Python value (from json.loads) to a CDXF node."""
+    if value is None:
+        return Scalar(ScalarType.NULL, None)
+    if isinstance(value, bool):
+        return Scalar(ScalarType.BOOLEAN, value)
+    if isinstance(value, int):
+        return Scalar(ScalarType.INTEGER, value)
+    if isinstance(value, float):
+        return Scalar(ScalarType.FLOAT, value)
+    if isinstance(value, str):
+        return Scalar(ScalarType.STRING, value)
+    if isinstance(value, dict):
+        entries = []
+        for k, v in value.items():
+            key_node = Scalar(ScalarType.STRING, k)
+            value_node = _from_native(v)
+            entries.append((key_node, value_node))
+        return Map(entries=entries)
+    if isinstance(value, list):
+        items = [_from_native(item) for item in value]
+        return Sequence(items=items)
+    raise ValueError(f"Unsupported JSON value type: {type(value)}")
+
+
+def _to_native(node) -> Any:
+    """Convert a CDXF node to a Python native value for json.dumps."""
+    if isinstance(node, Scalar):
+        return node.value
+    if isinstance(node, Map):
+        result = {}
+        for entry in node.entries:
+            # Skip comments — JSON can't represent them
+            if isinstance(entry, Comment):
+                continue
+            key, value = entry
+            # JSON keys must be strings
+            key_str = key.value if isinstance(key, Scalar) else str(key)
+            result[key_str] = _to_native(value)
+        return result
+    if isinstance(node, Sequence):
+        return [
+            _to_native(item)
+            for item in node.items
+            if not isinstance(item, Comment)
+        ]
+    # Fallback for types JSON can't represent
+    if hasattr(node, "value"):
+        return node.value
+    return str(node)