Public API

**********

Cone public API is the main interface of Cone.

.. image:: cone_public_api.png

.. module:: cone.public.api

   :platform: Unix, Windows

   :synopsis: Configuration interface.

.. moduleauthor:: Teemu Rytkonen <teemu.rytkonen@nokia.com>

Classes

-------

.. class:: ObjectContainer

	ObjectContainer is a base class for all Configuration related elements. It is container class for a tree structure, 

	where it can contain other ObjectContainer objects. So basically you can create B-tree type of hiararchy with it. 

	The main functionality of ObjectContainer is that **all children of an object container are accessible as members** 

	of the container.

	.. _example_member_access:

	Example of ObjectContainer member access:

	``objcontainer.configuration.get_name()``

	.. method:: _add(child)

	Add a ObjectContainer instance to this object. Checks with internal function :meth:`__supported_type__` if the given 

	child is a supported class for this object.

	.. method:: _add_to_path(path,child)

	Add a ObjectContainer instance to a specific node under this object. It creates any missing nodes between this object 

	and the path. For example __add_to_path__("foo.fii", obj), would create two nodes (foo and under it fii) if they are 

	missing (Uses internal :meth:`__default_class__` to retrieve the class which is created in this case). 

	.. method:: _remove(path)

	Remove a child from given path.

	.. method:: _get(path)

	get a child from given path.

	.. method:: _list()

	Get a list of names of immediate children of this ObjectContainer instance.

	.. method:: _objects()

	Get a list of immediate children objects of this ObjectContainer instance.

	.. method:: _traverse(filters)

	Get a list of children objects of this ObjectContainer instance, by filtering them with filters. This will cause a 

	recursive _traverse method call to all children of the ObjectContainer.

	.. method:: _path(toparent=None)

	Return the path to this object up to the toparent object. When toparent=None this will 

	return a full path to the object in the ObjectContainer hierarhcy.

	.. method:: _supported_type(obj)

	A method that is supposed to be overridden by the deriving classed if they need to change, which classes can be added 

	under each class. 

	Return True if the type of the obj is supported.

	.. method:: _default_class(obj)

	A method that is supposed to be overridden by the deriving classed if they need to change, what class is 

	the default class that is created with __add_to_path__ when objects are missing.

	Return a class.

.. class:: Base

	Base class for all :class:`~cone.public.api.Configuration` and its child objects. 

	.. method:: get_ref()

	return the ref of this object.

	.. method:: get_namepace()

	return the namespace of this object.

.. class:: Project

	Project is a container for Configuration's.

.. class:: Configuration

	ConE Configuration is the main interface for all configuration related activities. It is the main interface of ConE 

	itself as ConE is eventually a python interface to a configuration project. 

Configuration as a Container

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	The Configuration instance itself in ConE is actually just a container for a bunch of different elements. These elements can practically be any elements that exist in a 

	Configuration Project. 

	* :class:`~cone.public.api.Configuration` 

	* :class:`~cone.public.api.View`

	* :class:`~cone.public.api.Feature` 

	* :class:`~cone.public.api.Resource` 

	* :class:`~cone.public.plugin.Relation` 

	* :class:`~cone.public.api.Data` 

.. class:: Feature

	Feature element is the base class for any Configurable item in a Configuration Project.

.. class:: View

	A :class:`~cone.public.api.Configuration` can contain one or more View elements, which basically can define different type of tree structure of Feature elements that exist in the Configuration.

	A View element can contain :class:`~cone.public.api.Group` and :class:`FeaturePoxy` elements.

.. class:: Group

	Group element can be child element of a :class:`~View`. It can include other Groups and :class:`~FeaturePoxy` elements to define a View hierarhcy.

.. class:: FeatureProxy

	FeatureProxy element is a linking object inside View that has its own ref, name, etc but it basically just 

	points to an actual :class:`Feature` instance.

.. class:: Data

	Data element defines a data value for a :class:`Feature` element. The Data elements can be defined in a 

	:class:`Configuration` and single configurable :class:`Feature` can have multiple data definitions, in different 

	configurations. The new definition always overrides the previous one. However the entire data definition hierarchy 

	is stored and is available from the Cone API.

.. class:: Storage

	Storage offers platform and persistence independent interface to store :class:`Resource` elements (data files, 

	configuration files, etc).

.. class:: Resource

	Resource is an instance of single storable element. Basically on normal filesystem this would be same as one file.