Welcome to yarom‘s documentation!

API

Most statements correspond to some action on the database. Some of these actions may be complex, but intuitively a.B(), the Query form, will query against the database for the value or values that are related to a through B; on the other hand, a.B(c), the Update form, will add a statement to the database that a relates to c through B. For the Update form, a Relationship object describing the relationship stated is returned as a side-effect of the update.

The Update form can also be accessed through the set() method of a Property and the Query form through the get() method like:

a.B.set(c)

and:

a.B.get()

The get() method also allows for parameterizing the query in ways specific to the Property.

Notes:

  • Of course, when these methods communicate with an external database, they may fail due to the database being unavailable and the user should be notified if a connection cannot be established in a reasonable time. Also, some objects are created by querying the database; these may be made out-of-date in that case.
  • a : {x_0,...,x_n} means a could have the value of any one of x_0 through x_n

Classes

class yarom.dataObject.DataObject(ident=False, var=False, key=False, generate_key=False, **kwargs)[source]

Bases: yarom.graphObject.GraphObject, yarom.dataUser.DataUser

An object backed by the database

Attributes

rdf_type (rdflib.term.URIRef) The RDF type URI for objects of this type
rdf_namespace (rdflib.namespace.Namespace) The rdflib namespace (prefix for URIs) for objects from this class
properties (list of Property) Properties belonging to this object
owner_properties (list of Property) Properties belonging to parents of this object
__init__(ident=False, var=False, key=False, generate_key=False, **kwargs)[source]

A subclass of DataObject cannot have any required positional arguments.

Parameters:

ident : rdflib.term.URIRef or str

The identifier for this DataObject

var : str

In lieu of ident, sets the variable for this object

key : str or object

In lieu of ident or var, sets the identifier for this DataObject using the key value. For a namespace ex: and key a, the identifier would be ex:a.

generate_key : bool

If true generates a random key value

kwargs : dict

Values to set for named properties

defined_augment()[source]

This fuction must return False if identifier_augment() would raise an IdentifierMissingException. Override it when defining a non-standard identifier for subclasses of DataObjects.

get_owners(property_name)[source]

Return the owners along a property pointing to this object

graph_pattern(shorten=False)[source]

Get the graph pattern for this object.

It should be as simple as converting the result of triples() into a BGP

Parameters:

query : bool

Indicates whether or not the graph_pattern is to be used for querying (as in a SPARQL query) or for storage

shorten : bool

Indicates whether to shorten the URLs with the namespace manager attached to the self

identifier()[source]

The identifier for this object in the rdf graph.

This identifier may be randomly generated, but an identifier returned from the graph can be used to retrieve the specific object that it refers to.

If it is desireable to customize the identifier, a subclass of DataObject should override identifier_augment() rather than this method.

Returns:rdflib.term.URIRef
identifier_augment()[source]

Override this method to define an identifier in lieu of one explicity set.

One must also override defined_augment() to return True whenever this method could return a valid identifier. IdentifierMissingException should be raised if an identifier cannot be generated by this method.

Raises:IdentifierMissingException
classmethod open_set()[source]

The open set contains items that must be saved directly in order for their data to be written out

retract()[source]

Remove this object from the data store.

Retract removes an object and everything it points to, transitively, and everything which points to it.

Dual to save.

retract_object()[source]

Remove this object from the data store.

Retract removes an object and everything it points to, transitively, and everything which points to it.

Dual to save_object.

retract_objectG()[source]

Remove this object from the data store.

Retract removes an object and everything it points to, transitively, and everything which points to it.

Dual to save_objectG.

retract_references()[source]

Remove all references directly to or made by this object

retract_referencesG()[source]

Remove all references directly to or made by this object

save()[source]

Write in-memory data to the database. Derived classes should call this to update the store.

Dual to retract.

save_object()[source]

Write in-memory data to the database. Derived classes should call this to update the store.

Dual to retract_object.

triples()[source]

Returns 3-tuples of the connected component of the object graph starting from this object.

Returns:An iterable of triples
variable()[source]

Returns the variable to be usedin queries with this DataObject

Raises:IdentifierMissingException
defined

Returns True if this object has an identifier

To define a custom identifier, override defined_augment() to return True when your custom identifier would be defined. You must also override identifier_augment()

class yarom.dataObject.ObjectCollection(group_name=False, **kwargs)[source]

Bases: yarom.dataObject.DataObject

A convenience class for working with a collection of objects

Example:

v = ObjectCollection('unc-13 neurons and muscles')
n = P.Neuron()
m = P.Muscle()
n.receptor('UNC-13')
m.receptor('UNC-13')
for x in n.load():
    v.value(x)
for x in m.load():
    v.value(x)
# Save the group for later use
v.save()
...
# get the list back
u = ObjectCollection('unc-13 neurons and muscles')
nm = list(u.value())
Parameters:

group_name : string

A name of the group of objects

Attributes

name (DatatypeProperty) The name of the group of objects
group_name (DataObject) an alias for name
member (ObjectProperty) An object in the group
add (ObjectProperty) an alias for value
class yarom.dataObject.PropertyDataObject(ident=False, var=False, key=False, generate_key=False, **kwargs)[source]

Bases: yarom.dataObject.DataObject

A PropertyDataObject represents the property-as-object.

Try not to confuse this with the Property class

class yarom.dataObject.RDFProperty[source]

Bases: yarom.dataObject.DataObjectSingleton

The DataObject corresponding to rdf:Property

class yarom.dataObject.RDFSClass[source]

Bases: yarom.dataObject.DataObjectSingleton

The DataObject corresponding to rdfs:Class

yarom.dataObject.validate(do_type)[source]

Given a DataObject type, call validate() on all objects of that type in the RDF object graph

yarom.dataObject.validateG(do_type)[source]

Given a DataObject type, call validate() on all objects of that type in the Python object graph

class yarom.dataUser.DataUser(**kwargs)[source]

Bases: yarom.configure.Configureable

A convenience wrapper for users of the database

Classes which use the database should inherit from DataUser.

add_statements(graph)[source]

Add a set of statements to the database.

Annotates the addition with uploader name, etc

Parameters:

triples : iter of (rdflib.term.URIRef, rdflib.term.URIRef, rdflib.term.URIRef)

A set of triples to add to the graph

retract_statements(statements)[source]

Remove a set of statements from the database.

Parameters:

triples : iter of (rdflib.term.URIRef, rdflib.term.URIRef, rdflib.term.URIRef)

A set of triples to remove

class yarom.data.Data(conf=False)[source]

Bases: yarom.configure.Configuration, yarom.configure.Configureable

Provides configuration for access to the database.

Usally doesn’t need to be accessed directly

closeDatabase()[source]

Close a the configured database

classmethod open(file_name)[source]

Open a file storing configuration in a JSON format

openDatabase()[source]

Open a the configured database

class yarom.data.RDFSource(**kwargs)[source]

Bases: yarom.configure.ConfigValue, yarom.configure.Configureable

Base class for data sources.

Alternative sources should dervie from this class

open()[source]

Called on yarom.connect() to set up and return the rdflib graph. Must be overridden by sub-classes.

class yarom.data.SerializationSource(**kwargs)[source]

Bases: yarom.data.RDFSource

Reads from an RDF serialization or, if the configured database is more recent, then from that.

The database store is configured with:

"rdf.source" = "serialization"
"rdf.store" = <your rdflib store name here>
"rdf.serialization" = <your RDF serialization>
"rdf.serialization_format" = <your rdflib serialization format used>
"rdf.store_conf" = <your rdflib store configuration here>
class yarom.data.TrixSource(**kwargs)[source]

Bases: yarom.data.SerializationSource

A SerializationSource specialized for TriX

The database store is configured with:

"rdf.source" = "trix"
"rdf.trix_location" = <location of the TriX file>
"rdf.store" = <your rdflib store name here>
"rdf.store_conf" = <your rdflib store configuration here>
class yarom.data.SPARQLSource(**kwargs)[source]

Bases: yarom.data.RDFSource

Reads from and queries against a remote data store

"rdf.source" = "sparql_endpoint"
class yarom.data.SleepyCatSource(**kwargs)[source]

Bases: yarom.data.RDFSource

Reads from and queries against a local Sleepycat database

The database can be configured like:

"rdf.source" = "Sleepycat"
"rdf.store_conf" = <your database location here>
class yarom.data.DefaultSource(**kwargs)[source]

Bases: yarom.data.RDFSource

Reads from and queries against a configured database.

The default configuration.

The database store is configured with:

"rdf.source" = "default"
"rdf.store" = <your rdflib store name here>
"rdf.store_conf" = <your rdflib store configuration here>

Leaving unconfigured simply gives an in-memory data store.

class yarom.data.ZODBSource(*args, **kwargs)[source]

Bases: yarom.data.RDFSource

Reads from and queries against a configured Zope Object Database.

If the configured database does not exist, it is created.

The database store is configured with:

"rdf.source" = "ZODB"
"rdf.store_conf" = <location of your ZODB database>

Leaving unconfigured simply gives an in-memory data store.

exception yarom.configure.BadConf[source]

Bases: Exception

Special exception subclass for alerting the user to a bad configuration

__weakref__

list of weak references to the object (if defined)

class yarom.configure.ConfigValue[source]

Bases: object

A value to be configured.

Elements of a Configuration are, in fact, ConfigValue objects. They can be resolved an arbitrary time after the Configuration object is created by calling get().

get()[source]

Override this method to return a value when a configuration variable is accessed

__weakref__

list of weak references to the object (if defined)

class yarom.configure.Configuration(**kwargs)[source]

Bases: object

A simple configuration object. Enables setting and getting key-value pairs

copy(other)[source]

Copy configuration values from a different object.

Parameters:

other : dict or Configuration

A dict or Configuration object to copy the configuration from

Returns:

self

get(pname, default=None)[source]

Retrieve a configuration value.

Parameters:

pname : str

The key of the value to return.

default : object

The value to return if there is no value corresponding to the given key

Returns:

object

The value corresponding to the key in pname or default if none is available and a default is provided.

Raises:

KeyError

If the given key has no associated value and no default is provided

Call link() with the names of configuration values that should always be the same to link them together

classmethod open(file_name)[source]

Open a configuration file and read it to build the internal state.

Parameters:

file_name : str

The name of a configuration file encoded as JSON

Returns:

Configuration

a Configuration object with the configuration taken from the JSON file

__weakref__

list of weak references to the object (if defined)

class yarom.configure.Configureable(conf=None)[source]

Bases: object

An object which can be configured.

A Configureable object can access a Configuration object, Configureable.conf, which is shared among all Configureable objects.

The configuration variables which can affect the behavior of a class should be documented in the configuration_variables class variable. This table will be checked on each access of Configureable.conf

__weakref__

list of weak references to the object (if defined)

conf = <yarom.data.Data object>

The configuration

configuration_variables = {}

A table of configuration values used by the Configureable object for the purpose of documentation.

The table is indexed by the configuration value. Among the data included in the table should be:

  • a “description” which describes how the configuration value is used within the configureable object: broad generalization about the variable shouldn’t be here.
  • a “type” for the value of the config may also be included and may be a Python type or just a string description. This isn’t at all intended to be used for type checking, but is purely descriptive.
  • a “directly_configureable” indicator which should be set to True if the value passed in to the object for configuration variable is used more-or- less directly by the object. Sanitization of the value or translation into a more specific form are acceptable for a variable that is nonetheless directly_configureable. On the other hand, a configuration variable that has its value set within the object should have directly_configureable set to False.
exception yarom.graphObject.IdentifierMissingException(dataObject='[unspecified object]', *args, **kwargs)[source]

Bases: Exception

Indicates that an identifier should be available for the object in question, but there is none

__weakref__

list of weak references to the object (if defined)

class yarom.graphObject.GraphObject(**kwargs)[source]

Bases: object

An object which can be included in the object graph.

An abstract base class.

identifier()[source]

Must return an object representing this object or else raise an Exception.

variable()[source]

Must return a Variable object that identifies this GraphObject in queries.

The variable can be randomly generated when the object is created and stored in the object.

__weakref__

list of weak references to the object (if defined)

defined

Returns true if an identifier() would return an identifier

class yarom.graphObject.GraphObjectQuerier(q, graph)[source]

Bases: object

Performs queries for objects in the given graph.

The querier queries for objects at the center of a star graph. In SPARQL, the query has the form:

SELECT ?x WHERE {
    ?x  <p1> ?o1 .
    ?o1 <p2> ?o2 .
     ...
    ?on <pn> <a> .

    ?x  <q1> ?n1 .
    ?n1 <q2> ?n2 .
     ...
    ?nn <qn> <b> .
}

It is allowed that <px> == <py> for x != y.

Queries such as:

SELECT ?x WHERE {
    ?x  <p1> ?o1 .
     ...
    ?on <pn>  ?y .
}

or:

SELECT ?x WHERE {
    ?x  <p1> ?o1 .
     ...
    ?on <pn>  ?x .
}

or:

SELECT ?x WHERE {
    ?x  ?z ?o .
}

or:

SELECT ?x WHERE {
    ?x  ?z <a> .
}

are not supported and will be ignored without error.

__init__(q, graph)[source]

Initialize the querier.

Call the GraphObjectQuerier object to perform the query.

Parameters:

q : GraphObject

The object which is queried on

graph : object

The graph from which the objects are queried. Must implement a method triples() that takes a triple pattern, t, and returns a set of triples matching that pattern. The pattern for t is t[i] = None, 0 <= i <= 2, indicates that the i’th position can take any value.

__weakref__

list of weak references to the object (if defined)

class yarom.graphObject.ComponentTripler(start)[source]

Bases: object

Gets a set of triples with given graph object in the first or last position.

The ComponentTripler does not query against a backing graph, but instead uses the properties attached to the object.

__weakref__

list of weak references to the object (if defined)

class yarom.mapper.MappedClass(name, bases, dct)[source]

Bases: type

A type for MappedClasses

Sets up the graph with things needed for MappedClasses

deregister()[source]

Removes the class from the object graph.

Should make it possible to garbage collect

deregister() never touches the RDF graph itself.

classmethod make_class(name, bases, objectProperties=False, datatypeProperties=False)[source]

Intended to be used for setting up a class from the RDF graph, for instance.

map()[source]

Maps the class to the configured rdf graph.

register()[source]

Sets up the object graph related to this class

regsister() never touches the RDF graph itself.

Also registers the properties of this DataObject

unmap()[source]

Unmaps the class

yarom.mapper.get_most_specific_rdf_type(types)[source]

Gets the most specific rdf_type.

Returns the URI corresponding to the lowest in the DataObject class hierarchy from among the given URIs.

yarom.mapper.oid(identifier_or_rdf_type, rdf_type=False)[source]

Create an object from its rdf type

Parameters:

identifier_or_rdf_type : str or rdflib.term.URIRef

If rdf_type is provided, then this value is used as the identifier for the newly created object. Otherwise, this value will be the rdf_type of the object used to determine the Python type and the object’s identifier will be randomly generated.

rdf_type : str, rdflib.term.URIRef, False

If provided, this will be the rdf_type of the newly created object.

Returns:

The newly created object

yarom.connect(conf=False, do_logging=False, data=False, dataFormat='n3')[source]

Load desired configuration and open the database

Parameters:

conf : str, Data, Configuration or dict, optional

The configuration for the YAROM connection

do_logging : bool, optional

If True, turn on debug level logging. The default is False.

data : str, optional

If provided, specifies a file to load into the library.

dataFormat : str, optional

If provided, specifies the file format of the file pointed specified by data.

The formats available are those accepted by RDFLib’s serializer plugins. ‘n3’ is the default.

yarom.disconnect(c=False)[source]

Close the database

yarom.loadConfig(f)[source]

Load configuration for the module

yarom.setConf(conf)[source]

Set the configuration

Parameters:

conf : str, Data, Configuration or dict, optional

The configuration to load.

If a Data object is provided, then it’s used as is for the configuration. If either a Python dict or a Configuration object are provided, then the contents of that object is used to make a Data object for configuration. If a string is provided, then the file is read in as JSON to be parsed as a dict and from there is treated as if you had passed that dict to connect.

The default action is to attempt to open a file called ‘yarom.conf’ from your current directory as the configuration. Failing that, an ‘empty’ config with default values will be loaded.

Questions/concerns?

Bug reports and questions can be posted to the issue tracker on Github.

Indices and tables