# Cheap Settings
_A lightweight, low footprint settings system_
[](https://pypi.org/project/cheap-settings/)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/cheap-settings/)
[](https://pepy.tech/project/cheap-settings)
[](https://evanjpw.github.io/cheap-settings/)
`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).
```python
from os import environ
from typing import Optional
from cheap_settings import CheapSettings
class MySettings(CheapSettings):
# With explicit type annotations
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
# Or let cheap-settings infer types from the defaults (These work exactly the same as above):
max_annoyance_inferred = 0 # Infers int
annoyance_factor_inferred = 0.0 # Infers float
annoyance_name_inferred = "" # Infers str
# 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:
```python
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:
```python
# 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
```
**Settings Without Initializers**
You can define settings with type annotations but no default values - see [the documentation](https://evanjpw.github.io/cheap-settings/api/#settings-without-initializers) for details.
**User Request**: Pickling
A user asked for `cheap-settings` to support pickling (because [ray](https://github.com/ray-project/ray)). Done! You can
now pickle & unpickle classes derived from `CheapSettings`.
```python
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:
```shell
pip install cheap-settings
```
## Examples
Those would be in the [examples](https://github.com/evanjpw/cheap-settings/tree/main/examples) directory.
## Documentation
Visit [the documentation site](https://evanjpw.github.io/cheap-settings/) on GitHub Pages.
## TBD - Features to be Added
* Selectable different configurations for different environments (for example, DEV, STAGING, PROD)
* Expanded type support: `datetime`, `date`, `time`, `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](https://github.com/prostomarkeloff/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](https://github.com/Undertone0809/conftier) - Also similar in some ways, & also very cool. Also, quite a
bit more complexity.
* [python-config2](https://github.com/grimen/python-config2) - Also kind of similar. More features, more complexity.
* Python's own, built-in [configparser](https://docs.python.org/3/library/configparser.html) - 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](./LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "cheap-settings",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "application, config, configuration, configurations, env, environment, environments, python, python-config, settings",
"author": null,
"author_email": "Evan Williams <evanjpw@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/57/05/0e6ae4466f08fe01f70bc9e3248724752cc93d282593e09a22f50a7b221e/cheap_settings-1.2.2.tar.gz",
"platform": null,
"description": "# Cheap Settings\n\n_A lightweight, low footprint settings system_\n\n [](https://pypi.org/project/cheap-settings/)\n [](https://opensource.org/licenses/MIT)\n [](https://pypi.org/project/cheap-settings/)\n [](https://pepy.tech/project/cheap-settings)\n [](https://evanjpw.github.io/cheap-settings/)\n\n`cheap-settings` is a Python package for providing a very simple, very low impact, configuration. The Python\nconfiguration & settings landscape is virtually overflowing with clever, advanced, flexible solutions that cover\nmany needs. However, what _I_ needed was a bit different from any config/settings package that I was aware of.\n\nThe main thing that distinguishes `cheap_settings` from any alternative solutions is simplicity: it is _extremely_\nsimple (& ergonomic) to use, & it intentionally limits its scope & feature set to be simple to understand.\n\nAdditionally, it supports circumstances where it is difficult to bring your config file with you. All of your config\nis defined in the code or in the environment.\n\n## OK, How Does it Actually Work?\n\nDefine your settings class as a subclass of `CheapSettings`. Add your settings values to your class as class attributes.\nAdd type hints so `cheap_settings` knows how to convert values. Add initializers for your default values of the\nsettings.\n\nAt runtime, `cheap_settings` will read any environment variable with the same name as your attributes, *and override\nthe attribute value, automatically converting to the correct type (even for Optional types)*.\n\nThen, from anywhere in your code, you can use `MySettings.MY_VALUE`.\n\nIt intentionally doesn't allow you to access environment variables that don't have a corresponding attribute assigned in\nyour settings class, because you want to know if you are not using the correct setting name.\n\nIt also provides the option of overriding the config settings with command line arguments. If you like, it can add\narguments that correspond to your settings, & parse them. If you do that, the command line values override the\ninitializer values _and_ the environment variables.\n\nThat's it. That's what it does (& nothing else).\n\n```python\nfrom os import environ\nfrom typing import Optional\nfrom cheap_settings import CheapSettings\n\nclass MySettings(CheapSettings):\n # With explicit type annotations\n MAX_ANNOYANCE: int = 0\n ANNOYANCE_FACTOR: float = 0.0\n ANNOYANCE_NAME: str = \"\"\n ANNOYANCE_ATTRIBUTES: list = []\n AM_I_ANNOYED: bool = False\n HOW_ANNOYED_EACH_DAY: dict = {}\n # Python 3.10+ union syntax also works: `OPTIONAL_ANNOYANCE: float | None = None`\n OPTIONAL_ANNOYANCE: Optional[float] = None\n\n # Or let cheap-settings infer types from the defaults (These work exactly the same as above):\n max_annoyance_inferred = 0 # Infers int\n annoyance_factor_inferred = 0.0 # Infers float\n annoyance_name_inferred = \"\" # Infers str\n\n# As you would expect:\nassert MySettings.MAX_ANNOYANCE == 0\nassert MySettings.ANNOYANCE_FACTOR == 0.0\nassert MySettings.ANNOYANCE_NAME == \"\"\nassert MySettings.ANNOYANCE_ATTRIBUTES == []\nassert MySettings.AM_I_ANNOYED is False\nassert MySettings.HOW_ANNOYED_EACH_DAY == {}\nassert MySettings.OPTIONAL_ANNOYANCE is None\n\n# But what if we now set some environment variables?\n\nenviron[\"MAX_ANNOYANCE\"] = \"100\"\nenviron[\"ANNOYANCE_FACTOR\"] = \"2.71828\"\nenviron[\"ANNOYANCE_NAME\"] = \"leaf blowers\"\nenviron[\"ANNOYANCE_ATTRIBUTES\"] = '[\"noise!\", \"exhaust\"]' # Any valid JSON array\nenviron[\"AM_I_ANNOYED\"] = \"true\" # \"true\"/\"false\", \"1\"/\"0\", \"yes\"/\"no\", \"on\"/\"off\" (case-insensitive)\nenviron[\"HOW_ANNOYED_EACH_DAY\"] = '{\"Monday\": \"10%\", \"Tuesday\": \"90%\"}' # Any valid JSON object\nenviron[\"OPTIONAL_ANNOYANCE\"] = \"32.767\" # or \"none\" to set to None for Optional types\n\n# Now\n\nassert MySettings.MAX_ANNOYANCE == 100 # It's known to be an int from the type hint\nassert MySettings.ANNOYANCE_FACTOR == 2.71828 # Float works the same way\nassert MySettings.ANNOYANCE_NAME == \"leaf blowers\"\nassert MySettings.ANNOYANCE_ATTRIBUTES == [\"noise!\", \"exhaust\"] # Converts to list\nassert MySettings.AM_I_ANNOYED is True # Case-insensitive conversion of \"true\" or \"false\"\nassert MySettings.HOW_ANNOYED_EACH_DAY == {\"Monday\": \"10%\", \"Tuesday\": \"90%\"} # Converts to a dict\nassert MySettings.OPTIONAL_ANNOYANCE == 32.767 # Correctly converts with Optional types (or type unions!)\n```\n\nYou can also use inheritance:\n\n```python\nfrom cheap_settings import CheapSettings\n\nclass BaseSettings(CheapSettings):\n host: str = \"localhost\"\n port: int = 8080\n\nclass TestSettings(BaseSettings):\n debug: bool = True # Inherits host and port from BaseSettings\n```\n\nTo use command line arguments:\n\n```python\n# After defining MySettings...\nTestSettings.set_config_from_command_line()\n\n# You can also pass an instance of `argparse.ArgumentParser` to define your own command line arguments.\n# `set_config_from_command_line` will return the result from `parse_args`.\n\n# Now you can run: python myapp.py --host example.com --port 3000 --debug\nassert TestSettings.host == \"example.com\" # CLI overrides env vars and defaults\n```\n\n**Settings Without Initializers**\n\nYou can define settings with type annotations but no default values - see [the documentation](https://evanjpw.github.io/cheap-settings/api/#settings-without-initializers) for details.\n\n**User Request**: Pickling\n\nA user asked for `cheap-settings` to support pickling (because [ray](https://github.com/ray-project/ray)). Done! You can\nnow pickle & unpickle classes derived from `CheapSettings`.\n\n```python\nimport pickle\n\n# Pickle and unpickle the class\npickled = pickle.dumps(TestSettings)\nunpickled_class = pickle.loads(pickled)\n\n# Verify the class works after unpickling by comparing to the original\nassert unpickled_class.host == TestSettings.host\nassert unpickled_class.port == TestSettings.port\nassert unpickled_class.debug == TestSettings.debug\n```\n\n## Why would I want this?\n\n> _You keep using the word \"simple\". What do you mean by that, & why should I care about it?_\n\nMaybe you don't. Maybe you will not want this & don't really care about simplicity.\n\nHowever, I'll explain what I mean, & why _I_ cared sufficiently to write this.\n\nWhen I'm writing a new library/package/application/service, I'll quite often eventually need some kind of setting for\nsomething. Maybe it's a retry timeout. Maybe it's a buffer size, or a number of threads. Maybe it's a connection string.\n\nWhat 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\nat the top of the file, but that becomes a slightly later source of regret.\n\nSo, you need some kind of configuration or settings. Historically, people made a `settings.py` file that was just a\npython module & wrote them in there, which works, but has its own set of issues. Also, if you want to override these\nsettings, now you have to manually code it, which can become very unpleasant & lead to a messy pile of code.\n\nNow what? You could put your config in a config file! What format? Whatever. However, now you are dragging the config\nfile around, & maybe you need to `.gitignore` your config file(s), & now you will need a `config.whatever.example` file\nthat you need to keep in sync with your settings (& you also need to keep your various config files in sync).\n\nWhat if the code can't find your config file? Does it stop? Does it have reasonable default values? Where do you keep\nthose?\n\nHow do you deploy the config file? How do you keep it & your code together?\n\nWhat do you do about those environment variables, & command line options?\n\nMaybe you have decided to use a package. That's excellent. There are many options. This one, for example.\n\nTypically, you have to setup the config. Maybe it's manual, or maybe it just works. But now you have a config object.\nHow do you get it to the place that you need it? Do you pass it through function arguments? Make it an attribute on your\nobject(s)? Make a global instance? Why am I managing this thing? Why am I doing all of this plumbing? Why do I now\nhave `config.get(\"setting_name\", \"default-value-that-I-was-trying-to-avoid\")` or\n`getattr(config, \"thing_that_should_always_be_there\", \"but-what-if-it-isn't\")`?\n\nWhy is this difficult? It shouldn't be difficult. I'm trying to do a thing, not configure something.\n\nThat happened to me a lot. In response, I wrote this.\n\nYou make a class, which is a subclass of `CheapSettings`. You add the annoying values as attributes, right on the class\ndefinition. Put it in some file called `config.py` or something. You need to use the setting somewhere in your code?\n`from .config import MyConfig` (or whatever import path makes sense in your project). Then you can say\n`MyConfig.some_setting`. Done. You need to set it with an environment variable or a command line option? Already done.\nFor the command line parsing, add `MySettings.set_config_from_command_line()` (you can ignore the return value). How do\nyou deploy? However you want, your settings will follow you.\n\nYou are trying to do a thing. Do the thing. Don't spend any time configuring the thing.\n\nThat is why, maybe, you want this.\n\n## Installation\n\nReally? Really? You're looking for a settings/config manager for your Python code, & you want me to tell you how to\nuse `pip`. OK, cool. I'm happy to help, really:\n\n```shell\npip install cheap-settings\n```\n\n## Examples\n\nThose would be in the [examples](https://github.com/evanjpw/cheap-settings/tree/main/examples) directory.\n\n## Documentation\n\nVisit [the documentation site](https://evanjpw.github.io/cheap-settings/) on GitHub Pages.\n\n## TBD - Features to be Added\n\n* Selectable different configurations for different environments (for example, DEV, STAGING, PROD)\n* Expanded type support: `datetime`, `date`, `time`, `Decimal`, `UUID`, custom types with\n `from_string()` methods\n* Custom validators & converters for field-level validation and custom conversion functions\n\n## Alternatives\n\nYou probably don't actually want to use this. There are probably superior alternatives for what you are trying to do.\nFor example:\n\n* [betterconf](https://github.com/prostomarkeloff/betterconf) - This is remarkably similar to `cheap_settings`, but,\n better (it's right in the name). It has more features & does more stuff, at the cost of some complexity.\n* [conftier](https://github.com/Undertone0809/conftier) - Also similar in some ways, & also very cool. Also, quite a\n bit more complexity.\n* [python-config2](https://github.com/grimen/python-config2) - Also kind of similar. More features, more complexity.\n* Python's own, built-in [configparser](https://docs.python.org/3/library/configparser.html) - This does things a\n different way, but it's built into Python, so you do not need any dependencies.\n* Roll your own - The simplest is to be old school & write a `settings.py` & be done with it.\n\n# Contributing\n\nIf you _do_ decide to use this, I welcome your suggestions, comments, or pull requests.\n\n> Imagine a clever, relevant quote here.\n\n# License\n\nThis project is licensed under MIT License.\n\nSee [LICENSE](./LICENSE) for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight, low footprint settings system",
"version": "1.2.2",
"project_urls": {
"documentation": "https://evanjpw.github.io/cheap-settings/",
"homepage": "https://github.com/evanjpw/cheap-settings",
"issues": "https://github.com/evanjpw/cheap-settings/issues",
"repository": "https://github.com/evanjpw/cheap-settings"
},
"split_keywords": [
"application",
" config",
" configuration",
" configurations",
" env",
" environment",
" environments",
" python",
" python-config",
" settings"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e69ab00fb75232e76025e9a4cb3694ed57fc94d354026abf22b0bd1b638d2e05",
"md5": "f5757c08e9315ba17718c4c20758d0b6",
"sha256": "438a092707d9e6df875f0f058f95c6dd3ff22ec7d6380216f674cec3ca1b659a"
},
"downloads": -1,
"filename": "cheap_settings-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f5757c08e9315ba17718c4c20758d0b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17192,
"upload_time": "2025-10-17T12:37:53",
"upload_time_iso_8601": "2025-10-17T12:37:53.582805Z",
"url": "https://files.pythonhosted.org/packages/e6/9a/b00fb75232e76025e9a4cb3694ed57fc94d354026abf22b0bd1b638d2e05/cheap_settings-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "57050e6ae4466f08fe01f70bc9e3248724752cc93d282593e09a22f50a7b221e",
"md5": "35de50eb84765a69d23d7be8b5dbaf51",
"sha256": "92413b65c0fffa53bc117d9dcba9cc37b6e61ae612cfc8513afb3eb24589d034"
},
"downloads": -1,
"filename": "cheap_settings-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "35de50eb84765a69d23d7be8b5dbaf51",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 102014,
"upload_time": "2025-10-17T12:37:54",
"upload_time_iso_8601": "2025-10-17T12:37:54.616276Z",
"url": "https://files.pythonhosted.org/packages/57/05/0e6ae4466f08fe01f70bc9e3248724752cc93d282593e09a22f50a7b221e/cheap_settings-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-17 12:37:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "evanjpw",
"github_project": "cheap-settings",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cheap-settings"
}
JSON
