Code examples¶
In the following examples, consider the following my.yml
file:
Family:
Dad:
catpic: REF:Family/Mom/catpic
thumbnail: REF:Family/Dad/catpic
real name: Matthew Logan
spouse: REF:Family/Mom
Mom:
occupation: michelin cook
real name: Anastasia Logan
web: https://github.com
catpic: FILE:path/to/cat.jpg
Friends:
Albatros:
aliases: theunspoken, ninja
relationship: friend
url_bin: URL:file:path/to/bin.dat
Nappo:
aliases: Bappo
relationship: special
bin_source: file:path/to/bin.dat
NoAttributesHere:
NoEntitiesHere:
This is a functional YAML you may import. Notice the valspecs determining attribute data types.
CLI examples¶
Let’s jump-start from zero:
$ contacto -o my.db set -r Friends/Albatros/age 18
$ contacto -o my.db get
> Friends
- Albatros
- age: 18
The above example recursively created the Albatros friend and set his age
in the my.db
database.
Now let’s import the my.yml
file to expand our database:
$ contacto -o my.db import my.yml
$ contacto -o my.db get /Albatros
> Friends
- Albatros
- age : 18
- aliases: theunspoken, ninja
...
Data from my.yml
have been merged in.
Let’s merge Nappo
into Albatros
and print the result:
$ contacto -o my.db merge Friends/Nappo Friends/Albatros
$ contacto -o my.db get Friends/Albatros
> aliases : Bappo
relationship: special
...
As you can see, since the Friends/Albatros
is a strict refspec,
Group and Entity information is not printed, it is assumed to be known.
Plugin example¶
Plugins may be run from the CLI.
The following example lists available plugins and then runs
plug1
and plug2
.
The example assumes that contacto_plug1
and contacto_plug2
are
reachable as top-level modules in the current context
(see Plugins).
$ contacto -o my.db plugins -l
$ contacto -o my.db plugins plug1 plug2
API examples¶
This section illustrates the inner workings of Contacto.
We shall use an in-memory database:
>>> stor = Storage(':memory:')
Creating a contact tree¶
Let’s create a Friends/Albatros entity and set his age
to 18:
>>> friends = stor.create_group_safe('Friends')
>>> albtrs = friends.create_entity_safe('Albatros')
>>> age = albtrs.create_attribute_safe('age', DType.TEXT, '18')
>>> age is stor.get_attribute('Friends', 'Albatros', 'age')
True
This shows how tree elements create their children.
The Storage object stor
can then find the created attribute.
Merging entities¶
>>> nappo = friends.create_entity_safe('Nappo')
>>> _ = nappo.create_attribute_safe('age', DType.TEXT, '20')
>>> albtrs.merge(nappo)
>>> age.data
'20'
Notice that Albatros’s age was replaced by Nappo’s.
Filtering data¶
The View
class lets us scope things out.
Let’s add Nappo back with a different age (50):
>>> nappo = friends.create_entity_safe('Nappo')
>>> _ = nappo.create_attribute_safe('age', DType.TEXT, '50')
Now let’s use View
to only get 50-years-old friends:
>>> view = View(stor)
>>> view.set_attr_value_filter('50', False)
>>> view.filter()
>>> view.groups['Friends'].entities.keys()
dict_keys(['Nappo'])
Since Albatros isn’t 50 years old, he is filtered out.
Exporting filtered data¶
The Serial
class takes care of serialization:
>>> ser = Serial(view)
>>> ser.dump()
Friends
- Nappo
- age: 50