Metadata-Version: 2.4
Name: withopen
Version: 1.0.0
Summary: A structure-aware and data type text file manager for Python that enforces type safety, 1D/2D consistency, and automatic backups.
Author: henry
Author-email: osas2henry@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-python
Dynamic: summary

---

# 🪖 withopen-lite

**Your code's .txt sidekick**

A zero-dependency, structure-aware, and type-safe text file manager for Python.
It reads any .txt file in your working directory, validates its structure, and replaces repetitive file I/O logic with clean one-liners.

---

## 🎯 Why withopen-lite?

After writing hundreds of:

```python
with open(file) as f:
```

blocks and rebuilding the same read/write/append logic, I wanted something simpler.

withopen-lite is the minimalist edition:

* Skips folders and tags
* Focuses purely on data integrity and consistency

Perfect for:

* Small automation scripts
* CLI tools
* Local bot storage
* Quick data caching
* Learning structured file management

---

## ⚡ Key Features

| Feature                     | Description                                                       |
| --------------------------- | ----------------------------------------------------------------- |
| Type-safe validation        | Enforces consistent data types across rows and columns            |
| 1D and 2D structure locking | Detects and enforces whether your file is a list or list of lists |
| Auto backup                 | Every write automatically mirrors to (file)_backup.txt            |
| Zero dependencies           | Uses only Python built-ins (os and ast)                           |
| Simple API                  | `w()`, `a()`, `r()` only                                          |
| No tags or folders          | Reads any .txt in your working directory                          |
| Readable format             | Uses literal Python syntax (['a', 'b'] not JSON)                  |

---

## 🧩 Core Functions

### Understanding key parameters (explained once)

* `is2d`: Determines if the file is 1D (flat list) or 2D (list of lists).

  * Use `is2d=False` for a 1D list on the first write.
  * 2D lists are detected automatically (`is2d=None`) for beginners.

* `validate`: Checks that data types and structure are consistent.

  * Default is True, so beginners can skip it.
  * Set `validate=False` if you want to skip type and structure checks.

---

### Write: w(txt_name, write_list, is2d=None, validate=True)

Overwrite or create a new file. Locks file shape on first write.

```python
import withopen_lite as f

# Explicitly validating
f.w("tasks", [["Name", "Status"], ["Alice", "Done"]], validate=True)

# Using default behavior (validate=True)
f.w("tasks", [["Name", "Status"], ["Alice", "Done"]])

# 1D list example
f.w("fruits", ["apple", "banana", "pear"], is2d=False)
```

---

### Append: a(txt_name, append_list, is2d=None, validate=True)

Append data safely, enforcing structure and type consistency.

```python
# 2D append
f.a("tasks", [["Bob", "Pending"]])

# 1D append
f.a("fruits", ["orange"], is2d=False)

# Wrong example
f.a("tasks", ["Charlie", "Done"])
# Registers as flat list instead of 2D
```

---

### Read: r(txt_name, set_new=[], display=True, validate=True)

Read structured data. Returns `set_new` if file does not exist.

```python
# Read with validation
data = f.r("tasks")
print(data)

# Read using default behavior
data = f.r("tasks")
print(data)
```

* `set_new` is returned if the file does not exist
* `validate` ensures data types and structure are checked

---

## 🔄 Using Loops Safely

```python
datas = [
    ["Alice", 25, "Paris"],
    ["Bob", 30, "London"]
]

# Correct append
for row in datas:
    f.a("people", [row])

# Correct write if starting fresh
for row in datas:
    f.w("people", [row])

# Wrong
for row in datas:
    f.a("people", row)
# Registers file as flat list instead of 2D
```

---

## 🔍 Type Safety

```python
f.w("scores", [["user", "score"], ["Alice", 10]])
f.a("scores", [["Bob", "12"]])
```

```
Data type mismatch detected!
Line 1, Column 2
 Expected  : int
 Found     : str (from value: '12')
```

---

## 🧰 Backup Behavior

* Every file automatically maintains a mirror backup: `tasks_backup.txt`
* Reads backup if main file fails or is empty

---

## ⚡ Quick Reference

| Function | Usage          | Notes                      |
| -------- | -------------- | -------------------------- |
| w        | Write new data | Overwrites existing file   |
| a        | Append data    | Must match shape           |
| r        | Read data      | Returns default if missing |

**`is2d`**

* Needed for 1D flat lists
* Optional for 2D lists

**`validate`**

* Checks that file structure and data types match
* Default is True

---

## 📦 Installation

```bash
pip install withopen-lite
```

Or drop the single file:

```bash
withopen_lite.py
```

into your project folder.

---

## 🪖 Philosophy

Small tools should feel invisible.

withopen-lite is not a database.
It is a confidence layer between your code and plain text.
No frameworks, no clutter, just reliable data I/O.

---

## 📄 License

MIT License © 2025
Created by Henry
Part of the withopen project family

---
