Metadata-Version: 2.4
Name: cborld
Version: 0.1.0
Summary: CBOR-LD encode and decode for JSON-LD documents
Author: Subfile, LLC
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/subfile-llc/cborld
Project-URL: Repository, https://github.com/subfile-llc/cborld
Project-URL: Issues, https://github.com/subfile-llc/cborld/issues
Project-URL: Changelog, https://github.com/subfile-llc/cborld/blob/main/CHANGELOG.md
Keywords: cbor,cbor-ld,json-ld,linked-data,verifiable-credentials,semantic-web
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cbor2<6,>=5.6.0
Requires-Dist: base58>=2.1.1
Provides-Extra: context
Requires-Dist: PyLD>=2.0.0; extra == "context"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Dynamic: license-file

# Python CBOR-LD Processor

[![CI](https://github.com/subfile-llc/cborld/actions/workflows/ci.yml/badge.svg)](https://github.com/subfile-llc/cborld/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/cborld)](https://pypi.org/project/cborld/)
[![Python](https://img.shields.io/pypi/pyversions/cborld)](https://pypi.org/project/cborld/)

> A Python CBOR-LD processor for encoding and decoding JSON-LD documents.

## Table of Contents

- [Background](#background)
- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [Contribute](#contribute)
- [License](#license)

## Background

This library provides a [CBOR-LD 1.0](https://w3c.github.io/cbor-ld/)
processor for Python applications, ported from
[@digitalbazaar/cborld](https://github.com/digitalbazaar/cborld).

CBOR-LD is a compact binary serialization of JSON-LD that uses semantic
compression to achieve significantly better compression ratios than
general-purpose algorithms.

### Features

- Encode JSON-LD documents to compact CBOR-LD binary format
- Decode CBOR-LD bytes back to JSON-LD
- CBOR-LD 1.0 tag support (`0xCB1D` / 51997)
- Legacy format support (`legacy-range`, `legacy-singleton`)
- Built-in codecs: HTTP URLs, UUID URNs, DID URLs, data URLs, multibase,
  XSD dates/datetimes, cryptosuite strings
- Custom type table / registry entry support

### Requirements

Python 3.12+

## Install

### PyPI

```bash
pip install cborld
```

With optional [PyLD](https://github.com/digitalbazaar/pyld) support for
remote context resolution:

```bash
pip install cborld[context]
```

### Development

To install locally (for development):

```bash
git clone https://github.com/subfile-llc/cborld.git
cd cborld
pip install -e ".[dev]"
```

## Usage

### Encode

```python
from cborld import encode

cborld_bytes = await encode(
    jsonld_document={
        "@context": "https://www.w3.org/ns/activitystreams",
        "type": "Note",
        "summary": "CBOR-LD",
        "content": "CBOR-LD is awesome!",
    },
    document_loader=my_loader,
    registry_entry_id=1,
)
```

### Decode

```python
from cborld import decode

jsonld_document = await decode(
    cborld_bytes=cborld_bytes,
    document_loader=my_loader,
)
```

### Document Loader

Both `encode` and `decode` require a `document_loader` -- an async callable
that resolves JSON-LD context URLs. If you have PyLD installed, you can use the
built-in adapter:

```python
from cborld import pyld_document_loader

loader = pyld_document_loader(extra_documents={
    "https://example.org/v1": {"@context": {...}},
})

cborld_bytes = await encode(
    jsonld_document=doc,
    document_loader=loader,
    registry_entry_id=1,
)
```

### Custom Type Tables

For registry entry IDs other than 0 (uncompressed) and 1 (default table),
supply a `type_table_loader`:

```python
async def my_type_table_loader(*, registry_entry_id: int) -> dict:
    return {
        "context": {"https://example.org/v1": 0x8000},
        "url": {"https://example.org/v1": 0x8000},
        "none": {"https://example.org/v1": 0x8000},
    }

cborld_bytes = await encode(
    jsonld_document=doc,
    document_loader=loader,
    registry_entry_id=100,
    type_table_loader=my_type_table_loader,
)
```

### Error Handling

All CBOR-LD processing errors raise `CborldError`, which carries a
machine-readable `.code` attribute:

```python
from cborld import CborldError

try:
    doc = await decode(cborld_bytes=data, document_loader=loader)
except CborldError as e:
    print(f"Error [{e.code}]: {e}")
```

## API

### `encode(**kwargs) -> bytes`

Encodes a given JSON-LD document into CBOR-LD bytes.

| Parameter | Type | Description |
|-----------|------|-------------|
| `jsonld_document` | `dict` | The JSON-LD document to encode. |
| `document_loader` | `async (str) -> dict` | Resolves context URLs. |
| `format` | `str` | `"cbor-ld-1.0"` (default), `"legacy-range"`, or `"legacy-singleton"`. |
| `registry_entry_id` | `int` | Registry entry ID (`0` = uncompressed, `1` = default table). |
| `type_table_loader` | `async (registry_entry_id=int) -> dict` | Resolves registry IDs to type tables. Required when `registry_entry_id` > 1. |
| `diagnose` | `(str) -> None` | Optional diagnostic callback. |

### `decode(**kwargs) -> dict`

Decodes CBOR-LD bytes into a JSON-LD document.

| Parameter | Type | Description |
|-----------|------|-------------|
| `cborld_bytes` | `bytes` | The CBOR-LD bytes to decode. |
| `document_loader` | `async (str) -> dict` | Resolves context URLs. |
| `type_table_loader` | `async (registry_entry_id=int) -> dict` | Resolves registry IDs to type tables. |
| `diagnose` | `(str) -> None` | Optional diagnostic callback. |

## Contribute

Please follow the existing code style.

```bash
pip install -e ".[dev]"
pytest
ruff check src tests
```

## Specifications

- [CBOR-LD 1.0](https://w3c.github.io/cbor-ld/)

## License

[BSD-3-Clause](LICENSE) © [Digital Bazaar](https://github.com/digitalbazaar/cborld) / [Subfile](https://github.com/subfile-llc/cborld)
