Mercurial > hgrepos > Python > libs > ConfigMix
changeset 215:ab3d0326419c
Doc: Move the "doc" to "docs"
| author | Franz Glasner <fzglas.hg@dom66.de> |
|---|---|
| date | Wed, 08 May 2019 09:23:37 +0200 |
| parents | a35b0ca8b81f |
| children | c03c9162f7e6 |
| files | .hgignore doc/Makefile doc/_static/_dummy doc/_templates/_dummy doc/apidoc.rst doc/authors.rst doc/changes.rst doc/conf.py doc/index.rst doc/introduction.rst doc/license.rst doc/make.bat doc/readme.rst doc/todo.rst docs/Makefile docs/_static/_dummy docs/_templates/_dummy docs/apidoc.rst docs/authors.rst docs/changes.rst docs/conf.py docs/index.rst docs/introduction.rst docs/license.rst docs/make.bat docs/readme.rst docs/todo.rst |
| diffstat | 23 files changed, 917 insertions(+), 917 deletions(-) [+] |
line wrap: on
line diff
--- a/.hgignore Wed May 08 09:17:55 2019 +0200 +++ b/.hgignore Wed May 08 09:23:37 2019 +0200 @@ -5,5 +5,5 @@ *.egg-info build/ dist/ -doc/_build/ +docs/_build/ _venv*/ \ No newline at end of file
--- a/doc/Makefile Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = ConfigMix -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file
--- a/doc/apidoc.rst Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,78 +0,0 @@ -.. -*- coding: utf-8 -*- - -Package API Documentation -========================= - -.. contents:: - :local: - -Package :mod:`configmix` ------------------------- - -.. automodule:: configmix - :members: - :ignore-module-all: - - -Module :mod:`configmix.compat` ------------------------------- - -.. automodule:: configmix.compat - :members: - :undoc-members: - - -Module :mod:`configmix.config` ------------------------------- - -.. automodule:: configmix.config - :members: - :ignore-module-all: - - -Module :mod:`configmix.ini` ---------------------------- - -.. automodule:: configmix.ini - :members: - :ignore-module-all: - - -Module :mod:`configmix.json` ----------------------------- - -.. automodule:: configmix.json - :members: - :ignore-module-all: - - -Module :mod:`configmix.py` --------------------------- - -.. automodule:: configmix.py - :members: - :ignore-module-all: - - -Module :mod:`configmix.toml` ----------------------------- - -.. automodule:: configmix.toml - :members: - :ignore-module-all: - - -Module :mod:`configmix.variables` ---------------------------------- - -.. automodule:: configmix.variables - :members: - :ignore-module-all: - - -Module :mod:`configmix.yaml` ----------------------------- - -.. automodule:: configmix.yaml - :members: - :ignore-module-all:
--- a/doc/authors.rst Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,8 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _authors: - -Authors -======= - -.. include:: ../AUTHORS.txt
--- a/doc/changes.rst Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,60 +0,0 @@ -.. -*- coding: utf-8; mode: rst; -*- - -========= - Changes -========= - -All major changes over the versions are listed here. For breaking -changes have a look at :ref:`api-changes`, they are listed there in -detail. - -.. include:: ../CHANGES.txt - - -.. _api-changes: - -Breaking Changes -================ - -0.7 ---- - -- A major overhaul of how filename extensions are associated with loaders - has been done: - - + Filename extensions in :mod:`fnmatch` style are associated with - file-mode strings. - - These file-mode strings are associated with loader - functions separately via the mapping :py:data:`configmix.mode_loaders`. - - + :py:func:`configmix.set_assoc`, :py:func:`configmix.get_assoc`, - :py:func:`configmix.clear_assoc` and - :py:func:`configmix.get_default_assoc` are the new names for the old - `set_loader()`, `get_loader()`, `clear_loader()` and - `get_default_loader()` functions. - They are used for associating :mod:`fnmatch` style filename patterns - to file-mode strings. Previously they associated loader functions - directly. - - + :py:func:`configmix.set_assoc` now requires a :mod:`fnmatch` style - pattern instead of just a file extension string (i.e. a plain trailer). - The previons dictionary with mapping from filename extensions to loader - callables is now a list of tuples containing the :mod:`fnmatch` style - pattern and the corresponding loader callable. - - -0.6 ---- - -- :py:func:`configmix.safe_merge` does now a deepcopy of all source - configurations when merging. Changes in configuration instances - afterwards will not be reflected in the merged configuration any - more. - - The public signature of :py:func:`configmix.safe_merge` has *not* - changed. - -- The default file encoding when reading INI style files with - :py:func:`configmix.ini.load` is now "UTF-8". Previously it was undefined - and therefore dependent on the user's locale.
--- a/doc/conf.py Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,237 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/stable/config - -# -- Path setup -------------------------------------------------------------- - -# 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. -# -import datetime -import os -import sys -sys.path.insert(0, os.path.dirname(os.path.abspath('.'))) - -import configmix -from configmix.compat import u - - -# -- Project information ----------------------------------------------------- - -project = 'ConfigMix' -copyright = u('2015–2019, Franz Glasner. All rights reserved') -author = 'Franz Glasner' - -# The short X.Y version -version = '.'.join(configmix.__version__.split('.')[:2]) -# The full version, including alpha/beta/rc tags -release = configmix.__version__ -release_date = configmix.__date__ - -today = datetime.date.today().isoformat() - - -# -- 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.todo', - 'sphinx.ext.ifconfig', -# 'sphinx.ext.viewcode', - 'changelog', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = 'en' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path . -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - - -# -- 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 = 'alabaster' -html_theme = 'haiku' -# for the Haiku title -html_short_title = u("%s %s") % (project, release) -html_last_updated_fmt = "%s (rev %s)" % (today, configmix.__revision__) - -# 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 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'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - -html_show_sourcelink = False - - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = 'ConfigMixdoc' - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - 'papersize': 'a4paper', - - # The font size ('10pt', '11pt' or '12pt'). - # - 'pointsize': '11pt', - - # Additional stuff for the LaTeX preamble. - # - # NOTE: "inconsolata" in "fontpkg" errors within pdfTeX: seems to be - # incompatible with some header package. - # - 'preamble': r''' - \usepackage{inconsolata} - ''', - - 'fontpkg': r''' - \usepackage{charter} - \usepackage[defaultsans]{lato} - ''', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', - # Use "Version" instead of "Release" on the title - 'releasename': 'Version', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'ConfigMix.tex', '"ConfigMix" Documentation', - 'Franz Glasner', 'manual', True), -] - -latex_show_urls = 'footnote' -#latex_show_pagerefs = True - - -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'configmix', '"ConfigMix" Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'ConfigMix', '"ConfigMix" Documentation', - author, 'ConfigMix', 'One line description of project.', - 'Miscellaneous'), -] - - -# -- Extension configuration ------------------------------------------------- - -# -- Options for intersphinx extension --------------------------------------- - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} - -# -- Options for todo extension ---------------------------------------------- - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True -# Kein Link auf Pfad und Zeile -todo_link_only = True - -# -- Options for autodoc ----------------------------------------------------- - -autodoc_member_order = 'bysource' -autoclass_content = 'both' - - -# -- Options for changelog --------------------------------------------------- - -changelog_inner_tag_sort = ['breaking', 'feature', 'bugfix', 'misc', - 'test', 'doc'] - - -def setup(app): - # - # Custom release_date variable with a custom substitution |release_date| - # - app.add_config_value('release_date', '', 'env') - - import sphinx.transforms - - class IAMCustomSubstitutions(sphinx.transforms.SphinxTransform): - - default_priority = sphinx.transforms.DefaultSubstitutions.default_priority - def apply(self): - from docutils import nodes - for ref in self.document.traverse(nodes.substitution_reference): - refname = ref['refname'] - if refname == 'release_date': - stext = self.config[refname] - ref.replace_self(nodes.Text(stext, stext)) - - app.add_transform(IAMCustomSubstitutions)
--- a/doc/index.rst Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,44 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. ConfigMix documentation master file, created by - sphinx-quickstart on Tue Feb 27 22:03:52 2018. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -=========== - ConfigMix -=========== - -This is the documentation of the :mod:`configmix` package, a -library for helping with configuration files. - -.. toctree:: - :maxdepth: 3 - - readme - introduction - apidoc - changes - authors - license - -.. toctree:: - :hidden: - - todo - - -Indices and tables -================== - -.. only:: builder_html - - * :ref:`TODOINDEX` - * :ref:`genindex` - * :ref:`modindex` - * :ref:`search` - -.. only:: not builder_html - - * :ref:`TODOINDEX` - * :ref:`modindex`
--- a/doc/introduction.rst Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,402 +0,0 @@ -.. -*- coding: utf-8; indent-tabs-mode: nil; -*- - -.. _introduction: - -Introduction -============ - -.. contents:: - :local: - -The configurations can be read from different types of files: - -- :ref:`YAML files <yaml-files>` -- :ref:`JSON files <json-files>` -- :ref:`INI files <ini-files>` -- :ref:`TOML files <toml-files>` -- :ref:`executable Python scripts <executable-python-scripts>` - - -.. _yaml-files: - -YAML Files ----------- - -Need the :mod:`yaml` package (https://github.com/yaml/pyyaml) -(e.g. ``pip install pyyaml``) - -.. note:: All strings are returned as Unicode text strings. - -.. note:: The root object must be a *mapping* and therefore decode - into a Python :class:`dict` alike. This is checked by the - implementation. - -An example is: - -.. literalinclude:: ../tests/data/conf10.yml - :language: yaml - - -.. _json-files: - -JSON files ----------- - -Read the JSON file with the help of Python's native :mod:`json` package. - -.. note:: All strings are returned as Unicode text strings. - -.. note:: The root object must be an *object* and therefore decode - into a Python :class:`dict` alike. This is checked by the - implementation. - -An example is: - -.. literalinclude:: ../tests/data/conf10.json - :language: js - -For comments in JSON files see section :ref:`comments`. - - -.. _ini-files: - -INI Files ---------- - -Read the file and all sections named in parameter `extract` are flattened -into the resulting dictionary. By default the section named ``config`` is -used. - -Normally all values are returned as Unicode text strings. -But values can be annotated and therefore interpreted as other types: - - ``:int:`` - The value is handled in the same way as a Python :class:`int` - literal - - ``:float:`` - The value is interpreted as :class:`float` - - ``:bool:`` - The resulting value is a :class:`bool` where - - ``1``, ``true``, ``yes``, ``on`` - yield a Python ``True`` - - ``0``, ``false``, ``no``, ``off`` - yield a Python ``False`` - - The evaluation is done *case-insensitively*. - -.. note:: All strings are returned as Unicode text strings. - -.. note:: Contrary to the behaviour of the standard Python :mod:`configparser` - module the INI file reader is *case-sensitive*. - -The example INI style configuration below yields an equivalent -configuration to the YAML configuration above: - -.. literalinclude:: ../tests/data/conf10.ini - :language: ini - -As can be seen in this example -- INI file internal value interpolation -is done as in Python's standard :mod:`configparser` module. - -This example also illustrates how INI sections are used to build a -tree-ish configuration dictionary. - - -.. _toml-files: - -TOML Files ----------- - -Read the TOML file with the help of the pure Python :mod:`toml` -package (https://github.com/uiri/toml) (e.g. ``pip install toml``). - -All TOML features map seamingless to "ConfigMix". - -The example TOML style configuration below yields an equivalent -configuration to the YAML configuration above: - - -.. literalinclude:: ../tests/data/conf10.toml - :language: ini - - -.. _executable-python-scripts: - -Executable Python Scripts -------------------------- - -What will be exported: - -1. If loading is done with the `extract` parameter only the given keys are - extracted from the script. - -2. Otherwise it is checked if the scripts defines an ``__all__`` - sequence. If there is one it's contents are the keys to be - extracted. - -3. If there is no ``__all__`` object all names not starting with an - underscore ``_`` are found. - -This is analogous to as Python modules behave when importing them with -``from module import *``. - -.. note:: The Python configuration files are evaluated with ``exec`` and not - imported. - -The example configuration by Python script below yields an equivalent -configuration to the YAML configuration above: - -.. literalinclude:: ../tests/data/conf10.py - :language: python - - -.. _loading-and-merging: - -Loading and Merging -------------------- - -Basic usage of the API is as follows in this example:: - - import configmix - - # - # Note: With conf10 merging is rather pointless because the tree - # files # are really the same configuration. But is doesn't harm - # also here. - # - config = configmix.load("conf10.yml", "conf10.ini", "conf10.py") - - # Get a -- possibly interpolated -- configuration variable's value - value1 = config.getvar_s("key1") - - # Get a -- possibly interpolated -- variable from within the tree - value2 = config.getvar_s("tree1.tree2.key4") - - -By default filenames of the configuration files must have the extensions -(case-sensitivety depends on your OS): - - ``.ini`` - for INI configuration files - - ``.json`` - for JSON configuration files - - ``.py`` - for Python configuration files - - ``.toml`` - for TOML configuration file - - ``.yml`` or ``.yaml`` - for YAML configuration files - - -.. _getting-values: - -Getting configuration variables -------------------------------- - -Get a -- possibly interpolated -- configuration variable's value with:: - - value1 = config.getvar_s("key1") - -Get a raw configuration variable's value with:: - - value1_raw = config.getvar("key1") - -Because the configuration is not only a plain list of but a tree of -key-value pairs you will want to fetch them by separating the individual -level keys with a point ``.``. - -Looking at the example in chapter :ref:`yaml-files` -- when calling -``config.getvar_s("tree1.tree2.key4")`` you will get the value -``get this as `tree1.tree2.key4'``. - -This is true for both methods :py:meth:`.Configuration.getvar` and -:py:meth:`.Configuration.getvar_s`. - -Both methods also perform :ref:`variable-interpolation` and handle -:ref:`variable-namespaces`. Filtering is not supported. So -- the -variable name arguments of :py:meth:`.Configuration.getvar` and -:py:meth:`.Configuration.getvar_s` are of the form -``[namespace:]variable``. - - -.. _comments: - -Comments --------- - -By default all keys beginning with ``__comment`` or ``__doc`` are -filtered out and not given to the application. This allows comments in -JSON files -- but is not restricted to JSON files only. - -For all types of configuration files their respective standard comments -are allowed too. - - -.. _variable-namespaces: - -Variable Namespaces -------------------- - -Currently there are 4 namespaces: - -1. The unnamed namespace (which is also default). - - All the configuration variables are part of this namespace. - -2. The namespace ``OS`` - - Available functions: - - ``cwd`` - Contains the current working directory of the process - -3. The namespace ``ENV`` - - This namespace contains all the environment variables as they are - available from :py:data:`os.environ`. - -4. The namespace ``PY`` - - Contains selected values from the running Python: - - ``version`` - The return value of :py:func:`platform.python_version` - - ``version_maj_min`` - Just the major and minor version of the running Python - (``.`` separated) - - ``version_maj`` - Just the major version of the running Python - - ``implementation`` - The return value of :py:func:`platform.python_implementation` - - -Examples -~~~~~~~~ - -:: - - config.getvar("OS:cwd") - -yields the current working directory as :py:func:`os.getcwd` does. - - -.. _variable-interpolation: - -Variable Interpolation ----------------------- - -Configuration variable values that are read with -:py:meth:`.Configuration.getvar_s` are subject to variable -interpolation. The general syntactic pattern for this is:: - - {{[namespace:]variable[|filter[|filter...]]}} - -I.e.: between double curly braces an optional `namespace` name followed by -a colon ``:``, the `variable` and then zero or more filters, each one -introduced by a pipe symbol ``|``. - -Variables are expanded *lately* at runtime -- exactly when calling -:py:meth:`.Configuration.getvar_s`, -:py:meth:`.Configuration.substitute_variables_in_obj` or -:py:meth:`.Configuration.expand_variable` - - -Filter functions -~~~~~~~~~~~~~~~~ - -Interpolated values can be processed through a series of filter functions:: - - {{my.variable|filter1|filter2}} - -Available filter functions are: - - ``urlquote`` - - ``saslprep`` - - ``normpath`` - - ``abspath`` - - ``posixpath`` - - ``lower`` - - ``upper`` - - -Examples -~~~~~~~~ - -:: - - {{OS:cwd|posixpath}} - -expands to the current working directory as POSIX path: on Windows all -backslashes are replaced by forward slashes. - -:: - - {{ENV:PATH}} - -expands to the current search path from the process environment. - -:: - - {{PY:version}} - -expands to the current running Python version (e.g. ``3.6.4``). - -:: - - {{PY::implementation|upper}} - -expands to something like ``CPYTHON`` when using the standard Python -interpreter written in C. - - -Custom filename extensions and custom loaders ---------------------------------------------- - -If you want to have custom configuration file extensions and/or custom loaders -for custom configuration files you have various possibilities: - - Associate an additional new extension (e.g. ".conf") with an - existing configuration file style (e.g. YAML):: - - configmix.set_assoc("*.conf", configmix.get_assoc("*.yml")) - - Allow only files with extension ".cfg" in INI-style -- using the default - loader for INI-files:: - - configmix.clear_assoc() - configmix.set_assoc("*.cfg", configmix.get_default_assoc("*.ini")) - - Only a new configuration file style:: - - def my_custom_loader(filename): - ... - return some_dict_alike - - configmix.mode_loaders["myconfmode"] = my_custom_loader - configmix.clear_assoc() - configmix.set_assoc("*.my.configuration", "myconfmode") - - If :py:func:`~configmix.clear_assoc` will not be called then just a *new* - configuration file style will be installed. - - To select the loader not by extension but by an Emacs-compatible mode - declaration (e.g. ``mode: yaml``) in the first two lines of a file use:: - - configmix.set_assoc("*", configmix.try_determine_filemode)
--- a/doc/license.rst Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,11 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _license: - -License -======= - -The license is the 3-clause BSD license. - -.. literalinclude:: ../LICENSE.txt - :language: none
--- a/doc/make.bat Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build -set SPHINXPROJ=ConfigMix - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd
--- a/doc/readme.rst Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,7 +0,0 @@ -.. -*- coding: utf-8 -*- - -======== - README -======== - -.. include:: ../README.txt
--- a/doc/todo.rst Wed May 08 09:17:55 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _TODOINDEX: - -TODO List -========= - -.. ifconfig:: not todo_include_todos - - The list is not printed. Therefore this page is left blank - intentionally. - -.. todolist::
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/Makefile Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = ConfigMix +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/apidoc.rst Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,78 @@ +.. -*- coding: utf-8 -*- + +Package API Documentation +========================= + +.. contents:: + :local: + +Package :mod:`configmix` +------------------------ + +.. automodule:: configmix + :members: + :ignore-module-all: + + +Module :mod:`configmix.compat` +------------------------------ + +.. automodule:: configmix.compat + :members: + :undoc-members: + + +Module :mod:`configmix.config` +------------------------------ + +.. automodule:: configmix.config + :members: + :ignore-module-all: + + +Module :mod:`configmix.ini` +--------------------------- + +.. automodule:: configmix.ini + :members: + :ignore-module-all: + + +Module :mod:`configmix.json` +---------------------------- + +.. automodule:: configmix.json + :members: + :ignore-module-all: + + +Module :mod:`configmix.py` +-------------------------- + +.. automodule:: configmix.py + :members: + :ignore-module-all: + + +Module :mod:`configmix.toml` +---------------------------- + +.. automodule:: configmix.toml + :members: + :ignore-module-all: + + +Module :mod:`configmix.variables` +--------------------------------- + +.. automodule:: configmix.variables + :members: + :ignore-module-all: + + +Module :mod:`configmix.yaml` +---------------------------- + +.. automodule:: configmix.yaml + :members: + :ignore-module-all:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/authors.rst Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,8 @@ +.. -*- coding: utf-8 -*- + +.. _authors: + +Authors +======= + +.. include:: ../AUTHORS.txt
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/changes.rst Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,60 @@ +.. -*- coding: utf-8; mode: rst; -*- + +========= + Changes +========= + +All major changes over the versions are listed here. For breaking +changes have a look at :ref:`api-changes`, they are listed there in +detail. + +.. include:: ../CHANGES.txt + + +.. _api-changes: + +Breaking Changes +================ + +0.7 +--- + +- A major overhaul of how filename extensions are associated with loaders + has been done: + + + Filename extensions in :mod:`fnmatch` style are associated with + file-mode strings. + + These file-mode strings are associated with loader + functions separately via the mapping :py:data:`configmix.mode_loaders`. + + + :py:func:`configmix.set_assoc`, :py:func:`configmix.get_assoc`, + :py:func:`configmix.clear_assoc` and + :py:func:`configmix.get_default_assoc` are the new names for the old + `set_loader()`, `get_loader()`, `clear_loader()` and + `get_default_loader()` functions. + They are used for associating :mod:`fnmatch` style filename patterns + to file-mode strings. Previously they associated loader functions + directly. + + + :py:func:`configmix.set_assoc` now requires a :mod:`fnmatch` style + pattern instead of just a file extension string (i.e. a plain trailer). + The previons dictionary with mapping from filename extensions to loader + callables is now a list of tuples containing the :mod:`fnmatch` style + pattern and the corresponding loader callable. + + +0.6 +--- + +- :py:func:`configmix.safe_merge` does now a deepcopy of all source + configurations when merging. Changes in configuration instances + afterwards will not be reflected in the merged configuration any + more. + + The public signature of :py:func:`configmix.safe_merge` has *not* + changed. + +- The default file encoding when reading INI style files with + :py:func:`configmix.ini.load` is now "UTF-8". Previously it was undefined + and therefore dependent on the user's locale.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/conf.py Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,237 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/stable/config + +# -- Path setup -------------------------------------------------------------- + +# 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. +# +import datetime +import os +import sys +sys.path.insert(0, os.path.dirname(os.path.abspath('.'))) + +import configmix +from configmix.compat import u + + +# -- Project information ----------------------------------------------------- + +project = 'ConfigMix' +copyright = u('2015–2019, Franz Glasner. All rights reserved') +author = 'Franz Glasner' + +# The short X.Y version +version = '.'.join(configmix.__version__.split('.')[:2]) +# The full version, including alpha/beta/rc tags +release = configmix.__version__ +release_date = configmix.__date__ + +today = datetime.date.today().isoformat() + + +# -- 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.todo', + 'sphinx.ext.ifconfig', +# 'sphinx.ext.viewcode', + 'changelog', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- 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 = 'alabaster' +html_theme = 'haiku' +# for the Haiku title +html_short_title = u("%s %s") % (project, release) +html_last_updated_fmt = "%s (rev %s)" % (today, configmix.__revision__) + +# 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 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + +html_show_sourcelink = False + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ConfigMixdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + 'papersize': 'a4paper', + + # The font size ('10pt', '11pt' or '12pt'). + # + 'pointsize': '11pt', + + # Additional stuff for the LaTeX preamble. + # + # NOTE: "inconsolata" in "fontpkg" errors within pdfTeX: seems to be + # incompatible with some header package. + # + 'preamble': r''' + \usepackage{inconsolata} + ''', + + 'fontpkg': r''' + \usepackage{charter} + \usepackage[defaultsans]{lato} + ''', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', + # Use "Version" instead of "Release" on the title + 'releasename': 'Version', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'ConfigMix.tex', '"ConfigMix" Documentation', + 'Franz Glasner', 'manual', True), +] + +latex_show_urls = 'footnote' +#latex_show_pagerefs = True + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'configmix', '"ConfigMix" Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'ConfigMix', '"ConfigMix" Documentation', + author, 'ConfigMix', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True +# Kein Link auf Pfad und Zeile +todo_link_only = True + +# -- Options for autodoc ----------------------------------------------------- + +autodoc_member_order = 'bysource' +autoclass_content = 'both' + + +# -- Options for changelog --------------------------------------------------- + +changelog_inner_tag_sort = ['breaking', 'feature', 'bugfix', 'misc', + 'test', 'doc'] + + +def setup(app): + # + # Custom release_date variable with a custom substitution |release_date| + # + app.add_config_value('release_date', '', 'env') + + import sphinx.transforms + + class IAMCustomSubstitutions(sphinx.transforms.SphinxTransform): + + default_priority = sphinx.transforms.DefaultSubstitutions.default_priority + def apply(self): + from docutils import nodes + for ref in self.document.traverse(nodes.substitution_reference): + refname = ref['refname'] + if refname == 'release_date': + stext = self.config[refname] + ref.replace_self(nodes.Text(stext, stext)) + + app.add_transform(IAMCustomSubstitutions)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/index.rst Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,44 @@ +.. -*- coding: utf-8 -*- + +.. ConfigMix documentation master file, created by + sphinx-quickstart on Tue Feb 27 22:03:52 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +=========== + ConfigMix +=========== + +This is the documentation of the :mod:`configmix` package, a +library for helping with configuration files. + +.. toctree:: + :maxdepth: 3 + + readme + introduction + apidoc + changes + authors + license + +.. toctree:: + :hidden: + + todo + + +Indices and tables +================== + +.. only:: builder_html + + * :ref:`TODOINDEX` + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` + +.. only:: not builder_html + + * :ref:`TODOINDEX` + * :ref:`modindex`
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/introduction.rst Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,402 @@ +.. -*- coding: utf-8; indent-tabs-mode: nil; -*- + +.. _introduction: + +Introduction +============ + +.. contents:: + :local: + +The configurations can be read from different types of files: + +- :ref:`YAML files <yaml-files>` +- :ref:`JSON files <json-files>` +- :ref:`INI files <ini-files>` +- :ref:`TOML files <toml-files>` +- :ref:`executable Python scripts <executable-python-scripts>` + + +.. _yaml-files: + +YAML Files +---------- + +Need the :mod:`yaml` package (https://github.com/yaml/pyyaml) +(e.g. ``pip install pyyaml``) + +.. note:: All strings are returned as Unicode text strings. + +.. note:: The root object must be a *mapping* and therefore decode + into a Python :class:`dict` alike. This is checked by the + implementation. + +An example is: + +.. literalinclude:: ../tests/data/conf10.yml + :language: yaml + + +.. _json-files: + +JSON files +---------- + +Read the JSON file with the help of Python's native :mod:`json` package. + +.. note:: All strings are returned as Unicode text strings. + +.. note:: The root object must be an *object* and therefore decode + into a Python :class:`dict` alike. This is checked by the + implementation. + +An example is: + +.. literalinclude:: ../tests/data/conf10.json + :language: js + +For comments in JSON files see section :ref:`comments`. + + +.. _ini-files: + +INI Files +--------- + +Read the file and all sections named in parameter `extract` are flattened +into the resulting dictionary. By default the section named ``config`` is +used. + +Normally all values are returned as Unicode text strings. +But values can be annotated and therefore interpreted as other types: + + ``:int:`` + The value is handled in the same way as a Python :class:`int` + literal + + ``:float:`` + The value is interpreted as :class:`float` + + ``:bool:`` + The resulting value is a :class:`bool` where + + ``1``, ``true``, ``yes``, ``on`` + yield a Python ``True`` + + ``0``, ``false``, ``no``, ``off`` + yield a Python ``False`` + + The evaluation is done *case-insensitively*. + +.. note:: All strings are returned as Unicode text strings. + +.. note:: Contrary to the behaviour of the standard Python :mod:`configparser` + module the INI file reader is *case-sensitive*. + +The example INI style configuration below yields an equivalent +configuration to the YAML configuration above: + +.. literalinclude:: ../tests/data/conf10.ini + :language: ini + +As can be seen in this example -- INI file internal value interpolation +is done as in Python's standard :mod:`configparser` module. + +This example also illustrates how INI sections are used to build a +tree-ish configuration dictionary. + + +.. _toml-files: + +TOML Files +---------- + +Read the TOML file with the help of the pure Python :mod:`toml` +package (https://github.com/uiri/toml) (e.g. ``pip install toml``). + +All TOML features map seamingless to "ConfigMix". + +The example TOML style configuration below yields an equivalent +configuration to the YAML configuration above: + + +.. literalinclude:: ../tests/data/conf10.toml + :language: ini + + +.. _executable-python-scripts: + +Executable Python Scripts +------------------------- + +What will be exported: + +1. If loading is done with the `extract` parameter only the given keys are + extracted from the script. + +2. Otherwise it is checked if the scripts defines an ``__all__`` + sequence. If there is one it's contents are the keys to be + extracted. + +3. If there is no ``__all__`` object all names not starting with an + underscore ``_`` are found. + +This is analogous to as Python modules behave when importing them with +``from module import *``. + +.. note:: The Python configuration files are evaluated with ``exec`` and not + imported. + +The example configuration by Python script below yields an equivalent +configuration to the YAML configuration above: + +.. literalinclude:: ../tests/data/conf10.py + :language: python + + +.. _loading-and-merging: + +Loading and Merging +------------------- + +Basic usage of the API is as follows in this example:: + + import configmix + + # + # Note: With conf10 merging is rather pointless because the tree + # files # are really the same configuration. But is doesn't harm + # also here. + # + config = configmix.load("conf10.yml", "conf10.ini", "conf10.py") + + # Get a -- possibly interpolated -- configuration variable's value + value1 = config.getvar_s("key1") + + # Get a -- possibly interpolated -- variable from within the tree + value2 = config.getvar_s("tree1.tree2.key4") + + +By default filenames of the configuration files must have the extensions +(case-sensitivety depends on your OS): + + ``.ini`` + for INI configuration files + + ``.json`` + for JSON configuration files + + ``.py`` + for Python configuration files + + ``.toml`` + for TOML configuration file + + ``.yml`` or ``.yaml`` + for YAML configuration files + + +.. _getting-values: + +Getting configuration variables +------------------------------- + +Get a -- possibly interpolated -- configuration variable's value with:: + + value1 = config.getvar_s("key1") + +Get a raw configuration variable's value with:: + + value1_raw = config.getvar("key1") + +Because the configuration is not only a plain list of but a tree of +key-value pairs you will want to fetch them by separating the individual +level keys with a point ``.``. + +Looking at the example in chapter :ref:`yaml-files` -- when calling +``config.getvar_s("tree1.tree2.key4")`` you will get the value +``get this as `tree1.tree2.key4'``. + +This is true for both methods :py:meth:`.Configuration.getvar` and +:py:meth:`.Configuration.getvar_s`. + +Both methods also perform :ref:`variable-interpolation` and handle +:ref:`variable-namespaces`. Filtering is not supported. So -- the +variable name arguments of :py:meth:`.Configuration.getvar` and +:py:meth:`.Configuration.getvar_s` are of the form +``[namespace:]variable``. + + +.. _comments: + +Comments +-------- + +By default all keys beginning with ``__comment`` or ``__doc`` are +filtered out and not given to the application. This allows comments in +JSON files -- but is not restricted to JSON files only. + +For all types of configuration files their respective standard comments +are allowed too. + + +.. _variable-namespaces: + +Variable Namespaces +------------------- + +Currently there are 4 namespaces: + +1. The unnamed namespace (which is also default). + + All the configuration variables are part of this namespace. + +2. The namespace ``OS`` + + Available functions: + + ``cwd`` + Contains the current working directory of the process + +3. The namespace ``ENV`` + + This namespace contains all the environment variables as they are + available from :py:data:`os.environ`. + +4. The namespace ``PY`` + + Contains selected values from the running Python: + + ``version`` + The return value of :py:func:`platform.python_version` + + ``version_maj_min`` + Just the major and minor version of the running Python + (``.`` separated) + + ``version_maj`` + Just the major version of the running Python + + ``implementation`` + The return value of :py:func:`platform.python_implementation` + + +Examples +~~~~~~~~ + +:: + + config.getvar("OS:cwd") + +yields the current working directory as :py:func:`os.getcwd` does. + + +.. _variable-interpolation: + +Variable Interpolation +---------------------- + +Configuration variable values that are read with +:py:meth:`.Configuration.getvar_s` are subject to variable +interpolation. The general syntactic pattern for this is:: + + {{[namespace:]variable[|filter[|filter...]]}} + +I.e.: between double curly braces an optional `namespace` name followed by +a colon ``:``, the `variable` and then zero or more filters, each one +introduced by a pipe symbol ``|``. + +Variables are expanded *lately* at runtime -- exactly when calling +:py:meth:`.Configuration.getvar_s`, +:py:meth:`.Configuration.substitute_variables_in_obj` or +:py:meth:`.Configuration.expand_variable` + + +Filter functions +~~~~~~~~~~~~~~~~ + +Interpolated values can be processed through a series of filter functions:: + + {{my.variable|filter1|filter2}} + +Available filter functions are: + + ``urlquote`` + + ``saslprep`` + + ``normpath`` + + ``abspath`` + + ``posixpath`` + + ``lower`` + + ``upper`` + + +Examples +~~~~~~~~ + +:: + + {{OS:cwd|posixpath}} + +expands to the current working directory as POSIX path: on Windows all +backslashes are replaced by forward slashes. + +:: + + {{ENV:PATH}} + +expands to the current search path from the process environment. + +:: + + {{PY:version}} + +expands to the current running Python version (e.g. ``3.6.4``). + +:: + + {{PY::implementation|upper}} + +expands to something like ``CPYTHON`` when using the standard Python +interpreter written in C. + + +Custom filename extensions and custom loaders +--------------------------------------------- + +If you want to have custom configuration file extensions and/or custom loaders +for custom configuration files you have various possibilities: + + Associate an additional new extension (e.g. ".conf") with an + existing configuration file style (e.g. YAML):: + + configmix.set_assoc("*.conf", configmix.get_assoc("*.yml")) + + Allow only files with extension ".cfg" in INI-style -- using the default + loader for INI-files:: + + configmix.clear_assoc() + configmix.set_assoc("*.cfg", configmix.get_default_assoc("*.ini")) + + Only a new configuration file style:: + + def my_custom_loader(filename): + ... + return some_dict_alike + + configmix.mode_loaders["myconfmode"] = my_custom_loader + configmix.clear_assoc() + configmix.set_assoc("*.my.configuration", "myconfmode") + + If :py:func:`~configmix.clear_assoc` will not be called then just a *new* + configuration file style will be installed. + + To select the loader not by extension but by an Emacs-compatible mode + declaration (e.g. ``mode: yaml``) in the first two lines of a file use:: + + configmix.set_assoc("*", configmix.try_determine_filemode)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/license.rst Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,11 @@ +.. -*- coding: utf-8 -*- + +.. _license: + +License +======= + +The license is the 3-clause BSD license. + +.. literalinclude:: ../LICENSE.txt + :language: none
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/make.bat Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=ConfigMix + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/readme.rst Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,7 @@ +.. -*- coding: utf-8 -*- + +======== + README +======== + +.. include:: ../README.txt
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/todo.rst Wed May 08 09:23:37 2019 +0200 @@ -0,0 +1,13 @@ +.. -*- coding: utf-8 -*- + +.. _TODOINDEX: + +TODO List +========= + +.. ifconfig:: not todo_include_todos + + The list is not printed. Therefore this page is left blank + intentionally. + +.. todolist::