Anna - A Neat configuratioN Auxiliary
=====================================
Anna helps you configure your application by building the bridge between the components of
your application and external configuration sources. It allows you to keep your code short and
flexible yet explicit when it comes to configuration - the necessary tinkering is performed by
the framework.
Anna contains lots of "in-place" documentation aka doc strings so make sure you check out those
too ("``help`` yourself")!
80 seconds to Anna
------------------
Anna is all about *parameters* and *configuration sources*. You declare parameters as part of
your application (on a class for example) and specify their values in a configuration source.
All you're left to do with then is to point your application to the configuration source and
let the framework do its job.
An example is worth a thousand words
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Say we want to build an application that deals with vehicles. I'm into cars so the first thing
I'll do is make sure we get one of those::
>>> class Car:
... def __init__(self, brand, model):
... self._brand = brand
... self._model = model
>>>
>>> your_car = Car('Your favorite brand', 'The hottest model')
Great! We let the user specify the car's ``brand`` and ``model`` and return him a brand new car!
Now we're using ``anna`` for declaring the parameters::
>>> from anna import Configurable, parametrize, String, JSONAdaptor
>>>
>>> @parametrize(
... String('Brand'),
... String('Model')
... )
... class Car(Configurable):
... def __init__(self, config):
... super(Car, self).__init__(config)
>>>
>>> your_car = Car(JSONAdaptor('the_file_where_you_specified_your_favorite_car.json'))
The corresponding json file would look like this::
{
"Car/Parameters/Brand": "Your favorite brand",
"Car/Parameters/Model": "The hottest model",
}
It's a bit more to type but this comes at a few advantages:
* We can specify the type of the parameter and ``anna`` will handle the necessary conversions
for us; ``anna`` ships with plenty of parameter types so there's much more to it than just
strings!
* If we change your mind later on and want to add another parameter, say for example the color
of the car, it's as easy as declaring a new parameter ``String('Color')`` and setting it as
a class attribute; all the user needs to do is to specify the corresponding value in
the configuration source. Note that there's no need to change any interfaces/signatures or
other intermediate components which carry the user input to the receiving class; all it expects
is a configuration adaptor which points to the configuration source.
* The configuration source can host parameters for more than only one component, meaning again
that we don't need to modify intermediate parts when adding new components to our application;
all we need to do is provide the configuration adaptor.
Five minutes hands-on
---------------------
The 80 seconds intro piqued your curiosity? Great! So let's move on! For the following
considerations we'll pick up the example from above and elaborate on it more thoroughly.
Let's start with a quick Q/A session
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**So what happened when using the decorator ``parametrize``?** It received a number of parameters
as arguments which it set as attributes on the receiving class. Field names are deduced from
the parameters names applying CamelCase to _snake_case_with_leading_underscore conversion.
That is ``String('Brand')`` is set as ``Car._brand``.
**All right, but how did the instance receive its values then?** Note that ``Car`` inherits from
``Configurable`` and ``Configurable.__init__`` is where the actual instance configuration happens.
We provided it a configuration adaptor which points to the configuration source (in this case
a local file) and the specific values were extracted from there. Values are set on the instance
using the parameter's field name, that is ``String('Brand')`` will make an instance receive
the corresponding value at ``your_car._brand`` (``Car._brand`` is still the parameter instance).
**Okay, but how did the framework know where to find the values in the configuration source?**
Well there's a bit more going on during the call to ``parametrize`` than is written above.
In addition to setting the parameters on the class it also deduces a configuration path for
each parameter which specifies where to find the corresponding value in the source. The path
consists of a base path and the parameter's name: "<base-path>/<name>" (slashes are used
to delimit path elements). ``parametrize`` tries to get this base path from the receiving class
looking up the attribute ``CONFIG_PATH``. If it has no such attribute or if it's ``None`` then
the base path defaults to "<class-name>/Parameters". However in our example - although we didn't
set the config path explicitly - it was already there because ``Configurable`` uses a custom
metaclass which adds the class attribute ``CONFIG_PATH`` if it's missing or ``None`` using
the same default as above. So if you want to specify a custom path within the source you can do so
by specifying the class attribute ``CONFIG_PATH``.
**_snake_case_with_leading_underscore, not too bad but can I choose custom field names for the parameters too?**
Yes, besides providing a number of parameters as arguments to ``parametrize`` we have the option
to supply it a number of keyword arguments as well which represent field_name / parameter pairs;
the key is the field name and the value is the parameter: ``brand_name=String('Brand')``.
**Now that we declared all those parameters how does the user know what to specify?**
``anna`` provides a decorator ``document_parameters`` which will add all declared parameters to
the component's doc string under a new section. Another option for the user is to retrieve
the declared parameters via ``get_parameters`` (which is inherited from ``Configurable``) and
print their string representations which contain comprehensive information::
>>> for parameter in Car.get_parameters():
... print(parameter)
Of course documenting the parameters manually is also an option.
Alright so let's get to the code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
>>> from anna import Configurable, parametrize, String, JSONAdaptor
>>>
>>> @parametrize(
... String('Model'),
... brand_name=String('Brand')
... )
... class Car(Configurable):
... CONFIG_PATH = 'Car'
... def __init__(self, config):
... super(Car, self).__init__(config)
Let's first see what information we can get about the parameters::
>>> for parameter in Car.get_parameters():
... print(parameter)
...
{
"optional": false,
"type": "StringParameter",
"name": "Model",
"path": "Car"
}
{
"optional": false,
"type": "StringParameter",
"name": "Brand",
"path": "Car"
}
Note that it prints ``"StringParameter"`` because that's the parameter's actual class,
``String`` is just a shorthand. Let's see what we can get from the doc string::
>>> print(Car.__doc__)
None
>>> from anna import document_parameters
>>> Car = document_parameters(Car)
>>> print(Car.__doc__)
Declared parameters
-------------------
(configuration path: Car)
Brand : String
Model : String
Now that we know what we need to specify let's get us a car! The ``JSONAdaptor`` can also be
initialized with a ``dict`` as root element, so we're just creating our configuration on the fly::
>>> back_to_the_future = JSONAdaptor(root={
... 'Car/Brand': 'DeLorean',
... 'Car/Model': 'DMC-12',
... })
>>> doc_browns_car = Car(back_to_the_future)
>>> doc_browns_car.brand_name # Access via our custom field name.
'DeLorean'
>>> doc_browns_car._model # Access via the automatically chosen field name.
'DMC-12'
Creating another car is as easy as providing another configuration source::
>>> mr_bonds_car = Car(JSONAdaptor(root={
... 'Car/Brand': 'Aston Martin',
... 'Car/Model': 'DB5',
... }))
Let's assume we want more information about the brand than just its name. We have nicely stored
all information in a database::
>>> database = {
... 'DeLorean': {
... 'name': 'DeLorean',
... 'founded in': 1975,
... 'founded by': 'John DeLorean',
... },
... 'Aston Martin': {
... 'name': 'Aston Martin',
... 'founded in': 1913,
... 'founded by': 'Lionel Martin, Robert Bamford',
... }}
We also have a database access function which we can use to load stuff from the database::
>>> def load_from_database(key):
... return database[key]
To load this database information instead of just the brand's name we only have to modify
the ``Car`` class to declare a new parameter: ``ActionParameter`` (or ``Action``).
An ``ActionParameter`` wraps another parameter and let's us specify an action which is applied to
the parameter's value when it's loaded. For our case that is::
>>> from anna import ActionParameter
>>> Car.brand = ActionParameter(String('Brand'), load_from_database)
>>> doc_browns_car = Car(back_to_the_future)
>>> doc_browns_car.brand
{'founded by': 'John DeLorean', 'name': 'DeLorean', 'founded in': 1975}
>>> doc_browns_car.brand_name
'DeLorean'
Note that we didn't need to provide a new configuration source as the new ``brand`` parameter is
based on the brand name which is already present.
Say we also want to obtain the year in which the model was first produced and we have a function
for exactly that purpose however it requires the brand name and model name as one string::
>>> def first_produced_in(brand_and_model):
... return {'DeLorean DMC-12': 1981, 'Aston Martin DB5': 1963}[brand_and_model]
That's not a problem because an ``ActionParameter`` type lets us combine multiple parameters::
>>> Car.first_produced_in = ActionParameter(
... String('Brand'),
... lambda brand, model: first_produced_in('%s %s' % (brand, model)),
... depends_on=('Model',))
Other existing parameters, specified either by name of by reference via the keyword argument
``depends_on``, are passed as additional arguments to the given action.
In the above example we declared parameters on a class using ``parametrize`` but you could as well
use parameter instances independently and load their values via ``load_from_configuration`` which
expects a configuration adaptor as well as a configuration path which localizes the parameter's
value. You also have the option to provide a specification directly via
``load_from_representation``. This functions expects the specification as a unicode string and
additional (meta) data as a ``dict`` (a unit for ``PhysicalQuantities`` for example).
This introduction was meant to demonstrate the basic principles but there's much more to ``anna``
(especially when it comes to parameter types)! So make sure to check out also the other parts
of the docs!
Parameter types
---------------
A great variety of parameter types are here at your disposal:
* ``Bool``
* ``Integer``
* ``String``
* ``Number``
* ``Vector``
* ``Duplet``
* ``Triplet``
* ``Tuple``
* ``PhysicalQuantity``
* ``Action``
* ``Choice``
* ``Group``
* ``ComplementaryGroup``
* ``SubstitutionGroup``
Configuration adaptors
----------------------
Two adaptor types are provided:
* ``XMLAdaptor`` for connecting to xml files.
* ``JSONAdaptor`` for connecting to json files (following some additional conventions).
Generating configuration files
------------------------------
Configuration files can of course be created manually however ``anna`` also ships with a ``PyQt``
frontend that can be integrated into custom applications. The frontend provides input forms for
all parameter types as well as for whole parametrized classes together with convenience methods for
turning the forms' values into configuration adaptor instances which in turn can be dumped to
files. Both PyQt4 and PyQt5 are supported. See ``anna.frontends.qt``.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/Dominik1123/Anna",
"name": "anna",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "configuration framework",
"author": "Dominik Vilsmeier",
"author_email": "dominik.vilsmeier1123@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3b/c9/2e3a063ee353ac6728d7f015deba1f5418ac146d08157e3aa0a47b907b4d/anna-0.5.2.tar.gz",
"platform": null,
"description": "Anna - A Neat configuratioN Auxiliary\n=====================================\n\nAnna helps you configure your application by building the bridge between the components of\nyour application and external configuration sources. It allows you to keep your code short and\nflexible yet explicit when it comes to configuration - the necessary tinkering is performed by\nthe framework.\n\nAnna contains lots of \"in-place\" documentation aka doc strings so make sure you check out those\ntoo (\"``help`` yourself\")!\n\n\n80 seconds to Anna\n------------------\n\nAnna is all about *parameters* and *configuration sources*. You declare parameters as part of\nyour application (on a class for example) and specify their values in a configuration source.\nAll you're left to do with then is to point your application to the configuration source and\nlet the framework do its job.\n\nAn example is worth a thousand words\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nSay we want to build an application that deals with vehicles. I'm into cars so the first thing\nI'll do is make sure we get one of those::\n\n >>> class Car:\n ... def __init__(self, brand, model):\n ... self._brand = brand\n ... self._model = model\n >>>\n >>> your_car = Car('Your favorite brand', 'The hottest model')\n\nGreat! We let the user specify the car's ``brand`` and ``model`` and return him a brand new car!\n\nNow we're using ``anna`` for declaring the parameters::\n\n >>> from anna import Configurable, parametrize, String, JSONAdaptor\n >>>\n >>> @parametrize(\n ... String('Brand'),\n ... String('Model')\n ... )\n ... class Car(Configurable):\n ... def __init__(self, config):\n ... super(Car, self).__init__(config)\n >>>\n >>> your_car = Car(JSONAdaptor('the_file_where_you_specified_your_favorite_car.json'))\n\nThe corresponding json file would look like this::\n\n {\n \"Car/Parameters/Brand\": \"Your favorite brand\",\n \"Car/Parameters/Model\": \"The hottest model\",\n }\n\nIt's a bit more to type but this comes at a few advantages:\n\n* We can specify the type of the parameter and ``anna`` will handle the necessary conversions\n for us; ``anna`` ships with plenty of parameter types so there's much more to it than just\n strings!\n* If we change your mind later on and want to add another parameter, say for example the color\n of the car, it's as easy as declaring a new parameter ``String('Color')`` and setting it as\n a class attribute; all the user needs to do is to specify the corresponding value in\n the configuration source. Note that there's no need to change any interfaces/signatures or\n other intermediate components which carry the user input to the receiving class; all it expects\n is a configuration adaptor which points to the configuration source.\n* The configuration source can host parameters for more than only one component, meaning again\n that we don't need to modify intermediate parts when adding new components to our application;\n all we need to do is provide the configuration adaptor.\n\n\nFive minutes hands-on\n---------------------\n\nThe 80 seconds intro piqued your curiosity? Great! So let's move on! For the following\nconsiderations we'll pick up the example from above and elaborate on it more thoroughly.\n\nLet's start with a quick Q/A session\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n**So what happened when using the decorator ``parametrize``?** It received a number of parameters\nas arguments which it set as attributes on the receiving class. Field names are deduced from\nthe parameters names applying CamelCase to _snake_case_with_leading_underscore conversion.\nThat is ``String('Brand')`` is set as ``Car._brand``.\n\n**All right, but how did the instance receive its values then?** Note that ``Car`` inherits from\n``Configurable`` and ``Configurable.__init__`` is where the actual instance configuration happens.\nWe provided it a configuration adaptor which points to the configuration source (in this case\na local file) and the specific values were extracted from there. Values are set on the instance\nusing the parameter's field name, that is ``String('Brand')`` will make an instance receive\nthe corresponding value at ``your_car._brand`` (``Car._brand`` is still the parameter instance).\n\n**Okay, but how did the framework know where to find the values in the configuration source?**\nWell there's a bit more going on during the call to ``parametrize`` than is written above.\nIn addition to setting the parameters on the class it also deduces a configuration path for\neach parameter which specifies where to find the corresponding value in the source. The path\nconsists of a base path and the parameter's name: \"<base-path>/<name>\" (slashes are used\nto delimit path elements). ``parametrize`` tries to get this base path from the receiving class\nlooking up the attribute ``CONFIG_PATH``. If it has no such attribute or if it's ``None`` then\nthe base path defaults to \"<class-name>/Parameters\". However in our example - although we didn't\nset the config path explicitly - it was already there because ``Configurable`` uses a custom\nmetaclass which adds the class attribute ``CONFIG_PATH`` if it's missing or ``None`` using\nthe same default as above. So if you want to specify a custom path within the source you can do so\nby specifying the class attribute ``CONFIG_PATH``.\n\n**_snake_case_with_leading_underscore, not too bad but can I choose custom field names for the parameters too?**\nYes, besides providing a number of parameters as arguments to ``parametrize`` we have the option\nto supply it a number of keyword arguments as well which represent field_name / parameter pairs;\nthe key is the field name and the value is the parameter: ``brand_name=String('Brand')``.\n\n**Now that we declared all those parameters how does the user know what to specify?**\n``anna`` provides a decorator ``document_parameters`` which will add all declared parameters to\nthe component's doc string under a new section. Another option for the user is to retrieve\nthe declared parameters via ``get_parameters`` (which is inherited from ``Configurable``) and\nprint their string representations which contain comprehensive information::\n\n >>> for parameter in Car.get_parameters():\n ... print(parameter)\n\nOf course documenting the parameters manually is also an option.\n\nAlright so let's get to the code\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n >>> from anna import Configurable, parametrize, String, JSONAdaptor\n >>>\n >>> @parametrize(\n ... String('Model'),\n ... brand_name=String('Brand')\n ... )\n ... class Car(Configurable):\n ... CONFIG_PATH = 'Car'\n ... def __init__(self, config):\n ... super(Car, self).__init__(config)\n\nLet's first see what information we can get about the parameters::\n\n >>> for parameter in Car.get_parameters():\n ... print(parameter)\n ...\n {\n \"optional\": false,\n \"type\": \"StringParameter\",\n \"name\": \"Model\",\n \"path\": \"Car\"\n }\n {\n \"optional\": false,\n \"type\": \"StringParameter\",\n \"name\": \"Brand\",\n \"path\": \"Car\"\n }\n\nNote that it prints ``\"StringParameter\"`` because that's the parameter's actual class,\n``String`` is just a shorthand. Let's see what we can get from the doc string::\n\n >>> print(Car.__doc__)\n None\n >>> from anna import document_parameters\n >>> Car = document_parameters(Car)\n >>> print(Car.__doc__)\n\n Declared parameters\n -------------------\n (configuration path: Car)\n\n Brand : String\n Model : String\n\n\nNow that we know what we need to specify let's get us a car! The ``JSONAdaptor`` can also be\ninitialized with a ``dict`` as root element, so we're just creating our configuration on the fly::\n\n >>> back_to_the_future = JSONAdaptor(root={\n ... 'Car/Brand': 'DeLorean',\n ... 'Car/Model': 'DMC-12',\n ... })\n >>> doc_browns_car = Car(back_to_the_future)\n >>> doc_browns_car.brand_name # Access via our custom field name.\n 'DeLorean'\n >>> doc_browns_car._model # Access via the automatically chosen field name.\n 'DMC-12'\n\nCreating another car is as easy as providing another configuration source::\n\n >>> mr_bonds_car = Car(JSONAdaptor(root={\n ... 'Car/Brand': 'Aston Martin',\n ... 'Car/Model': 'DB5',\n ... }))\n\nLet's assume we want more information about the brand than just its name. We have nicely stored\nall information in a database::\n\n >>> database = {\n ... 'DeLorean': {\n ... 'name': 'DeLorean',\n ... 'founded in': 1975,\n ... 'founded by': 'John DeLorean',\n ... },\n ... 'Aston Martin': {\n ... 'name': 'Aston Martin',\n ... 'founded in': 1913,\n ... 'founded by': 'Lionel Martin, Robert Bamford',\n ... }}\n\nWe also have a database access function which we can use to load stuff from the database::\n\n >>> def load_from_database(key):\n ... return database[key]\n\nTo load this database information instead of just the brand's name we only have to modify\nthe ``Car`` class to declare a new parameter: ``ActionParameter`` (or ``Action``).\nAn ``ActionParameter`` wraps another parameter and let's us specify an action which is applied to\nthe parameter's value when it's loaded. For our case that is::\n\n >>> from anna import ActionParameter\n >>> Car.brand = ActionParameter(String('Brand'), load_from_database)\n >>> doc_browns_car = Car(back_to_the_future)\n >>> doc_browns_car.brand\n {'founded by': 'John DeLorean', 'name': 'DeLorean', 'founded in': 1975}\n >>> doc_browns_car.brand_name\n 'DeLorean'\n\nNote that we didn't need to provide a new configuration source as the new ``brand`` parameter is\nbased on the brand name which is already present.\n\nSay we also want to obtain the year in which the model was first produced and we have a function\nfor exactly that purpose however it requires the brand name and model name as one string::\n\n >>> def first_produced_in(brand_and_model):\n ... return {'DeLorean DMC-12': 1981, 'Aston Martin DB5': 1963}[brand_and_model]\n\nThat's not a problem because an ``ActionParameter`` type lets us combine multiple parameters::\n\n >>> Car.first_produced_in = ActionParameter(\n ... String('Brand'),\n ... lambda brand, model: first_produced_in('%s %s' % (brand, model)),\n ... depends_on=('Model',))\n\nOther existing parameters, specified either by name of by reference via the keyword argument\n``depends_on``, are passed as additional arguments to the given action.\n\nIn the above example we declared parameters on a class using ``parametrize`` but you could as well\nuse parameter instances independently and load their values via ``load_from_configuration`` which\nexpects a configuration adaptor as well as a configuration path which localizes the parameter's\nvalue. You also have the option to provide a specification directly via\n``load_from_representation``. This functions expects the specification as a unicode string and\nadditional (meta) data as a ``dict`` (a unit for ``PhysicalQuantities`` for example).\n\nThis introduction was meant to demonstrate the basic principles but there's much more to ``anna``\n(especially when it comes to parameter types)! So make sure to check out also the other parts\nof the docs!\n\n\nParameter types\n---------------\n\nA great variety of parameter types are here at your disposal:\n\n* ``Bool``\n* ``Integer``\n* ``String``\n* ``Number``\n* ``Vector``\n* ``Duplet``\n* ``Triplet``\n* ``Tuple``\n* ``PhysicalQuantity``\n* ``Action``\n* ``Choice``\n* ``Group``\n* ``ComplementaryGroup``\n* ``SubstitutionGroup``\n\n\nConfiguration adaptors\n----------------------\n\nTwo adaptor types are provided:\n\n* ``XMLAdaptor`` for connecting to xml files.\n* ``JSONAdaptor`` for connecting to json files (following some additional conventions).\n\n\nGenerating configuration files\n------------------------------\n\nConfiguration files can of course be created manually however ``anna`` also ships with a ``PyQt``\nfrontend that can be integrated into custom applications. The frontend provides input forms for\nall parameter types as well as for whole parametrized classes together with convenience methods for\nturning the forms' values into configuration adaptor instances which in turn can be dumped to\nfiles. Both PyQt4 and PyQt5 are supported. See ``anna.frontends.qt``.\n\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A Neat configuratioN Auxiliary",
"version": "0.5.2",
"project_urls": {
"Homepage": "https://gitlab.com/Dominik1123/Anna"
},
"split_keywords": [
"configuration",
"framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e4a7e45c81dbc15c2978c73ea58277333bb696eb41c36aae174443efb74fef94",
"md5": "14cc8852558487347b5c7a66ad4e54be",
"sha256": "985891ae04bb080b36387a38953202ec6280105b3fa54066b813b104a857edba"
},
"downloads": -1,
"filename": "anna-0.5.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "14cc8852558487347b5c7a66ad4e54be",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 84570,
"upload_time": "2024-08-20T20:31:24",
"upload_time_iso_8601": "2024-08-20T20:31:24.692950Z",
"url": "https://files.pythonhosted.org/packages/e4/a7/e45c81dbc15c2978c73ea58277333bb696eb41c36aae174443efb74fef94/anna-0.5.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3bc92e3a063ee353ac6728d7f015deba1f5418ac146d08157e3aa0a47b907b4d",
"md5": "1316e1a593d922bfceec7f1b6111d17f",
"sha256": "4ac977992a3c2162de34184fbb322037f52d26df530bb12a49a4bd97f93a54ff"
},
"downloads": -1,
"filename": "anna-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "1316e1a593d922bfceec7f1b6111d17f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 83189,
"upload_time": "2024-08-20T20:31:26",
"upload_time_iso_8601": "2024-08-20T20:31:26.417629Z",
"url": "https://files.pythonhosted.org/packages/3b/c9/2e3a063ee353ac6728d7f015deba1f5418ac146d08157e3aa0a47b907b4d/anna-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-20 20:31:26",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "Dominik1123",
"gitlab_project": "Anna",
"lcname": "anna"
}
JSON