diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 7ea4bae..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,153 +0,0 @@ -# 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) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where 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 " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @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/tiramisu.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/tiramisu.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/tiramisu" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/tiramisu" - @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." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -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." diff --git a/doc/_templates/module.rst b/doc/_templates/module.rst deleted file mode 100644 index d0127bc..0000000 --- a/doc/_templates/module.rst +++ /dev/null @@ -1,6 +0,0 @@ -{{ fullname }} -{{ underline }} - -.. automodule:: {{ fullname }} - :members: - :noindex: diff --git a/doc/api.txt b/doc/api.txt deleted file mode 100644 index 7fb526f..0000000 --- a/doc/api.txt +++ /dev/null @@ -1,15 +0,0 @@ -Auto generated library's API -================================ - -.. autosummary:: - :toctree: api - :template: module.rst - - tiramisu.option - tiramisu.setting - tiramisu.config - tiramisu.value - tiramisu.autolib - tiramisu.error - tiramisu.storage - diff --git a/doc/api/tiramisu.autolib.txt b/doc/api/tiramisu.autolib.txt deleted file mode 100644 index 6cac1fb..0000000 --- a/doc/api/tiramisu.autolib.txt +++ /dev/null @@ -1,6 +0,0 @@ -tiramisu.autolib -================ - -.. automodule:: tiramisu.autolib - :members: - :noindex: \ No newline at end of file diff --git a/doc/api/tiramisu.config.txt b/doc/api/tiramisu.config.txt deleted file mode 100644 index e212fb9..0000000 --- a/doc/api/tiramisu.config.txt +++ /dev/null @@ -1,6 +0,0 @@ -tiramisu.config -=============== - -.. automodule:: tiramisu.config - :members: - :noindex: \ No newline at end of file diff --git a/doc/api/tiramisu.error.txt b/doc/api/tiramisu.error.txt deleted file mode 100644 index ce8ce5a..0000000 --- a/doc/api/tiramisu.error.txt +++ /dev/null @@ -1,6 +0,0 @@ -tiramisu.error -============== - -.. automodule:: tiramisu.error - :members: - :noindex: \ No newline at end of file diff --git a/doc/api/tiramisu.option.txt b/doc/api/tiramisu.option.txt deleted file mode 100644 index 50e000d..0000000 --- a/doc/api/tiramisu.option.txt +++ /dev/null @@ -1,6 +0,0 @@ -tiramisu.option -=============== - -.. automodule:: tiramisu.option - :members: - :noindex: \ No newline at end of file diff --git a/doc/api/tiramisu.setting.txt b/doc/api/tiramisu.setting.txt deleted file mode 100644 index 259455f..0000000 --- a/doc/api/tiramisu.setting.txt +++ /dev/null @@ -1,5 +0,0 @@ -tiramisu.setting -================ - -.. automodule:: tiramisu.setting - :members: diff --git a/doc/api/tiramisu.storage.txt b/doc/api/tiramisu.storage.txt deleted file mode 100644 index 86cb062..0000000 --- a/doc/api/tiramisu.storage.txt +++ /dev/null @@ -1,6 +0,0 @@ -tiramisu.storage -================ - -.. automodule:: tiramisu.storage - :members: - :noindex: \ No newline at end of file diff --git a/doc/api/tiramisu.value.txt b/doc/api/tiramisu.value.txt deleted file mode 100644 index 64f247c..0000000 --- a/doc/api/tiramisu.value.txt +++ /dev/null @@ -1,5 +0,0 @@ -tiramisu.value -============== - -.. automodule:: tiramisu.value - :members: diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index 3a0147d..0000000 --- a/doc/conf.py +++ /dev/null @@ -1,295 +0,0 @@ -# -*- coding: utf-8 -*- -# -# tiramisu documentation build configuration file, created by -# sphinx-quickstart on Tue Nov 20 14:29:31 2012. -# -# 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.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sphinx.ext.autosummary', 'sphinx.ext.extlinks'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.txt' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'tiramisu' -copyright = u'2013, tiramisu team' - -# 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 = '1' -# The full version, including alpha/beta/rc tags. -release = '1.0' - -# 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 = 'traditional' - -# 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 -# " v 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 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 = 'tiramisudoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'tiramisu.tex', u'tiramisu Documentation', - u'gwen', '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 - -# 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', 'tiramisu', u'tiramisu Documentation', - [u'gwen'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- 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 = [ - ('index', 'tiramisu', u'tiramisu Documentation', - u'gwen', 'tiramisu', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - - -# -- Options for Epub output --------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = u'tiramisu' -epub_author = u'gwen' -epub_publisher = u'gwen' -epub_copyright = u'2012, gwen' - -# The language of the text. It defaults to the language option -# or en if the language is not set. -#epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -#epub_identifier = '' - -# A unique identification for the text. -#epub_uid = '' - -# A tuple containing the cover image and cover page html template filenames. -#epub_cover = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files shat should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] - -# A list of files that should not be packed into the epub file. -#epub_exclude_files = [] - -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 - -# Allow duplicate toc entries. -#epub_tocdup = True - -todo_include_todos = True - -extlinks = {'api': ('./api/tiramisu.%s', ""), - 'test': ('./api/test.%s', "")} - - -autosummary_generate = True - - diff --git a/doc/config.png b/doc/config.png deleted file mode 100644 index a468275..0000000 Binary files a/doc/config.png and /dev/null differ diff --git a/doc/config.svg b/doc/config.svg deleted file mode 100644 index 3ff4bc9..0000000 --- a/doc/config.svg +++ /dev/null @@ -1,257 +0,0 @@ - - - - - - - - - - - - image/svg+xml - - - - - - - - Config - - - - - OptionDescription - - - - Option - - - - Option - - - - OptionDescription - - - - Option - - - - - - - - diff --git a/doc/config.txt b/doc/config.txt deleted file mode 100644 index f1ab1ce..0000000 --- a/doc/config.txt +++ /dev/null @@ -1,570 +0,0 @@ -.. default-role:: literal - -=============================== -Options handling basics -=============================== - -Tiramisu is made of almost three main objects : - -- :class:`tiramisu.option.Option` stands for the option types -- :class:`tiramisu.option.OptionDescription` is the shema, the option's structure -- :class:`tiramisu.config.Config` which is the whole configuration entry point - -Accessing the `Option`'s -------------------------- - -The :class:`~tiramisu.config.Config` object attribute access notation stands for -the value of the configuration's :class:`~tiramisu.option.Option`. -:class:`~tiramisu.config.Config`'s object attribute is the name of the option, -and the value is the value accessed by the `__getattr__` attribute access -mechanism. - -If the attribute of the `Config` called by `__getattr__` has not been set before -(by the classic `__setattr__` mechanism), the default value of the `Option` -object is returned, and if no `Option` has been declared in the -`OptionDescription` (that is the schema of the configuration), an -`AttributeError` is raised. - -:: - - >>> from tiramisu.config import Config - >>> from tiramisu.option import BoolOption, OptionDescription - >>> - >>> gcdummy = BoolOption('dummy', 'dummy', default=False) - >>> gcdummy.impl_getdefault() - False - >>> cfg.dummy - False - >>> descr = OptionDescription('tiramisu', '', [gcdummy]) - >>> cfg = Config(descr) - >>> cfg.dummy = True - >>> cfg.dummy - True - >>> cfg.idontexist - AttributeError: 'OptionDescription' object has no attribute 'idontexist' - -The `Option` objects (in this case the :class:`~tiramisu.option.BoolOption`), -are organized into a tree into nested -:class:`~tiramisu.option.OptionDescription` objects. - -.. image:: config.png - -Every option has a name, as does every option group. The parts -of the full name of the option are separated by dots: e.g. -``cfg.optgroup.optname``. - -Let's make the protocol of accessing a `Config`'s attribute explicit -(because explicit is better than implicit): - -1. If the option has not been declared, an `AttributeError` is raised, - -2. If an option is declared, but neither a value nor a default value has - been set, the returned value is `None`, - -3. If an option is declared and a default value has been set, but no value - has been set, the returned value is the default value of the option, - -4. If an option is declared, and a value has been set, the returned value is - the value of the option. - -But there are special exceptions. We will see later on that an option can be a -:term:`mandatory option`. A mandatory option is an option that must have a value -defined. - -Setting the value of an option ------------------------------- - -An important part of the setting's configuration consists of setting the -value's option. There are different ways of setting values, -the first one is of course the `__setattr__` method - -:: - - cfg.name = value - -And if you wanna come back to a default value, use the builtin `del()` function:: - - del(cfg.name) - -.. module:: tiramisu.config - -.. _`tree`: - -The handling of options -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The handling of options is split into two parts: the description of -which options are available, what their possible values and defaults are -and how they are organized into a tree. A specific choice of options is -bundled into a configuration object which has a reference to its option -description (and therefore makes sure that the configuration values -adhere to the option description). - -Common manipulations ------------------------- - -Let's perform some common manipulation on some options - ->>> from tiramisu.config import Config ->>> from tiramisu.option import UnicodeOption, OptionDescription ->>> # ->>> var1 = UnicodeOption('var1', 'first variable') ->>> var2 = UnicodeOption('var2', '', u'value') ->>> # ->>> od1 = OptionDescription('od1', 'first OD', [var1, var2]) ->>> rootod = OptionDescription('rootod', '', [od1]) - -let's set somme access rules on the main namespace - ->>> c = Config(rootod) ->>> c.read_write() - -let's travel the namespaces - ->>> print c -[od1] ->>> print c.od1 -var1 = None -var2 = value ->>> print c.od1.var1 -None ->>> print c.od1.var2 -value - -let's modify a value (be careful to the value's type...) - ->>> c.od1.var1 = 'value' -Traceback (most recent call last): -ValueError: invalid value value for option var1 ->>> c.od1.var1 = u'value' ->>> print c.od1.var1 -value ->>> c.od1.var2 = u'value2' ->>> print c.od1.var2 -value2 - -let's come back to the default value - ->>> del(c.od1.var2) ->>> print c.od1.var2 -value - -The value is saved in a :class:`~tiramisu.value.Value` object. It is on this -object that we have to trigger the `reset`, which take the option itself -(`var2`) as a parameter. - -On the other side, in the `read_only` mode, it is not possible to modify the value - ->>> c.read_only() ->>> c.od1.var2 = u'value2' -Traceback (most recent call last): -tiramisu.error.PropertiesOptionError: cannot change the value for option var2 this option is frozen - - -let's retrieve the option `var1` description - ->>> var1.impl_get_information('doc') -'first variable' - -And if the option has been lost, it is possible to retrieve it again: - ->>> c.unwrap_from_path('od1.var1').impl_get_information('doc') -'first variable' - -Searching for an option -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In an application, knowing the path of an option is not always feasible. -That's why a tree of options can easily be searched. First, let's build such a tree:: - ->>> var1 = UnicodeOption('var1', '') ->>> var2 = UnicodeOption('var2', '') ->>> var3 = UnicodeOption('var3', '') ->>> od1 = OptionDescription('od1', '', [var1, var2, var3]) ->>> var4 = UnicodeOption('var4', '') ->>> var5 = UnicodeOption('var5', '') ->>> var6 = UnicodeOption('var6', '') ->>> var7 = UnicodeOption('var1', '', u'value') ->>> od2 = OptionDescription('od2', '', [var4, var5, var6, var7]) ->>> rootod = OptionDescription('rootod', '', [od1, od2]) ->>> c = Config(rootod) ->>> c.read_write() - -Second, let's find an option by it's name:: - - >>> print c.find(byname='var1') - [, - ] - -If the option name is unique, the search can be stopped once one matched option -has been found: - - >>> print c.find_first(byname='var1') - - -Instead of the option's object, the value or path can be retrieved: - - >>> print c.find(byname='var1', type_='value') - [None, u'value'] - >>> print c.find(byname='var1', type_='path') - ['od1.var1', 'od2.var1'] - -Finaly, a search can be performed on the values, the type or even a combination -of all these criteria: - - - >>> print c.find(byvalue=u'value', type_='path') - ['od2.var1'] - >>> print c.find(bytype=UnicodeOption, type_='path') - ['od1.var1', 'od1.var2', 'od1.var3', 'od2.var4', 'od2.var5', 'od2.var6', 'od2.var1'] - >>> print c.find(byvalue=u'value', byname='var1', bytype=UnicodeOption, type_='path') - ['od2.var1'] - -The search can be performed in a subtree: - ->>> print c.od1.find(byname='var1', type_='path') -['od1.var1'] - -In a root tree or in a subtree, all option can be retrieved in a dict container: - - >>> print c.make_dict() - {'od2.var4': None, 'od2.var5': None, 'od2.var6': None, 'od2.var1': u'value', - 'od1.var1': None, 'od1.var3': None, 'od1.var2': None} - -If the organisation in a tree is not important, -:meth:`~config.SubConfig.make_dict()` results can be flattened - ->>> print c.make_dict(flatten=True) -{'var5': None, 'var4': None, 'var6': None, 'var1': u'value', 'var3': None, -'var2': None} - -.. note:: be carefull with this `flatten` parameter, here we have just lost - two options named `var1` - -One can export only interesting parts of a tree of options into a dict, for -example the options that are in the same group that a given `var1` option:: - - >>> print c.make_dict(withoption='var1') - {'od2.var4': None, 'od2.var5': None, 'od2.var6': None, 'od2.var1': u'value', - 'od1.var1': None, 'od1.var3': None, 'od1.var2': None} - >>> print c.make_dict(withoption='var1', withvalue=u'value') - {'od2.var4': None, 'od2.var5': None, 'od2.var6': None, 'od2.var1': u'value'} - -and of course, :meth:`~config.SubConfig.make_dict()` can be called in a subtree: - ->>> print c.od1.make_dict(withoption='var1') -{'var1': None, 'var3': None, 'var2': None} - -The owners -~~~~~~~~~~~ - -.. glossary:: - - owner - - When a value is set on an option, an owner is set too, that's why one can know - at any time if a value is a default value or not. Let's create a tree:: - - >>> var1 = UnicodeOption('var1', '', u'oui') - >>> od1 = OptionDescription('od1', '', [var1]) - >>> rootod = OptionDescription('rootod', '', [od1]) - >>> c = Config(rootod) - >>> c.read_write() - -Then let's retrieve the owner associated to an option:: - - >>> print c.getowner(var1) - default - >>> c.od1.var1 = u'no' - >>> print c.getowner(var1) - user - >>> del(c.var1) - >>> print c.getowner(var1) - default - -You can create your own owner, for example to distinguish modification made by -one user to an other one's. - - >>> from tiramisu.setting import owners - >>> owners.addowner('toto') - >>> c.cfgimpl_get_settings().setowner(owners.toto) - >>> print c.getowner(var1) - default - >>> c.od1.var1 = u'no' - >>> print c.getowner(var1) - toto - -The properties -~~~~~~~~~~~~~~ - -A property is an information on an option's state. -Let's create options with properties:: - - >>> var1 = UnicodeOption('var1', '', u'value', properties=('hidden',)) - >>> var2 = UnicodeOption('var2', '', properties=('mandatory',)) - >>> var3 = UnicodeOption('var3', '', u'value', properties=('frozen', 'unknown')) - >>> var4 = UnicodeOption('var4', '', u'value') - >>> od1 = OptionDescription('od1', '', [var1, var2, var3]) - >>> od2 = OptionDescription('od2', '', [var4], properties=('hidden',)) - >>> rootod = OptionDescription('rootod', '', [od1, od2]) - >>> c = Config(rootod) - >>> c.read_write() - -A hidden value is a value that cannot be accessed in read/write mode. This -option cannot be modified any more. Let's try to access to an option's value -with a hidden option:: - - >>> print c.od1.var1 - Traceback (most recent call last): - tiramisu.error.PropertiesOptionError: trying to access to an option named: var1 - with properties ['hidden'] - >>> c.read_only() - >>> print c.od1.var1 - value - -A mandatory option is an option with a value that shall not be `None`. The -value has to be defined. Accessing to such an option is easy in read/write -mode. But in read only mode, an error is raised if no value has been defined:: - - >>> c.read_write() - >>> print c.od1.var2 - None - >>> c.read_only() - >>> print c.od1.var2 - Traceback (most recent call last): - tiramisu.error.PropertiesOptionError: trying to access to an option named: var2 - with properties ['mandatory'] - >>> c.read_write() - >>> c.od1.var2 = u'value' - >>> c.read_only() - >>> print c.od1.var2 - value - -A frozen option, is an option that cannot be modified by a user. -Let's try to modify a frozen option:: - - >>> c.read_write() - >>> print c.od1.var3 - value - >>> c.od1.var3 = u'value2' - Traceback (most recent call last): - tiramisu.error.PropertiesOptionError: cannot change the value for option var3 this option is frozen - >>> c.read_only() - >>> print c.od1.var3 - value - -Tiramisu allows us to use user defined properties. Let's define and use one in -read/write or read only mode:: - - >>> c.cfgimpl_get_settings().append('unknown') - >>> print c.od1.var3 - Traceback (most recent call last): - tiramisu.error.PropertiesOptionError: trying to access to an option named: - var3 with properties ['unknown'] - >>> c.cfgimpl_get_settings().remove('unknown') - >>> print c.od1.var3 - value - -Many properties can be defined at the same time on an option:: - - >>> c.cfgimpl_get_settings().extend(['unknown1', 'unknown2']) - -Properties can also be defined on an option group (that is, on an -:term:`option description`) let's hide a group and try to access to it:: - - >>> c.read_write() - >>> print c.od2.var4 - Traceback (most recent call last): - tiramisu.error.PropertiesOptionError: trying to access to an option named: od2 - with properties ['hidden'] - >>> c.read_only() - >>> print c.od2.var4 - value - -Furthermore, let's retrieve the properties, delete and add the `hidden` property:: - - >>> c.read_write() - >>> c.cfgimpl_get_settings()[rootod.od1.var1] - ['hidden'] - >>> print c.od1.var1 - Traceback (most recent call last): - tiramisu.error.PropertiesOptionError: trying to access to an option named: - var1 with properties ['hidden'] - >>> c.cfgimpl_get_settings()[rootod.od1.var1].remove('hidden') - >>> c.cfgimpl_get_settings()[rootod.od1.var1] - [] - >>> print c.od1.var1 - value - >>> c.cfgimpl_get_settings()[rootod.od1.var1].append('hidden') - >>> c.cfgimpl_get_settings()[rootod.od1.var1] - ['hidden'] - >>> print c.od1.var1 - Traceback (most recent call last): - tiramisu.error.PropertiesOptionError: trying to access to an option named: - var1 with properties ['hidden'] - - -.. _multi-option: - -The multi-options -~~~~~~~~~~~~~~~~~~~~~ - -.. glossary:: - - multi-option - - Multi-options are normal options that have list of values (multiple values) - instead of values:: - - >>> var1 = UnicodeOption('var1', '', [u'val1', u'val2'], multi=True) - >>> od1 = OptionDescription('od1', '', [var1]) - >>> rootod = OptionDescription('rootod', '', [od1]) - >>> c = Config(rootod) - >>> c.read_write() - -A multi-option's value can be manipulated like a list:: - - >>> print c.od1.var1 - [u'val1', u'val2'] - >>> c.od1.var1 = [u'var1'] - >>> print c.od1.var1 - [u'var1'] - >>> c.od1.var1.append(u'val3') - >>> print c.od1.var1 - [u'var1', u'val3'] - >>> c.od1.var1.pop(1) - u'val3' - >>> print c.od1.var1 - [u'var1'] - -But it is not possible to set a value to a multi-option which is not a list:: - - >>> c.od1.var1 = u'error' - Traceback (most recent call last): - ValueError: invalid value error for option var1 which must be a list - - -The master/slave groups -~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. glossary:: - - master/slave - - A master/slave group is an :class:`~tiramisu.option.OptionDescription` and the - options that lives inside. - - Inside this group, a special option, named master option, has the same name as - the group. The group (the option description) is set to type `master`. - All options in a master group is a multi-option (see :ref:`multi-option`). - The slave options have a `default_multi` attribute set to `True`:: - - >>> from tiramisu.setting import groups - >>> from tiramisu.config import Config - >>> from tiramisu.option import UnicodeOption, OptionDescription - >>> - >>> var1 = UnicodeOption('master', '', multi=True) - >>> var2 = UnicodeOption('slave1', '', multi=True) - >>> var3 = UnicodeOption('slave2', '', multi=True, default_multi=u"default") - >>> - >>> od1 = OptionDescription('master', '', [var1, var2, var3]) - >>> od1.impl_set_group_type(groups.master) - >>> - >>> rootod = OptionDescription('rootod', '', [od1]) - >>> c = Config(rootod) - >>> c.read_write() - -The length of the lists can be modified:: - - >>> print c.master - master = [] - slave1 = [] - slave2 = [] - >>> c.master.master.append(u'oui') - >>> print c.master - master = [u'oui'] - slave1 = [None] - slave2 = [u'default'] - >>> c.master.master = [u'non'] - >>> print c.master - master = [u'non'] - slave1 = [None] - slave2 = [u'default'] - >>> - >>> c.master.master = [u'oui', u'non'] - >>> print c.master - master = [u'oui', u'non'] - slave1 = [None, None] - slave2 = [u'default', u'default'] - -But it is forbidden to change the lenght of a slave:: - - >>> c.master.slave1[0] = u'super' - >>> print c.master - master = [u'oui', u'non'] - slave1 = [u'super', None] - slave2 = [u'default', u'default'] - >>> c.master.slave1 = [u'new1', u'new2'] - >>> print c.master - master = [u'oui', u'non'] - slave1 = [u'new1', u'new2'] - slave2 = [u'default', u'default'] - >>> c.master.slave1 = [u'new1'] - Traceback (most recent call last): - tiramisu.error.SlaveError: invalid len for the slave: slave1 which has master.master as master - >>> c.master.slave1 = [u'new1', u'new2', u'new3'] - tiramisu.error.SlaveError: invalid len for the slave: slave1 which has master.master as master - -you have to call the `pop` function on the master:: - - >>> c.master.master = [u'oui'] - Traceback (most recent call last): - tiramisu.error.SlaveError: invalid len for the master: master which has slave1 as slave with greater len - >>> c.master.master.pop(0) - u'oui' - >>> print c.master - master = [u'non'] - slave1 = [u'new2'] - slave2 = [u'default'] - -Configuration's interesting methods ------------------------------------------- - -A `Config` object is informed by an `option.OptionDescription` -instance. The attributes of the ``Config`` objects are the names of the -children of the ``OptionDescription``. - -Here are the (useful) methods on ``Config`` (or `SubConfig`). - -.. currentmodule:: tiramisu.config - -.. class:: Config - -.. autoclass:: SubConfig - :members: find, find_first, __iter__, iter_groups, iter_all, make_dict - - .. automethod:: __init__ - - .. rubric:: Summary - - .. autosummary:: - - find - find_first - - __iter__ - iter_groups - iter_all - - make_dict - - .. rubric:: Methods - - -A :class:`~config.CommonConfig` is a abstract base class. A -:class:`~config.SubConfig` is an just in time created objects that wraps an -::class:`~option.OptionDescription`. A SubConfig differs from a Config in the -fact that a config is a root object and has an environnement, a context which -defines the different properties, access rules, vs... There is generally only -one Config, and many SubConfigs. diff --git a/doc/consistency.txt b/doc/consistency.txt deleted file mode 100644 index 9de8748..0000000 --- a/doc/consistency.txt +++ /dev/null @@ -1,306 +0,0 @@ -.. default-role:: literal - -.. currentmodule:: tiramisu - -The global consistency -=========================== - -Identical option names ----------------------- - -If an :class:`~option.Option()` happens to be defined twice in the -:term:`schema` (e.g. the :class:`~option.OptionDescription()`), -that is the two options actually have the same name, an exception is raised. - -The calculation is currently carried out in the samespace, for example -if `config.gc.name` is defined, another option in `gc` with the name -`name` is **not** allowed, whereas `config.whateverelse.name` is still -allowed. - -Option's values type validation --------------------------------- - -When a value is set to the option, the value is validated by the -option's :class:`option.Option()` validator's type. - -Notice that if the option is `multi`, that is the `multi` attribute is set to -`True`, then the validation of the option value accepts a list of values -of the same type. - -For example, an :class:`option.IntOption` validator waits for an `int` object of -course, an :class:`option.StrOption` validator waits for an `str`, vs... - -Where are located the values -------------------------------- - -The entry point of the acces to the values is the :class:`setting.Setting()` of -the root configuration object, but the values are actually located in the -:class:`value.Values()` object, in order to be delegated in some kind of a -`tiramisu.storage`, which can be a in-memory storage, or a persistent (for the -time being, a sqlite3) storage. - -:class:`value.Values()` is also responsible of the owners and the calculation -of the options that have callbacks. - -Requirements ------------- - -Configuration options can specify requirements as parameters at the init -time, the specification of some links between options or groups allows -to carry out a dependencies calculation. For example, an option can ben -hidden if another option has been set with some expected value. This is -just an example, the possibilities are hudge. - -A requirement is a list of dictionaries that have fairly this form:: - - [{'option': a, 'expected': False, 'action': 'disabled', 'inverse': True, - 'transitive':True, 'same_action': True}] - -Actually a transformation is made to this dictionary during the validation of -this requires at the :class:`~option.Option()`'s init. The dictionary becomes -a tuple, wich is passed to the :meth:`~setting.Settings.apply_requires()` -method. Take a look at the code to fully understand the exact meaning of the -requirements: - -.. automethod:: tiramisu.setting.Settings.apply_requires - - -The path of the option is required, the second element is the value wich is -expected to trigger the callback, it is required too, and the third one is the -callback's action name (`hide`, `show`...), wich is a -:class:`~setting.Property()`. Requirements are validated in -:class:`setting.Setting`. - - -Let's create an option wich has requirements:: - - >>> from tiramisu.option import * - >>> from tiramisu.config import * - >>> var2 = UnicodeOption('var2', '', u'oui') - >>> var1 = UnicodeOption('var1', '', u'value', requires=[{'option':var2, 'expected':u'non', 'action':'hidden'}]) - >>> var3 = UnicodeOption('var3', '', u'value', requires=[{'option':var2, 'expected':u'non', 'action':'hidden'}, {'option':var2, 'expected':u'non', 'action':'disabled'}]) - >>> var4 = UnicodeOption('var4', '', u'oui') - >>> od1 = OptionDescription('od1', '', [var1, var2, var3]) - >>> od2 = OptionDescription('od2', '', [var4], requires=[{'option':od1.var2, 'expected':u'oui', 'action':'hidden', 'inverse':True}]) - >>> rootod = OptionDescription('rootod', '', [od1, od2]) - >>> c = Config(rootod) - >>> c.read_write() - -The requirement here is the dict `{'option':var2, 'expected':u'non', -'action':'hidden'}` wich means that is the option `'od1.var2'` is set to -`'non'`, the option `'od1.var1'` is gonna be hidden. On the other hand, if the -option `'od1.var2'` is different from `'non'`, the option `'od1.var1'` is not -hidden any more:: - - >>> print c.cfgimpl_get_settings()[rootod.od1.var1] - [] - >>> print c.od1.var1 - value - >>> print c.od1.var2 - oui - >>> c.od1.var2 = u'non' - >>> print c.cfgimpl_get_settings()[rootod.od1.var1] - ['hidden'] - >>> print c.od1.var1 - Traceback (most recent call last): - tiramisu.error.PropertiesOptionError: trying to access to an option named: - var1 with properties ['hidden'] - >>> c.od1.var2 = u'oui' - >>> print c.cfgimpl_get_settings()[rootod.od1.var1] - [] - >>> print c.od1.var1 - value - -The requirement on `od2` is `{'option':od1.var2, 'expected':u'oui', -'action':'hidden', 'inverse':True}`, which means that if the option `od1.var2` -is set to `oui`, the option is not hidden (because of the `True` at the end of -the tuple wich means 'inverted', take a look at the :doc:`consistency` -document.):: - - >>> print c.od2.var4 - oui - >>> c.od1.var2 = u'non' - >>> print c.od2.var4 - Traceback (most recent call last): - tiramisu.error.PropertiesOptionError: trying to access to an option named: od2 with properties ['hidden'] - >>> c.od1.var2 = u'oui' - >>> print c.od2.var4 - oui - -Requirements can be accumulated - - >>> print c.cfgimpl_get_settings()[rootod.od1.var3] - [] - >>> c.od1.var2 = u'non' - >>> print c.cfgimpl_get_settings()[rootod.od1.var3] - ['disabled', 'hidden'] - >>> c.od1.var2 = u'oui' - >>> print c.cfgimpl_get_settings()[rootod.od1.var3] - [] - -Requirements can be accumulated for different or identical properties (inverted -or not):: - - >>> a = UnicodeOption('var3', '', u'value', requires=[{'option':od1.var2, - ... 'expected':'non', 'action':'hidden'}, {'option':od1.var1, 'expected':'oui', - ... 'action':'hidden'}]) - >>> a = UnicodeOption('var3', '', u'value', requires=[{'option':od1.var2, - ... 'expected':'non', 'action':'hidden'}, {'option':od1.var1, 'excepted':'oui', - ... 'action':'disabled', 'inverse':True}]) - -But it is not possible to have inverted requirements on the same property. -Here is an impossible situation:: - - >>> a = UnicodeOption('var3', '', u'value', requires=[{'option':od1.var2, - ... 'expected':'non', 'action':'hidden'}, {'option':od1.var1, 'expected':'oui', - ... 'hidden', True}]) - - Traceback (most recent call last): - ValueError: inconsistency in action types for option: var3 action: hidden - -Validation upon a whole configuration object ----------------------------------------------- - -An option's integrity can be validated towards a whole configuration. - -This type of validation is very open. Let's take a use case : an option -has a certain value, and the value of this option can change the owner -of another option or option group... Everything is possible. - -.. currentmodule:: tiramisu.option - -Other hooks are availables to validate upon a whole configuration at any time, -for example the consistency between two options (typically, an -:class:`IPOption` and a :class:`NetworkOption`). - -Let's define validator (wich is a normal python function):: - - >>> def valid_a(value, letter=''): - ... return value.startswith(letter) - -Here is an option wich uses this validator:: - - >>> var1 = UnicodeOption('var1', '', u'oui', validator=valid_a, validator_args={'letter': 'o'}) - >>> od1 = OptionDescription('od1', '', [var1]) - >>> rootod = OptionDescription('rootod', '', [od1]) - >>> c = Config(rootod) - >>> c.read_write() - -The validation is applied at the modification time:: - - >>> c.od1.var1 = u'non' - Traceback (most recent call last): - ValueError: invalid value non for option var1 - >>> c.od1.var1 = u'oh non' - -You can disabled this validation:: - - >>> c.cfgimpl_get_settings().remove('validator') - >>> c.od1.var1 = u'non' - - -Values that are calculated --------------------------------- - -An option that have a callback is considered to have a value that is to be -calculated. - -An option's property with a `force_store_value` attribute is considered to be -modified at the first calculation. - -.. automodule:: tiramisu.autolib - :members: - -This is the typically protocol for accessing a option's for a calculated value, -but some twisted ways are also possible, take a look at the `force_store_value` -attribute. - -.. glossary:: - - force store value - - A calculated value (that is, an option that has a callback) with the - attribute `force_store_value` enabled is considered to be modified at - the first calculation - -Let's create four calculation functions:: - - def return_calc(): - #return an unicode value - return u'calc' - - def return_value(value): - return value - - def return_value_param(param=u''): - return param - - def return_no_value_if_non(value): - #if value is not u'non' return value - if value == u'non': - return None - else: - return value - -Then we create four options using theses functions:: - - >>> var1 = UnicodeOption('var1', '', callback=return_calc) - >>> var2 = UnicodeOption('var2', '', callback=return_value, callback_params={'': (u'value',)}) - >>> var3 = UnicodeOption('var3', '', callback=return_value_param, callback_params={'param': (u'value_param',)}) - >>> var4 = UnicodeOption('var4', '', callback=return_no_value_if_non, callback_params={'': (('od1.var5', False),)}) - >>> var5 = UnicodeOption('var5', '', u'oui') - >>> od1 = OptionDescription('od1', '', [var1, var2, var3, var4, var5]) - >>> rootod = OptionDescription('rootod', '', [od1]) - >>> c = Config(rootod) - >>> c.read_write() - -The first option `var1` returns the result of the `return_calc` function, wich -is `u'calc'`:: - - >>> print c.od1.var1 - calc - -The second option `var2` returns the result of the `return_value` fucntion, -wich is `value`. The parameter `u'value'` is passed to this function:: - - >>> print c.od1.var2 - value - -The third option `var3` returns the result of the function `return_value_param` -with the named parameter `param` and the value `u'value_param'`:: - - >>> print c.od1.var3 - value_param - -The fourth option `var4` returns the reslut of the function `return_no_value_if_non` -that is the value of `od1.var5` exceptif the value is u`non`:: - - >>> print c.od1.var4 - oui - >>> c.od1.var5 = u'new' - >>> print c.od1.var4 - new - >>> c.od1.var5 = u'non' - >>> print c.od1.var4 - None - -The calculation replaces the default value. -If we modify the value, the calculation is not carried out any more:: - - >>> print c.od1.var1 - calc - >>> c.od1.var1 = u'new_value' - >>> print c.od1.var1 - new_value - -To force the calculation to be carried out in some cases, one must add the -`frozen` and the `force_default_on_freeze` properties:: - - >>> c.cfgimpl_get_settings()[rootod.od1.var1].append('frozen') - >>> c.cfgimpl_get_settings()[rootod.od1.var1].append('force_default_on_freeze') - >>> print c.od1.var1 - calc - >>> c.cfgimpl_get_settings()[rootod.od1.var1].remove('frozen') - >>> c.cfgimpl_get_settings()[rootod.od1.var1].remove('force_default_on_freeze') - >>> print c.od1.var1 - new_value diff --git a/doc/doctest.txt b/doc/doctest.txt deleted file mode 100644 index d717c29..0000000 --- a/doc/doctest.txt +++ /dev/null @@ -1,92 +0,0 @@ -Test framework -================== - -Have a look at the :file:`test` subdirectory of the project. -We are using py.test_ - -.. _py.test: http://pytest.org/latest/ - - -config APIs ------------------ - -.. automodule:: test.test_config - :members: - -option APIs ---------------- - -.. automodule:: test.test_option - :members: - - -others ----------- - -.. automodule:: test.test_mandatory - :members: - -.. automodule:: test.test_config_big_example - :members: - -.. automodule:: test.test_option_default - :members: - -.. automodule:: test.test_option_consistency - :members: - -.. automodule:: test.test_cache - :members: - -.. automodule:: test.test_option_setting - :members: - -.. automodule:: test.test_freeze - :members: - -.. automodule:: test.test_config_ip - :members: - -.. automodule:: test.test_slots - :members: - -.. automodule:: test.test_reverse_from_path - :members: - -.. automodule:: test.test_requires - :members: - -.. automodule:: test.test_option_owner - :members: - -.. automodule:: test.test_permissive - :members: - -.. automodule:: test.test_option_type - :members: - -.. automodule:: test.test_dereference - :members: - -.. automodule:: test.test_storage - :members: - -.. automodule:: test.test_option_calculation - :members: - -.. automodule:: test.test_option_with_special_name - :members: - -.. automodule:: test.test_config_domain - :members: - -.. automodule:: test.test_symlink - :members: - -.. automodule:: test.test_metaconfig - :members: - -.. automodule:: test.test_parsing_group - :members: - - diff --git a/doc/eole-report/presentation/Makefile b/doc/eole-report/presentation/Makefile deleted file mode 100644 index 7b32a56..0000000 --- a/doc/eole-report/presentation/Makefile +++ /dev/null @@ -1,12 +0,0 @@ -SRC=$(wildcard *.tex) -OBJ=$(subst .tex,.pdf,$(SRC)) - -pdf: $(OBJ) - -%.pdf: %.tex - pdflatex $< - -clean: - rm -f $(OBJ) - rm -f *.aux *.log *.toc *.snm *.out *.nav - diff --git a/doc/eole-report/presentation/definition.tex b/doc/eole-report/presentation/definition.tex deleted file mode 100644 index 4bbea9f..0000000 --- a/doc/eole-report/presentation/definition.tex +++ /dev/null @@ -1,69 +0,0 @@ -\begin{frame} - \frametitle{Comparaison entre le noyau de Créole et Tiramisu} - \begin{itemize} - \item \emph{Tiramisu} a pour objectif de - \begin{itemize} - \item remplacer le noyau \emph{Creole} (\texttt{EoleDict}) de manière transparente ; - \item résoudre les problèmes inhérents à \texttt{CreoleServ} ; - \end{itemize} - \item au niveau du code, il y a enfin une vraie séparation du c\oe ur et du fonctionnel ; - \item valide le type \emph{et la structure}, l'ajout de types est aisé. - \item \emph{Creole} : \texttt{EoleDict, EoleVars} $ \Leftrightarrow $ \texttt{Config, Option}\\ - cf \texttt{tiramisu/doc/build/pydoc/index.html} - \item intégré à \texttt{gen\_config}, \texttt{cheetah}, \texttt{DTD Creole}, syntaxe \texttt{Creole} \dots - \item \texttt{eole-report/D02CoherenceVariables.pdf} - \end{itemize} -\end{frame} - -\begin{frame} - \frametitle{Gestionnaire de configuration existants} - \begin{itemize} - \item Le gestionnaire de conf de Victor Stinner $\Rightarrow$ \emph{NuFw}; - \item puppet, cfgengine... $\Rightarrow$ intéressant, de nombreux comportements peuvent être repris, mais tel quel difficilement compatible avec \emph{Creole}; - \item \emph{Creole} $\Leftrightarrow$ \texttt{tiramisu/doc/build/glossary.html} -\end{itemize} -\end{frame} - -\begin{frame} - \frametitle{Un "vrai" serveur de config} - \begin{itemize} - \item un serveur de données de configuration ; - \item $1^{ere}$ méthode : exportation (snapshot) d'un état de la config $ \Rightarrow $ Créole ; - \item $2^{eme}$ méthode : JIT (just in time) calculation, une modification -de l'état de la configuration est possible \emph{pendant} la manipulation et l'utilisation de la conf $ \Rightarrow $ Tiramisu. - \item \texttt{doc/getting-started.html} - \end{itemize} -\end{frame} - -\begin{frame} - \frametitle{Qu'est-ce qu'un gestionnaire de conf moderne ?} - \begin{itemize} - \item c'est une organisation arborescente des données (les données sont imbriquées) ; - \item c'est un accès facile aux données (typiquement une interface de type \emph{dictionnaire}) ; - \item clefs-valeurs, mais quelles valeurs exactement ? $ \Rightarrow $ calcul JIT (just in time) ; - \item \texttt{eole-report/D01AccesVariables.pdf} -\end{itemize} -\end{frame} - -\begin{frame} - \frametitle{Définition d'un gestionnaire de configuration} - \begin{itemize} - \item les families, groups, master \dots~ ce sont des \emph{schémas} de données (\texttt{OptionDescription}) ; - \item c'est la configuration (\texttt{Config}) qui est responsable de l'accès aux valeurs ; - \item la configuration est aisément manipulable, et a un point d'entrée unique ; - \item l'accès aux valeurs des \texttt{Options} de configuration ne peut se faire \emph{que} depuis la conf racine. - \item \texttt{eole-report/D01AccesVariables.pdf} - \end{itemize} -\end{frame} - -\begin{frame} - \frametitle{Organisation en espace de nommage} - \begin{itemize} - \item dans \emph{tiramisu} l'accent est mis sur l'organisation arborescente des données ; - \item la validation des options de configuration se fait par l'appartenance aux groupes (families, master/slaves \dots) ; - \item l'organisation en groupes est unifiée par l'espace de nommage ; - \item \texttt{eole-report/D03ReglesEtats.pdf} - \item lisibilité d'une config : \texttt{tiramisu/report/build/index.html} rapport html d'une config - \end{itemize} -\end{frame} - diff --git a/doc/eole-report/presentation/statut.tex b/doc/eole-report/presentation/statut.tex deleted file mode 100644 index 1bee414..0000000 --- a/doc/eole-report/presentation/statut.tex +++ /dev/null @@ -1,61 +0,0 @@ - -\begin{frame} - \frametitle{Etats ("status") de la configuration} - \begin{itemize} - \item système d'états de la configuration par \emph{droits d'accès} ; - \item \texttt{read write}, \texttt{read only} ; - \item correspond à \texttt{freeze}, \texttt{hidden}, \texttt{disabled} \dots ; - \item \texttt{doc/status.html} ; - \item \texttt{eole-report/D03ReglesEtats.pdf} ; - \end{itemize} -\end{frame} - -\begin{frame} - \frametitle{hidden if in, hidden if not in} - \begin{itemize} - \item les hidden if in, disabled if, \dots sont généralisés - \item dans tiramisu, ce sont des pré-requis sur une (des) variables - \item \texttt{eole-report/D03ReglesEtats.pdf} - \item \texttt{doc/consistency.html} - \end{itemize} -\end{frame} - -\begin{frame} - \frametitle{un peu de mathématiques : prévenir les deadlocks} - \begin{itemize} -\item sûreté : prévention des deadlocks ; -\item dans tiramisu, le modèle est suffisamment abstrait pour que son exploitation mathématique soit -réalisable par les techniques de \emph{Model Checking} ; -\item soit on a besoin de ne connaître que l'ensemble des états, pas leurs liens $\Rightarrow$ espace d'états ; -\item soit on a besoin de connaître toutes les relations $\Rightarrow$ graphe d'accessibilité ; -\item la configuration est modélisable en une structure de \emph{Kripe} ; -\item déjà le parsing de la conf est facile, la preuve : \texttt{tiramisu/report/build/index.html} - \end{itemize} -\end{frame} - -\begin{frame} - \frametitle{un peu de mathématiques (suite) CreoleLint} - \begin{itemize} -\item exemple : $ P = 3 \wedge Q = 1 \triangleleft \langle P = 1 \hookleftarrow Q = 0 \rangle$ -\item la propriété \og dans aucun état on a $P = 3$ et $Q = 1$ \fg~ est-elle vraie ? -Pour vérifier cette propriété, on a besoin de connaître l'espace d'états ; -\item la propriété \og chaque chemin débutant dans un état accessible $P=1$ passe par un état où $Q=3$ et $P=2$ \fg~ -est-elle vraie ? Cela demande de connaître le graphe d'accessibilité ; -\item les structures de \emph{Kripe} sont des machines à états étiquetées par les valuations de toutes les variables propositionnelles ; -\item une compliation statique devient possible dans \emph{CreoleLint} \dots - \end{itemize} -\end{frame} - -\begin{frame} - \frametitle{compatibilité Créole : ce qui reste à faire} - \begin{itemize} -\item les options spéciales sont implémentées (auto, fill, obligatoire, \dots) reste la librairie des fonctions pour les variables automatiques \texttt{eosfunc} ; -\item tous les états sont implémentés (hidden, disabled, mode (normal/expert), \dots), il faut fixer les comportement \texttt{read write} ; -\item les "valprec" (valeur précédentes) et une mémoire de \emph{tous} les états antérieurs ; -\item fixer les comportement des hides (sous-groupes récursifs, \dots) ; -\item validations master/slaves, validations globales au regard de la configuration entière puisque c'est possible maintenant. -\end{itemize} - -\end{frame} - - diff --git a/doc/eole-report/presentation/tiramisu.tex b/doc/eole-report/presentation/tiramisu.tex deleted file mode 100644 index a6067c9..0000000 --- a/doc/eole-report/presentation/tiramisu.tex +++ /dev/null @@ -1,36 +0,0 @@ -%%presentation -\documentclass{beamer} -\usepackage{beamerthemetree} -%%impression -%\documentclass[a4paper,9pt]{extarticle} -%\usepackage{beamerarticle} -%% - -% class FR -\usepackage[T1]{fontenc} -\usepackage[utf8]{inputenc} -\usepackage[frenchb]{babel} - -% image -%% \usepackage{graphicx} -\usepackage{alltt} -\usecolortheme{crane} -\beamertemplatetransparentcovered -%\logo{\includegraphics[height=1cm]{ban.png}} - -\title{Tiramisu} -\subtitle{gestionnaire de configuration} -\author{Gwen} -\institute{\texttt{git clone git://git.labs.libre-entreprise.org/tiramisu.git} \\ -\texttt{firefox tiramisu/doc/build/index.html}} - -\date{\today} - -\begin{document} -\frame{\titlepage} - -\include{definition} -\include{statut} - -\end{document} - diff --git a/doc/error.txt b/doc/error.txt deleted file mode 100644 index 3a0bf0e..0000000 --- a/doc/error.txt +++ /dev/null @@ -1,19 +0,0 @@ -Errors that may be encountered -================================== - -Three builtins exceptions are used : ------------------------------------------ - -- **ValueError** : Validation error, parameters error, a list instead - of a Multi, or if the value does not make sense - -- **TypeError** : type error in a parameter - -- **AttributeError** : wrong path or unknownd option or optiondescription - -And five other exceptions : ------------------------------- - -.. automodule:: tiramisu.error - :members: - diff --git a/doc/getting-started.txt b/doc/getting-started.txt deleted file mode 100644 index 509a1c4..0000000 --- a/doc/getting-started.txt +++ /dev/null @@ -1,86 +0,0 @@ -================================== -Getting started -================================== - -What is options handling ? -================================= - -Due to more and more available options required to set up an operating system, -compiler options or whatever, it became quite annoying to hand the necessary -options to where they are actually used and even more annoying to add new -options. To circumvent these problems the configuration control was -introduced... - -What is Tiramisu ? -=================== - -Tiramisu is an options handler and an options controller, which aims at -producing flexible and fast options access. The main advantages are its access -rules and the fact that the whole consistency is preserved at any time, see -:doc:`consistency`. There is of course type and structure validations, but also -validations towards the whole options. Furthermore, options can be reached and -changed according to the access rules from nearly everywhere in your appliance. - -Just the facts -============== - -.. _gettingtiramisu: - -`tiramisu`\ 's home page is here_ - -.. _here: https://forge.cadoles.com/Cadoles/tiramisu - -Download ---------- - - -To obtain a copy of the sources, check it out from the repository using `git`. -We suggest using `git` if one wants to access to the current developments. - -:: - - git clone https://forge.cadoles.com/Cadoles/tiramisu.git - -This will get you a fresh checkout of the code repository in a local directory -named ``tiramisu``. - -Getting started -------------------- - -Option objects can be created in different ways. Let's perform very basic -:class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object -manipulations: - -:: - - >>> from tiramisu.config import Config - >>> from tiramisu.option import OptionDescription, BoolOption - >>> # let's create a group of options... with only one option inside - >>> descr = OptionDescription("optgroup", "", [ - ... BoolOption("bool", "", default=False)]) - >>> # c is a namespace as well as a container for the options - >>> c = Config(descr) - >>> c.bool - False - >>> c.bool = True - >>> c.bool - True - -So by now, we have: - -- a namespace (which is `c` here) -- the access of an option's value by the - attribute access way (here `bool`, which is a boolean option - :class:`~tiramisu.option.BoolOption()`. - -So, option objects are produced at the entry point `c` and then handed down to -where they are actually used when `c.bool` is triggered. This keeps options -local but available at any timer and consistent. - -Once the namespace is created, we can set a -:meth:`~config.CommonConfig.read_write()` access to the options:: - - >>> c.read_write() - -which enables us to set a bunch of access rules that we wil explain later in -:doc:`status`. diff --git a/doc/glossary.txt b/doc/glossary.txt deleted file mode 100644 index 32e9052..0000000 --- a/doc/glossary.txt +++ /dev/null @@ -1,86 +0,0 @@ -.. default-role:: literal - -Glossary -========== - -.. glossary:: - - configuration - - Global configuration object, wich contains the whole configuration - options *and* their descriptions (option types and group) - - schema - option description - - see :class:`tiramisu.option.OptionDescription` - - The schema of a configuration : - - - the option types - - - how they are organised in groups or even subgroups, that's why we - call them **groups** too. - - configuration option - - An option object wich has a name and a value and can be accessed - from the configuration object - - access rules - - Global access rules are : :meth:`~config.CommonConfig.read_write()` or - :meth:`~config.Config.read_only()`, see :doc:`status` - - default value - - Default value of a configuration option. The default value can be - set at instanciation time, or even at any moment. Remember that if - you reset the default value, the owner reset to `default` - - freeze - - A whole configuration can be frozen (used in read only access). See - :ref:`frozen` for details. - - A single option can be frozen too. - - value owner - - When an option is modified, including at the instanciation, we - always know who has modified it. It's the owner of the option, see - :doc:`status` for more details. - - option with properties - - an option wich has property like 'hidden' or 'disabled' is an option - wich has restricted acces rules - - hidden option - - a hidden option has a different behaviour on regards to the access - of the value in the configuration, see :doc:`status` for more details. - - disabled option - - a disabled option has a different behaviour on regards to the access - of the value in the configuration, see :doc:`status` for more details. - - mandatory option - - A mandatory option is a configuration option wich value has to be - set, that is the default value cannot be `None`. - - consistency - - Preserving the consistency in a whole configuration is a tricky thing, - tiramisu takes care of it for you, see :doc:`consistency` for details. - - context - - The context is a :class:`tiramisu.setting.Setting()` object in the - configuration that enables us to access to the global properties - - for example the `read_write` or `read_only` :term:`access rules` - - diff --git a/doc/index.txt b/doc/index.txt deleted file mode 100644 index 51972bd..0000000 --- a/doc/index.txt +++ /dev/null @@ -1,62 +0,0 @@ -.. default-role:: literal - -.. meta:: - - :description: configuration management - :keywords: config, configuration - -.. title:: tiramisu - -The tasting of `Tiramisu` -========================= - -.. image:: logo.png - :height: 150px - -`Tiramisu` - - is a cool, refreshing Italian dessert, - - it is also an `options controller tool`_. - -.. _`options controller tool`: http://en.wikipedia.org/wiki/Configuration_management#Overview - - -It's a pretty small, local (that is, straight on the operating system) options -handler and controller. - -controlling options explanations --------------------------------------- - -.. toctree:: - :maxdepth: 1 - - getting-started - config - option - storage - status - consistency - error - glossary - api - doctest - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - -.. note:: The tiramisu code is licensed under the `LGPL licence`_ - and this documentation is licensed under the `Creative Commons - Attribution-ShareAlike 3.0 Unported License`_\ . - - - -.. _`Creative Commons Attribution-ShareAlike 3.0 Unported License`: http://creativecommons.org/licenses/by-sa/3.0/deed.en_US - -.. _`LGPL licence`: http://www.gnu.org/licenses/lgpl.html - -.. todolist:: diff --git a/doc/logo.png b/doc/logo.png deleted file mode 100644 index 084a534..0000000 Binary files a/doc/logo.png and /dev/null differ diff --git a/doc/option.txt b/doc/option.txt deleted file mode 100644 index 47053b8..0000000 --- a/doc/option.txt +++ /dev/null @@ -1,125 +0,0 @@ -.. default-role:: literal - -.. module:: tiramisu.option - -The options types -=================== - -Description of Options ----------------------- - -All the constructors take a ``name`` and a ``doc`` argument as first -arguments to give to the option or option description a name and a description document. -Most constructors take a ``default`` argument that specifies the default -value of the option. If this argument is not supplied the default value -is assumed to be ``None``. - -The `Option` base class -------------------------- - -It's the abstract base class for almost all options (except the symlink). - -.. _optioninit: - -.. autoclass:: Option - :special-members: - :members: - -All option types ------------------- - -BoolOption -~~~~~~~~~~ - -.. autoclass:: BoolOption - :private-members: - -IntOption -~~~~~~~~~ - -.. autoclass:: IntOption - :private-members: - -FloatOption -~~~~~~~~~~~ - -.. autoclass:: FloatOption - :private-members: - -StrOption -~~~~~~~~~ - -.. autoclass:: StrOption - :private-members: - -UnicodeOption -~~~~~~~~~~~~~ - -.. autoclass:: UnicodeOption - :private-members: - -SymLinkOption -~~~~~~~~~~~~~ - -.. autoclass:: SymLinkOption - :private-members: - - -``SymLinkOption`` redirects to another configuration option in the -configuration, that is : - -- retrieves the value of the target, -- can set the value of the target too - -IPOption -~~~~~~~~ - -.. autoclass:: IPOption - :private-members: - -PortOption -~~~~~~~~~~ - -.. autoclass:: PortOption - :private-members: - -NetmaskOption -~~~~~~~~~~~~~ - -.. autoclass:: NetmaskOption - :private-members: - -NetworkOption -~~~~~~~~~~~~~ - -.. autoclass:: NetworkOption - :private-members: - -DomainnameOption -~~~~~~~~~~~~~~~~ - -.. autoclass:: DomainnameOption - :private-members: - -ChoiceOption -~~~~~~~~~~~~ - -.. autoclass:: ChoiceOption - :private-members: - - -.. _optdescr: - -The `OptionDescription` class -------------------------------- - -.. autoclass:: OptionDescription - :special-members: - :members: - - -If you need to access to an option object, you can do it with the -OptionDescription object. Not only the value of the option by attribute access, -but the option object itself that lives behind the scene. It can always be -accessed internally. The option objects are in the `_children` -`OptionDescription`'s attribute. diff --git a/doc/status.txt b/doc/status.txt deleted file mode 100644 index 4e9217f..0000000 --- a/doc/status.txt +++ /dev/null @@ -1,155 +0,0 @@ -.. default-role:: literal - -Local statuses and global settings -===================================== - -Available configuration statuses ----------------------------------- - -.. currentmodule:: tiramisu - -The configuration's status lives in an :class:`setting.Setting()` object. -This configuration status corresponds to specific attributes or bunch of -attributes that can be accessed together with some `setting.Setting` -method: - -**read write status** - - The configuration can be accessed by `__get__` and `__set__` - properties, except for the `hidden` configuration options but, yes, it is - possible to modify a disabled option. - - To enable read-write status, call - :class:`~config.CommonConfig.read_write()` on the config. - -**read only status** - - The whole configuration is `frozen`, that is modifiying a value is - forbidden. We can access to a configuration option only with the - `__getattr__` property. - - The configuration has not an access to the hidden options - but can read the disabled options. - - To enable read only status, call :class:`~config.SubConfig.read_only()` on - the config. - -.. csv-table:: **Configuration's statuses summary** - :header: " ", "Hidden", "Disabled", "Mandatory" - - "read only status", `False`, `True`, `True` - "read-write status", `True`, `False`, `False` - -.. _`frozen`: - -Freezing a configuration ---------------------------- - -At the configuration level, :class:`~setting.Setting()` enables us to freeze the -whole configuration, wich means that the frozen :class:`~option.Option()`'s -values cannot be modified. - -It is possible to *freeze* a single :class:`~option.Option()` object with -:meth:`~config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen -option, it raises a `TypeError: trying to change a frozen option object`. - -To find out if an option `myoption` is frozen, just make an assertion on the -settings like that:: - - 'frozen' in cfg.cfgimpl_get_settings()[myoption] - -Moreover, frozen option can return their default values if -:meth:`~option.Option.force_default()` is called on this option. - -.. glossary:: - - force default on freeze - - A single option is frozen and we want the option to return something - else than his value, typically it is his default value. - - In the option's values, an attribute can be set - :attr:`force_default_on_freeze`, that forces this behavior. - -Restricted access to an `Option()` ------------------------------------ - -.. autoclass:: tiramisu.setting.Property - -The `properties` attribute is in charge of the access rules' option's value. - -Configuration options access statuses are defined at configuration level -that corresponds to the `option.Option()`'s `properties` attribute, -for example: hidden, disabled. - -Use the pythonic way to know if a property is there:: - - 'hidden' in c.cfgimpl_get_settings() - 'frozen' in c.cfgimpl_get_settings()[opt] - -To access to the global settings:: - - cfg.cfgimpl_get_settings() - cfg.cfgimpl_get_settings()[option1] - -to add, or suppress a global property:: - - cfg.cfgimpl_get_settings()[option1].append('hidden') - cfg.cfgimpl_get_settings()[option1].remove('hidden') - -to activate, deactivate properties:: - - cfg.cfgimpl_get_settings().append('hidden') - cfg.cfgimpl_get_settings().remove('hidden') - -The global properties are living in e :class:`~setting.Setting` object. A -`Setting` object also takes care of the way to access option values and the -storage in the cache. - -Value owners -------------- - -Every configuration option has a **owner**. When the option is instanciated, -the owner is :obj:`setting.owners.default` because a default value has been set -(including `None`, wich means that no value has been set yet). - -.. method:: config.CommonConfig.getowner() - - This method can retrieve an Option's owner. - -- At the instance of the `Config` object, the value owner is - :obj:`setting.owners.default` because - the default values are set at the instance of the configuration option - object, - -- at the modification of an option, the owner is `owners.default`, (which is - :obj:`owners.user`) - -Special behaviors for an option ---------------------------------- - -**mandatory** - - A mandatory option shall return a value. If a value, or a default value - has not been set, a error is raised. - -**has a callback** - - This means that it is a calculated value and therefore automatically - protected it cannot be modified by attribute access. - -**force_store_value** - - if the configuration option has a default value, the default is - returned, otherwise the value is calculated. - - Its inner state is represented by `option.Option.force_default()` - -Configuration options have default values that are stored in the -`Option()` object itself. Default values, the `default`, can be set in -various ways. - -If a default value is modified by overriding it, not only the value of -the option resets to the default that is proposed, but the owner is -modified too, it is reseted to `owners.default`. - diff --git a/doc/storage.png b/doc/storage.png deleted file mode 100644 index 9bef2b3..0000000 Binary files a/doc/storage.png and /dev/null differ diff --git a/doc/storage.svg b/doc/storage.svg deleted file mode 100644 index d710cbc..0000000 --- a/doc/storage.svg +++ /dev/null @@ -1,265 +0,0 @@ - - - - - - - - - - - - image/svg+xml - - - - - - - - - - Config - - - - - Values - - - - Settings - - - - - - - - - - - - Storage - - - Option - - - - diff --git a/doc/storage.txt b/doc/storage.txt deleted file mode 100644 index 6bfb18c..0000000 --- a/doc/storage.txt +++ /dev/null @@ -1,52 +0,0 @@ -Storage -======= - -.. automodule:: tiramisu.storage - -.. automethod:: tiramisu.storage.set_storage - -.. image:: storage.png - -Dictionary -~~~~~~~~~~ - -.. automodule:: tiramisu.storage.dictionary - -Dictionary settings: - -.. automethod:: tiramisu.storage.dictionary.storage.Setting - -Sqlite3 -~~~~~~~ - -.. automodule:: tiramisu.storage.sqlite3 - -Sqlite3 settings: - -.. automethod:: tiramisu.storage.sqlite3.storage.Setting - -Example -~~~~~~~ - ->>> from tiramisu.option import StrOption, OptionDescription ->>> from tiramisu.config import Config ->>> from tiramisu.storage import set_storage ->>> set_storage('sqlite3', dir_database='/tmp/tiramisu') ->>> s = StrOption('str', '') ->>> o = OptionDescription('od', '', [s]) ->>> c1 = Config(o, persistent=True, session_id='xxxx') ->>> c1.str ->>> c1.str = 'yes' ->>> c1.str -'yes' ->>> del(c1) ->>> c2 = Config(o, persistent=True, session_id='xxxx') ->>> c2.str -'yes' ->>> del(c2) ->>> list_sessions() -['xxxx'] ->>> delete_session('xxxx') ->>> c3 = Config(o, persistent=True, session_id='xxxx') ->>> c3.str -