Configuration models for Django allowing config management with auditing.
django-config-models
.. |CI| image:: https://github.com/openedx/django-config-models/workflows/Python%20CI/badge.svg?branch=master .. _CI: https://github.com/openedx/django-config-models/actions?query=workflow%3A%22Python+CI%22
.. |Codecov| image:: http://codecov.io/github/openedx/django-config-models/coverage.svg?branch=master .. _Codecov: http://codecov.io/github/openedx/django-config-models?branch=master
.. |pypi-badge| image:: https://img.shields.io/pypi/v/django-config-models.svg :target: https://pypi.python.org/pypi/django-config-models/ :alt: PyPI
.. |doc-badge| image:: https://readthedocs.org/projects/django-config-models/badge/?version=latest :target: http://django-config-models.readthedocs.io/en/latest/ :alt: Documentation
.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/django-config-models.svg :target: https://pypi.python.org/pypi/django-config-models/ :alt: Supported Python versions
.. |license-badge| image:: https://img.shields.io/github/license/edx/django-config-models.svg :target: https://github.com/openedx/django-config-models/blob/master/LICENSE.txt :alt: License
.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen :alt: Maintenance status
This app allows other apps to easily define a configuration model that can be hooked into the admin site to allow configuration management with auditing.
Add config_models
to your INSTALLED_APPS
list.
Create a subclass of ConfigurationModel
, with fields for each
value that needs to be configured::
class MyConfiguration(ConfigurationModel):
frobble_timeout = IntField(default=10)
frazzle_target = TextField(defalut="debug")
This is a normal django model, so it must be synced and migrated as usual.
The default values for the fields in the ConfigurationModel
will be
used if no configuration has yet been created.
Register that class with the Admin site, using the ConfigurationAdminModel
::
from django.contrib import admin
from config_models.admin import ConfigurationModelAdmin
admin.site.register(MyConfiguration, ConfigurationModelAdmin)
Use the configuration in your code::
def my_view(self, request):
config = MyConfiguration.current()
fire_the_missiles(config.frazzle_target, timeout=config.frobble_timeout)
Use the admin site to add new configuration entries. The most recently created
entry is considered to be current
.
The current ConfigurationModel
will be cached in the configuration
django cache,
or in the default
cache if configuration
doesn't exist. The configuration
and default
caches
are specified in the django CACHES
setting. The caching can be per-process, per-machine, per-cluster, or
some other strategy, depending on the cache configuration.
You can specify the cache timeout in each ConfigurationModel
by setting the cache_timeout
property.
You can change the name of the cache key used by the ConfigurationModel
by overriding
the cache_key_name
function.
ConfigurationModels
are just django models, so they can be extended with new fields
and migrated as usual. Newly added fields must have default values and should be nullable,
so that rollbacks to old versions of configuration work correctly.
The full documentation is at https://django-config-models.readthedocs.org.
The code in this repository is licensed under the AGPL 3.0 unless otherwise noted.
Please see LICENSE.txt
for details.
If you're having trouble, we have discussion forums at
discuss.openedx.org <https://discuss.openedx.org>
_ where you can connect with others in the
community.
Our real-time conversations are on Slack. You can request a Slack invitation
, then join our community Slack workspace
.
For anything non-trivial, the best path is to open an issue
__ in this
repository with as many details about the issue you are facing as you
can provide.
__ https://github.com/openedx/django-config-models /issues
For more information about these options, see the Getting Help
_ page.
.. _Slack invitation: https://openedx.org/slack .. _community Slack workspace: https://openedx.slack.com/ .. _Getting Help: https://openedx.org/getting-help
Contributions are very welcome.
Please read How To Contribute <https://github.com/openedx/.github/blob/master/CONTRIBUTING.md>
_ for details.
This project is currently accepting all types of contributions, bug fixes, security fixes, maintenance work, or new features. However, please make sure to have a discussion about your new feature idea with the maintainers prior to beginning development to maximize the chances of your change being accepted. You can start a conversation by creating a new issue on this repo summarizing your idea.
All community members are expected to follow the Open edX Code of Conduct
_.
.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/
The assigned maintainers for this component and other project details may be
found in Backstage
_. Backstage pulls this data from the catalog-info.yaml
file in this repo.
.. _Backstage: https://backstage.openedx.org/catalog/default/component/django-config-models
Please do not report security issues in public. Please email security@edx.org.
.. All enhancements and patches to django-config-models will be documented in this file. It adheres to the structure of http://keepachangelog.com/ , but in reStructuredText instead of Markdown (for ease of incorporation into Sphinx documentation and the PyPI description).
This project adheres to Semantic Versioning (http://semver.org/).
.. There should always be an "Unreleased" section for changes pending release.
[2.5.1] - 2023-09-22
* Fixed issues with Django 4.2
[2.5.0] - 2023-08-07
ConfigurationModel.current
: it will make sure that it does not return None for current configuration.[2.4.0] - 2023-07-19
* Added support for Django42 in CI
* Switch from ``edx-sphinx-theme`` to ``sphinx-book-theme`` since the former is
deprecated
[2.3.0] - 2022-01-19
[2.2.2] - 2021-20-12
* Updated dependencies after removing unnecessary constraint on edx-django-utils, so the constraint will no longer be advertised.
[2.2.1] - 2021-20-12
[2.2.0] - 2021-07-14
* Added support for django3.2
[2.1.2] - 2021-06-24
[2.1.1] - 2021-01-28
* Fix deprecated reference of ``util.memcache.safe_key``
[2.1.0] - 2021-01-12
[2.0.2] - 2020-05-10
* Fix html escaping of edit links in admin
[2.0.1] - 2020-05-08
[2.0.0] - 2020-02-06
* Dropping support for Python 2.7
* Switch to using edx-django-utils TieredCache (a two-layer cache that uses both
Django's cache and an internal request-level cache) to reduce the number of
memcached roundtrips. This was a major performance issue that accounted for
10-20% of transaction time for certain courseware views in edx-platform.
* It is now REQUIRED to add `RequestCacheMiddleware` `to middleware
<https://github.com/openedx/edx-django-utils/tree/master/edx_django_utils/cache#tieredcachemiddleware>`_
to use ConfigModels.
* Remove usage of the "configuration" cache setting. ConfigModels now always use
the default Django cache.
* Django Rest Framework 3.7 and 3.8 are no longer supported.
[1.0.1] - 2019-04-23
[1.0.0] - 2019-04-23
Changed
-------
* Unpin django-rest-framework requirements. This is a potentially **breaking change** if people were
relying on this package to ensure the correct version of djangorestframework was being installed.
[0.2.0] - 2018-07-13
[0.1.10] - 2018-05-21
Changed
-------
* Don't assume the user model is Django's default auth.User
[0.1.9] - 2017-08-07
[0.1.8] - 2017-06-19
Added
-----
* Support for Django 1.11.
[0.1.7] - 2017-06-19
[0.1.6] - 2017-06-01
Added
-----
* Support for Django 1.10.
[0.1.1] - [0.1.5] - 2017-06-01
Added
[0.1.0] - 2016-10-06
Added
_____
* First release on PyPI.