Metadata-Version: 2.1
Name: nubby
Version: 0.0.2
Summary: Config loader that injects configs using Bevy.
Home-page: https://github.com/ZechCodes/Nubby
License: MIT
Author: ZechCodes
Author-email: hi@zech.codes
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Provides-Extra: toml
Provides-Extra: yaml
Requires-Dist: Bevy (>=2.0.2,<3.0.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0) ; extra == "yaml"
Requires-Dist: tomlkit (>=0.13.2,<0.14.0) ; extra == "toml"
Requires-Dist: tramp (>=0.1.10,<0.2.0)
Project-URL: Documentation, https://github.com/ZechCodes/Nubby/blob/main/README.md
Project-URL: Repository, https://github.com/ZechCodes/Nubby
Description-Content-Type: text/markdown

# Nubby

A simple config loader for Python using Bevy for dependency injection. You just need to create a model, declare what
file name it should look for, and mark that model as a dependency wherever you need to have it made available.

## Installation

```bash
pip install nubby
```

You can optionally install the `toml` or `yaml` extras to support those file formats.

```bash
pip install nubby[toml]
pip install nubby[yaml]
```

Out of the box Nubby will use `tomllib` to read TOML files but the `toml` extra installs the `tomlkit` package which
allows writing to TOML files.

## Usage

Nubby is designed to have the smallest possible API surface area. You just need to create a model type that implements
the `ConfigModel` interface and declare the file name it should look for. Then you can inject that model wherever you
need it using Bevy.

The `ConfigModel` type provides some helper functionality for setting the file name as a class keyword argument.
Alternatively you can set the `__config_filename__` attribute on the class directly.

The file name shouldn't include the file extension. Nubby's file handlers look for supported file extensions in the
search paths. By default, the current working directory is the only search path. You can add more paths using the
`nubby.controllers.get_active_controller().add_path` method. It is also possible to add more file handlers using the
`nubby.controllers.get_active_controller().add_handler` method.

Here's a basic example of loading a model from a file.

```python
from dataclasses import dataclass
from bevy import inject, dependency
from nubby import ConfigModel

@dataclass
class Person(ConfigModel, filename="person_info"):
    name: str
    age: int

    def to_dict(self):
        return {"name": self.name, "age": self.age}

@inject
def print_person_details(person: Person = dependency()):
    print(f"{person.name} is {person.age} years old")
```

Running `print_person_details()` will print the name and age of the person loaded from the `person_info` file.
Depending on the available file handlers it could be a json, toml, or yaml file.

Note that it is not necessary to pass anything to the `print_person_details` function. Bevy automatically injects the
`Person` model and loads the appropriate config file.

To save any modifications to a model just call the active controller's `save` method, passing it the updated model.

```python
from dataclasses import dataclass
from nubby import ConfigModel
from nubby.controllers import get_active_controller

@dataclass
class Person(ConfigModel, filename="person_info"):
    name: str
    age: int

    def to_dict(self):
        return {"name": self.name, "age": self.age}

person = Person("Bob", 31)
get_active_controller().save(person)
```

The `save` method will update the in-memory cache as well as the file on disk. It will not update any models that have
already been created.
