| Name | dymmond-settings JSON |
| Version |
1.0.3
JSON |
| download |
| home_page | |
| Summary | Generic settings system applied to any application |
| upload_time | 2024-03-07 18:08:08 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
dymmond_settings
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Dymmond Lazy Settings
<p align="center">
<em>🚀 Generic settings system applied to any application. 🚀</em>
</p>
<p align="center">
<a href="https://github.com/dymmond/dymmond-settings/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" target="_blank">
<img src="https://github.com/dymmond/dymmond-settings/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" alt="Test Suite">
</a>
<a href="https://pypi.org/project/dymmond-settings" target="_blank">
<img src="https://img.shields.io/pypi/v/dymmond-settings?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypi.org/project/dymmond-settings" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/dymmond-settings.svg?color=%2334D058" alt="Supported Python versions">
</a>
</p>
---
**Documentation**: [https://settings.dymmond.com](https://settings.dymmond.com) 📚
**Source Code**: [https://github.com/dymmond/dymmond-settings](https://github.com/dymmond/dymmond-settings)
**The official supported version is always the latest released**.
---
## Motivation
**Not overcomplicating what it should be easy by default.**
In the current technological environment almost for certain, every system needs some sort of settings.
These settings are often inside a `settings.py` file or similar and then internally is called everywhere
needed.
The problem encountered is the fact that those are not considered `lazy`.
What does that mean? Means that you often face issues when trying to get your application up and running
and those settings need be loaded beforehand but not evaluated until the time "comes".
The `dymmond-settings` was created with the purpose of addressing those same `lazy` settings problems.
The current Dymmond ecosystem uses a similar system an it was where this package came from.
No hard dependencies, just pure Python using `dataclasses`. Yes, you read properly, the settings
system is built on top of the default Python dataclasses, which means, you can take full advantage
of the built-in in your favour.
Of course some defaults are provided and some extra functionality on top to make sure you can use
it without too much hassle.
## Installation
To install, you can simply run.
```shell
$ pip install dymmond-settings
```
## How to use it
This is the best part. Inspired by the way the Dymmond ecosystem
([Esmerald][esmerald], [Edgy][edgy], [Saffier][saffier], [Mongoz][mongoz]) operates, these settings
aim to mimic exactly the same behaviour.
You can simply import the global `Settings` object and extend and then call the `settings` lazy
object anywhere in your code without the risk of blowing up beforehand.
## Defaults
The settings system provides some defaults for you that usually are common in every application
but **you are not entitled to use them**.
These defaults can be overridden at any given time, of course.
### Attributes
* **debug** - Boolean flag generally used to indicate if the application should be in debug mode
or not. This is particularly useful if you want to separate some settings by environment.
<sup>Default: `False`</sup>
* **environment** - String value indicating the the environment of the `settings`. This can be
particularly useful if you want to show specific settings by the given environment. You can use
the provided values from `dymmond_settings.enums.EnvironmentType` or create your own.
<sup>Default: `production`</sup>
* **version** - A value indicating a possible the `version` of your application running the settings.
It defaults to the current version of `dymmond_settings` if nothing is provided.
<sup>Default: `dymmond_settings.__version__`</sup>
### Functions
Although Python `dataclasses` also provides that same functionality for you, `dymmond_settings`
makes it easier for you to use it.
All `dymmond_settings` objects can be used with any of the normal `dataclasses` functionalities
and applications.
#### dict()
This simply converts your settings module into a python dictionary. This provides the same level
of functionality of `asdict` from the Python `dataclasses` module when `exclude_none` is set
to `False` (default).
**Parameters**:
- **exclude_none** - Excludes the values containing `None`.
- **upper** - Boolean flag indicating if the keys should be in upper case.
```python
from dataclasses import dataclass, field
from dymmond_settings import Settings
@dataclass
class AppSettings(Settings):
...
my_settings = AppSettings()
my_settings.dict()
```
Or if you want to exclude the `None` values.
```python
from dataclasses import dataclass, field
from dymmond_settings import Settings
@dataclass
class AppSettings(Settings):
...
my_settings = AppSettings()
my_settings.dict(exclude_none=True)
```
Or if you want the keys to be upper case.
```python
from dataclasses import dataclass, field
from dymmond_settings import Settings
@dataclass
class AppSettings(Settings):
...
my_settings = AppSettings()
my_settings.dict(upper=True)
```
#### tuple()
This simply converts your settings module into a python tuple but is slightly different from the
`astuple` from Python `dataclasses` module.
The default from `dataclasses` provides a tuple with all the values of the object provided `astuple`
whereas `dymmond_settings` tuple function provides **a list of tuples key/pair valued**.
As per [dict](#dict) functionality, the `tuple()` also provides a `exclude_none` in case you want
a list attributes with the values set.
**Parameters**:
- **exclude_none** - Excludes the values containing `None`.
- **upper** - Boolean flag indicating if the keys should be in upper case.
```python
from dataclasses import dataclass, field
from dymmond_settings import Settings
@dataclass
class AppSettings(Settings):
...
my_settings = AppSettings()
my_settings.tuple()
```
Or if you want to exclude the `None` values.
```python
from dataclasses import dataclass, field
from dymmond_settings import Settings
@dataclass
class AppSettings(Settings):
...
my_settings = AppSettings()
my_settings.tuple(exclude_none=True)
```
Or if you want the tuple to contain the *keys* in upper case.
```python
from dataclasses import dataclass, field
from dymmond_settings import Settings
@dataclass
class AppSettings(Settings):
...
my_settings = AppSettings()
my_settings.tuple(upper=True)
```
## How to use it
There are many ways you can use the settings and all of them valid. Here we show just a few examples
how to use it.
### The auto detection
When using the settings system, you kinda need to be able to tell your application where to look up
for the settings when loading, right?
Well yes and no, if you don't want to rely of the auto-load
of the settings for you and you want to take charge of if, you can simply skip this but if you don't,
well, this is the way.
As mentioned before, to make sure you use the automatic detection of the settings in your application
**you need to set an environment variable**, called `SETTINGS_MODULE`.
When the `SETTINGS_MODULE` is set and pointing to your settings, this will make the `settings`
object from `dymmond_settings` aware of it and make it available globally and in lazy mode.
Confusing? Well, let us see an example.
Let us imagine we have a `settings.py` file somewhere in the code, example: `myapp/config/settings.py`.
Let us also create our custom application settings and provide some values, like this:
```python
from dataclasses import dataclass, field
from dymmond_settings import Settings
@dataclass
class AppSettings(Settings):
debug: bool = False
my_setting: str = field(default="works")
```
Simple so far, right? Ok, no we need to make sure our system is aware of these new settings and for
that we will set the `SETTINGS_MODULE` to point it out to our custom settings. Like this:
```shell
$ SETTINGS_MODULE='myapp.config.settings.AppSettings' python ...
```
And that is it, really! Although looking very simple, there is a lot of magic happening behind the scenes
that you don't need to worry about.
Now, because we made the application aware, we are also able to use the `settings` object provided
by the `dymmond_settings` anywhere in your code base by simply importing it.
Like this:
```python
from dymmond_settings import settings
def get_my_settings() -> str:
return settings.my_setting
```
This simple `settings` is very powerful and `lazy`, which makes it perfect if you want to use it
anywhere in your codebase without those annoying imports happening all over the place.
[esmerald]: https://esmerald.dev
[edgy]: https://edgy.tarsild.io
[saffier]: https://saffier.tarsild.io
[mongoz]: https://mongoz.tarsild.io
Raw data
{
"_id": null,
"home_page": "",
"name": "dymmond-settings",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "dymmond_settings",
"author": "",
"author_email": "Tiago Silva <tiago.silva@dymmond.com>",
"download_url": "https://files.pythonhosted.org/packages/03/a7/1ee489705b6621d84eb4abe807b3dae366512946b1f45eb600c7e6c90001/dymmond_settings-1.0.3.tar.gz",
"platform": null,
"description": "# Dymmond Lazy Settings\n\n<p align=\"center\">\n <em>\ud83d\ude80 Generic settings system applied to any application. \ud83d\ude80</em>\n</p>\n\n<p align=\"center\">\n<a href=\"https://github.com/dymmond/dymmond-settings/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main\" target=\"_blank\">\n <img src=\"https://github.com/dymmond/dymmond-settings/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main\" alt=\"Test Suite\">\n</a>\n\n<a href=\"https://pypi.org/project/dymmond-settings\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/dymmond-settings?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n</a>\n\n<a href=\"https://pypi.org/project/dymmond-settings\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/pyversions/dymmond-settings.svg?color=%2334D058\" alt=\"Supported Python versions\">\n</a>\n</p>\n\n---\n\n**Documentation**: [https://settings.dymmond.com](https://settings.dymmond.com) \ud83d\udcda\n\n**Source Code**: [https://github.com/dymmond/dymmond-settings](https://github.com/dymmond/dymmond-settings)\n\n**The official supported version is always the latest released**.\n\n---\n\n## Motivation\n\n**Not overcomplicating what it should be easy by default.**\n\nIn the current technological environment almost for certain, every system needs some sort of settings.\nThese settings are often inside a `settings.py` file or similar and then internally is called everywhere\nneeded.\n\nThe problem encountered is the fact that those are not considered `lazy`.\n\nWhat does that mean? Means that you often face issues when trying to get your application up and running\nand those settings need be loaded beforehand but not evaluated until the time \"comes\".\n\nThe `dymmond-settings` was created with the purpose of addressing those same `lazy` settings problems.\n\nThe current Dymmond ecosystem uses a similar system an it was where this package came from.\n\nNo hard dependencies, just pure Python using `dataclasses`. Yes, you read properly, the settings\nsystem is built on top of the default Python dataclasses, which means, you can take full advantage\nof the built-in in your favour.\n\nOf course some defaults are provided and some extra functionality on top to make sure you can use\nit without too much hassle.\n\n## Installation\n\nTo install, you can simply run.\n\n```shell\n$ pip install dymmond-settings\n```\n\n## How to use it\n\nThis is the best part. Inspired by the way the Dymmond ecosystem\n([Esmerald][esmerald], [Edgy][edgy], [Saffier][saffier], [Mongoz][mongoz]) operates, these settings\naim to mimic exactly the same behaviour.\n\nYou can simply import the global `Settings` object and extend and then call the `settings` lazy\nobject anywhere in your code without the risk of blowing up beforehand.\n\n## Defaults\n\nThe settings system provides some defaults for you that usually are common in every application\nbut **you are not entitled to use them**.\n\nThese defaults can be overridden at any given time, of course.\n\n### Attributes\n\n* **debug** - Boolean flag generally used to indicate if the application should be in debug mode\nor not. This is particularly useful if you want to separate some settings by environment.\n\n <sup>Default: `False`</sup>\n\n* **environment** - String value indicating the the environment of the `settings`. This can be\nparticularly useful if you want to show specific settings by the given environment. You can use\nthe provided values from `dymmond_settings.enums.EnvironmentType` or create your own.\n\n <sup>Default: `production`</sup>\n\n* **version** - A value indicating a possible the `version` of your application running the settings.\nIt defaults to the current version of `dymmond_settings` if nothing is provided.\n\n <sup>Default: `dymmond_settings.__version__`</sup>\n\n### Functions\n\nAlthough Python `dataclasses` also provides that same functionality for you, `dymmond_settings`\nmakes it easier for you to use it.\n\nAll `dymmond_settings` objects can be used with any of the normal `dataclasses` functionalities\nand applications.\n\n#### dict()\n\nThis simply converts your settings module into a python dictionary. This provides the same level\nof functionality of `asdict` from the Python `dataclasses` module when `exclude_none` is set\nto `False` (default).\n\n**Parameters**:\n\n- **exclude_none** - Excludes the values containing `None`.\n- **upper** - Boolean flag indicating if the keys should be in upper case.\n\n```python\nfrom dataclasses import dataclass, field\n\nfrom dymmond_settings import Settings\n\n\n@dataclass\nclass AppSettings(Settings):\n ...\n\n\nmy_settings = AppSettings()\nmy_settings.dict()\n```\n\nOr if you want to exclude the `None` values.\n\n```python\nfrom dataclasses import dataclass, field\n\nfrom dymmond_settings import Settings\n\n\n@dataclass\nclass AppSettings(Settings):\n ...\n\n\nmy_settings = AppSettings()\nmy_settings.dict(exclude_none=True)\n```\n\nOr if you want the keys to be upper case.\n\n```python\nfrom dataclasses import dataclass, field\n\nfrom dymmond_settings import Settings\n\n\n@dataclass\nclass AppSettings(Settings):\n ...\n\n\nmy_settings = AppSettings()\nmy_settings.dict(upper=True)\n```\n\n#### tuple()\n\nThis simply converts your settings module into a python tuple but is slightly different from the\n`astuple` from Python `dataclasses` module.\n\nThe default from `dataclasses` provides a tuple with all the values of the object provided `astuple`\nwhereas `dymmond_settings` tuple function provides **a list of tuples key/pair valued**.\n\nAs per [dict](#dict) functionality, the `tuple()` also provides a `exclude_none` in case you want\na list attributes with the values set.\n\n**Parameters**:\n\n- **exclude_none** - Excludes the values containing `None`.\n- **upper** - Boolean flag indicating if the keys should be in upper case.\n\n```python\nfrom dataclasses import dataclass, field\n\nfrom dymmond_settings import Settings\n\n\n@dataclass\nclass AppSettings(Settings):\n ...\n\n\nmy_settings = AppSettings()\nmy_settings.tuple()\n```\n\nOr if you want to exclude the `None` values.\n\n```python\nfrom dataclasses import dataclass, field\n\nfrom dymmond_settings import Settings\n\n\n@dataclass\nclass AppSettings(Settings):\n ...\n\n\nmy_settings = AppSettings()\nmy_settings.tuple(exclude_none=True)\n```\n\nOr if you want the tuple to contain the *keys* in upper case.\n\n```python\nfrom dataclasses import dataclass, field\n\nfrom dymmond_settings import Settings\n\n\n@dataclass\nclass AppSettings(Settings):\n ...\n\n\nmy_settings = AppSettings()\nmy_settings.tuple(upper=True)\n```\n\n## How to use it\n\nThere are many ways you can use the settings and all of them valid. Here we show just a few examples\nhow to use it.\n\n### The auto detection\n\nWhen using the settings system, you kinda need to be able to tell your application where to look up\nfor the settings when loading, right?\n\nWell yes and no, if you don't want to rely of the auto-load\nof the settings for you and you want to take charge of if, you can simply skip this but if you don't,\nwell, this is the way.\n\nAs mentioned before, to make sure you use the automatic detection of the settings in your application\n**you need to set an environment variable**, called `SETTINGS_MODULE`.\n\nWhen the `SETTINGS_MODULE` is set and pointing to your settings, this will make the `settings`\nobject from `dymmond_settings` aware of it and make it available globally and in lazy mode.\n\nConfusing? Well, let us see an example.\n\nLet us imagine we have a `settings.py` file somewhere in the code, example: `myapp/config/settings.py`.\n\nLet us also create our custom application settings and provide some values, like this:\n\n```python\nfrom dataclasses import dataclass, field\n\nfrom dymmond_settings import Settings\n\n\n@dataclass\nclass AppSettings(Settings):\n debug: bool = False\n my_setting: str = field(default=\"works\")\n```\n\nSimple so far, right? Ok, no we need to make sure our system is aware of these new settings and for\nthat we will set the `SETTINGS_MODULE` to point it out to our custom settings. Like this:\n\n```shell\n$ SETTINGS_MODULE='myapp.config.settings.AppSettings' python ...\n```\n\nAnd that is it, really! Although looking very simple, there is a lot of magic happening behind the scenes\nthat you don't need to worry about.\n\nNow, because we made the application aware, we are also able to use the `settings` object provided\nby the `dymmond_settings` anywhere in your code base by simply importing it.\n\nLike this:\n\n```python\nfrom dymmond_settings import settings\n\n\ndef get_my_settings() -> str:\n return settings.my_setting\n```\n\nThis simple `settings` is very powerful and `lazy`, which makes it perfect if you want to use it\nanywhere in your codebase without those annoying imports happening all over the place.\n\n[esmerald]: https://esmerald.dev\n[edgy]: https://edgy.tarsild.io\n[saffier]: https://saffier.tarsild.io\n[mongoz]: https://mongoz.tarsild.io\n",
"bugtrack_url": null,
"license": "",
"summary": "Generic settings system applied to any application",
"version": "1.0.3",
"project_urls": {
"Changelog": "https://settings.dymmond.com/release-notes/",
"Documentation": "https://settings.dymmond.com",
"Funding": "https://github.com/sponsors/tarsil",
"Homepage": "https://github.com/dymmond/dymmond-settings",
"Source": "https://github.com/dymmond/dymmond-settings"
},
"split_keywords": [
"dymmond_settings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3a16f473aaa4eba8b38a756d9148d335aebdd089916dfdaf6f3001e0adbc81a7",
"md5": "39085096e93f710603bef2e888b90888",
"sha256": "6c700b057da8c02eda55e56ecb7d1dd9a29e222724452d790139b7ff2d1eff92"
},
"downloads": -1,
"filename": "dymmond_settings-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "39085096e93f710603bef2e888b90888",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10471,
"upload_time": "2024-03-07T18:08:05",
"upload_time_iso_8601": "2024-03-07T18:08:05.902752Z",
"url": "https://files.pythonhosted.org/packages/3a/16/f473aaa4eba8b38a756d9148d335aebdd089916dfdaf6f3001e0adbc81a7/dymmond_settings-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "03a71ee489705b6621d84eb4abe807b3dae366512946b1f45eb600c7e6c90001",
"md5": "9ecaa8332f66248e9fabdbac98401ff2",
"sha256": "e4eea2912361d7827a1e81aff290500d65bb4a555cf76e5533e182f288e04018"
},
"downloads": -1,
"filename": "dymmond_settings-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "9ecaa8332f66248e9fabdbac98401ff2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9132,
"upload_time": "2024-03-07T18:08:08",
"upload_time_iso_8601": "2024-03-07T18:08:08.098689Z",
"url": "https://files.pythonhosted.org/packages/03/a7/1ee489705b6621d84eb4abe807b3dae366512946b1f45eb600c7e6c90001/dymmond_settings-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-07 18:08:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sponsors",
"github_project": "tarsil",
"github_not_found": true,
"lcname": "dymmond-settings"
}
