Metadata-Version: 2.4
Name: varfile
Version: 0.1.1
Summary: A simple parser for .var variable files with object-mapping support
Author: Ely
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# varfile

**varfile** is a fast, lightweight, zero-dependency Python library for working with `.var` configuration files. It combines the simplicity of INI-style configs with Python-friendly object access, automatic type conversion, and easy file editing.

## Features

* **Dot Notation Access**
  Access configuration values naturally:

  ```python
  config.Database.host
  ```

  instead of:

  ```python
  config["Database"]["host"]
  ```

* **Automatic Type Conversion**
  Values are automatically converted to the appropriate Python types:

  * `int`
  * `float`
  * `bool`
  * `str`

* **Easy Editing**
  Modify values directly in memory and save them back to disk with a single command.

* **Robust Parsing**
  Handles comments, special characters, URLs containing `#`, and other common edge cases.

* **Clean Serialization**
  Preserves formatting conventions such as lowercase booleans (`true` / `false`) when writing files.

---

# Installation

Install with pip:

```bash
pip install varfile
```

Or with uv:

```bash
uv add varfile
```
or
```bash
uv pip install varfile
```

---

# Quick Start

## 1. Create a `.var` File

Create a file named `demo.var`:

```ini
# Global settings
app_name = "Varfile Demo"
environment = "development"
debug_mode = true
max_users = 150

[Database]
host = "127.0.0.1"
port = 5432
timeout = 45.8
enabled = false
url = "https://varfiletest.com/#user1"
```

---

## 2. Read Configuration Values

Load a file and access values using dot notation:

```python
import varfile

config = varfile.load("demo.var")

print(config.app_name)          # Varfile Demo
print(config.max_users)         # 150
print(config.Database.port)     # 5432
print(config.Database.enabled)  # False
```

---

## 3. Modify and Save Values

Update values in memory and write them back to the file:

```python
import varfile

config = varfile.load("demo.var")

config.max_users = 100
config.Database.port = 5000

varfile.dump(config, "demo.var")

print("Configuration updated successfully!")
```

---

## 4. Create a Configuration From Scratch

You can also build configuration files programmatically:

```python
import varfile

config = varfile.VarConfig()

config.new_setting = "Hello World"
config.user_count = 1

config.FeatureToggle = {
    "dark_mode": True,
    "beta_tester": False
}

varfile.dump(config, "new_config.var")
```

Generated `new_config.var`:

```ini
new_setting = "Hello World"
user_count = 1

[FeatureToggle]
dark_mode = true
beta_tester = false
```

---

# API Reference

| Function / Class                 | Description                                                           |
| -------------------------------- | --------------------------------------------------------------------- |
| `varfile.load(filepath)`         | Load a `.var` file from disk and return a `VarConfig` object.         |
| `varfile.dump(config, filepath)` | Save a `VarConfig` object to a `.var` file.                           |
| `varfile.loads(string_data)`     | Parse `.var` content from a string.                                   |
| `varfile.dumps(config)`          | Convert a configuration object into `.var` formatted text.            |
| `varfile.VarConfig()`            | Create a new empty configuration container with dot notation support. |

---

# Why varfile?

Many configuration formats are either too limited or unnecessarily complex. varfile aims to provide a middle ground:

* Easy to read
* Easy to edit
* Python-friendly
* No external dependencies
* Clean object-style access

Whether you're building a small script or a larger application, varfile keeps configuration management simple.
