Permalink
Browse files

documents are updated

  • Loading branch information...
1 parent b97a969 commit a1394eb4318e7ef7034878688fce19f828a7d5eb @pylover committed Nov 27, 2013
Showing with 100 additions and 49 deletions.
  1. +3 −1 doc/conf.py
  2. +3 −28 doc/pymlconf.rst
  3. +4 −0 generate.docs
  4. +7 −3 pymlconf/__init__.py
  5. +40 −15 pymlconf/config_manager.py
  6. +43 −2 pymlconf/config_nodes.py
View
@@ -20,6 +20,8 @@
# -- General configuration -----------------------------------------------------
+autoclass_content="both"
+
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
@@ -120,7 +122,7 @@
# 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']
+#html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
View
@@ -1,10 +1,10 @@
pymlconf Package
================
-:mod:`pymlconf` Package
------------------------
+:mod:`config_manager` Module
+----------------------------
-.. automodule:: pymlconf.__init__
+.. automodule:: pymlconf.config_manager
:members:
:undoc-members:
:show-inheritance:
@@ -17,35 +17,10 @@ pymlconf Package
:undoc-members:
:show-inheritance:
-:mod:`config_manager` Module
-----------------------------
-
-.. automodule:: pymlconf.config_manager
- :members:
- :undoc-members:
- :show-inheritance:
-
:mod:`errors` Module
--------------------
.. automodule:: pymlconf.errors
:members:
:undoc-members:
:show-inheritance:
-
-:mod:`mergable` Module
-----------------------
-
-.. automodule:: pymlconf.mergable
- :members:
- :undoc-members:
- :show-inheritance:
-
-:mod:`yaml_helper` Module
--------------------------
-
-.. automodule:: pymlconf.yaml_helper
- :members:
- :undoc-members:
- :show-inheritance:
-
View
@@ -0,0 +1,4 @@
+#! /bin/bash
+
+#sphinx-apidoc --force -o doc pymlconf pymlconf/tests
+sphinx-build -Eab html doc/ doc/_build/
View
@@ -1,14 +1,18 @@
-from pymlconf.config_nodes import ConfigList,ConfigDict
+from pymlconf.config_nodes import Mergable, ConfigList, ConfigDict, ConfigNamespace
from pymlconf.config_manager import ConfigManager
-from pymlconf.errors import ConfigurationError
+from pymlconf.errors import ConfigurationError, ConfigKeyError, ConfigurationMergeError
__version__ = '0.3.5'
__all__ = ['ConfigManager',
+ 'Mergable',
'ConfigList',
'ConfigDict',
- 'ConfigurationError']
+ 'ConfigNamespace',
+ 'ConfigurationError',
+ 'ConfigKeyError',
+ 'ConfigurationMergeError']
# TODO: Reserved keys in configuration file
View
@@ -6,18 +6,10 @@
from pymlconf.compat import basestring
+
class ConfigManager(ConfigDict):
"""
- The main class to using the pymlconf package.
-
- Parameters::
- init_value: Initial configuration value that you can pass it before reading the files and directories.can be 'yaml string' or python dictionary.
-
- dirs: Python list or a string that contains comma separated list of directories which contains config files with specified extension(default *.conf).
-
- files: Python list or a string that contains comma separated list of files which contains yaml config entries.
-
- filename_as_namespace: when loading dirs, use the filename as a namespace.
+ The main class which exposes pymlconf package.
Example::
@@ -34,11 +26,30 @@ class ConfigManager(ConfigDict):
"""
- default_extension = ".conf"
+ default_extension = ".conf"
- # Operations
def __init__(self, init_value=None, dirs=None, files=None, filename_as_namespace=True,
extension='.conf',root_file_name='root'):
+ """
+ :param init_value: Initial configuration value that you can pass it before reading the files and directories.can be 'yaml string' or python dictionary.
+ :type init_value: str or dict
+
+ :param dirs: Python list or a string that contains semi-colon separated list of directories which contains configuration files with specified extension(default \*.conf).
+ :type dirs: str or list
+
+ :param files: Python list or a string that contains semi-colon separated list of files which contains yaml configuration entries.
+ :type files: str or list
+
+ :param filename_as_namespace: when loading dirs, use the filename as a namespace. default: true.
+ :type filename_as_namespace: bool
+
+ :param extension: File extension to search for configuration files, in dirs parameter, default '.conf'
+ :type extension: str
+
+ :param root_file_name: Filename to treat as root configuration file, so it loads first, and do not uses the filesname as namespaces.
+ :type root_file_name: str
+
+ """
super(ConfigManager,self).__init__(data=init_value)
self.default_extension = extension
self.root_file_name = root_file_name
@@ -54,13 +65,20 @@ def __init__(self, init_value=None, dirs=None, files=None, filename_as_namespace
def load_files(self, files, filename_as_namespace=False):
"""
- load files which contains yaml config entries.and merge it by current ConfigManager instance
+ load files which contains yaml configuration entries.and merge it by current ConfigManager instance
+
+ :param files: files to load and merge into exisiting configuration instance
+ :type files: list
+
+ :param filename_as_namespace: when loading files, use the filename as a namespace. default: false.
+ :type filename_as_namespace: bool
+
"""
for f in files:
if not os.path.exists(f):
continue
if filename_as_namespace:
- assert f.endswith(self.default_extension), 'Invalid config filename.expected: ns1.ns2.*%s' % self.default_extension
+ assert f.endswith(self.default_extension), 'Invalid configuration filename.expected: ns1.ns2.*%s' % self.default_extension
namespace = os.path.splitext(os.path.split(f)[1])[0]
if namespace == self.root_file_name:
node = self
@@ -72,7 +90,14 @@ def load_files(self, files, filename_as_namespace=False):
def load_dirs(self, dirs, filename_as_namespace=True):
"""
- load directories which contains config files with specified extension, and merge it by current ConfigManager instance
+ load directories which contains configuration files with specified extension, and merge it by current ConfigManager instance
+
+ :param dirs: Dirs to search for configuration files.
+ :type dirs: list
+
+ :param filename_as_namespace: when loading dirs, use the filename as a namespace. default: true.
+ :type filename_as_namespace: bool
+
"""
candidate_files = []
for d in dirs:
View
@@ -7,14 +7,28 @@
class Mergable(object):
+ """ Base class for all configuration nodes, so all configuration nodes are mergable
+ """
__metaclass__ = abc.ABCMeta
def __init__(self,data=None):
+ """
+ :param data: Initial value to constract a mergable instance. default: None.
+ :type data: list or dict
+ """
if data:
self.merge(data)
@abc.abstractmethod
def can_merge(self, data):
+ """
+ Determines whenever can merge with the passed argument or not.
+
+ :param data: An object to test.
+ :type data: any
+
+ :returns: bool
+ """
raise NotImplementedError()
@abc.abstractmethod
@@ -23,15 +37,31 @@ def _merge(self,data):
@abc.abstractmethod
def copy(self):
+ """
+ When implemented, returns copy of current config instance.
+
+ :returns: :class:`.Mergable`
+ """
return copy.deepcopy(self)
@classmethod
@abc.abstractmethod
def empty(cls):
+ """
+ When implemented, returns an empty instance of drived :class:`.Mergable` class.
+
+ :returns: :class:`.Mergable`
+ """
raise NotImplementedError()
@classmethod
def make_mergable_if_possible(cls,data):
+ """
+ Makes an object mergable if possible. Returns the virgin object if cannot convert it to a mergable instance.
+
+ :returns: :class:`.Mergable` or type(data)
+
+ """
if isinstance(data, dict):
return ConfigDict(data=data)
elif isiterable(data):
@@ -42,7 +72,10 @@ def make_mergable_if_possible(cls,data):
def merge(self, *args):
"""
Merges this instance with new instances, in-place.
- returns the self.empty(), if the empty string or None was passed as data.
+
+ :param \*args: Configuration values to merge with current instance.
+ :type \*args: iterable
+
"""
for data in args:
to_merge = None
@@ -66,6 +99,9 @@ def _ensure_namespaces(self,*namespaces):
class ConfigDict(OrderedDict, Mergable):
+ """
+ Configuration node that represents python dictionary data.
+ """
def __init__(self, data=None):
OrderedDict.__init__(self)
@@ -107,13 +143,18 @@ def empty(cls):
return cls()
class ConfigNamespace(ConfigDict, Mergable):
+ """
+ Configuration node that represents the configuration namespace node.
+ """
def __init__(self, data=None):
ConfigDict.__init__(self)
Mergable.__init__(self, data=data)
class ConfigList(list, Mergable):
-
+ """
+ Configuration node that represents the python list data.
+ """
def __init__(self, data=None):
list.__init__(self)
Mergable.__init__(self, data=data)

0 comments on commit a1394eb

Please sign in to comment.