Pyttings

Lightweight Python settings management with namespacing and modular files. Inspired by Django.

Features

• Namespaced Settings: Use a prefix (e.g., PYTTING_) to avoid conflicts.
• Custom Prefix: Change the prefix using PYTTING_ENV_PREFIX.
• Modular Settings: Load settings from a module with PYTTING_SETTINGS_MODULE.
• Environment Variables: Override settings easily, with automatic type parsing.
• Type Hint Support: Converts environment variables to the expected type (recommended but not required).
• Union Type Support: Supports multiple possible types for a setting.
• Collection Type Validation: Ensures list, tuple, set, and dict elements match expected types.
• Custom Class Parsers: Use a __pyttings_convert__ method (or a custom-defined method) to parse settings into custom objects, configurable via PYTTING_CUSTOM_CLASS_METHOD_NAME.

Installation

pip install pyttings

Quick Start

1. Define Your Settings Module (myapp/settings.py):

DEBUG: bool = True
OTHER_BOOLEAN = True  # Type hint is not required but recommended
DATABASE_URL: str = "sqlite:///db.sqlite3"
PORT: int = 8000
SOME_LIST: list[str] = ["a", "b", "c"]
SOME_DICT: dict[str, str] = {"a": "b", "c": "d"}
SOME_SET: set[str] = {"a", "b", "c"}
SOME_UNION_TYPE: dict | str = "some_str"

2. Set the Settings Module:

export PYTTING_SETTINGS_MODULE="myapp.settings"

3. Use Pyttings:

from pyttings import settings

print(settings.DEBUG)  # Output: True
print(settings.DATABASE_URL)  # Output: sqlite:///db.sqlite3
print(settings.PORT)  # Output: 8000
print(settings.SOME_LIST)  # Output: ['a', 'b', 'c']

Configuration

Required: PYTTING_SETTINGS_MODULE

Specify the settings module using the PYTTING_SETTINGS_MODULE environment variable. This is mandatory for Pyttings to know where to load your settings from.

export PYTTING_SETTINGS_MODULE="myapp.settings"

Optional: PYTTING_ENV_PREFIX

By default, Pyttings uses PYTTING_ as the prefix for environment variables. For example, to override the DEBUG setting, you would set:

export PYTTING_DEBUG="False"

If you want to use a custom prefix (e.g., MYAPP_), set the PYTTING_ENV_PREFIX environment variable:

export PYTTING_ENV_PREFIX="MYAPP_"
export MYAPP_DEBUG="False"

Now, Pyttings will look for MYAPP_DEBUG instead of PYTTING_DEBUG.

Optional: PYTTING_CUSTOM_CLASS_METHOD_NAME

You can change the method name used for custom class parsing. By default, Pyttings looks for __pyttings_convert__. To use a custom method name, set:

export PYTTING_CUSTOM_CLASS_METHOD_NAME="custom_method_name"

Advanced Features

Automatic Type Parsing

Pyttings automatically converts environment variables to match the expected type based on the settings module.

# myapp/settings.py
DEBUG: bool = True
PORT: int = 8000

export PYTTING_DEBUG="False"
export PYTTING_PORT="8080"

Pyttings will automatically convert PYTTING_DEBUG to False (boolean) and PYTTING_PORT to 8080 (integer), ensuring type consistency.

Union Type Support

If a setting is defined with a union type hint, Pyttings will try each type until a valid conversion is found.

SOME_UNION_TYPE: dict | str = "some_str"

export PYTTING_SOME_UNION_TYPE='{"key": "value"}'

Pyttings will first attempt to convert the value to a dict, succeeding if valid, or fallback to str.

Collection Type Validation

Pyttings ensures that lists, tuples, sets, and dictionaries maintain correct element types.

ALLOWED_HOSTS: list[str] = ["localhost", "127.0.0.1"]

export PYTTING_ALLOWED_HOSTS='["example.com", "api.example.com"]'

Pyttings will correctly parse PYTTING_ALLOWED_HOSTS as a list[str].

Custom Class Parsers

You can define custom classes that implement a conversion method (default: __pyttings_convert__, configurable via PYTTING_CUSTOM_CLASS_METHOD_NAME).

Example

class MultipleArgsCustomClass:
    def __init__(self, int_value: int, str_value: str, value: int | str):
        self.int_value = int_value
        self.str_value = str_value
        self.value = value

    @classmethod
    def __pyttings_convert__(
        cls, value: dict[str, int | str]
    ) -> "MultipleArgsCustomClass":
        return cls(
            int_value=value["int_value"],
            str_value=value["str_value"],
            value=value["value"],
        )

# myapp/settings.py
...
SOME_MULTIPLE_CUSTOM_CLASS: MultipleArgsCustomClass = MultipleArgsCustomClass(1, "2", 3)

export PYTTING_SOME_MULTIPLE_CUSTOM_CLASS='{"int_value": 3, "str_value": "2", "value": "1"}'

Pyttings will correctly parse the value into an instance of MultipleArgsCustomClass using the __pyttings_convert__ method.

Strict Type Enforcement & SettingMisconfigured

If Pyttings cannot parse a setting into its expected type, it raises SettingMisconfigured. This ensures settings are always correctly configured and prevents unexpected behavior.

For example:

ALLOWED_HOSTS: list[str] = ["localhost"]
SOME_STRICT_LIST: list[str] = ["localhost"]

export PYTTING_ALLOWED_HOSTS="123"
export PYTTING_SOME_STRICT_LIST=[1,2,3]

Since 123 is not a valid list and [1,2,3] is not a valid list[str], Pyttings will raise:

SettingMisconfigured: Invalid type for ALLOWED_HOSTS with configured value '123'.
Expected list[str].

SettingMisconfigured: Invalid type for SOME_STRICT_LIST with configured value '[1,2,3]'.
Expected list[str].

Similarly, if a custom class method does not meet the required signature (single argument with a type hint), Pyttings will raise an error.

Contributing

Contributions are welcome! If you'd like to contribute to Pyttings, please follow these steps:

1. Fork the repository on GitHub.
2. Create a new branch for your feature or bugfix.
3. Make your changes and ensure tests pass.
4. Submit a pull request with a clear description of your changes.

Please ensure your code follows the project's style and includes appropriate tests. See the Makefile.

License

Pyttings is licensed under the MIT License. See the LICENSE file for details.