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}
meansa
could have the value of any one ofx_0
throughx_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 anIdentifierMissingException
. Override it when defining a non-standard identifier for subclasses of DataObjects.
-
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.
-
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 overrideidentifier_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.
-
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
-
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
-
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 theConfiguration
object is created by callingget()
.-
__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
-
link
(*names)[source]¶ 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 aConfiguration
object,Configureable.conf
, which is shared among allConfigureable
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 ofConfigureable.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 toFalse
.
-
-
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.
-
variable
()[source]¶ Must return a
Variable
object that identifies thisGraphObject
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>
forx != 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 fort
ist[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.
-
-
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
orrdflib.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
ordict
, optionalThe 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.
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.