withopen 1.0.0

A structure-aware and data type text file manager for Python that enforces type safety, 1D/2D consistency, and automatic backups.

---

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

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.

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.

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

# 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

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

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

pip install withopen-lite

Or drop the single file:

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

---