Metadata-Version: 2.4
Name: hiu-os
Version: 0.1.0
Summary: A simple OS simulation in Python
Author-email: Abbas Faramarzi <abbasfaramarzi@example.com>
License: MIT
Project-URL: Homepage, https://github.com/abbasfaamarzi/hiu_os
Project-URL: Bug Tracker, https://github.com/abbasfaamarzi/hiu_os/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file


<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>HiuOs</title>
</head>
<body>
    <div style="text-align: center; padding: 2rem;">
        <img src="hiu_os/logo.png" alt="لوگوی HiuOs" style="max-width: 100%; height: auto;">
        <h1 style="margin-top: 20px;">Welcome to HiuOs</h1>
    </div>
</body>
</html>
# 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:

```python
from hiu import HiuOs
```

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

```python
from __system__._run_ import OperationsSystem
```

---

## Quick Start

```python
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.

```python
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:

```python
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:**

```python
# 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:**

```python
# 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:

```python
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:

```python
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:

```python
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.

```python
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:

```python
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:

```python
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:

```python
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.*
