How to create new Artifact Type¶
Basics¶
Each artifact type must realize Glare Artifact Type Interface (GATI)
and be inherited from glare.objects.base.BaseArtifact
class.
GATI obliges to specify only one class method – get_type_name
that returns a string with unique artifact type name. Other methods
and fields are optional.
Note
Conventionally it is recommended to give names in the plural, in lowercase, with words separated by underscores.
Example of code for minimal artifact type:
from glare.objects import base class HelloWorld(base.BaseArtifact): @classmethod def get_type_name(cls): return "hello_worlds"
Custom artifact fields¶
Users can add type specific fields to their artifact type to extend
its logic and functionality. Follow the requirements of
oslo.versionedobjects library all new fields must be placed in class
dictionary attribute called fields
:
from glare.objects import base class HelloWorld(base.BaseArtifact): ... fields = {...}
There is a large number of possible field options. Let’s look at the most popular ones.
Fields of primitive types¶
- Users are allowed to create additional fields of 5 primitive types:
- IntegerField
- FloatField
- FlexibleBooleanField
- StringField
- Link
First four are taken from oslo.versionedobjects directly, Link is a glare-specific field which stores links in specific format to other artifacts in the system.
Note
It’s recommended to use FlexibleBoolean field instead of just Boolean, because it has more sophisticated coercing. For instance, it accepts string parameters like “true”, “yes”, “1” and so on, and successfully coerces it to boolean value True.
Users can create their own fields with method init
from Attribute class.
This method’s first parameter must be an appropriate field class, other
parameters are optional and will be discussed later. In next example we
will create 5 new custom fields, one for each primitive type:
from oslo_versionedobjects import fields from glare.objects import base from glare.objects.meta import wrappers from glare.objects.meta import fields as glare_fields Field = wrappers.Field.init class HelloWorld(base.BaseArtifact): @classmethod def get_type_name(cls): return "hello_worlds" fields = { 'my_int': Field(fields.IntegerField), 'my_float': Field(fields.FloatField), 'my_bool': Field(fields.FlexibleBooleanField), 'my_string': Field(fields.StringField), 'my_link': Field(glare_fields.Link) }
Compound types¶
There are two collections, that may contain fields of primitive types:
List and Dict. Fields of compound types are created with method init
of classes ListAttribute and DictAttribute respectively.
Unlike Attribute class’ init
, this method takes field type class as
a first parameter, but not just field class. So, IntegerField must be changed
to Integer, FloatField to Float, and so on. Finally for collection of
links user should use LinkType. Let’s add several new compound fields to
HelloWorld class.
from oslo_versionedobjects import fields from glare.objects import base from glare.objects.meta import wrappers from glare.objects.meta import fields as glare_fields Field = wrappers.Field.init Dict = wrappers.DictField.init List = wrappers.ListField.init class HelloWorld(base.BaseArtifact): @classmethod def get_type_name(cls): return "hello_worlds" fields = { ... 'my_list_of_str': List(fields.String), 'my_dict_of_int': Dict(fields.Integer), 'my_list_of_float': List(fields.Float), 'my_dict_of_bools': Dict(fields.FlexibleBoolean), 'my_list_of_links': List(glare_fields.LinkType) }
Other parameters, like collection max size, possible item values,
and so on, also can be specified with additional parameters to init
method. They will be discussed later.
Blob and Folder types¶
The most interesting fields in glare framework are Blob and Folder (or BlobDict). These fields allow users to work binary data, which is stored in a standalone cloud storage, like Swift or Ceph. The difference between Blob and Folder is that Blob sets unique endpoint and may contain only one binary object, on the other hand Folder may contain lots of binaries with names specified by user.
Example of Blob and Folder fields:
from oslo_versionedobjects import fields from glare.objects import base from glare.objects.meta import wrappers from glare.objects.meta import fields as glare_fields Field = wrappers.Field.init Dict = wrappers.DictField.init List = wrappers.ListField.init Blob = wrappers.BlobField.init Folder = wrappers.FolderField.init class HelloWorld(base.BaseArtifact): @classmethod def get_type_name(cls): return "hello_worlds" fields = { ... 'my_blob': Blob(), 'my_folder': Folder(), }