Metadata-Version: 2.4
Name: just-cdb
Version: 0.2.0
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering
Requires-Dist: click>=8.0.0
License-File: LICENSE
Summary: High-performance CDB reader for SOFiSTiK® databases with SQL query interface
Keywords: cdb,sofistik,structural-engineering,sql,sqlite,parser,database,zero-copy,rust
Author-email: Thomas Oberbichler <thomas.oberbichler@gmail.com>
License: ISC
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/oberbichler/just-cdb
Project-URL: Issues, https://github.com/oberbichler/just-cdb/issues
Project-URL: Repository, https://github.com/oberbichler/just-cdb

<p align="center">
  <img src="https://raw.githubusercontent.com/oberbichler/just-cdb/main/logo.svg" alt="just-cdb logo" width="400" />
</p>

<p align="center">
  <i>A high-performance, completely self-contained CDB reader for SOFiSTiK® databases with a built-in SQL query engine.</i>
</p>

<p align="center">
  <a href="https://pypi.org/project/just-cdb/"><img src="https://img.shields.io/pypi/v/just-cdb.svg" alt="PyPI Version" /></a>
  <a href="https://pypi.org/project/just-cdb/"><img src="https://img.shields.io/pypi/pyversions/just-cdb.svg" alt="Supported Python Versions" /></a>
  <a href="https://doc.rust-lang.org/edition-guide/rust-2024/index.html"><img src="https://img.shields.io/badge/Rust-2024-orange.svg" alt="Rust Edition" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-ISC-blue.svg" alt="License" /></a>
</p>


## Features
An elegant, modern CDB reader designed to make extracting structural engineering data simple, robust, and fast:

* **Lightweight & Self-Contained:** Completely free of commercial dependencies. Read and parse CDB files anywhere without heavy background installations or dynamic linking issues.
* **Run Anywhere (Windows, macOS, Linux):** Built with native cross-platform capability from day one. Run analyses, automate reporting, or inspect files seamlessly on your Macbook, a Linux cloud server, or standard Windows PCs.
* **Instant SQL Queries:** Forget writing complex binary parsing logic. This tool automatically mounts structural CDB data into an easy-to-query format, letting you use standard SQL filters, joins, and aggregations (e.g., extracting specific node coordinates or material properties).
* **Instant Loading & Memory Efficient:** Employs ultra-fast virtual memory mapping and lazy loading. Even multi-gigabyte files open instantly because it only decodes the specific categories your code or query asks for.
* **Simple Command-Line & Python APIs:** Comes with a user-friendly command-line interface (CLI) to quickly inspect file info, list categories, or export data to Markdown and JSON, alongside a clean Python API for your custom workflows.

## Installation

We recommend using [uv](https://docs.astral.sh/uv/) for Python package management.

If you want to use the `just-cdb` CLI globally on your system:

```bash
uv tool install just-cdb
```

Install it directly into your Python project:

```bash
uv add just-cdb

// or via pip
pip install just-cdb
```

You can run the CLI instantly without installing it:

```bash
uvx just-cdb
```

## CLI Usage
After installation, the command line interface `just-cdb` is instantly available.

### 1. Show Metadata
Get key details about any CDB database file:
```bash
just-cdb info path/to/database.cdb
```
*Output:*
```text
CDB File Information:
- Source             : path/to/database.cdb
- File Size          : 5_684_212 bytes
- CDBase Version     : v12.7.0.32
- Flags              : 0x00000001
- Records            : 1_420 / 2_500 (used / max)
- Total Pages (Keys) : 14
- Chain Head Block   : 142
- Page Dir Start     : 16
- Next Free Record   : 43
```

You can also run with the `--verbose` / `-v` flag to get a detailed, perfectly aligned breakdown of KWH categories present in the file:
```bash
just-cdb info path/to/database.cdb -v
```
*Output:*
```text
... (CDB File Information) ...

Content Summary:
- Total Keys (KWH/KWL Pairs) : 14
- Unique Categories (KWH)    : 3

Categories present in this file:
- KWH    0 :      1 key
- KWH   20 :      5 keys
- KWH  100 :      8 keys
```

### 2. List All Keys
List all primary category key pairs (`KWH` / `KWL`) inside the database directory:
```bash
just-cdb keys path/to/database.cdb
```

### 3. Extract Raw Records
Retrieve binary payloads for any specific Key Word High (`KWH`) and Key Word Low (`KWL`) pair:
```bash
just-cdb records path/to/database.cdb 20 0
```
*Output:*
```text
Found 1_005 records for Key pair (20, 0)
Record #0 (12_345 bytes): payload=0x68656c6c6f20776f726c6421
```

You can also use the `--raw` flag to write the raw binary payloads of all matching records directly to `stdout` (e.g., to pipe them to another command or save directly to a file):
```bash
just-cdb records path/to/database.cdb 20 0 --raw > category_20.bin
```

### 4. Query with SQL
Query your CDB structures using robust SQL with custom formats (`json`, `ndjson`, `markdown`, `ascii`):
```bash
just-cdb query path/to/database.cdb "SELECT * FROM node WHERE id > 10" --format markdown
```
*Output:*
```text
| id | type | x     | y     |
|----|------|-------|-------|
| 11 | 1    | 12.34 | 56.78 |
| 12 | 2    | 90.12 | 34.56 |
```

---

## Python API Usage
Use `just-cdb` programmatically inside your Python apps:

```python
from just_cdb import CDBFile, OutputFormat

# Open the CDB file (runs in lazy-loading mode by default)
with CDBFile("path/to/database.cdb") as cdb:
    # 1. Fetch metadata
    header = cdb.get_header()
    print(f"Total pages: {header.total_pages}")

    # 2. Get list of all key pairs (kwh, kwl)
    all_keys = cdb.keys()
    print(f"Available keys: {all_keys}")

    # 3. Retrieve raw record bytes
    records = cdb.get_records(kwh=20, kwl=0)
    for rec in records:
        print(f"Size: {rec.size} bytes, payload: {rec.payload}")

    # 4. Query with SQL (loads referenced tables on demand!)
    rows = cdb.query("SELECT * FROM node WHERE id > 10 LIMIT 3")
    for row in rows:
        print(row)  # Raw dictionary format

    # 5. Format and stream queries directly to standard output or a file
    cdb.query_formatted("SELECT * FROM node", format=OutputFormat.Markdown)
```

## Trademark Disclaimer
SOFiSTiK® is a registered trademark of SOFiSTiK AG. This project is entirely independent and is not affiliated with, sponsored, or endorsed by SOFiSTiK AG.

