A package to create and use app specific settings with type hints.
Project description
typed_app_settings
A small django module for app specific settings (using type annotations).
Why another app settings module for Django?
With other existing approaches to make your reusable django apps configurable
using the global project's settings.py
file, it is not possible to get proper
IDE support including type checking.
This module aims to provide IDE support (mainly auto completion) and static type checking (for example with mypy or pylance).
Installation
Installation is easy. Just pip install
the module like so:
pip install typed-app-settings
Usage
-
Define a settings class in your app folder
# my_app/conf.py from typed_app_settings import typed_app_settings_prefix, undefined @typed_app_settings_prefix("MY_APP") # see below for the two alternative decorators class Settings: SOME_STRING: str = "This is a cool string!" SOME_NUMBER: int = 30 SOME_URL: str = undefined() settings = Settings()
-
Override some settings in your global
settings.py
# my_project/settings.py MY_APP_SOME_URL = "http://example.com" MY_APP_SOME_NUMBER = 42
-
Use the settings in your
views.py
or elsewhere# my_app/views.py from somewhere import fetch_url from .conf import settings def my_cool_view(request): ... content = fetch_url(settings.SOME_URL) ...
Available decorators
You can choose between two styles of decorators which only differ in the way
they look up overridden values in the project's settings.py
file.
typed_app_settings_prefix
With this decorator, you define a prefix which is used to override settings
in settings.py
.
Example:
# my_app/conf.py
from typed_app_settings import typed_app_settings_prefix
@typed_app_settings_prefix("MY_APP")
class Settings:
SOME_STR: str = "default value"
SOME_NUMBER: int = 10
# my_project/settings.py
...
MY_APP_SOME_STR = "default value"
MY_APP_SOME_NUMBER = 20
...
typed_app_settings_dict
With this decorator, you define a dictionary which is resides in your settings.py
and is used to override settings.
Example:
# my_app/conf.py
from typed_app_settings import typed_app_settings_dict
@typed_app_settings_dict("MY_APP")
class Settings:
SOME_STR: str = "default value"
SOME_NUMBER: int = 10
# my_project/settings.py
...
MY_APP = {
"SOME_STR": "default value",
"SOME_NUMBER": 20,
}
...
Functions
undefined
This function is used to indicate that a setting must be configured in your settings.py
.
from typed_apps_settings import typed_app_settings_prefix, undefined
@typed_app_settings_prefix("MY_APP")
class Settings:
...
THIS_MUST_BE_CONFIGURED: str = undefined()
...
settings = Settings()
settings.THIS_MUST_BE_CONFIGURED # raises ImproperlyConfigured when no setting
# is provided in settings.py
Automatic imports
There is some magic implemented when using "special" type annotations.
Automatic module loading
If a setting is annotated with types.ModuleType
and an override of type str
is provided in settings.py
, then this override is treated as a path to a module
which is imported on first attribute access.
Example:
# my_app/conf.py
from types import ModuleType
from typed_apps_settings import typed_app_settings_prefix
from . import forms
@typed_app_settings_prefix("MY_APP")
class Settings:
...
FORMS: ModuleType = forms # it is important to reference the default module
# directly, so that mypy and pylance do not complain
...
settings = Settings()
# my_project/settings.py
...
MY_APP_FORMS = "path.to.other.forms"
# my_app/views.py
from .conf import settings
def my_view(request):
...
form = settings.FORMS.CustomerForm(request.POST)
...
Automatic class loading
If a setting is annotated with typing.Type
or type
and an override of type str
is provided in settings.py
, then this override is treated as a path to a class
which is imported on first attribute access.
Note: This behaviour is similar to automatic module loading, except it returns a class instead of a module.
Example:
# my_app/conf.py
import typing
from typed_apps_settings import typed_app_settings_prefix
from .forms import CustomerForm
@typed_app_settings_prefix("MY_APP")
class Settings:
...
CUSTOMER_FORM: typing.Type = CustomerForm # it is important to define the default class
# directly, so that mypy and pylance do not complain
...
settings = Settings()
# my_project/settings.py
...
MY_APP_CUSTOMER_FORM = "path.to.other.forms.CustomerForm"
# my_app/views.py
from .conf import settings
def my_view(request):
...
form = settings.CUSTOMER_FORM(request.POST)
...
Caveats
No runtime type checking (right now)
In the current version, there is no automatic runtime type checking, but it may be implemented in a future version.
Changelog
0.1
- Initial release
0.1-post1
- Update classifiers
0.2
- Add function
undefined
which provides better IDE support. The classUndefinedValue
should not be instantiated directly and may be changed or even removed in the future. - Update README
- Update classifiers
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for typed_app_settings-0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 772a1a4e012616621c12fc91d8a81f201b9281f6a70a3e96c0441b2e381ae245 |
|
MD5 | 077684abc49bc512422ad529c3587ea6 |
|
BLAKE2b-256 | 56dd718344f7abc2b284b1c86eef0a4fee86d840e7f6be2a00d11ff76d6bfdb2 |