Metadata-Version: 2.4
Name: withopen_lite
Version: 2.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, or 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)                |
| Smart select indexing       | Select columns or elements directly from read data                |

---

## 🧩 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`: Controls how structure, type, and integrity are checked.

  * In normal mode (for reading) it checks only structure and data types.
  * In write and append it also adds a metadata tag for corruption detection.
  * Default is True, so beginners can skip it.
  * Set `validate=False` if you want to skip all validation and write plain files.

---

## ✨ Validation System (validate Parameter)

### Overview

The validate parameter now performs two roles depending on where it is used.

| Function   | What it does                                                                        |
| ---------- | ----------------------------------------------------------------------------------- |
| r()        | Validates structure and data types only                                             |
| w() or a() | Validates structure and data types and adds a metadata tag for corruption detection |

### Normal Validation (Structure and Data Types)

This check confirms that data shapes and element types remain consistent.
It ensures:

* Each row or list has the same structure.
* Data types match between rows and columns.

If inconsistency occurs, withopen lite displays a detailed message showing where it happened.

Example:

```python
TypeError: 🪖 𝗪𝗜𝗧𝗛𝗢𝗣𝗘𝗡 ▸ ❌ Data type mismatch detected!
Line 1 Column 2
Expected: int
Found: str (from value '12')
```

### Metadata Tag (Corruption Detection)

When validate=True in write or append, a small metadata tag is automatically added at the bottom of both the main and backup files.

Example:

```
--- [ (c) withopen_lite Last Updated: 2025 10 30 21:09:43 ] ---
```

**Purpose:**

* Confirms that the file was last saved correctly using withopen lite.
* Helps detect incomplete or manually edited files.
* Triggers automatic fallback to the backup file if corruption is detected.

The tag is not part of your data. It is an integrity marker used internally by the reader.

### When to Keep validate=True

Keep validation enabled if you are using only withopen lite for reading and writing, or if you want automatic protection against corruption and structure errors.
This is the safest default.

### When to Set validate=False

Set validate=False if you are using standard file handlers, external systems, or other tools that expect plain text files without the metadata tag.

```python
f.w("datafile", my_list, validate=False)
f.a("datafile", more_data, validate=False)
```

This skips structure checking and prevents the metadata tag from being added.

### Summary

| Function                | validate=True Behavior          | Metadata Tag Added | Structure and Type Validation |
| ----------------------- | ------------------------------- | ------------------ | ----------------------------- |
| r()                     | Validates data structure only   | ❌                  | ✅                             |
| w()                     | Validates and adds metadata tag | ✅                  | ✅                             |
| a()                     | Validates and adds metadata tag | ✅                  | ✅                             |
| All with validate=False | Raw read or write, no 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

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

# Using default validation
f.w("tasks", [["Name", "Status"], ["Alice", "Done"]])

# One dimensional 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
# Two dimensional append
f.a("tasks", [["Bob", "Pending"]])

# One dimensional 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, index=None, set_new=None, display=True, validate=True)`

Read structured data, now with smart selection indexing.

```python
# Normal read
data = f.r("tasks")
print(data)

# Select a specific column
names = f.r("tasks", index=0)

# Select multiple columns
subset = f.r("tasks", index=[0, 2])

# Return default if file does not exist
data = f.r("missing_file", set_new=[["Header1", "Header2"]])
```

#### Parameters

| Parameter | Type                      | Default | Description                                     |
| --------- | ------------------------- | ------- | ----------------------------------------------- |
| txt_name  | str                       | None    | Base file name (with or without .txt extension) |
| index     | int, list, tuple, or None | None    | Select specific columns or elements directly    |
| set_new   | list or None              | []      | Default return if file is missing               |
| display   | bool                      | True    | Prints notice if file does not exist            |
| validate  | bool                      | True    | Checks structure and data types after reading   |

#### Behavior

* Reads file.txt first, then file_backup.txt as fallback.
* Returns set_new if neither exists.
* Uses smart_select for column or element selection.

#### Examples

```python
# tasks.txt → [["Name", "Status"], ["Alice", "Done"], ["Bob", "Pending"]]

f.r("tasks", index=0)
# → ["Name", "Alice", "Bob"]

f.r("tasks", index=[0, 1])
# → [["Name", "Status"], ["Alice", "Done"], ["Bob", "Pending"]]
```

---

## 🔄 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 called file_backup.txt
* Reads backup if main file fails or is incomplete

---

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

**index**
New in this version. Select columns or items directly from your data.

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

**validate**
Checks that file structure and data types match. In write and append it also adds a metadata tag for corruption detection. Default is True.

---

## 📦 Installation

```bash
pip install withopen lite
```

---

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

---
