1 How to use cone APIs

     2 ====================

     3 

     4 The ConE public usage is described here with few common use cases as HowTo guides. 

     5 

     6 How to open a Configuration project

     7 -----------------------------------

     8 

     9 To open a project with ConE the api offers a Storage and Project classes. The Storage is the storage 

    10 agostic implemenetation for cpf/zip, filestorage and soon also a webstorage. To access anything in ConE 

    11 you must a project open. 

    12 

    13 .. code-block:: python 

    14 

    15     from cone.public import api,exceptions

    16     """ 

    17     The Storage access can be given as a extra parameter. It can have values r=read|w=write|a=append. 

    18     The default Storage access is read, which will fail if the storage does not exist.

    19     

    20     The Storage.open method will try which of the storage implementations can open that particular path.

    21     So for example the path can be 

    22     'foo/bar'  => Opened with FileStorage

    23     'test.cpf' => Opened with ZipStorage

    24     'test.zip' => Opened with ZipStorage 

    25     """

    26     

    27     """ Open a storage to current path and give it to the project. """

    28     prj = api.Project(api.Storage.open('.'))

    29     """ Create a new storage to a cpf file and give it to the project. """

    30     prj = api.Project(api.Storage.open('test.cpf', 'w'))

    31 

    32 

    33 How to access and manipulate Configurations

    34 -------------------------------------------

    35 

    36 A Configuration normally is presented inside the Configuration project as a .confml file. So when you

    37 are accessing configurations your are actually accessing confml files. The project offers funtionality to 

    38 get,add, remove configurations, which acts on root configurations inside the given project.

    39 

    40 How to List configuration's

    41 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

    42 

    43 .. code-block:: python 

    44 

    45     from cone.public import api,exceptions

    46     """ Create a storage to current path and give it to the project """

    47     prj = api.Project(api.Storage.open('.'))

    48     """ list and print all root configurations  """

    49     configlist = prj.list_configurations()

    50     for config in configlist:

    51         print config

    52 

    53 How to Open configuration

    54 ^^^^^^^^^^^^^^^^^^^^^^^^^

    55 

    56 

    57 .. code-block:: python 

    58 

    59     from cone.public import api,exceptions

    60     """ Create a storage to current path and give it to the project """

    61     prj = api.Project(api.Storage.open('.'))

    62     """ open a with name """

    63     """ 

    64     get_configuration raises a NotFound exception if the given configuration resource 

    65     is not found from Storage

    66     """

    67     try:

    68         myconfig = prj.get_configuration('myconfig.confml')

    69     except exceptions.NotFound:

    70         print "myconfml is not found from project!"

    71 

    72 How to remove Configuration

    73 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

    74 

    75 To remove a Configuration call  ``remove_configuration`` method of Configuration.

    76 

    77 .. code-block:: python

    78 

    79     myconfig = prj.get_configuration('myconfig.confml')

    80     myconfig.remove_configuration('my_remove.confml')

    81     """ finally save and close project """

    82     prj.save()

    83     prj.close()

    84 

    85 How to include a one Configuration to an other Configuration

    86 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    87 

    88 To include a one Configuration to an other call ``include_configuration()`` method of Configuration and pass the filename of Configuration as a parameter.

    89 

    90 .. code-block:: python

    91 

    92     myconfig = prj.get_configuration('myconfig.confml')

    93     myconfig.include_configuration('../data.confml')

    94 

    95 Feature Access and manipulation

    96 -------------------------------

    97 

    98 How to add a Feature to Configuration

    99 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   100 

   101 To add a Feature to Configuration ``add_feature()`` method can be used.

   102 

   103 .. code-block:: python

   104 

   105     conf = api.Configuration("myconf.confml")

   106     conf.add_feature(api.Feature("feature1"))

   107 

   108 How to add a child Feature to Feature

   109 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   110 

   111 Childs can be added under Feature by ``add_feature()`` method and passing the parent Feature as a second paremeter:

   112 

   113 .. code-block:: python

   114 

   115     conf = api.Configuration("myconf.confml")

   116     conf.add_feature(api.Feature("feature1"))

   117     conf.add_feature(api.Feature("feature11"),'feature1')

   118 

   119 How to remove Feature from Configuration

   120 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   121 

   122 Features can be removed from Configuration by a following way:

   123 

   124 .. code-block:: python

   125 

   126     conf1 = api.Configuration("myconf.confml")

   127     conf1.add_feature('feature1.feature12') # Add feature to Configuration

   128     conf1.remove_feature('feature1.feature12') # and then remove it

   129     """ finally save and close project """

   130     prj.save()

   131     prj.close()

   132 

   133 

   134 How to get a Feature from Configuration

   135 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   136 

   137 Features can be accessed through View:

   138 

   139 .. code-block:: python

   140 

   141     from cone.public import api

   142     """ Create a storage to current path and give it to the project """

   143     prj = api.Project(api.Storage.open('.'))

   144     """ open the first configuration from the list """

   145     firstconfig = prj.get_configuration(configlist[0])

   146     """ get default view of first configuration """

   147     default_view = firstconfig.get_default_view()

   148     """ fetch example_feature1 from default view """

   149     feature = default_view.get_feature('example_feature1')

   150 

   151 Feature can be accessed also by a property:

   152 

   153 .. code-block:: python

   154 

   155     from cone.public import api

   156     """ Create a storage to current path and give it to the project """

   157     prj = api.Project(api.Storage.open('.'))

   158     """ open the first configuration from the list """

   159     firstconfig = prj.get_configuration(configlist[0])

   160     """ get default view of first configuration """

   161     default_view = firstconfig.get_default_view()

   162     """ fetch example_feature1 from default view """

   163     feature = default_view.example_feature1

   164 

   165 How to list all Features inside a certain View

   166 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   167 

   168 All Features can listed by calling ``list_all_features()`` method of View. Default view returns always 

   169 the view from the Root configuration point of view.

   170 

   171 .. code-block:: python

   172 

   173     from cone.public import api

   174     """ Create a storage to current path and give it to the project """

   175     prj = api.Project(api.Storage.open('.'))

   176     """ open the first configuration from the list """

   177     firstconfig = prj.get_configuration(configlist[0])

   178     """ get default view of first configuration """

   179     default_view = firstconfig.get_default_view()

   180     """ get all features in list from default view """

   181     features = default_view.list_all_features()

   182 

   183 All features can be listed also using some custom View:

   184 

   185 .. code-block:: python

   186 

   187     from cone.public import api

   188     """ Create a storage to current path and give it to the project """

   189     prj = api.Project(api.Storage.open('.'))

   190     """ open the first configuration from the list """

   191     firstconfig = prj.get_configuration(configlist[0])

   192     """ get my_view view to first configuration """

   193     view = firstconfig.get_view("my_view")

   194     """ fetch example_feature1 from my_view view """

   195     features = view.list_all_features()

   196 

   197 How to list Features inside a certain View

   198 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   199 

   200 To list immediate Features found under the certain View can be done by calling ``list_features()`` method.

   201 

   202 .. code-block:: python

   203 

   204     myconfig = api.Configuration("root.confml")

   205     view = myconfig.get_view("my_view")

   206     features = view.list_features()

   207 

   208 How to list all Features inside a certain Configuration

   209 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   210 

   211 To list all Features found under a certain Configuration can be done by calling ``list_all_features()`` method of Configuration.

   212 

   213 .. code-block:: python

   214 

   215     from cone.public import api

   216     """ Create a storage to current path and give it to the project """

   217     prj = api.Project(api.Storage.open('.'))

   218     """ open the first configuration from the list """

   219     firstconfig = prj.get_configuration(configlist[0])

   220     """ get all features in list from configuration """

   221     features = firstconfig.list_all_features()

   222 

   223 How to read a value for a specific Feature

   224 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   225 

   226 The a value of specific Feature can be read by calling ``get_value()`` method or using value property.

   227 

   228 .. code-block:: python

   229 

   230     value1 = my_feature1.get_value()

   231     value2 = my_feature2.value

   232 

   233 How to read a possible options of selection Feature

   234 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   235 

   236 To list possible options of selection Feature can be done by calling ``get_valueset()`` method of Feature.

   237 

   238 .. code-block:: python

   239 

   240     feature = api.Feature('my_selection_feature',type='selection')

   241     feature.add_option('one', '1')

   242     feature.add_option('two', '2')

   243     value_set = feature.get_valueset()

   244     feature.get_option('1').get_name() #returns  'one'

   245 

   246 How to read a type of specific Feature

   247 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   248 

   249 To read a specific type on Feature ``get_type()`` method or type property can be used. 

   250 

   251 .. code-block:: python

   252 

   253     feature = dview.get_feature('my_feature')

   254     feature.get_type() # returns type of the Feature

   255     feature.type # returns type of the Feature

   256 

   257 How to set a value for a specific Feature

   258 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   259 

   260 To set value for a specific Feature can be done by calling ``set_value()`` method or ``value`` property.

   261 

   262 .. code-block:: python

   263 

   264     feature1 = dview.get_feature('my_feature1')

   265     feature2 = dview.get_feature('my_feature2')

   266     feature1.set_value(123)

   267     feature2.value = "my_value"

   268     """ finally save and close project """

   269     prj.save()

   270     prj.close()

   271 

   272 Data access and manipulation

   273 ----------------------------

   274 The data access inside a configuration is possible, but basically this can be avoided by manipulating the values 

   275 of features, which actually modify the data elements inside the configuration.

   276 However if direct data element access is needed, here's how you can do it.

   277 

   278 How to add Data to Configuration

   279 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   280 

   281 To add Data to Configuration can be done by calling ``add_data()`` method of Configuration: 

   282 

   283 .. code-block:: python

   284 

   285     conf = api.Configuration("data.confml")

   286     conf.add_data(api.Data(ref='feature1', value=123))

   287     conf.add_data(api.Data(fqn='feature1.feature12', value="test"))

   288     """ finally save and close project """

   289     prj.save()

   290     prj.close()

   291     

   292 

   293