cleandb 5.0

easy to set up alternative to SQl, bugs and leak proof by design and also support multiple console interactions

---

# 🧾 A data cleaning and quality solution for messy data, bug prevention, and leakage control.

A lightweight, Python-native, zero-dependency utility for managing structured .txt files. Ideal for structured data storage where full database integration is overkill. Uses simple 1D/2D list logic

---

## 📦 Features

- ✅ **Structured Data Enforcement (1D/2D)**
- ✍️ **Write, Read, Append, and Delete Operations with Built-in Validation**
- 🔍 **Sql select style Read filtering**
- 🧹 **Selective Deletes & Trimming**
- 🎗️ **Multi-Console Safe for Concurrent Access**
- 💾 **Manual Backups or Timed Snapshots**
- 🧪 **Debug Tool & Auto-Clean Invalid Rows**
- 🗂️ **Clean Folder & Versioned File Organization**
- 🔐 **File Hiding and Visibility Controls**
- 🗃️ **No External Dependencies**
- 💪 **Strong anti-corruption and Tamper mechanism**
---

## Why Use This Package?

**For Data Professionals (Analysts, Scientists, Engineers):**

* Build quick dashboards and visualizations from real-time text data.
* Process and clean scraped or pipeline data without needing a database.
* Track, audit, and version small datasets during experimentation.
* Validate incoming data and auto-correct format issues on the fly (clean from the source).
* Run fast, repeatable data operations locally without SQL overhead.

**For General Developers:**

* Great for automation scripts, bots, or microservices.
* Ideal for prototyping features without setting up a database.
* Use as a flat-file backend for small apps or CLI tools.
* Snapshot and backup data safely without extra libraries.
* Handle concurrent access and reduce race-condition bugs automatically.

---

## 📦 Installation 
pip install cleandb

## ♻️ Upgrade
pip install --upgrade cleandb

---

## 🚀 Quick Usage

```python

# import
import cleandb as db

# Create a 2D structured file
db.w("tasks", [["Read", "Done"], ["Code", "Pending"]], is2d=True)

# Append to file
db.a("tasks", [["Test", "Pending"]])

# Read all data
db.r("tasks")

# Delete rows where status is "Done"
db.d("tasks", del_list=["Done"], index=1)

# Manual backup
db.backup("tasks")

# Snapshot every 6 hours
db.snapshot("tasks", unit="h", gap=6)
```

---

## 🧰 Function Overview

### 🔄 Write

```python
w(txt_name, write_list, is2d=None)
```

Overwrites data and validates structure. Use `[]` to reset file and structure.

---

### 📖 Read

```python
r(txt_name, index=None, set_new=[], notify_new=True)
```

Reads data or returns `set_new` if file doesn't exist.

---

### ➕ Append

```python
a(txt_name, append_list, is2d=None)
```

Appends new data to file. Must match existing structure.

---

### ❌ Delete

```python
d(txt_name, del_list=[], index=None, cutoff=None, keep=None, reverse=False, size=None)
```

Deletes rows by value, with support for:

* `cutoff`: Max deletions per value
* `keep`: Keep N rows per value
* `reverse`: Reverse traversal
* `size`: Trim file to last N rows

---

### 💾 Backup

```python
backup(txt_name, display=True)
```

Creates manual backup. Use `'*'` to back up all files.

---

### ⏱ Snapshot

```python
snapshot(txt_name, unit, gap, trim=None, begin=0, display=True)
```

Creates a time-based snapshot if the gap is met. Units:

* `'s'`, `'m'`, `'h'`, `'d'`, `'mo'`, `'y'`

---

### 🧹 Debug

```python
debug(txt_name, is2d=None, clean=None, length=None, display=True)
```

Scans file for validation issues and optionally cleans/fixes it.

---

### 🧨 Remove

```python
remove(txt_name, display=True)
```

Permanently deletes file and all backups.

---

### 🙈 Hide / Unhide

```python
hide(txt_name, display=True)
unhide(txt_name, display=True)
```

Hides or unhides files or all files with `'*'`.

---

### 📋 List Files

```python
listdir(display=True)
```

Returns list of all stored file names.

---

### ℹ️ File Info

```python
info(txt_name, display=True)
describe(txt_name, display=True)
```

Shows metadata about file: type, shape, size, etc.

---

## 🧠 Notes

* **Structure Locking**: On first write/append, the shape (1D/2D) and row length (for 2D) is saved.
* Use `w("file", [])` to reset the file and clear the structure lock.
* Only `list` data is supported (1D or 2D).
* All changes sync automatically across backups.
* Files are validated before every write operation.

---

## 🛡 Good Practices

* Always use the provided `w`, `a`, `r`, `d`, etc. functions for access.
* Don't manually edit `.txt` files — structure validation may fail.
* Schedule `snapshot()` calls during long-running processes.
* Use `debug()` if you're unsure why writes are failing.

---

## 🧪 Example Workflow

```python
# Setup
import cleandb as db

# first write / create a new file
db.w("expenses", [["Rent", 1200], ["Food", 300]])

# Add a new expense
db.a("expenses", [["Internet", 60]])

# Show last 2 entries
db.print(r("expenses", index=[-2, -1]))

# Remove "Food" entry
db.d("expenses", del_list=["Food"], index=0)

# Take a snapshot every 24 hours
db.snapshot("expenses", unit="d", gap=1 , trim = 12)
```

---

## 📂 Backup & Recovery

* Backups are stored under `Backup 💾/`
* Snapshots are stored under `Snapshot 📸/`
* To restore, simply copy the file back to main data directory

---

## 📜 License

This project is free to use, modify, and distribute. No warranty is provided.

---

## 🙋 Contribution

Feel free to fork, improve, and send pull requests.

---

## ✅ End of README

---