Metadata-Version: 2.1
Name: simple-file-settings
Version: 0.1.2
Summary: Access and updates settings from a file as a class.
Home-page: https://github.com/NathanVaughn/simple-file-settings
License: MIT
Author: Nathan Vaughn
Author-email: nvaughn51@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Provides-Extra: toml
Provides-Extra: yaml
Requires-Dist: pyyaml (>=6.0.1,<7.0.0) ; extra == "yaml"
Requires-Dist: tomli (>=2.0.1,<3.0.0) ; (python_version < "3.11") and (extra == "toml")
Requires-Dist: tomli-w (>=1.0.0,<2.0.0) ; extra == "toml"
Requires-Dist: typeguard (>=4.2.1,<5.0.0)
Project-URL: Issues, https://github.com/NathanVaughn/simple-file-settings/issues
Project-URL: Repository, https://github.com/NathanVaughn/simple-file-settings.git
Description-Content-Type: text/markdown

# Simple-File-Settings

[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![GitHub license](https://img.shields.io/github/license/NathanVaughn/simple-file-settings)](https://github.com/NathanVaughn/simple-file-settings/blob/main/LICENSE)
[![PyPi versions](https://img.shields.io/pypi/pyversions/simple-file-settings)](https://pypi.org/project/simple-file-settings)
[![PyPi downloads](https://img.shields.io/pypi/dm/simple-file-settings)](https://pypi.org/project/simple-file-settings)

---

Sometimes, you just need to save and retain a few settings for your desktop program,
like a theme preference, or last viewed directory. This is a library intended to easily
load and save simple configuration data to and from disk through a
type-checked data class.

## Usage

First, a basic use case:

```bash
pip install simple-file-settings
```

```python
import os
from simplefilesettings.json import JSONClass

class _Settings(JSONClass):
    class Config:
        json_file = os.path.join(os.path.expanduser("~"), "config.json")

    mqtt_host: str = "mqtt"
    mqtt_port: int = 1883
    serial_port: str = "COM1"
    serial_baud_rate: int = 115200
    log_file_directory: str = os.path.join(os.getcwd(), "logs")
    force_light_mode: bool = False
    joystick_inverted: bool = False
    max_moving_map_tracks: int = 5000
    takeoff_height: float = 3

Settings = _Settings()

# this will attempt to load the value from the file on disk, or revert to the default
print(Settings.serial_port)

# this will save the change to the config file
Settings.serial_port = "/dev/tty1"
```

Inherit `simplefilesettings.json.JSONClass` and add class attributes with
type hints and optionally default values. Attributes without type hints will not be
loaded or saved. Attributes starting with an underscore will cause an error.
If a default is not provided, `None` is assumed.

```python
from simplefilesettings.json import JSONClass

class _Settings(JSONClass):
    name: str = "John"  # valid
    age = 26 # invalid
    _height_cm: int # invalid
```

By default, a JSON file called `settings.json` in the current working directory
is used. To change this, add a nested class called `Config` with an attribute
`json_file`. This accepts any path-like variable.

```python
import os
from simplefilesettings.json import JSONClass

class _Settings(JSONClass):
    class Config:
        json_file = os.path.join(os.path.expanduser("~"), "config.json")

    name: str = "John"
```

Data types not serializable for the file format (JSON, TOML, YAML, see below)
are not supported.

By default, when any attribute is accessed, the configured file will be read.
If the file does not exist, the default value will be used.
If the file has a parse error, it will be deleted automatically.
To only read the file one time, set the `Config` value `always_read` to `False`.

When any attribute has its value set, that will be written to the configured file.

```python
from simplefilesettings.json import JSONClass

class _Settings(JSONClass):
    name: str = "John"

Settings = _Settings()
print(Settings.name)
Settings.name = "Bob"
```

Running this twice will print `John` the first time and `Bob` the second time.

If JSON isn't your thing, TOML and YAML are available with the `[toml]` and `[yaml]`
extras.

```python
from simplefilesettings.toml import TOMLClass
from simplefilesettings.yaml import YAMLClass

class _TSettings(TOMLClass):
    name: str = "John"

    class Config:
        toml_file = os.path.join(os.path.expanduser("~"), "config.toml")

class _YSettings(YAMLClass):
    name: str = "John"

    class Config:
        yaml_file = os.path.join(os.path.expanduser("~"), "config.yaml")

```

## Development

```bash
python -m pip install pipx --upgrade
pipx ensurepath
pipx install poetry
pipx install vscode-task-runner
# (Optionally) Add pre-commit plugin
poetry self add poetry-pre-commit-plugin
```

