hiu-os 0.1.0

A simple OS simulation in Python

<title>HiuOs</title>

Welcome to HiuOs

# HiuOs

A fluent, cursor‑based filesystem navigator and management system for Python applications.

HiuOs provides an intuitive, chainable interface to interact with the file system – reading, writing, updating, and deleting files and directories with minimal boilerplate. It includes built‑in support for JSON, Pickle, plain text files, and directories, along with automatic path resolution, lifecycle logging, and naming convention utilities.

---

Features

• Fluent Navigation – traverse the filesystem using attribute chaining:
  os.assets.ledgers.my_data_json.read
• CRUD Operations – create, read, update, clear, and delete any resource.
• Automatic Creation – missing directories and files are created on‑the‑fly (toggleable).
• Multiple Formats – handles .json, .pkl (Pickle), .txt, .log, .md, and more.
• Smart Path Resolution – automatically finds the application root and builds relative paths.
• Dictionary‑with‑Attributes – DictAttr allows obj.key access on read results.
• Naming Utilities – convert between snake_case, PascalCase, camelCase, and kebab‑case.
• Lifecycle Logging – optionally log every operation to a log.json file.
• Extensible – add your own file handlers by implementing a simple interface.

---

Installation

The package is part of the project and requires no external dependencies beyond Python 3.7+.

Simply import the main class:

from hiu import HiuOs

Or, if you prefer the lower‑level entry point:

from __system__._run_ import OperationsSystem

---

Quick Start

from hiu import HiuOs

# Instantiate the system
os = HiuOs()

# Read the application settings (JSON)
settings = os.settings.read
print(settings.style)          # "Light" (attribute access)

# Update a setting
os.settings.update({"style": "Dark", "color": "Blue"})

# Create a new JSON file in the ledgers folder
os.ledgers.inventory_json.create({"items": ["apple", "banana"]})

# Read it back
inventory = os.ledgers.inventory_json.read
print(inventory.items)         # ['apple', 'banana']

# List contents of the assets directory
assets_content = os.assets.read   # returns a DictAttr of {name: full_path}

# Delete the file we created
os.ledgers.inventory_json.delete()

---

Core Concepts

1. Curser – The Fluent Navigator

Curser is the central class. It represents a path and can be chained to navigate deeper into the filesystem.

from __system__ import Curser

cursor = Curser()                     # starts at the application root
cursor = Curser("/some/absolute/path")# starts at a custom location

Navigation is done via attribute access:

cursor.assets.default.settings_json

If the attribute name matches a known extension (e.g., json, txt, pkl), it is treated as a file; otherwise it is a directory.
You can also use call syntax: cursor("assets")("default")("settings_json").

Auto‑creation is enabled by default (AUTO_CREATE = True). When you navigate to a path that does not exist, it is created automatically (as a directory or empty file).

---

2. Operations on Resources

Every Curser object exposes five core methods:

Method	Description
create(data)	Creates the file/directory (overwrites if exists).
read	Returns the content (dict/list for JSON/Pickle, string for text).
update(data)	Overwrites content (for files) or renames (for directories).
clear()	Empties a file or removes all contents of a directory.
delete()	Permanently removes the file or entire directory tree.

Examples:

# Write a text file
os.assets.notes_txt.create("Hello, world!")

# Read the file
text = os.assets.notes_txt.read   # returns a string

# Update (overwrite)
os.assets.notes_txt.update("New content")

# Clear (truncate to empty)
os.assets.notes_txt.clear()

# Delete
os.assets.notes_txt.delete()

Directory operations:

# Create a directory (if not exists)
os.assets.new_folder.create()

# List contents (returns DictAttr)
contents = os.assets.new_folder.read
for name, full_path in contents.items():
    print(name, full_path)

# Rename the directory
os.assets.new_folder.update(new_name="renamed_folder")

# Clear all contents (keep the directory itself)
os.assets.renamed_folder.clear()

# Delete the directory
os.assets.renamed_folder.delete()

---

3. Paths and Shortcuts

The HiuOs class provides convenient properties for commonly used locations:

• desktop – application root.
• assets, default, fonts, ledgers – subdirectories.
• settings – settings.json file.
• configs, logs, paths – configuration and log files.

All properties are Curser instances, so you can chain operations directly:

os.settings.update({"theme": "dark"})
os.logs.create({})   # creates logs.json if missing

The tree property returns a structured representation of all available cursors and their paths.

---

4. DictAttr – Dictionary with Attribute Access

Many read operations return a DictAttr object, which works like a dictionary but also allows attribute‑style access:

data = os.settings.read
print(data.style)       # instead of data["style"]

This makes the code cleaner and more Pythonic.

---

5. Naming Utilities (SnakePascalName)

Convert between naming conventions easily:

from __operations__.__file__.__base__.__keywords__ import SnakePascalName

SnakePascalName.to_snake_case("MyClassName")   # "my_class_name"
SnakePascalName.to_pascal_case("my_class_name")# "MyClassName"
SnakePascalName.to_camel_case("my_class_name") # "myClassName"
SnakePascalName.to_kebab_case("MyClassName")   # "my-class-name"

---

6. Lifecycle Logging

If you instantiate a Curser with save_log=True, every operation will log details (time, operation type, status) to log.json in the configs folder.

cursor = Curser(save_log=True)
cursor.settings_json.update({"foo": "bar"})   # logged

The logging uses the LifeCycleLog class, which provides hooks for start, working, and stop events.

---

Advanced Usage

Adding Custom File Formats

To support a new format (e.g., YAML), create a class that implements the HttpOperatorRequest interface (methods create, read, update, clear, delete). Then register it in the Curser.file_operations dictionary:

from __system__ import Curser
from my_yaml_handler import YamlFile

Curser.file_operations["yaml"] = YamlFile

Now you can navigate to *.yaml files and perform operations.

Toggling Auto‑Creation

Set the class variable AUTO_CREATE to False to disable automatic creation:

Curser.AUTO_CREATE = False

Now navigating to a missing path will raise an error instead of creating it.

Using the Underlying Handlers Directly

You can also call the static methods of the built‑in handlers:

from __operations__.__file__.__json__ import JsonFile

data = JsonFile.read("path/to/file.json")
JsonFile.update("path/to/file.json", {"key": "value"})

---

API Reference (Main Classes)

Class / Module	Purpose
HiuOs (from hiu)	Main entry point; extends OperationsSystem.
OperationsSystem (from _run_)	High‑level accessor with shortcut properties.
Api (from __api__)	Base class providing resource properties (assets, settings, etc.).
Curser (from __curser__)	Fluent filesystem navigator and operation executor.
InterpreterMixin (from __interpreter__)	Maps verbs like rename, list to CRUD operations.
OperationsMixin (from __operators__)	Provides create, read, update, clear, delete.
Path (from __path__)	Static path utilities (split, join, main_dir, etc.).
Formats (from __formats__)	File name parsing, extension extraction, naming helpers.
DictAttr (from __formats__)	Dictionary with attribute‑style access.
SnakePascalName (from __keywords__)	Naming convention conversion.
LifeCycleLog (from __log__)	Lifecycle logging (start/working/stop).

---

Limitations & Caveats

• Hardcoded backslashes in AppCurser.getattrs – the code uses \\ for Windows; consider using os.path.join for cross‑platform safety.
• Duplicate DictAttr – appears in both __formats__.py and __serializers__.py; centralisation is recommended.
• Formats.column_syntax – the implementation (name[:-2] and name[-1]) is likely buggy; intended to split on the last underscore.
• Global AUTO_CREATE – affects all cursors; per‑cursor control might be desired.
• Lifecycle logging – expects the cursor to have an update method, which couples logging to the cursor’s storage.
• Operation aliases (e.g., list → read) may conflict with reserved attribute names; this is by design.

---

License

This project is part of the HiuOS ecosystem. All rights reserved.