Package: anna
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 (”helpyourself”)!80 seconds to AnnaAnna is all aboutparametersandconfiguration 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 wordsSay 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’sbrandandmodeland return him a brand new car!Now we’re usingannafor 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 andannawill handle the necessary conversions
for us;annaships 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 parameterString('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-onThe 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 sessionSo 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 isString('Brand')is set asCar._brand.All right, but how did the instance receive its values then?Note thatCarinherits fromConfigurableandConfigurable.__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 isString('Brand')will make an instance receive
the corresponding value atyour_car._brand(Car._brandis 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 toparametrizethan 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).parametrizetries to get this base path from the receiving class
looking up the attributeCONFIG_PATH. If it has no such attribute or if it’sNonethen
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 becauseConfigurableuses a custom
metaclass which adds the class attributeCONFIG_PATHif it’s missing orNoneusing
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 attributeCONFIG_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 toparametrizewe 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?annaprovides a decoratordocument_parameterswhich 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 viaget_parameters(which is inherited fromConfigurable) 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,Stringis 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 : StringNow that we know what we need to specify let’s get us a car! TheJSONAdaptorcan also be
initialized with adictas 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
theCarclass to declare a new parameter:ActionParameter(orAction).
AnActionParameterwraps 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 newbrandparameter 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 anActionParametertype 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 argumentdepends_on, are passed as additional arguments to the given action.In the above example we declared parameters on a class usingparametrizebut you could as well
use parameter instances independently and load their values viaload_from_configurationwhich
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 viaload_from_representation. This functions expects the specification as a unicode string and
additional (meta) data as adict(a unit forPhysicalQuantitiesfor example).This introduction was meant to demonstrate the basic principles but there’s much more toanna(especially when it comes to parameter types)! So make sure to check out also the other parts
of the docs!Parameter typesA great variety of parameter types are here at your disposal:BoolIntegerStringNumberVectorDupletTripletTuplePhysicalQuantityActionChoiceGroupComplementaryGroupSubstitutionGroupConfiguration adaptorsTwo adaptor types are provided:XMLAdaptorfor connecting to xml files.JSONAdaptorfor connecting to json files (following some additional conventions).Generating configuration filesConfiguration files can of course be created manually howeverannaalso ships with aPyQtfrontend 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. Seeanna.frontends.qt.