ndca 3.0.0

NDCA (Nested Data Collection API) — a fast, safe, and human-readable nested data storage and manipulation library for Python.

NDCA — Nested Data Collection API (v3.0.0)

NDCA (Nested Data Collection API) is a fast, secure, and production-ready Python library for storing, reading, and manipulating nested structured data using a compact human-readable format. NDCA is designed for robustness, atomic persistence, safe in-memory operations, and an ergonomic API suitable for scripts, services, and small-to-medium projects.

---

Highlights

• Human-readable NDCA format for nested objects and lists
• Deep-copy safety on reads/writes to avoid accidental mutation
• Atomic file writes to protect data integrity on crashes or interruptions
• Optional autosave per-file instance (file("x.ndca", autosave=True))
• Path-based get/write/delete API supporting nested keys and list indices
• Merge, append, remove-from-list, dump/load-from-text, and table operations
• Table utilities: create, insert, find, update, delete, sort, CSV import/export
• Pagination support for lists and tables
• Version 3.0.0 — stable initial feature set

---

Installation

Install via pip:

pip install ndca

Or include locally by copying the NDCA module into your project.

---

NDCA File Format

NDCA uses a human-readable format to represent nested objects and lists:

Objects

<[key]="value";[key2]=123;[key3]=true;>

Lists

(value1;value2;value3;)

Nested Structures

<[name]="Viren";[age]=12;[skills]=("Python";"Bash";"NDCA");[settings]=<[theme]="dark";[enabled]=true;>;>

Rules

• Objects start with < and end with >
• Keys are wrapped in square brackets [key]
• Key/value pairs are separated with =
• Each item ends with ;
• Lists are wrapped in ( )
• Strings use double quotes " "
• Booleans (true/false) and null (null) are supported
• Supports nested objects and lists

---

Basic Usage

from ndca import NDCA

store = NDCA()

store.write("user", '<[name]="Viren";[age]=12;>')
store.write("config", '<[enabled]=true;[theme]="dark";>')

print(store.get("user"))
# Output: '<[name]="Viren";[age]=12;>'

---

Core Features

• get(path, default) — Read nested values safely
• write(path, value) — Write nested values
• delete(path) — Remove keys or list elements
• exists(path) — Check if path exists
• merge(other) — Merge dictionaries
• append(path, value) — Append to lists
• remove_from_list(path, value) — Remove items from lists
• dump() / dumps() — Return deep copy or serialize NDCA data
• load(filename) / load_from_text(text) — Load NDCA data from file or string
• save(filename) / hash_write(filename) — Save with atomic write and optional hash

---

Table Utilities

NDCA supports lightweight table structures with rows and columns:

• table_create(path, columns) — Create a new table
• table_insert(path, row) — Insert a row
• table_get_row(path, index) — Retrieve a specific row
• table_find(path, criteria) — Query rows by dict or callable
• table_update_row(path, index, updates) — Update specific row fields
• table_delete_row(path, index) — Remove a row
• table_index(path, key, unique=False) — Index rows by key
• table_sort(path, key, reverse=False) — Sort rows
• table_to_csv(path, filename, include_header=True) — Export to CSV
• table_from_csv(path, filename, columns=None) — Import from CSV

---

Pagination Support

page_data = store.paginate("mylist", page=1, per_page=10)
print(page_data["items"])

Returns a dictionary with page, per_page, total, and items.

---

Version

NDCA Version: 3.0.0

---

Example NDCA Data

<[user]=<[name]="Viren";[age]=12;>;[settings]=<[theme]="dark";[notifications]=true;>;[skills]=("Python";"Bash";"NDCA");>

---

License

Read the license under this project!