configglue team mailing list archive

[Ricardo Kirkner <ricardo.kirkner@xxxxxxxxxxxxx>]

Ricardo Kirkner has proposed merging lp:~ricardokirkner/configglue/update-docs-1.0 into lp:configglue.

Requested reviews:
  Configglue developers (configglue)

For more details, see:
https://code.launchpad.net/~ricardokirkner/configglue/update-docs-1.0/+merge/69902

updated docs for the 1.0 release
-- 
https://code.launchpad.net/~ricardokirkner/configglue/update-docs-1.0/+merge/69902
Your team Configglue developers is requested to review the proposed merge of lp:~ricardokirkner/configglue/update-docs-1.0 into lp:configglue.

=== modified file 'doc/contents.rst'
--- doc/contents.rst	2011-04-21 02:42:18 +0000
+++ doc/contents.rst	2011-07-30 20:07:27 +0000
@@ -18,6 +18,7 @@
     faq/index
     ref/index
     misc/index
+    releases/index
 
 Indices, glossary and tables
 ============================

=== modified file 'doc/index.rst'
--- doc/index.rst	2011-07-09 19:37:20 +0000
+++ doc/index.rst	2011-07-30 20:07:27 +0000
@@ -70,3 +70,6 @@
     * **Third-party distributions:**
       :doc:`Overview <misc/distributions>`
 
+    * **configglue over time:**
+      :doc:`Release notes and upgrading instructions <releases/index>`
+

=== added file 'doc/misc/api-stability.rst'
--- doc/misc/api-stability.rst	1970-01-01 00:00:00 +0000
+++ doc/misc/api-stability.rst	2011-07-30 20:07:27 +0000
@@ -0,0 +1,62 @@
+=============
+API stability
+=============
+
+:doc:`The release of configglue 1.0 </releases/1.0>` comes with a promise of API
+stability and forwards-compatibility. In a nutshell, this means that code you
+develop against configglue 1.0 will continue to work against 1.1 unchanged, and you
+should need to make only minor changes for any 1.X release.
+
+What "stable" means
+===================
+
+In this context, stable means:
+
+   - All the public APIs -- everything documented in the linked documents below,
+     and all methods that don't begin with an underscore -- will not be moved or
+     renamed without providing backwards-compatible aliases.
+
+   - If new features are added to these APIs -- which is quite possible --
+     they will not break or change the meaning of existing methods. In other
+     words, "stable" does not (necessarily) mean "complete."
+
+   - If, for some reason, an API declared stable must be removed or replaced, it
+     will be declared deprecated but will remain in the API for at least two
+     minor version releases. Warnings will be issued when the deprecated method
+     is called.
+
+   - We'll only break backwards compatibility of these APIs if a bug or
+     security hole makes it completely unavoidable.
+
+Stable APIs
+===========
+
+In general, everything covered in the documentation is considered stable as
+of 1.0.
+
+Exceptions
+==========
+
+There are a few exceptions to this stability and backwards-compatibility
+promise.
+
+Security fixes
+--------------
+
+If we become aware of a security problem we'll do everything necessary to
+fix it. This might mean breaking backwards compatibility; security trumps the
+compatibility guarantee.
+
+APIs marked as internal
+-----------------------
+
+Certain APIs are explicitly marked as "internal" in a couple of ways:
+
+    - Some documentation may refer to internals and mention them as such. If the
+      documentation says that something is internal, we reserve the right to
+      change it.
+
+    - Functions, methods, and other objects prefixed by a leading underscore
+      (``_``). This is the standard Python way of indicating that something is
+      private; if any method starts with a single ``_``, it's an internal API.
+

=== modified file 'doc/misc/index.rst'
--- doc/misc/index.rst	2011-04-21 02:42:18 +0000
+++ doc/misc/index.rst	2011-07-30 20:07:27 +0000
@@ -8,3 +8,4 @@
    :maxdepth: 2
    
    distributions
+   api-stability

=== modified file 'doc/ref/app/base.rst'
--- doc/ref/app/base.rst	2011-07-09 19:37:20 +0000
+++ doc/ref/app/base.rst	2011-07-30 20:07:27 +0000
@@ -13,7 +13,7 @@
 ``App``
 -------
 
-.. class:: App([schema=None, plugin_manager=None, name=None, create_dirs=True])
+.. class:: App([schema=None, plugin_manager=None, name=None, parser=None])
 
 This is the base class from which your application should inherit in order to
 easily integrate itself with configglue.
@@ -55,13 +55,18 @@
     If none is provided, the application will take the name of the script used
     to invoke it from the command line.
 
-.. attribute:: App.create_dirs
+.. attribute:: App.parser
+
+    .. versionadded:: 1.0
 
     *Optional*.
 
-    If ``False``, directories where configuration files are looked for will
-    not get created if they don't exist.
-
-    The default is to create non-existant directories.
-
+    If provided, it will be used as the parser for commandline options to
+    be extended by configglue.
+
+    .. note:: The custom parser is responsible for providing a 'validate' option,
+        or else validation will not be available on the commandline.
+
+    By default a :class:`optparse.OptionParser` instance will be created with an
+    option named 'validate' to allow triggering configuration validation.
 

=== modified file 'doc/ref/schemas/options.rst'
--- doc/ref/schemas/options.rst	2011-07-17 22:32:16 +0000
+++ doc/ref/schemas/options.rst	2011-07-30 20:07:27 +0000
@@ -121,7 +121,7 @@
 ``ListOption``
 ---------------------
 
-.. class:: ListOption(item, [remove_duplicates=False, **attributes])
+.. class:: ListOption(item, [remove_duplicates=False, parse_json=True, **attributes])
 
 A list of items.
 
@@ -139,6 +139,23 @@
     If ``True``, duplicate elements will be removed from the parsed
     value.
 
+.. attribute:: DictOption.parse_json
+
+    .. versionadded:: 1.0
+
+    *Optional*.
+
+    The value for this option can be specified as a json string representing
+    the list.
+
+    Parsing will be attempted as if the value is a json string; if it fails,
+    or the json string doesn't represent a list, the original semantics
+    will be applied (ie, the value is interpreted as a newline-separated
+    string).
+
+    If ``False``, no attempt is made at trying to parse the value as a json
+    string.
+
 ``StringOption``
 ----------------------
 
@@ -170,7 +187,7 @@
 ``DictOption``
 --------------------
 
-.. class:: DictOption([spec=None, strict=False, item=None, **attributes])
+.. class:: DictOption([spec=None, strict=False, item=None, parse_json=True, **attributes])
 
 A dictionary.
 
@@ -197,3 +214,19 @@
     of this type. This should be an instance of a subclass of
     :class:`~configglue.schema.Option`.
 
+.. attribute:: DictOption.parse_json
+
+    .. versionadded:: 1.0
+
+    *Optional*.
+
+    The value for this option can be specified as a json string representing
+    the dictionary.
+
+    Parsing will be attempted as if the value is a json string; if it fails,
+    or the json string doesn't represent a dictionary, the original semantics
+    will be applied (ie, the value represents the name of a section defining
+    the dictionary).
+
+    If ``False``, no attempt is made at trying to parse the value as a json
+    string.

=== added directory 'doc/releases'
=== added file 'doc/releases/1.0-porting-guide.rst'
--- doc/releases/1.0-porting-guide.rst	1970-01-01 00:00:00 +0000
+++ doc/releases/1.0-porting-guide.rst	2011-07-30 20:07:27 +0000
@@ -0,0 +1,51 @@
+===============================================
+Porting your apps from configglue 0.11.1 to 1.0
+===============================================
+
+.. highlight:: python
+
+configglue 1.0 breaks compatibility with 0.11.1 in some areas.
+
+This guide will help you port 0.11.1 projects and apps to 1.0. The first part of
+this document includes the common changes needed to run with 1.0.
+
+.. seealso::
+
+    The :doc:`1.0 release notes </releases/1.0>`. That document explains the new
+    features in 1.0 more deeply; the porting guide is more concerned with
+    helping you quickly update your code.
+
+Common changes
+==============
+
+This section describes the changes between 0.11.1 and 1.0 that most users will
+need to make.
+
+Remove ``pyschema`` from the package namespace
+----------------------------------------------
+
+All the code in the ``configglue.pyschema`` namespace was moved to the
+``configglue`` namespace. Therefore, just rename all your imports that look
+like
+
+::
+
+    import configglue.pyschema.schema
+    from configglue.pyschema.schema import Schema
+
+to
+
+::
+
+    import configglue.schema
+    from configglue.schema import Schema
+
+Rename options
+--------------
+
+All option classes called ``<Foo>ConfigOption`` were being deprecated in favour
+of the corresponding ``<Foo>Option`` classes. The ``<Foo>ConfigOption``
+classes have now been removed, so make sure you rename them to the new names.
+
+The same applies to the ``ConfigOption`` and ``ConfigSection`` classes, which
+have been renamed to ``Option`` and ``Section`` respetively.

=== added file 'doc/releases/1.0.rst'
--- doc/releases/1.0.rst	1970-01-01 00:00:00 +0000
+++ doc/releases/1.0.rst	2011-07-30 20:07:27 +0000
@@ -0,0 +1,96 @@
+============================
+configglue 1.0 release notes
+============================
+
+Welcome to configglue 1.0!
+
+Stability and forwards-compatibility
+====================================
+
+:doc:`The release of configglue 1.0 </releases/1.0>` comes with a promise of API
+stability and forwards-compatibility. In a nutshell, this means that code you
+develop against configglue 1.0 will continue to work against 1.1 unchanged, and you
+should need to make only minor changes for any 1.X release.
+
+See the :doc:`API stability guide </misc/api-stability>` for full details.
+
+Backwards-incompatible changes
+==============================
+
+configglue 1.0 has a number of backwards-incompatible changes from configglue 0.11.1. If
+you have apps written against configglue 0.11.1 that you need to port, see our
+detailed porting guide:
+
+.. toctree::
+   :maxdepth: 1
+
+   1.0-porting-guide
+
+What changed in configglue 1.0
+==============================
+
+We are including here the main changes in configglue 1.0. Please refer to the
+documentation as your definitive guide. Anywhere you see something like:
+
+.. versionadded:: 1.0
+
+You'll know that you're looking at something new or changed.
+
+The major highlights of configglue 1.0 are:
+
+Removal of deprecated features
+------------------------------
+
+A number of features and methods which had previously been marked as deprecated,
+and which were scheduled for removal prior to the 1.0 release, are no longer
+present in configglue. These include:
+
+    - the ``configglue.pyschema`` namespace was dropped in favor of
+      ``configglue``. All modules under the ``configglue.pyschema`` namespace
+      can now be found under the ``configglue`` namespace.
+    - all ``<Foo>ConfigOption`` classes are now called ``<Foo>Option``
+    - the ``ConfigOption`` class is now called ``Option``
+    - the ``ConfigSection`` class is now called ``Section``
+
+Support for customizing the OptionParser
+----------------------------------------
+
+When using the configglue-enabled application base class (see
+:class:`~configglue.app.base.App`), you can pass in a custom
+:class:`optparse.OptionParser` instance to be used as the base commandline
+parser that configglue will extend with the options from the schema.
+
+.. note:: If you provide a custom parser, you'll need to include a boolean
+    option named 'validate' or else, config validation will not be available on
+    the commandline.
+
+Support for specifying complex options using json
+-------------------------------------------------
+
+Certain option types, like :class:`~configglue.schema.DictOption` and
+:class:`~configglue.schema.ListOption` now support being specified as json on
+the configuration files and commandline.
+
+For example, in order to override a :class:`~configglue.schema.DictOption`
+called ``foo`` on the commandline, you can do so by passing in::
+
+    --foo='{"bar": "42"}'
+
+In order to specify the value for this option in the configuration file, you
+can choose between any of the following approaches.
+
+1. Standard syntax (pre 1.0)
+::
+
+    [__main__]
+    foo = mydict
+
+    [mydict]
+    bar = 42
+
+2. JSON-enabled syntax
+::
+
+    [__main__]
+    foo = {"bar": "42"}
+

=== added file 'doc/releases/index.rst'
--- doc/releases/index.rst	1970-01-01 00:00:00 +0000
+++ doc/releases/index.rst	2011-07-30 20:07:27 +0000
@@ -0,0 +1,23 @@
+=============
+Release notes
+=============
+
+Release notes for the official configglue releases. Each release note will tell you
+what's new in each version, and will also describe any backwards-incompatible
+changes made in that version.
+
+For those upgrading to a new version of configglue, you will need to check
+all the backwards-incompatible changes and deprecated features for
+each 'final' release from the one after your current configglue version,
+up to and including the new version.
+
+Final releases
+==============
+
+1.0 release
+-----------
+.. toctree::
+   :maxdepth: 1
+
+   1.0
+