KTBS engine

I provide an implementation of the kTBS engine.

This implementation is defined as a rdfrest.cores.local.Service; it reuses the mix-in classes defined in ktbs.api.

To obtain a KTBS engine conforming with the Ktbs interface of the Abstract KTBS API, use service.make_ktbs().

Service implementation

I provide an entry point to create a local kTBS.

ktbs.engine.service.make_ktbs(root_uri=None, repository=None, create=None)[source]

I create a kTBS engine conforming with the Abstract KTBS API.

Parameters:
  • root_uri – the URI to use as the root of this kTBS (defaults to <ktbs:/>)
  • repository – where to store kTBS data
  • create – whether the data repository should be initialized; (see below)

Parameter repository can be either a path (in which case data will be stored in a directory of that name, which will be created if needed), or a string of the form ":store_type:configuration_string" where store_type is a registered store type in rdflib, and configuration_string is used to initialize this store.

If repository is omitted or None, a volatile in-memory repository will be created.

If the repository is in-memory or a non-existing path, it will be initialized. In all other cases (i.e. existing path or explicit store_type), the repository is assumed to be already initialized; the force-init option in the rdf_database section can be set to force the initialization in those cases.

class ktbs.engine.service.KtbsService(service_config=None)[source]

The KTBS service.

get(uri, rdf_types=None, _no_spawn=False)[source]

I override rdfrest.cores.local.Service.get()

If the original implementation returns None, I try to make an Obsel.

classmethod init_ktbs(service)[source]

I populate the root resource’s graph of a new service.

Resource implementation

Inheritance diagram of ktbs.engine.resource

I provide the common implementation of all local KTBS resources.

class ktbs.engine.resource.KtbsResource(service, uri)[source]

I provide common methods and class parameters for all KTBS Resources.

Especially, I include a number of of required other mixins.

classmethod mint_uri(target, new_graph, created, basename=None, suffix='')[source]

I override rdfrest.cores.local.ILocalCore.mint_uri().

I use the skos:prefLabel of the resource to mint a URI, else the basename (if provided), else the class name.

class ktbs.engine.resource.KtbsPostableMixin(service, uri)[source]

I implement the common post-related functionalities for KtbsResources.

check_posted_graph(parameters, created, new_graph)[source]

I implement rdfrest.cores.local.GraphPostableMixin.check_posted_graph().

KtbsRoot implementation

Inheritance diagram of ktbs.engine.ktbs_root

I provide the implementation of ktbs:KtbsRoot .

class ktbs.engine.ktbs_root.KtbsRoot(service, uri)[source]

I provide the implementation of ktbs:KtbsRoot .

delete(parameters=None, _trust=True)[source]

I override rdfrest.util.EditableCore.delete().

A kTBS root can never be deleted.

ack_post(parameters, created, new_graph)[source]

I override rdfrest.util.GraphPostableMixin.ack_post().

find_created(new_graph)[source]

I override rdfrest.util.GraphPostableMixin.find_created().

I look for the ktbs:hasBase property, pointing to a ktbs:Base.

Base implementation

Inheritance diagram of ktbs.engine.base

I provide the implementation of ktbs:Base .

class ktbs.engine.base.Base(service, uri)[source]

I provide the implementation of ktbs:Base .

get_state(parameters=None)[source]

I override get_state()

I support parameter “prop” to enrich the Base description with additional information. I consider an empty dict as equivalent to no dict.

check_parameters(to_check, parameters, method)[source]

I implement check_parameters()

I also convert parameters values from strings to usable datatypes.

ack_delete(parameters)[source]

I override rdfrest.util.EditableCore.ack_delete().

ack_post(parameters, created, new_graph)[source]

I override rdfrest.util.GraphPostableMixin.ack_post().

check_deletable(parameters)[source]

I override rdfrest.util.EditableCore.check_deletable().

Only an empty base can be deleted.

find_created(new_graph)[source]

I override rdfrest.util.GraphPostableMixin.find_created().

I look for the ktbs:contains property, pointing to something a base can contain.

classmethod create_lock(uri)[source]

I override WithLockMixin.create_lock.

As base creation is protected by the KtbsRoot lock, we are sure that this method can not be called concurrently. So rather than taking the existing semaphore as is and hoping it is correctly set, we force it to 1.

That way, if a previous kTBS didn’t clean up its semaphores, it won’t block a new instance.

class ktbs.engine.base.InBase(service, uri)[source]

I provide common implementation of all elements contained in a base.

ack_delete(parameters)[source]

I override rdfrest.util.DeletableMixin.ack_delete().

delete(parameters=None, _trust=False)[source]

I override rdfrest.cores.local.EditableCore.delete().

edit(*args, **kwds)[source]

I override rdfrest.cores.local.EditableCore.edit().

TraceModel implementation

Inheritance diagram of ktbs.engine.trace_model

I provide the implementation of ktbs:TraceModel .

class ktbs.engine.trace_model.TraceModel(service, uri)[source]

I provide the implementation of ktbs:TraceModel .

classmethod complete_new_graph(service, uri, parameters, new_graph, resource=None)[source]

I implement ILocalCore.complete_new_graph().

At create time, I add default values for missing information about the trace model.

Trace implementation

Inheritance diagram of ktbs.engine.trace

I provide the implementation of ktbs:StoredTrace and ktbs:ComputedTrace .

class ktbs.engine.trace.AbstractTrace(service, uri)[source]

I provide the implementation of ktbs:AbstractTrace .

unit

I return this trace’s time unit.

I get it from the model if available, and store it in the trace’s metadata in case the model is not available.

obsel_collection

I override api.trace.AbstractTrace.obsel_collection.

Instead of an OpportunisticObselCollection, I return the actual resource, as there is no need to optimize transfer in a local implementation.

classmethod check_new_graph(service, uri, parameters, new_graph, resource=None, added=None, removed=None)[source]

I implement check_new_graph()

I check that the sources exist and are in the same base.

classmethod create(service, uri, new_graph)[source]

I implement create()

I create the obsel collection and the statistics resource associated with this trace, and I notify this trace’s sources.

prepare_edit(parameters)[source]

I overrides rdfrest.cores.local.ILocalCore.prepare_edit()

I store old values of some properties (sources, pseudomon range) to handle the change in ack_edit().

ack_edit(parameters, prepared)[source]

I overrides rdfrest.cores.local.ILocalCore.ack_edit()

I reflect changes in the related resources (sources, obsel collection).

check_deletable(parameters)[source]

I implement check_deletable()

I refuse to be deleted if I am the source of another trace.

ack_delete(parameters)[source]

I implement ack_delete()

class ktbs.engine.trace.StoredTrace(service, uri)[source]

I provide the implementation of ktbs:StoredTrace .

classmethod check_new_graph(service, uri, parameters, new_graph, resource=None, added=None, removed=None)[source]

I implement check_new_graph()

I check the temporal extension of this trace.

classmethod complete_new_graph(service, uri, parameters, new_graph, resource=None)[source]

I implement ILocalCore.complete_new_graph().

At create time, I add default values for missing information about the trace.

check_new(created)[source]

I override GraphPostableMixin.check_new().

I check if the created resource exists in my obsel collection.

post_graph(graph, parameters=None, _trust=False, _created=None, _rdf_type=None)[source]

I override rdfrest.util.GraphPostableMixin.post_graph().

I allow for multiple obsels to be posted at the same time.

get_created_class(rdf_type)[source]

I override rdfrest.cores.mixins.GraphPostableMixin.get_created_class Only obsels can be posted to a trace.

class ktbs.engine.trace.ComputedTrace(service, uri)[source]

I provide the implementation of ktbs:ComputedTrace .

classmethod create(service, uri, new_graph)[source]

I implement AbstractTrace.create()

I notify this trace’s method, and I ensure that it is run once to compute the computed properties (model, origin) of this trace.

prepare_edit(parameters)[source]

I overrides rdfrest.cores.local.ILocalCore.prepare_edit()

I store old values of some properties (parameters, method) to handle the change in ack_edit().

ack_edit(parameters, prepared)[source]

I overrides rdfrest.cores.local.ILocalCore.ack_edit()

I reflect changes in the related resources (method, obsel collection).

ack_delete(parameters)[source]

I override ack_delete()

I notify my method that I’m no longer using it.

get_state(parameters=None)[source]

I override get_state()

I systematically call force_state_refresh() to ensure all computations have been performed.

force_state_refresh(parameters=None)[source]

I override force_state_refresh()

I recompute my data if needed.

Obsel implementation

Inheritance diagram of ktbs.engine.obsel

I provide the implementation of ktbs:Obsel .

class ktbs.engine.obsel.Obsel(trace, uri)[source]

I provide the implementation of ktbs:Obsel .

ktbs.engine.obsel.get_obsel_bounded_description(node, graph, fill=None)[source]

I override rdfrest.util.bounded_description() for obsels.

In order to clearly differenciate attributes from relations, related obsels must be linked to the trace by the ktbs:hasTrace.

Parameters:
  • node – the node (uri or blank) to return a description of
  • graph – the graph from which to retrieve the description
  • fill – if provided, fill this graph rather than a fresh one, and return it

Method implementation

Inheritance diagram of ktbs.engine.method

I provide the implementation of ktbs:Method .

class ktbs.engine.method.Method(service, uri)[source]

I provide the implementation of ktbs:Method .

classmethod create(service, uri, new_graph)[source]

I implement create()

classmethod complete_new_graph(service, uri, parameters, new_graph, resource=None)[source]

I implement ILocalCore.complete_new_graph().

I handle the deprecated property ktbs:inherits, replacing it with ktbs:hasParentMethod

classmethod check_new_graph(service, uri, parameters, new_graph, resource=None, added=None, removed=None)[source]

I overrides rdfrest.cores.local.ILocalCore.check_new_graph()

I check that parent and parameters are acceptable

prepare_edit(parameters)[source]

I overrides rdfrest.cores.local.ILocalCore.prepare_edit()

I store old values of some properties (parent, parameters) to handle the change in ack_edit().

ack_edit(parameters, prepared)[source]

I overrides rdfrest.cores.local.ILocalCore.ack_edit()

I reflect changes in the related resources (parent method)

ack_delete(parameters)[source]

I overrides rdfrest.cores.local.ILocalCore.ack_delete()

check_deletable(parameters)[source]

I implement check_deletable()

I refuse to be deleted if I am used by a trace.

BuiltinMethod implementation

I implement a built-in method registry.

ktbs.engine.builtin_method.iter_builtin_method_impl()[source]

I return an iterable of all supported built-in methods.

ktbs.engine.builtin_method.register_builtin_method_impl(implementation)[source]

I register the implementation of a builtin method.

ktbs.engine.builtin_method.unregister_builtin_method_impl(implementation)[source]

I unresgister the implementation of a builtin method.

ktbs.engine.builtin_method.get_builtin_method_impl(uri, _return_fake=False)[source]

I return the implementation of a given built-in method.

If no such implementation is found, I return None, unless return_fake is True; in the latter case, I return a fake implementation object that will fail to perform any computation.

TraceObsels implementation

Inheritance diagram of ktbs.engine.trace_obsels

I provide the implementation of kTBS obsel collections.

class ktbs.engine.trace_obsels.AbstractTraceObsels(service, uri)[source]

I provide the implementation of ktbs:AbstractTraceObsels

classmethod init_graph(graph, obsels_uri, trace_uri)[source]

I populate graph as an empty obsel collection for the given trace.

get_etag()[source]

Return the entity tag.

This tag changes at every modification of the obsel collection.

set_etag(val)[source]

Set the etag.

See-also:get-etag()
etag

Return the entity tag.

This tag changes at every modification of the obsel collection.

get_str_mon_tag()[source]

Return the strictly monotonic tag.

This tag only changes when the obsel collection is modified in a non-strictly monotonic way.

In other words, it does not change as long as obsels are added after all existing obsels, without any relation to previous obsels.

set_str_mon_tag(val)[source]

Set the str_mon_tag.

See-also:get-str_mon_tag()
str_mon_tag

Return the strictly monotonic tag.

This tag only changes when the obsel collection is modified in a non-strictly monotonic way.

In other words, it does not change as long as obsels are added after all existing obsels, without any relation to previous obsels.

get_pse_mon_tag()[source]

Return the pseudo-monotonic tag.

This tag only changes when the obsel collection is modified in a non-pseudo-monotonic way.

In other words, it does not change as arcs are only added between obsels withing the pseudo-monotonicity range (see get_pseudomon_range>()) of the trace.

set_pse_mon_tag(val)[source]

Set the pse_mon_tag.

See-also:get-pse_mon_tag()
pse_mon_tag

Return the pseudo-monotonic tag.

This tag only changes when the obsel collection is modified in a non-pseudo-monotonic way.

In other words, it does not change as arcs are only added between obsels withing the pseudo-monotonicity range (see get_pseudomon_range>()) of the trace.

get_log_mon_tag()[source]

Return the logically monotonic tag.

This tag only changes when the obsel collection is modified in a non-monotonic way.

In other words, it does not change as long as arcs are only added to the graph, not removed.

set_log_mon_tag(val)[source]

Set the log_mon_tag.

See-also:get-log_mon_tag()
log_mon_tag

Return the logically monotonic tag.

This tag only changes when the obsel collection is modified in a non-monotonic way.

In other words, it does not change as long as arcs are only added to the graph, not removed.

add_obsel_graph(graph, _trust=True)[source]

Add an obsel described in graph.

If you need to add only one obsel, you can use this method without using any edit() context.

If you need to call this method multiple time, it is more efficient to wrap all the calls to add_obsel_graph inside a single edit() context, which then must have the add_obsels_only parameter set.

This should be used instead of the edit() context when no arc has to be removed, as it will not change the log_mon_tag:meth`.

get_state(parameters=None)[source]

I override get_state()

I support some parameters to get “slices” of the obsel collection. Note that, contrarily to what the interface specifies, slice graphs are static copies of the data; they are not automatically updated, and the slicing parameters are not supported by ~rdfrest.cores.ICore.force_state_refresh:meth.

I consider an empty dict as equivalent to no dict.

check_parameters(to_check, parameters, method)[source]

I implement check_parameters()

I also convert parameters values from strings to usable datatypes.

prepare_edit(parameters)[source]

I overrides rdfrest.cores.local.ILocalCore.prepare_edit()

I store old values related to monotonicity. change in ack_edit().

ack_edit(parameters, prepared)[source]

I override rdfrest.cores.local.ILocalCore.ack_edit() to update bookkeeping metadata and force transformed trace to refresh.

delete(parameters=None, _trust=False)[source]

I override KtbsResource.delete().

Deleting an obsel collection simply empties it, but does not actually destroy the resource.

iter_etags(parameters=None)[source]

I override rdfrest.cores.mixins.BookkeepingMixin._iter_etags()

I return self.etag, plus the appropriate monotonicity tag depending on the given parameters.

IMPORTANT: the only parameter actually used to determine monotonicity etags are ‘maxe’ and ‘before’, as it would be too costly to determine it for other parameters. Note however that get_state() does use this method with an accurate ‘maxe’ value (based on the actual obsels rather than on paremeters), in order to precisely get etags.

class ktbs.engine.trace_obsels.StoredTraceObsels(service, uri)[source]

I provide the implementation of ktbs:StoredTraceObsels

class ktbs.engine.trace_obsels.ComputedTraceObsels(service, uri)[source]

I provide the implementation of ktbs:ComputedTraceObsels

get_state(parameters=None)[source]

I override get_state()

I support parameter ‘refresh’ to bypass the updating of the obsels, or force a recomputation of the trace.

force_state_refresh(parameters=None)[source]

I override force_state_refresh()

I recompute the obsels if needed.

edit(parameters=None, clear=False, _trust=False)[source]

I override KtbsResource.edit().

delete(parameters=None, _trust=False)[source]

I override AbstractTraceObsels.delete().

You can not empty a computed trace.