cheap-settings 0.1.3.post1

A lightweight, low footprint settings system

Cheap Settings

A lightweight, low footprint settings system

cheap-settings is a Python package for providing a very simple, very low impact, configuration. The Python configuration & settings landscape is virtually overflowing with clever, advanced, flexible solutions that cover many needs. However, what I needed was a bit different from any config/settings package that I was aware of.

The main thing that distinguishes cheap_settings from any alternative solutions is simplicity: it is extremely simple (& ergonomic) to use, & it intentionally limits its scope & feature set to be simple to understand.

Additionally, it supports circumstances where it is difficult to bring your config file with you. All of your config is defined in the code or in the environment.

OK, How Does it Actually Work?

Define your settings class as a subclass of CheapSettings. Add your settings values to your class as class attributes. Add type hints so cheap_settings knows how to convert values. Add initializers for your default values of the settings.

At runtime, cheap_settings will read any environment variable with the same name as your attributes, and override the attribute value, automatically converting to the correct type (even for Optional types).

Then, from anywhere in your code, you can use MySettings.MY_VALUE.

It intentionally doesn't allow you to access environment variables that don't have a corresponding attribute assigned in your settings class, because you want to know if you are not using the correct setting name.

It also provides the option of overriding the config settings with command line arguments. If you like, it can add arguments that correspond to your settings, & parse them. If you do that, the command line values override the initializer values and the environment variables.

That's it. That's what it does (& nothing else).

from os import environ
from typing import Optional
from cheap_settings import CheapSettings

class MySettings(CheapSettings):
    MAX_ANNOYANCE: int = 0
    ANNOYANCE_FACTOR: float = 0.0
    ANNOYANCE_NAME: str = ""
    ANNOYANCE_ATTRIBUTES: list = []
    AM_I_ANNOYED: bool = False
    HOW_ANNOYED_EACH_DAY: dict = {}
    # Python 3.10+ union syntax also works: `OPTIONAL_ANNOYANCE: float | None = None`
    OPTIONAL_ANNOYANCE: Optional[float] = None

# As you would expect:
assert MySettings.MAX_ANNOYANCE == 0
assert MySettings.ANNOYANCE_FACTOR == 0.0
assert MySettings.ANNOYANCE_NAME == ""
assert MySettings.ANNOYANCE_ATTRIBUTES == []
assert MySettings.AM_I_ANNOYED is False
assert MySettings.HOW_ANNOYED_EACH_DAY ==  {}
assert MySettings.OPTIONAL_ANNOYANCE is None

# But what if we now set some environment variables?

environ["MAX_ANNOYANCE"] = "100"
environ["ANNOYANCE_FACTOR"] = "2.71828"
environ["ANNOYANCE_NAME"] = "leaf blowers"
environ["ANNOYANCE_ATTRIBUTES"] = '["noise!", "exhaust"]'  # Any valid JSON array
environ["AM_I_ANNOYED"] = "true"  # "true"/"false", "1"/"0", "yes"/"no", "on"/"off" (case-insensitive)
environ["HOW_ANNOYED_EACH_DAY"] = '{"Monday": "10%", "Tuesday": "90%"}'  # Any valid JSON object
environ["OPTIONAL_ANNOYANCE"] = "32.767"  # or "none" to set to None for Optional types

# Now

assert MySettings.MAX_ANNOYANCE == 100  # It's known to be an int from the type hint
assert MySettings.ANNOYANCE_FACTOR == 2.71828  # Float works the same way
assert MySettings.ANNOYANCE_NAME == "leaf blowers"
assert MySettings.ANNOYANCE_ATTRIBUTES == ["noise!", "exhaust"]  # Converts to list
assert MySettings.AM_I_ANNOYED is True  # Case-insensitive conversion of "true" or "false"
assert MySettings.HOW_ANNOYED_EACH_DAY ==  {"Monday": "10%", "Tuesday": "90%"}  # Converts to a dict
assert MySettings.OPTIONAL_ANNOYANCE == 32.767  # Correctly converts with Optional types (or type unions!)

You can also use inheritance:

from cheap_settings import CheapSettings

class BaseSettings(CheapSettings):
    host: str = "localhost"
    port: int = 8080

class TestSettings(BaseSettings):
    debug: bool = True  # Inherits host and port from BaseSettings

To use command line arguments:

# After defining MySettings...
TestSettings.set_config_from_command_line()

# You can also pass an instance of `argparse.ArgumentParser` to define your own command line arguments.
# `set_config_from_command_line` will return the result from `parse_args`.

# Now you can run: python myapp.py --host example.com --port 3000 --debug
assert TestSettings.host == "example.com"  # CLI overrides env vars and defaults

User Request: Pickling

A user asked for cheap-settings to support pickling (because ray). Done! You can now pickle & unpickle classes derived from CheapSettings.

import pickle

# Pickle and unpickle the class
pickled = pickle.dumps(TestSettings)
unpickled_class = pickle.loads(pickled)

# Verify the class works after unpickling by comparing to the original
assert unpickled_class.host == TestSettings.host
assert unpickled_class.port == TestSettings.port
assert unpickled_class.debug == TestSettings.debug

Why would I want this?

You keep using the word "simple". What do you mean by that, & why should I care about it?

Maybe you don't. Maybe you will not want this & don't really care about simplicity.

However, I'll explain what I mean, & why I cared sufficiently to write this.

When I'm writing a new library/package/application/service, I'll quite often eventually need some kind of setting for something. Maybe it's a retry timeout. Maybe it's a buffer size, or a number of threads. Maybe it's a connection string.

What do you do with it? You could code it inline, but that tends to be a source of regret. You could make it a constant at the top of the file, but that becomes a slightly later source of regret.

So, you need some kind of configuration or settings. Historically, people made a settings.py file that was just a python module & wrote them in there, which works, but has its own set of issues. Also, if you want to override these settings, now you have to manually code it, which can become very unpleasant & lead to a messy pile of code.

Now what? You could put your config in a config file! What format? Whatever. However, now you are dragging the config file around, & maybe you need to .gitignore your config file(s), & now you will need a config.whatever.example file that you need to keep in sync with your settings (& you also need to keep your various config files in sync).

What if the code can't find your config file? Does it stop? Does it have reasonable default values? Where do you keep those?

How do you deploy the config file? How do you keep it & your code together?

What do you do about those environment variables, & command line options?

Maybe you have decided to use a package. That's excellent. There are many options. This one, for example.

Typically, you have to setup the config. Maybe it's manual, or maybe it just works. But now you have a config object. How do you get it to the place that you need it? Do you pass it through function arguments? Make it an attribute on your object(s)? Make a global instance? Why am I managing this thing? Why am I doing all of this plumbing? Why do I now have config.get("setting_name", "default-value-that-I-was-trying-to-avoid") or getattr(config, "thing_that_should_always_be_there", "but-what-if-it-isn't")?

Why is this difficult? It shouldn't be difficult. I'm trying to do a thing, not configure something.

That happened to me a lot. In response, I wrote this.

You make a class, which is a subclass of CheapSettings. You add the annoying values as attributes, right on the class definition. Put it in some file called config.py or something. You need to use the setting somewhere in your code? from .config import MyConfig (or whatever import path makes sense in your project). Then you can say MyConfig.some_setting. Done. You need to set it with an environment variable or a command line option? Already done. For the command line parsing, add MySettings.set_config_from_command_line() (you can ignore the return value). How do you deploy? However you want, your settings will follow you.

You are trying to do a thing. Do the thing. Don't spend any time configuring the thing.

That is why, maybe, you want this.

Installation

Really? Really? You're looking for a settings/config manager for your Python code, & you want me to tell you how to use pip. OK, cool. I'm happy to help, really:

pip install cheap-settings

TBD - Features to be Added

• Settings without initializers
• Use the initializer type as the setting type (no type hint needed)
• Selectable different configurations for different environments (for example, DEV, STAGING, PROD)
• Expanded type support: datetime, date, time, pathlib.Path, Decimal, UUID, custom types with from_string() methods
• Custom validators & converters for field-level validation and custom conversion functions

Alternatives

You probably don't actually want to use this. There are probably superior alternatives for what you are trying to do. For example:

• betterconf - This is remarkably similar to cheap_settings, but, better (it's right in the name). It has more features & does more stuff, at the cost of some complexity.
• conftier - Also similar in some ways, & also very cool. Also, quite a bit more complexity.
• python-config2 - Also kind of similar. More features, more complexity.
• Python's own, built-in configparser - This does things a different way, but it's built into Python, so you do not need any dependencies.
• Roll your own - The simplest is to be old school & write a settings.py & be done with it.

Contributing

If you do decide to use this, I welcome your suggestions, comments, or pull requests.

Imagine a clever, relevant quote here.

License

This project is licensed under MIT License.

See LICENSE for details.