withopen-lite 2.0.1

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

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.

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.

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.

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

# 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

# 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

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

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

---