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 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.
- graph_pattern(query=False, 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 openSet()[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(query=False, visited_list=False)[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[source]¶
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.DataObjectType
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
- 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: builtins.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: builtins.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().
- __weakref__¶
list of weak references to the object (if defined)
- class yarom.configure.Configuration(**kwargs)[source]¶
Bases: builtins.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[source]¶
Bases: builtins.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 at 0x7ff38dbe50f0>¶
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: builtins.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[source]¶
Bases: builtins.object
An object which can be included in the object graph.
- defined()[source]¶
Returns true if an identifier() would return an identifier
- identifier()[source]¶
Must return an rdflib.term.URIRef object representing this object or else raise an Exception.
- __weakref__¶
list of weak references to the object (if defined)
- class yarom.graphObject.Legends(start, graph=None)[source]¶
Bases: builtins.object
Gets a list of the objects which can not be deleted freely from the transitive closure.
“Heroes get remembered, but legends never die.”
- __weakref__¶
list of weak references to the object (if defined)
- 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 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.
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.
Questions/concerns?¶
Bug reports and questions can be posted to the issue tracker on Github.