[Python-modules-commits] [pystaticconfiguration] 01/03: New upstream version 0.10.3
Sophie Brun
sbrun-guest at moszumanska.debian.org
Wed Oct 25 13:03:50 UTC 2017
This is an automated email from the git hooks/post-receive script.
sbrun-guest pushed a commit to branch debian/master
in repository pystaticconfiguration.
commit ce0779caff4a6e05d828897a382ebbda4ab40e73
Author: Sophie Brun <sophie at freexian.com>
Date: Wed Oct 25 12:19:14 2017 +0200
New upstream version 0.10.3
---
.gitignore | 34 +++
.landscape.yaml | 5 +
.pyautotest | 7 +
.travis.yml | 16 +
LICENSE | 202 +++++++++++++
NOTICE | 13 +
README.rst | 135 +++++++++
dobi.yaml | 51 ++++
dockerfiles/Dockerfile | 24 ++
docs/source/conf.py | 46 +++
docs/source/config.rst | 24 ++
docs/source/getters.rst | 14 +
docs/source/index.rst | 58 ++++
docs/source/loader.rst | 9 +
docs/source/overview.rst | 254 ++++++++++++++++
docs/source/readers.rst | 7 +
docs/source/release_notes.rst | 33 ++
docs/source/schema.rst | 7 +
docs/source/testing.rst | 7 +
docs/source/validation.rst | 8 +
setup.cfg | 15 +
setup.py | 35 +++
staticconf/__init__.py | 11 +
staticconf/config.py | 615 ++++++++++++++++++++++++++++++++++++++
staticconf/errors.py | 13 +
staticconf/getters.py | 130 ++++++++
staticconf/loader.py | 350 ++++++++++++++++++++++
staticconf/proxy.py | 147 +++++++++
staticconf/readers.py | 167 +++++++++++
staticconf/schema.py | 220 ++++++++++++++
staticconf/testing.py | 92 ++++++
staticconf/validation.py | 175 +++++++++++
staticconf/version.py | 2 +
testing/__init__.py | 0
testing/testifycompat.py | 40 +++
tests/__init__.py | 0
tests/config_test.py | 681 ++++++++++++++++++++++++++++++++++++++++++
tests/data/__init__.py | 0
tests/getters_test.py | 100 +++++++
tests/integration_test.py | 99 ++++++
tests/loader_test.py | 339 +++++++++++++++++++++
tests/proxy_test.py | 144 +++++++++
tests/readers_test.py | 62 ++++
tests/schema_test.py | 104 +++++++
tests/testing_test.py | 41 +++
tests/validation_test.py | 148 +++++++++
tox.ini | 33 ++
47 files changed, 4717 insertions(+)
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..ff93fb2
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,34 @@
+*.py[co]
+
+# Packages
+*.egg
+*.egg-info
+dist
+build
+eggs
+parts
+bin
+var
+sdist
+develop-eggs
+.installed.cfg
+
+# Installer logs
+pip-log.txt
+
+# Unit test / coverage reports
+.coverage
+.tox
+htmlcov/
+
+#Translations
+*.mo
+
+#Mr Developer
+.mr.developer.cfg
+
+.idea
+.*.sw[po]
+
+.dobi
+.cache
diff --git a/.landscape.yaml b/.landscape.yaml
new file mode 100644
index 0000000..220b307
--- /dev/null
+++ b/.landscape.yaml
@@ -0,0 +1,5 @@
+
+strictness: high
+
+ignore-patterns:
+ - docs/source/conf.py
diff --git a/.pyautotest b/.pyautotest
new file mode 100644
index 0000000..f48470e
--- /dev/null
+++ b/.pyautotest
@@ -0,0 +1,7 @@
+test_runner_name: full_suite
+command:
+ - 'py.test'
+ - '-v'
+ - '-s'
+ - '--tb=short'
+ - tests
diff --git a/.travis.yml b/.travis.yml
new file mode 100644
index 0000000..434fb0c
--- /dev/null
+++ b/.travis.yml
@@ -0,0 +1,16 @@
+language: python
+matrix:
+ include:
+ - env: TOXENV=py26
+ - env: TOXENV=py27
+ - env: TOXENV=py34
+ - env: TOXENV=py35
+ python: 3.5
+ - env: TOXENV=py36
+ python: 3.6
+ - env: TOXENV=pypy
+ - env: TOXENV=docs
+ - env: TOXENV=coverage
+install: pip install tox coveralls
+script: tox
+after_success: coveralls
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..d645695
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/NOTICE b/NOTICE
new file mode 100644
index 0000000..c2a4f4e
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,13 @@
+Copyright 2012 Daniel Nephin
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..63a463f
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,135 @@
+PyStaticConfiguration
+=====================
+
+A python library for loading, validating and reading configuration from many
+heterogeneous formats. Configuration is split into two phases.
+
+Configuration Loading
+---------------------
+
+Configuration is read from files or python objects, flattened, and merged
+into a container called a `namespace`. Namespaces are used to separate
+unrelated configuration groups.
+
+If configuration is changed frequently, it can also be reloaded easily
+with very little change to the existing code.
+
+
+Configuration Reading
+---------------------
+
+A configuration value is looked up in the `namespace`. It is validating and
+converted to the requested type.
+
+
+.. contents:: Contents
+ :local:
+ :depth: 1
+ :backlinks: none
+
+
+
+Build Status
+------------
+
+.. image:: https://travis-ci.org/dnephin/PyStaticConfiguration.svg?branch=master
+ :target: https://travis-ci.org/dnephin/PyStaticConfiguration
+ :alt: Travis CI build status
+
+.. image:: https://img.shields.io/pypi/v/PyStaticConfiguration.svg
+ :target: https://pypi.python.org/pypi/PyStaticConfiguration
+ :alt: Latest PyPI version
+
+.. image:: https://coveralls.io/repos/github/dnephin/PyStaticConfiguration/badge.svg?branch=master
+ :target: https://coveralls.io/github/dnephin/PyStaticConfiguration?branch=master
+ :alt: Code Test Coverage
+
+
+
+Install
+-------
+
+* PyStaticConfiguration is available on pypi: https://pypi.python.org/pypi/PyStaticConfiguration
+* The source is hosted on github: https://github.com/dnephin/PyStaticConfiguration
+
+.. code-block:: bash
+
+ $ pip install PyStaticConfiguration
+
+
+Also see the
+`release notes <http://pythonhosted.org/PyStaticConfiguration/release_notes.html>`_.
+
+Documentation
+-------------
+
+http://pythonhosted.org/PyStaticConfiguration/
+
+
+Examples
+--------
+
+A common minimal use of staticconf would be to use a single yaml configuration
+file and read some values from it.
+
+.. code-block:: python
+
+ import staticconf
+
+ filename = 'hosts.yaml'
+ namespace = 'hosts'
+
+ # Load configuration from the file into namespace `hosts`
+ staticconf.YamlConfiguration(filename, namespace=namespace)
+ ...
+
+ # Some time later on, read values from that namespace
+ print staticconf.read('database.slave', namespace=namespace)
+ print staticconf.read('database.master', namespace=namespace)
+
+
+`hosts.yaml` might look something like this:
+
+.. code-block:: yaml
+
+ database:
+ slave: dbslave_1
+ master: dbmaster_1
+
+
+A more involved example would load configuration from multiple files, create
+a watcher for reloading, and read some config values.
+
+.. code-block:: python
+
+ from functools import partial
+ import os
+ import staticconf
+
+
+ def load_config(config_path, defaults='~/.myapp.yaml`)
+ # First load global defaults if the file exists
+ staticconf.INIConfiguration('/etc/myapp.ini', optional=True)
+
+ # Next load user defaults
+ staticconf.YamlConfiguration(defaults, optional=True)
+
+ # Next load the specified configuration file
+ staticconf.YamlConfiguration(config_path)
+
+ # Now let's override it with some environment settings
+ staticconf.DictConfiguration(
+ (k[5:].lower(), v) for k, v in os.environ if k.startswith('MYAPP_'))
+
+
+ def build_watcher(filename):
+ return staticconf.ConfigFacade.load(
+ filenames, 'DEFAULT', partial(load_config, filename))
+
+ def run(config_path):
+ watcher = build_watcher(config_path)
+ while is_work():
+ watcher.reload_if_changed()
+
+ current_threshold = staticconf.read_float('current_threshold')
+ do_some_work(current_thresold)
diff --git a/dobi.yaml b/dobi.yaml
new file mode 100644
index 0000000..2ce9202
--- /dev/null
+++ b/dobi.yaml
@@ -0,0 +1,51 @@
+
+meta:
+ project: pystaticconf
+ default: test
+
+
+mount=source:
+ bind: .
+ path: /work
+
+mount=pypiconf:
+ bind: ~/.pypirc
+ path: /root/.pypirc
+ file: true
+
+image=builder:
+ image: staticconf-dev
+ context: dockerfiles/
+ dockerfile: Dockerfile
+
+
+job=test:
+ use: builder
+ mounts: [source]
+ interactive: true
+ command: tox
+ env: ['TOXENV={env.TOXENV:}']
+
+job=shell:
+ use: builder
+ mounts: [source, pypiconf]
+ interactive: true
+ command: bash
+
+job=clean:
+ use: builder
+ mounts: [source]
+ command: "find -name *.pyc -o -name __pycache__ -exec rm -rf {} \\;"
+
+job=docs:
+ use: builder
+ mounts: [source]
+ command: "tox -e docs"
+ artifact: docs/build
+
+job=release:
+ use: builder
+ mounts: [source, pypiconf]
+ interactive: true
+ depends: [docs]
+ command: "python3 setup.py sdist upload upload_docs"
diff --git a/dockerfiles/Dockerfile b/dockerfiles/Dockerfile
new file mode 100644
index 0000000..fb719c3
--- /dev/null
+++ b/dockerfiles/Dockerfile
@@ -0,0 +1,24 @@
+
+FROM ubuntu:xenial
+
+ENV LANG C.UTF-8
+RUN export DEBIAN_FRONTEND=noninteractive; \
+ apt-get update && apt-get install -y --no-install-recommends \
+ software-properties-common
+
+RUN export DEBIAN_FRONTEND=noninteractive; \
+ add-apt-repository ppa:fkrull/deadsnakes && \
+ apt-get update && apt-get install -y --no-install-recommends \
+ python2.6 \
+ python2.7 \
+ python3.4 \
+ python3.5 \
+ pypy \
+ curl
+
+RUN curl -Ls https://bootstrap.pypa.io/get-pip.py | python3
+RUN pip install \
+ tox \
+ yapyautotest
+
+WORKDIR /work
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..f7bb83a
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+
+import staticconf
+import sphinx_rtd_theme
+
+# -- General configuration -----------------------------------------------------
+
+extensions = [
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.todo',
+ 'sphinx.ext.coverage',
+ 'sphinx.ext.viewcode',
+ 'sphinx.ext.intersphinx',
+]
+
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+
+# General information about the project.
+project = u'PyStaticConfiguration'
+copyright = u'2013, Daniel Nephin'
+
+version = staticconf.version
+release = version
+
+exclude_patterns = []
+
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_static_path = []
+
+htmlhelp_basename = 'PyStaticConfigurationdoc'
+
+# -- Extensions ----------------------------------------------------------------
+
+autodoc_member_order = 'groupwise'
+
+intersphinx_mapping = {
+ 'http://docs.python.org/': None,
+}
diff --git a/docs/source/config.rst b/docs/source/config.rst
new file mode 100644
index 0000000..ce40a53
--- /dev/null
+++ b/docs/source/config.rst
@@ -0,0 +1,24 @@
+
+Config
+======
+
+.. automodule:: staticconf.config
+ :members: ConfigNamespace,
+ get_namespace,
+ validate,
+ view_help,
+ ConfigurationWatcher,
+ IComparator,
+ InodeComparator,
+ MTimeComparator,
+ MD5Comparator,
+ ReloadCallbackChain,
+ ConfigFacade,
+ reload
+
+Errors
+------
+
+.. automodule:: staticconf.errors
+ :members:
+
diff --git a/docs/source/getters.rst b/docs/source/getters.rst
new file mode 100644
index 0000000..fa49a74
--- /dev/null
+++ b/docs/source/getters.rst
@@ -0,0 +1,14 @@
+
+Getters
+=======
+
+.. automodule:: staticconf.getters
+ :members:
+
+
+Proxy
+-----
+
+.. automodule:: staticconf.proxy
+ :members:
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..3b872c9
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,58 @@
+
+PyStaticConfiguration Documentation
+===================================
+
+Build Status
+------------
+
+
+.. image:: https://travis-ci.org/dnephin/PyStaticConfiguration.svg?branch=master
+ :target: https://travis-ci.org/dnephin/PyStaticConfiguration
+ :alt: Travis CI build status
+
+.. image:: https://img.shields.io/pypi/v/PyStaticConfiguration.svg
+ :target: https://pypi.python.org/pypi/PyStaticConfiguration
+ :alt: Latest PyPI version
+
+.. image:: https://coveralls.io/repos/github/dnephin/PyStaticConfiguration/badge.svg?branch=master
+ :target: https://coveralls.io/github/dnephin/PyStaticConfiguration?branch=master
+ :alt: Code Test Coverage
+
+
+Install
+-------
+
+* PyStaticConfiguration is available on pypi: https://pypi.python.org/pypi/PyStaticConfiguration
+* The source is hosted on github: https://github.com/dnephin/PyStaticConfiguration
+
+.. code-block:: bash
+
+ $ pip install PyStaticConfiguration
+
+
+Also see the :doc:`release_notes`
+
+
+Contents
+--------
+
+.. toctree::
+ :maxdepth: 2
+
+ overview
+ config
+ loader
+ validation
+ readers
+ schema
+ getters
+ testing
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/docs/source/loader.rst b/docs/source/loader.rst
new file mode 100644
index 0000000..c06d307
--- /dev/null
+++ b/docs/source/loader.rst
@@ -0,0 +1,9 @@
+
+
+Configuration Loading
+=====================
+
+.. automodule:: staticconf.loader
+ :members:
+ :undoc-members:
+
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
new file mode 100644
index 0000000..5deb9df
--- /dev/null
+++ b/docs/source/overview.rst
@@ -0,0 +1,254 @@
+Overview
+========
+
+:mod:`staticconf` is a library for loading configuration values from many
+heterogeneous formats and reading those values. This process is split into two
+phases.
+
+Configuration Loading
+---------------------
+
+Configuration is read from files or python objects (:class:`dict`,
+:class:`list`, or any :class:`object` with attributes), flattened, and merged
+into a container called a :class:`staticconf.config.ConfigNamespace`.
+Namespaces are used to group related configuration together.
+
+If configuration is changed frequently, it can also be reloaded easily
+with very little change to the existing code.
+
+
+See :mod:`staticconf.loader` for a list of supported file formats and config
+loading examples.
+
+See :func:`staticconf.config.ConfigFacade.load` for examples of building
+a reloader.
+
+See :class:`staticconf.config.ConfigNamespace` for more details about
+namespaces.
+
+
+
+Reading configuration values
+----------------------------
+Once configuration data is loaded into a
+:class:`staticconf.config.ConfigNamespace` there are three options for
+retrieving the configuration values. All of them have a similar set of methods
+which use validators to ensure you're getting the type you expect. When a value
+is missing they will raise :class:`staticconf.errors.ConfigurationError` unless
+a default was given. They will raises
+:class:`staticconf.errors.ValidationError` if the value in the config fails to
+validate.
+
+The list of provided validators is :mod:`staticconf.validation`, but you can
+create custom validators for any type. Functions for reading
+configuration values are named using a convention based on the validator name.
+For example the methods for getting a date using
+:func:`staticconf.validation.validate_date` would be:
+
+* ``staticconf.read_date()``
+* ``schema.date()``
+* ``staticconf.get_date()``
+
+
+Readers
+~~~~~~~
+
+:mod:`staticconf.readers`
+
+Readers are the most straightforward option. They simply lookup the value in
+the namespace and return it. There is no caching of the type-coercion.
+
+
+Schema
+~~~~~~
+
+:mod:`staticconf.schema`
+
+Schemas are classes where each property is an accessor for a configuration
+value. The type-coercion is cached on the class. This can be useful if you're
+performing more involved coercion (such as converting a large list to a
+mapping, or building complex types).
+
+
+Getters
+~~~~~~~
+
+:mod:`staticconf.getters`
+
+Getters have the same properties as schema accessors, but do not use a class.
+See the module documentation for some limitations with this option.
+
+
+
+Example
+-------
+
+For this example we'll use yaml configuration files. Given two files,
+a `application.yaml`:
+
+.. code-block:: yaml
+
+ pid: /var/run/app1.pid
+
+ storage_paths:
+ - /mnt/storage
+ - /mnt/nfs
+
+ min_date: 2014-12-12
+
+ groups:
+ users:
+ - userone
+ - usertwo
+ admins:
+ - admin
+
+
+And an `overrides.yaml`
+
+.. code-block:: yaml
+
+ max_files: 10
+
+ groups:
+ users:
+ - customuser
+
+
+First load some configuration from a file. This is often done during the
+"startup" phase of an application, such as after :mod:`argparse` has completed
+(potentially where one of the command line args is a config filename). For a
+web application, this might happen during the initialization of the webapp.
+
+.. code-block:: python
+
+ import staticconf
+
+ app_config = 'application.yaml'
+ app_custom = 'overrides.yaml'
+
+ YamlConfiguration(app_config)
+ YamlConfiguration(app_custom, optional=True)
+
+
+Now we've loaded up our application config, and overridden it with the data
+from `overrides.yaml`. `overrides.yaml` was optional, so if the file was missing
+there would be no error.
+
+Next we'll want to read these values at some point.
+
+.. code-block:: python
+
+ import staticconf
+
+ pid = staticconf.read_string('pid')
+
+ storage_paths = staticconf.read_list_of_string('storage_paths')
+
+ # This is the just the list of one user `customuser` since we loaded our
+ # `overrides.yaml` over the original list
+ # Also notice the key was flattened, so we use a dotted notation
+ users = staticconf.read_list_of_string('groups.users')
+
+ # Using doted notation allows us to preserve any part of the mapping
+ # structure, so in this case, the admins from `application.yaml` are
+ # still there
+ admins = staticconf.read_list_of_string('groups.admins')
+
+ # We can also read other types. In our config this was a string, but we're
+ # reading a date, so we receive a datetime.date object
+ min_date = staticconf.read_date('min_date')
+
+
+See :class:`staticconf.config.ConfigFacade` for examples of how to reload
+configuration on changes.
+
+
+Logging
+-------
+
+:mod:`staticconf` logs a message at `INFO` level when configuration is loaded
+with the message "Unexpected value in <namespace> configuration: ...", with the
+list of unexpected values. Unexpected values are those that haven't been
+registered by a :mod:`staticconf.schema` or :mod:`staticconf.getter`.
+
+This message is used to debug configuration errors. If you'd like to disable it
+you can set the logging level for `staticconf.config` to `WARN`.
+
+
+Reading dicts
+-------------
+By default :mod:`staticconf` flattens all the values it receives from
+the loaders. There are two ways to get dicts from a loader.
+
+Disable Flatten
+~~~~~~~~~~~~~~~
+
+You can call loaders with the kwargs ``flatten=False``.
+
+Example:
+
+.. code-block:: python
+
+ YamlConfiguration(filename, flatten=False)
+
+The disadvantage with this approach is that the entire config file will
+preserve its nested structure, so you lose out of the ability to easily
+merge and override configuration files.
+
+Custom Reader
+~~~~~~~~~~~~~
+
+The second option is to represent a dict structures using lists of values
+(either a list of pairs or a list of dicts). This list can then be converted
+into a dict mapping using a custom getter/reader.
+
+Below are some examples on how this is done. The :mod:`staticconf.readers`
+interface is used as an example, but the same can be done for the
+:mod:`staticconf.getters` and :mod:`staticconf.schema` interfaces
+by replacing :func:`staticconf.readers.build_reader` with
+:func:`staticconf.getters.build_getter` or
+:func:`staticconf.schema.build_value_type`.
+
+
+Create a reader which translates a list of dicts into a mapping
+
+.. code-block:: python
+
... 4045 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/pystaticconfiguration.git
More information about the Python-modules-commits
mailing list