Metadata-Version: 2.4
Name: ndca
Version: 3.0.0
Summary: NDCA (Nested Data Collection API) — a fast, safe, and human-readable nested data storage and manipulation library for Python.
Author: Viren Sahti
License: License & Disclaimer
        Copyright © 2026-2027 Viren Sahti
        
        This software is provided "as is", without any warranty, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or non-infringement.
        
        By using this software, you agree that Viren is not responsible for any direct or indirect damages, loss of data, profits, or other consequences arising from:
        - Misuse of the software
        - Criminal activity, hacking, or any illegal use
        - Modifications or derivative works
        - Software bugs, failures, or security breaches
        
        This software may only be used for legitimate purposes. Redistribution, modification, or claiming the code as your own is strictly prohibited. All rights remain with Viren Sahti.
        
        Use at your own risk.
Keywords: ndca,nested,data,storage,serialization,configuration,table,csv,python,library
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Database :: Database Engines/Servers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Requires-Dist: isort>=6.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == "test"
Dynamic: license-file

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

```bash
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

```python
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

```python
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!
