Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge branch 'release/0.4'

  • Loading branch information...
commit 53c5de7e7e9d79b285565ff515ce39d6bdc02f18 2 parents 6569982 + 96130ae
@jezdez jezdez authored
View
1  AUTHORS
@@ -0,0 +1 @@
+Jannis Leidel <jannis@leidel.info>
View
27 LICENSE
@@ -0,0 +1,27 @@
+Copyright (c) 2011, Jannis Leidel and individual contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ * Neither the name of django-appconf nor the
+ names of its contributors may be used to endorse or promote products
+ derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
View
4 MANIFEST.in
@@ -1 +1,3 @@
-include README.rst
+include README.rst
+include LICENSE
+include AUTHORS
View
162 README.rst
@@ -1,10 +1,16 @@
django-appconf
==============
-An app configuration object to be used for handling configuration
-defaults of packaged apps gracefully. Say you have an app called ``myapp``
-and want to define a few defaults, and refer to the defaults easily in the
-apps code. Add a ``settings.py`` to your app's models.py::
+A helper class for handling configuration defaults of packaged Django
+apps gracefully.
+
+Overview
+--------
+
+Say you have an app called ``myapp`` with a few defaults, which you want
+to refer to in the app's code without repeating yourself all the time.
+``appconf`` provides a simple class to implement those defaults. Simply add
+something like the following code somewhere in your app files::
from appconf import AppConf
@@ -14,132 +20,50 @@ apps code. Add a ``settings.py`` to your app's models.py::
"two",
)
- class Meta:
- app_label = 'myapp'
-
-The settings are initialized with the app label of where the setting is
-located at. E.g. if your ``models.py`` is in the ``myapp`` package,
-the prefix of the settings will be ``MYAPP``.
-
-The ``MyAppConf`` class will automatically look at Django's
-global setting to determine each of the settings. E.g. adding this to
-your site's ``settings.py`` will set the ``SETTING_1`` app setting
-accordingly::
-
- MYAPP_SETTING_1 = "uno"
-
-Usage
------
-
-Instead of using ``from django.conf import settings`` as you would
-usually do, you can **optionally** switch to using your apps own
-settings module to access the settings::
-
- from myapp.models import MyAppConf
-
- myapp_settings = MyAppConf()
-
- print myapp_settings.MYAPP_SETTING_1
+.. note::
-``AppConf`` class automatically work as proxies for the other
-settings, which aren't related to the app. For example the following
-code is perfectly valid::
+ ``AppConf`` classes depend on being imported during startup of the Django
+ process. Even though there are multiple modules loaded automatically,
+ only the ``models`` modules (usually the ``models.py`` file of your
+ app) are guaranteed to be loaded at startup. Therefore it's recommended
+ to put your ``AppConf`` subclass(es) there, too.
- from myapp.models import MyAppConf
+The settings are initialized with the capitalized app label of where the
+setting is located at. E.g. if your ``models.py`` with the ``AppConf`` class
+is in the ``myapp`` package, the prefix of the settings will be ``MYAPP``.
- settings = MyAppConf()
+You can override the default prefix by specifying a ``prefix`` attribute of
+an inner ``Meta`` class::
- if "myapp" in settings.INSTALLED_APPS:
- print "yay, myapp is installed!"
-
-In case you want to set some settings ad-hoc, you can simply pass
-the value when instanciating the ``AppConf`` class::
-
- from myapp.models import MyAppConf
-
- settings = MyAppConf(SETTING_1='something completely different')
-
- if 'different' in settings.MYAPP_SETTINGS_1:
- print 'yay, I'm different!'
-
-Custom handling
----------------
-
-Each of the settings can be individually configured with callbacks.
-For example, in case a value of a setting depends on other settings
-or other dependencies. The following example sets one setting to a
-different value depending on a global setting::
-
- from django.conf import settings
from appconf import AppConf
- class MyCustomAppConf(AppConf):
- ENABLED = True
-
- def configure_enabled(self, value):
- return value and not self.DEBUG
+ class MyAppConf(AppConf):
+ SETTING_1 = "one"
+ SETTING_2 = (
+ "two",
+ )
-The value of ``MYAPP_ENABLED`` will vary depending on the
-value of the global ``DEBUG`` setting.
+ class Meta:
+ prefix = 'acme'
-Each of the app settings can be customized by providing
-a method ``configure_<lower_setting_name>`` that takes the default
-value as defined in the class attributes as the only parameter.
-The method needs to return the value to be use for the setting in
-question.
+The ``MyAppConf`` class will automatically look at Django's global settings
+to determine if you've overridden it. For example, adding this to your site's
+``settings.py`` would override ``SETTING_1`` of the above ``MyAppConf``::
-After each of the ``_configure`` method have be called, the ``AppConf``
-class will additionally call a main ``configure`` method, which can
-be used to do any further custom configuration handling, e.g. if multiple
-settings depend on each other. For that a ``configured_data`` dictionary
-is provided in the setting instance::
+ MYAPP_SETTING_1 = "uno"
+In case you want to use a different settings object instead of the default
+``'django.conf.settings'``, set the ``holder`` attribute of the inner
+``Meta`` class to a dotted import path::
- from django.conf import settings
from appconf import AppConf
- class MyCustomAppConf(AppConf):
- ENABLED = True
- MODE = 'development'
-
- def configure_enabled(self, value):
- return value and not self.DEBUG
-
- def configure(self):
- mode = self.configured_data['MODE']
- enabled = self.configured_data['ENABLED']
- if not enabled and mode != 'development':
- print "WARNING: app not enabled in %s mode!" % mode
-
-Changelog
----------
-
-0.3 (2011-08-23)
-^^^^^^^^^^^^^^^^
-
-* Added tests with 100% coverage.
-
-* Added ability to subclass ``Meta`` classes.
-
-* Fixed various bugs with subclassing and configuration in subclasses.
-
-0.2.2 (2011-08-22)
-^^^^^^^^^^^^^^^^^^
-
-* Fixed another issue in the ``configure()`` API.
-
-0.2.1 (2011-08-22)
-^^^^^^^^^^^^^^^^^^
-
-* Fixed minor issue in ``configure()`` API.
-
-0.2 (2011-08-22)
-^^^^^^^^^^^^^^^^
-
-* Added ``configure()`` API to ``AppConf`` class which is called after
- configuring each setting.
-
-0.1 (2011-08-22)
-^^^^^^^^^^^^^^^^
+ class MyAppConf(AppConf):
+ SETTING_1 = "one"
+ SETTING_2 = (
+ "two",
+ )
-* First public release.
+ class Meta:
+ prefix = 'acme'
+ holder = 'acme.conf.settings'
View
95 appconf.py
@@ -1,18 +1,22 @@
import sys
# following PEP 386, versiontools will pick it up
-__version__ = (0, 3, 0, "final", 0)
+__version__ = (0, 4, 0, "final", 0)
class AppConfOptions(object):
- def __init__(self, meta, app_label=None):
- self.app_label = app_label
+ def __init__(self, meta, prefix=None):
+ self.prefix = prefix
+ self.holder_path = getattr(meta, 'holder', 'django.conf.settings')
+ self.holder = import_attribute(self.holder_path)
+ self.proxy = getattr(meta, 'proxy', False)
+ self.configured_data = {}
def prefixed_name(self, name):
- if name.startswith(self.app_label.upper()):
+ if name.startswith(self.prefix.upper()):
return name
- return "%s_%s" % (self.app_label.upper(), name.upper())
+ return "%s_%s" % (self.prefix.upper(), name.upper())
def contribute_to_class(self, cls, name):
cls._meta = self
@@ -38,20 +42,21 @@ def __new__(cls, name, bases, attrs):
attr_meta = type('Meta', (object,), {})
meta = getattr(new_class, 'Meta', None)
- app_label = getattr(meta, 'app_label', None)
- if app_label is None:
- # Figure out the app_label by looking one level up.
+ prefix = getattr(meta, 'prefix', getattr(meta, 'app_label', None))
+ if prefix is None:
+ # Figure out the prefix by looking one level up.
# For 'django.contrib.sites.models', this would be 'sites'.
model_module = sys.modules[new_class.__module__]
- app_label = model_module.__name__.split('.')[-2]
+ prefix = model_module.__name__.split('.')[-2]
- new_class.add_to_class('_meta', AppConfOptions(meta, app_label))
+ new_class.add_to_class('_meta', AppConfOptions(meta, prefix))
new_class.add_to_class('Meta', attr_meta)
for parent in parents[::-1]:
if hasattr(parent, '_meta'):
new_class._meta.names.update(parent._meta.names)
new_class._meta.defaults.update(parent._meta.defaults)
+ new_class._meta.configured_data.update(parent._meta.configured_data)
for name in filter(lambda name: name == name.upper(), attrs):
prefixed_name = new_class._meta.prefixed_name(name)
@@ -59,10 +64,15 @@ def __new__(cls, name, bases, attrs):
new_class._meta.defaults[prefixed_name] = attrs.pop(name)
# Add all attributes to the class.
- for obj_name, obj in attrs.items():
- new_class.add_to_class(obj_name, obj)
+ for name, value in attrs.items():
+ new_class.add_to_class(name, value)
- return new_class._configure()
+ new_class._configure()
+ for name, value in new_class._meta.configured_data.iteritems():
+ prefixed_name = new_class._meta.prefixed_name(name)
+ setattr(new_class._meta.holder, prefixed_name, value)
+ new_class.add_to_class(name, value)
+ return new_class
def add_to_class(cls, name, value):
if hasattr(value, 'contribute_to_class'):
@@ -71,25 +81,37 @@ def add_to_class(cls, name, value):
setattr(cls, name, value)
def _configure(cls):
- from django.conf import settings
# the ad-hoc settings class instance used to configure each value
obj = cls()
- obj.configured_data = dict()
for name, prefixed_name in obj._meta.names.iteritems():
default_value = obj._meta.defaults.get(prefixed_name)
- value = getattr(settings, prefixed_name, default_value)
+ value = getattr(obj._meta.holder, prefixed_name, default_value)
callback = getattr(obj, "configure_%s" % name.lower(), None)
if callable(callback):
value = callback(value)
- obj.configured_data[name] = value
- obj.configured_data = obj.configure()
-
- # Finally, set the setting in the global setting object
- for name, value in obj.configured_data.iteritems():
- prefixed_name = obj._meta.prefixed_name(name)
- setattr(settings, prefixed_name, value)
-
- return cls
+ cls._meta.configured_data[name] = value
+ cls._meta.configured_data = obj.configure()
+
+
+def import_attribute(import_path, exception_handler=None):
+ from django.utils.importlib import import_module
+ module_name, object_name = import_path.rsplit('.', 1)
+ try:
+ module = import_module(module_name)
+ except: # pragma: no cover
+ if callable(exception_handler):
+ exctype, excvalue, tb = sys.exc_info()
+ return exception_handler(import_path, exctype, excvalue, tb)
+ else:
+ raise
+ try:
+ return getattr(module, object_name)
+ except: # pragma: no cover
+ if callable(exception_handler):
+ exctype, excvalue, tb = sys.exc_info()
+ return exception_handler(import_path, exctype, excvalue, tb)
+ else:
+ raise
class AppConf(object):
@@ -100,13 +122,16 @@ class AppConf(object):
__metaclass__ = AppConfMetaClass
def __init__(self, **kwargs):
- from django.conf import settings
- self._holder = settings
for name, value in kwargs.iteritems():
- setattr(self, self._meta.prefixed_name(name), value)
+ setattr(self, name, value)
def __dir__(self):
- return sorted(list(set(dir(self._holder))))
+ return sorted(list(set(self._meta.names.keys())))
+
+ # For instance access..
+ @property
+ def configured_data(self):
+ return self._meta.configured_data
# For Python < 2.6:
@property
@@ -114,15 +139,21 @@ def __members__(self):
return self.__dir__()
def __getattr__(self, name):
- return getattr(self._holder, name)
+ if self._meta.proxy:
+ return getattr(self._meta.holder, name)
+ raise AttributeError("%s not found. Use '%s' instead." %
+ (name, self._meta.holder_path))
def __setattr__(self, name, value):
if name == name.upper():
- return setattr(self._holder, name, value)
+ setattr(self._meta.holder,
+ self._meta.prefixed_name(name), value)
object.__setattr__(self, name, value)
def configure(self):
"""
- Hook for doing any extra configuration.
+ Hook for doing any extra configuration, returning a dictionary
+ containing the configured data.
+
"""
return self.configured_data
View
130 docs/Makefile
@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-appconf.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-appconf.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/django-appconf"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-appconf"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ make -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
View
48 docs/changelog.rst
@@ -0,0 +1,48 @@
+Changelog
+=========
+
+0.4 (2011-08-24)
+----------------
+
+* Renamed ``app_label`` attribute of the inner ``Meta`` class to ``prefix``.
+ The old form ``app_label`` will work in the meantime.
+
+* Added ``holder`` attribute to the inner ``Meta`` class to be able to
+ specify a custom "global" setting holder. Default: "'django.conf.settings'"
+
+* Added ``proxy`` attribute to the inner ``Meta`` class to enable proxying
+ of ``AppConf`` instances to the settings holder, e.g. the global Django
+ settings.
+
+* Fixed issues with ``configured_data`` dictionary available in the
+ ``configure`` method of ``AppConf`` classes with regard to subclassing.
+
+0.3 (2011-08-23)
+----------------
+
+* Added tests with 100% coverage.
+
+* Added ability to subclass ``Meta`` classes.
+
+* Fixed various bugs with subclassing and configuration in subclasses.
+
+0.2.2 (2011-08-22)
+------------------
+
+* Fixed another issue in the ``configure()`` API.
+
+0.2.1 (2011-08-22)
+------------------
+
+* Fixed minor issue in ``configure()`` API.
+
+0.2 (2011-08-22)
+----------------
+
+* Added ``configure()`` API to ``AppConf`` class which is called after
+ configuring each setting.
+
+0.1 (2011-08-22)
+----------------
+
+* First public release.
View
220 docs/conf.py
@@ -0,0 +1,220 @@
+# -*- coding: utf-8 -*-
+#
+# django-appconf documentation build configuration file, created by
+# sphinx-quickstart on Thu Aug 25 14:26:22 2011.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'django-appconf'
+copyright = u'2011, Jannis Leidel and individual contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.4'
+# The full version, including alpha/beta/rc tags.
+release = '0.4'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'django-appconfdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'django-appconf.tex', u'django-appconf Documentation',
+ u'Jannis Leidel and individual contributors', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'django-appconf', u'django-appconf Documentation',
+ [u'Jannis Leidel and individual contributors'], 1)
+]
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}
View
12 docs/index.rst
@@ -0,0 +1,12 @@
+.. include:: ../README.rst
+
+Contents
+========
+
+.. toctree::
+ :maxdepth: 1
+
+ installation
+ usage
+ reference
+ changelog
View
20 docs/installation.rst
@@ -0,0 +1,20 @@
+Installation
+============
+
+* Install django-appconf with your favorite Python package manager::
+
+ pip install django-appconf
+
+* Add ``'appconf'`` to your ``INSTALLED_APPS`` setting::
+
+ INSTALLED_APPS = (
+ # other apps
+ "appconf",
+ )
+
+
+.. _staticfiles: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/
+.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles
+
+.. _dependencies:
+
View
170 docs/make.bat
@@ -0,0 +1,170 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^<target^>` where ^<target^> is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\django-appconf.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\django-appconf.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+:end
View
76 docs/reference.rst
@@ -0,0 +1,76 @@
+=========
+Reference
+=========
+
+.. currentmodule:: appconf
+
+.. class:: AppConf
+
+ A representation of a template tag. For example::
+
+ class MyAppConf(AppConf):
+ SETTING_1 = "one"
+ SETTING_2 = (
+ "two",
+ )
+
+ .. method:: configure_*(value)
+
+ Method for each of the app settings for custom configuration
+ which gets the value passed of the class attribute or the
+ appropriate override value of the :attr:`~appconf.AppConf.Meta.holder`
+ settings, e.g.::
+
+ class MyAppConf(AppConf):
+ DEPLOYMENT_MODE = "dev"
+
+ def configure_deployment_mode(self, value):
+ if on_production():
+ value = "prod"
+ return value
+
+ The method **must return** the value to be use for the setting in
+ question.
+
+ .. automethod:: configure
+ .. autoattribute:: configured_data
+
+ The dictionary attribute which can be used to do any further custom
+ configuration handling in the :meth:`~appconf.AppConf.configure`
+ method, e.g. if multiple settings depend on each other.
+
+.. class:: AppConf.Meta
+
+ An ``AppConf`` takes options via a ``Meta`` inner class::
+
+ class MyAppConf(AppConf):
+ SETTING_1 = "one"
+ SETTING_2 = (
+ "two",
+ )
+
+ class Meta:
+ proxy = False
+ prefix = 'myapp'
+ holder = 'django.conf.settings'
+
+ .. attribute:: prefix
+
+ Explicitly choose a prefix for all settings handled by the
+ ``AppConf`` class. If not given, the prefix will be the capitalized
+ class module name.
+
+ For example, ``acme`` would turn into settings like
+ ``ACME_SETTING_1``.
+
+ .. attribute:: holder
+
+ The global settings holder to use when looking for overrides and
+ when setting the configured values.
+
+ Defaults to ``'django.conf.settings'``.
+
+ .. attribute:: proxy
+
+ A boolean, if set to ``True`` will enable proxying attribute access
+ to the :attr:`~appconf.AppConf.Meta.holder`.
View
95 docs/usage.rst
@@ -0,0 +1,95 @@
+Usage
+=====
+
+It's strongly recommended to use the usual ``from django.conf import settings``
+in your own code to access the configured settings.
+
+But you can also **OPTIONALLY** use your app's own settings object directly,
+by instantiating it in place::
+
+ from myapp.models import MyAppConf
+
+ myapp_settings = MyAppConf()
+
+ print myapp_settings.SETTING_1
+
+Note that accessing the settings that way means they don't have a prefix.
+
+``AppConf`` instances don't automatically work as proxies for the global
+settings. But you can enable this if you want by setting the ``proxy``
+attribute of the inner ``Meta`` class to ``True``::
+
+ from appconf import AppConf
+
+ class MyAppConf(AppConf):
+ SETTING_1 = "one"
+ SETTING_2 = (
+ "two",
+ )
+
+ class Meta:
+ proxy = True
+
+ myapp_settings = MyAppConf()
+
+ if "myapp" in myapp_settings.INSTALLED_APPS:
+ print "yay, myapp is installed!"
+
+In case you want to override some settings programmatically, you can
+simply pass the value when instantiating the ``AppConf`` class::
+
+ from myapp.models import MyAppConf
+
+ myapp_settings = MyAppConf(SETTING_1='something completely different')
+
+ if 'different' in myapp_settings.SETTINGS_1:
+ print 'yay, I'm different!'
+
+Custom configuration
+--------------------
+
+Each of the settings can be individually configured with callbacks.
+For example, in case a value of a setting depends on other settings
+or other dependencies. The following example sets one setting to a
+different value depending on a global setting::
+
+ from django.conf import settings
+ from appconf import AppConf
+
+ class MyCustomAppConf(AppConf):
+ ENABLED = True
+
+ def configure_enabled(self, value):
+ return value and not settings.DEBUG
+
+The value of ``MYAPP_ENABLED`` will vary depending on the
+value of the global ``DEBUG`` setting.
+
+Each of the app settings can be customized by providing
+a method ``configure_<lower_setting_name>`` that takes the default
+value as defined in the class attributes of the ``AppConf`` subclass
+or the override value from the global settings as the only parameter.
+The method **must return** the value to be use for the setting in
+question.
+
+After each of the ``*_configure`` methods have been called, the ``AppConf``
+class will additionally call a main ``configure`` method, which can
+be used to do any further custom configuration handling, e.g. if multiple
+settings depend on each other. For that a ``configured_data`` dictionary
+is provided in the setting instance::
+
+ from django.conf import settings
+ from appconf import AppConf
+
+ class MyCustomAppConf(AppConf):
+ ENABLED = True
+ MODE = 'development'
+
+ def configure_enabled(self, value):
+ return value and not settings.DEBUG
+
+ def configure(self):
+ mode = self.configured_data['MODE']
+ enabled = self.configured_data['ENABLED']
+ if not enabled and mode != 'development':
+ print "WARNING: app not enabled in %s mode!" % mode
View
11 setup.py
@@ -7,15 +7,16 @@
setup(
name='django-appconf',
version=":versiontools:appconf:",
- description='An app configuration object to be used for handling '
- 'configuration defaults of packaged apps gracefully.',
+ description='A helper class for handling configuration defaults '
+ 'of packaged apps gracefully.',
long_description=read(path.join(path.dirname(__file__), 'README.rst')),
author='Jannis Leidel',
author_email='jannis@leidel.info',
- url='https://github.com/jezdez/django-appconf/',
+ license = 'BSD',
+ url='http://django-appconf.readthedocs.org/',
py_modules=['appconf'],
classifiers=[
- "Development Status :: 3 - Alpha",
+ "Development Status :: 4 - Beta",
'Environment :: Web Environment',
'Framework :: Django',
'Intended Audience :: Developers',
@@ -28,6 +29,6 @@
'Topic :: Utilities',
],
setup_requires=[
- 'versiontools >= 1.5',
+ 'versiontools >= 1.6',
],
)
View
32 tests/testapp/models.py
@@ -1,5 +1,12 @@
from appconf import AppConf
+
+class CustomHolder(object):
+ pass
+
+custom_holder = CustomHolder()
+
+
class TestConf(AppConf):
SIMPLE_VALUE = True
@@ -17,7 +24,7 @@ def configure(self):
class PrefixConf(TestConf):
class Meta:
- app_label = 'prefix'
+ prefix = 'prefix'
class YetAnotherPrefixConf(PrefixConf):
@@ -25,7 +32,7 @@ class YetAnotherPrefixConf(PrefixConf):
SIMPLE_VALUE = False
class Meta:
- app_label = 'yetanother_prefix'
+ prefix = 'yetanother_prefix'
class SeparateConf(AppConf):
@@ -35,3 +42,24 @@ class SeparateConf(AppConf):
class Meta(PrefixConf.Meta):
pass
+
+class SubclassConf(TestConf):
+
+ def configure(self):
+ self.configured_data['CONFIGURE_METHOD_VALUE2'] = False
+ return self.configured_data
+
+
+class ProxyConf(TestConf):
+
+ class Meta:
+ proxy = True
+
+
+class CustomHolderConf(AppConf):
+
+ SIMPLE_VALUE = True
+
+ class Meta:
+ holder = 'testapp.models.custom_holder' # instead of django.conf.settings
+ prefix = 'custom_holder'
View
48 tests/testapp/tests.py
@@ -2,13 +2,14 @@
from django.test import TestCase
from testapp.models import (TestConf, PrefixConf, YetAnotherPrefixConf,
- SeparateConf)
+ SeparateConf, ProxyConf, CustomHolderConf,
+ custom_holder)
class TestConfTests(TestCase):
def test_basic(self):
- self.assertEquals(TestConf._meta.app_label, 'testapp')
+ self.assertEquals(TestConf._meta.prefix, 'testapp')
def test_simple(self):
self.assertTrue(hasattr(settings, 'TESTAPP_SIMPLE_VALUE'))
@@ -24,24 +25,49 @@ def test_configure_method(self):
def test_init_kwargs(self):
custom_conf = TestConf(CUSTOM_VALUE='custom')
- self.assertEquals(custom_conf.TESTAPP_CUSTOM_VALUE, 'custom')
+ self.assertEquals(custom_conf.CUSTOM_VALUE, 'custom')
self.assertEquals(settings.TESTAPP_CUSTOM_VALUE, 'custom')
+ self.assertRaises(AttributeError, lambda: custom_conf.TESTAPP_CUSTOM_VALUE)
+ custom_conf.CUSTOM_VALUE_SETATTR = 'custom'
+ self.assertEquals(settings.TESTAPP_CUSTOM_VALUE_SETATTR, 'custom')
+ custom_conf.custom_value_lowercase = 'custom'
+ self.assertRaises(AttributeError, lambda: settings.custom_value_lowercase)
def test_init_kwargs_with_prefix(self):
custom_conf = TestConf(TESTAPP_CUSTOM_VALUE2='custom2')
self.assertEquals(custom_conf.TESTAPP_CUSTOM_VALUE2, 'custom2')
self.assertEquals(settings.TESTAPP_CUSTOM_VALUE2, 'custom2')
+ def test_proxy(self):
+ custom_conf = ProxyConf(CUSTOM_VALUE3='custom3')
+ self.assertEquals(custom_conf.CUSTOM_VALUE3, 'custom3')
+ self.assertEquals(settings.TESTAPP_CUSTOM_VALUE3, 'custom3')
+ self.assertEquals(custom_conf.TESTAPP_CUSTOM_VALUE3, 'custom3')
+ self.assertTrue('tests.testapp' in custom_conf.INSTALLED_APPS)
+
def test_dir_members(self):
- settings = TestConf()
- self.assertTrue('TESTAPP_SIMPLE_VALUE' in dir(settings), dir(settings))
+ custom_conf = TestConf()
+ self.assertTrue('TESTAPP_SIMPLE_VALUE' in dir(settings))
self.assertTrue('TESTAPP_SIMPLE_VALUE' in settings.__members__)
+ self.assertTrue('SIMPLE_VALUE' in dir(custom_conf))
+ self.assertTrue('SIMPLE_VALUE' in custom_conf.__members__)
+ self.assertFalse('TESTAPP_SIMPLE_VALUE' in dir(custom_conf))
+ self.assertFalse('TESTAPP_SIMPLE_VALUE' in custom_conf.__members__)
+
+ def test_custom_holder(self):
+ custom_conf = CustomHolderConf()
+ self.assertTrue(hasattr(custom_holder, 'CUSTOM_HOLDER_SIMPLE_VALUE'))
+ self.assertEquals(custom_holder.CUSTOM_HOLDER_SIMPLE_VALUE, True)
+
+ def test_subclass_configured_data(self):
+ self.assertTrue('TESTAPP_CONFIGURE_METHOD_VALUE2' in dir(settings))
+ self.assertEquals(settings.TESTAPP_CONFIGURE_METHOD_VALUE2, False)
class PrefixConfTests(TestCase):
- def test_app_label(self):
- self.assertEquals(PrefixConf._meta.app_label, 'prefix')
+ def test_prefix(self):
+ self.assertEquals(PrefixConf._meta.prefix, 'prefix')
def test_simple(self):
self.assertTrue(hasattr(settings, 'PREFIX_SIMPLE_VALUE'))
@@ -58,8 +84,8 @@ def test_configure_method(self):
class YetAnotherPrefixConfTests(TestCase):
- def test_app_label(self):
- self.assertEquals(YetAnotherPrefixConf._meta.app_label,
+ def test_prefix(self):
+ self.assertEquals(YetAnotherPrefixConf._meta.prefix,
'yetanother_prefix')
def test_simple(self):
@@ -82,8 +108,8 @@ def test_configure_method(self):
class SeparateConfTests(TestCase):
- def test_app_label(self):
- self.assertEquals(SeparateConf._meta.app_label, 'prefix')
+ def test_prefix(self):
+ self.assertEquals(SeparateConf._meta.prefix, 'prefix')
def test_simple(self):
self.assertTrue(hasattr(settings, 'PREFIX_SEPARATE_VALUE'))
View
8 tests/tox.ini
@@ -12,6 +12,14 @@ commands =
echo "Type the following to open the coverage report: python -m webbrowser -t file://{envtmpdir}/index.html"
downloadcache = {toxworkdir}/_download/
+[testenv:docs]
+changedir = ../docs
+deps =
+ Sphinx
+commands =
+ make clean
+ make html
+
[testenv:py25-1.2.X]
basepython = python2.5
deps =
Please sign in to comment.
Something went wrong with that request. Please try again.