Metadata-Version: 2.4
Name: litejson
Version: 0.1.0
Summary: Simplified work with JSON files with support for point keys
Author-email: Abemerik <abemerik1@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Abemerik/litejson
Project-URL: Repository, https://github.com/Abemerik/litejson
Project-URL: Documentation, https://github.com/Abemerik/litejson/blob/main/docs/DOCS.md
Project-URL: Issues, https://github.com/Abemerik/litejson/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 🗃️ litejson

[🇷🇺 Читать на русском](docs/README.ru.md) · [📖 Документация на русском](docs/DOCS.ru.md)  
[📖 Complete documentation](docs/DOCS.md)


**Simple JSON file handling without boilerplate**

---

## 📌 Quick Start

```python
from litejson import JsonFile

# Open a file
config = JsonFile("config.json")

# Write data
config.set("user.name", "Egor")
config.set("user.theme", "dark")
config.save()

# Read data
print(config.get("user.name"))  # Egor
```

**3 lines — and you're already working with JSON.**

---

## 📦 Installation

```bash
pip install litejson
```

Or if you want to install from the repository:

```bash
git clone https://github.com/Abemerik/litejson.git
cd litejson
pip install -e .
```

---

## 🧠 What is it and why

`litejson` is a simple library for working with JSON files. It removes all the boilerplate that usually annoys beginners:

- ❌ No more writing `with open(...) as f` every time
- ❌ No more checking if a key exists (to avoid `KeyError`)
- ❌ No more remembering `json.dump()` and `json.load()`

Instead, you just write:

```python
file.set("user.settings.theme", "dark")
```

And the library does everything for you.

---

## ✨ Features

| Feature | Example |
|---------|---------|
| **Dot notation keys** | `file.get("user.settings.theme")` |
| **Auto-creation of nested dicts** | `file.set("a.b.c", 123)` creates `{"a": {"b": {"c": 123}}}` |
| **Context manager** | `with JsonFile("data.json") as f:` |
| **Clear exceptions** | `KeyNotFoundError` instead of `KeyError` |
| **Built-in help** | `file.docs()` — right from the code |

---

## 📖 Usage Examples

### 1️⃣ Bot Configuration

```python
from litejson import JsonFile

config = JsonFile("bot_config.json")

def set_setting(key, value):
    config.set(key, value)
    config.save()

def get_setting(key):
    return config.get(key)

# Usage
set_setting("language", "en")
set_setting("notifications", True)

print(get_setting("language"))  # en
```

---

### 2️⃣ Working with Users (nested keys)

```python
from litejson import JsonFile

users = JsonFile("users.json")

users.set("user.123.name", "Egor")
users.set("user.123.age", 16)
users.set("user.123.settings.theme", "dark")
users.set("user.123.settings.language", "en")
users.save()

# Read
name = users.get("user.123.name")
theme = users.get("user.123.settings.theme")

print(f"{name} uses {theme} theme")  # Egor uses dark theme
```

---

### 3️⃣ Context Manager (auto-save)

```python
from litejson import JsonFile

with JsonFile("data.json") as file:
    file.set("name", "Egor")
    file.set("age", 16)
# The data is automatically saved when exiting the block
```

---

### 4️⃣ Checking if a key exists

```python
from litejson import JsonFile

file = JsonFile("config.json")

if not file.exists("user.theme"):
    file.set("user.theme", "light")
    file.save()
```

---

### 5️⃣ Built-in Help

```python
file.docs()
```

Prints a list of all methods with brief descriptions.

---

## 📋 All Methods

| Method | What it does | Example |
|--------|--------------|---------|
| `read()` | Returns all file contents | `data = file.read()` |
| `save()` | Saves changes to the file | `file.save()` |
| `get(key)` | Returns value by key | `name = file.get("user.name")` |
| `set(key, value)` | Sets value by key | `file.set("theme", "dark")` |
| `pop(key)` | Removes key and returns its value | `old = file.pop("temp")` |
| `keys()` | Returns top-level keys list | `for k in file.keys():` |
| `items()` | Returns `(key, value)` pairs | `for k, v in file.items():` |
| `clear()` | Clears all data | `file.clear()` |
| `exists(key)` | Checks if key exists | `if file.exists("name"):` |
| `reload()` | Reloads data from file | `file.reload()` |
| `docs()` | Prints brief help | `file.docs()` |

---

## 🆚 Comparison with standard json

**Without litejson:**

```python
import json

try:
    with open("config.json", "r") as f:
        data = json.load(f)
except FileNotFoundError:
    data = {}

if "user" in data and "settings" in data["user"]:
    theme = data["user"]["settings"]["theme"]
else:
    theme = None

# To save
data["user"]["settings"]["theme"] = "dark"
with open("config.json", "w") as f:
    json.dump(data, f, indent=2)
```

**With litejson:**

```python
from litejson import JsonFile

file = JsonFile("config.json")
theme = file.get("user.settings.theme")
file.set("user.settings.theme", "dark")
file.save()
```

**3x less code, 10x more readable.**

---

## 📂 Project Structure

```
litejson/
├── src/
│   └── litejson/
│       ├── __init__.py
│       ├── core.py      # Main JsonFile class
│       └── exceptions.py # Custom exceptions
├── tests/
│   └── test_core.py    # Tests (pytest)
├── README.md
├── DOCS.md
├── pyproject.toml
└── LICENSE
```

---

## 📄 License

**MIT License**

---

## 🔗 Links

- **GitHub:** [github.com/Abemerik/litejson](https://github.com/Abemerik/litejson)
- **PyPI:** [pypi.org/project/litejson](https://pypi.org/project/litejson)
- **Author:** [@Abemerik](https://t.me/Abemerik)

---

## 🧑‍💻 Author

**Abemerik** — Python developer.

If you find a bug or want to suggest an improvement — create an Issue on GitHub. I'd appreciate any help and feedback.

---

**🔥 litejson — work with JSON without pain.**
