OldMan: Python OLDM¶

Why a new term?¶

Some similar projects employ the term Object RDF Mapper for denoting the mapping between objects and RDF graphs. This terminology uses the same initials than the well-known notion of Object Relational Mapper (ORM) that consider table rows instead of RDF graphs.

The Object Linked Data Mapper (OLDM) term avoids this confusion. It also emphasizes that the manipulated resources are supposed to be on the Web, not just in a local database. It should lead users to interact with data stores on which they not always have full control (e.g. a tiers Web API).

Mission¶

OldMan has one main objective: help you to declare your models using RDF triples and JSON-LD contexts instead of programming Python model classes yourself.

However, OldMan does not force you to express all your domain logic in a declarative style. OldMan makes easy for you to add dynamically plain-old Python methods to resource objects.

By adopting a declarative style:

1. You can provide both RDF and JSON data to your clients.
2. Your schema (including validation constraints) can be published and reused by hypermedia-driven Web clients.
3. Your declared domain logic becomes independent of Python and its frameworks.

It also acknowledges that IRIs or compact URIs (CURIEs) -like strings are not always pleasant to use: arbitrary short names and objects are usually more user-friendly. However, you can still manipulate IRIs when it is relevant for you to do so. Everything remains mapped to IRIs.

Current core features¶

• Resource-centric validation based on RDF vocabularies:

  • Hydra: hydra:required , hydra:readonly and hydra:writeonly;
  • Literal validation for common XSD types;
  • Literal validation for arbitrary property (e.g. foaf:mbox);
  • JSON-LD collections (set, list and language maps);

• IRI generation for new resources (objects);

• Inheritance (attributes and Python methods);

• An attribute can require its value to be a collection (a set, a list or a language map);

• Arbitrary attribute names (e.g. plural names for collections);

• Extensibility to various sorts of data stores (not just SPARQL endpoints);

• Optional resource cache relying on the popular dogpile.cache library.

Status¶

OldMan is a young project under active development started in April 2014. Feel free to join us on Github and to subscribe to our mailing list oldman AT librelist.com.

Only Python 2.7 is currently supported, but support for Python 3.x is of course something we would like to consider.

Planned features¶

See our issue tracker.

Continue to installation or the quickstart.

Virtualenv¶

Because OldMan is still a young project, you will have to use development versions of some external libraries, such as RDFlib.

Thus, we recommend you to isolate the installation of OldMan and its dependencies by using Virtualenv.

If virtualenv is not already installed on your computer, you can install it with easy_install or pip:

$ sudo easy_install-2.7 install virtualenv

or:

$ sudo pip2 install virtualenv

Now create a directory where to install your virtualenv. For instance:

$ mkdir -p ~/envs/oldman-2.7

Move in, init and activae your virtualenv:

$ cd ~/envs/oldman-2.7
$ virtualenv2 .
$ source bin/activate

Install OldMan and its dependencies¶

$ mkdir src
$ cd src
$ git clone https://github.com/oldm/OldMan.git oldman
$ cd oldman

Install first the concrete requirements:

$ pip install -r requirements.txt

And then install oldman and its abstract (not yet fulfilled) dependencies:

$ python setup.py install

To test your installation, we encourage you to install the nose testing library:

$ pip install nose

You can run the tests:

$ nosetests tests/

Hope everything is ok!

Continue to the quickstart example.

Model creation¶

First, let’s import some functions and classes:

from rdflib import Graph
from oldman import ResourceManager, parse_graph_safely, SPARQLDataStore

and create the RDF graph schema_graph that will contain our schema:

schema_graph = Graph()

The data graph is where we store the data that we generate. By default, it stores data in memory.

The role of the schema graph is to contain most of the domain logic necessary to build our models. In this example, we load it from a RDF file:

schema_url = "https://raw.githubusercontent.com/oldm/OldMan/master/examples/quickstart_schema.ttl"
parse_graph_safely(schema_graph, schema_url, format="turtle")

Another main piece of the domain logic is found in the JSON-LD context. Here, we just need its IRI:

context_iri = "https://raw.githubusercontent.com/oldm/OldMan/master/examples/quickstart_context.jsonld"

We now have almost enough domain knowledge to create our models.

But first of all, we have to decide where to store our data. Here we create an in-memory RDF graph and use it as a SPARQL endpoint (SPARQLDataStore):

data_graph = Graph()
data_store = SPARQLDataStore(data_graph)

We extract the prefix information from the schema graph:

data_store.extract_prefixes(schema_graph)

Then we instantiate the central object of this framework, the ResourceManager object. Basically, it creates Model objects and offers convenient method to retrieve and create Resource objects:

manager = ResourceManager(schema_graph, data_store)

Finally, we create our LocalPerson Model object. For that, we need:

• The IRI or a JSON-LD term of the RDFS class of the model. Here “LocalPerson” is an alias for http://example.org/myvoc#LocalPerson defined in the context file ;

• The JSON-LD context;

• A prefix for creating the IRI of new resources (optional) ;

• An IRI fragment (optional);

• To declare that we want to generate incremental IRIs with short numbers for new Resource objects.

  lp_model = manager.create_model("LocalPerson", context_iri,
                                  iri_prefix="http://localhost/persons/",
                                  iri_fragment="me", incremental_iri=True)
  

Resource editing¶

Now that the domain logic has been declared, we can create Resource objects for two persons, Alice and Bob:

alice = lp_model.create(name="Alice", emails={"alice@example.org"},
                        short_bio_en="I am ...")
bob = lp_model.new(name="Bob", blog="http://blog.example.com/",
                   short_bio_fr=u"J'ai grandi en ... .")

Alice is already stored in the data_store but not Bob. Actually, it cannot be saved yet because some information is still missing: its email addresses. This information is required by our domain logic. Let’s satisfy this constraint and save Bob:

>>> bob.is_valid()
False
>>> bob.emails = {"bob@localhost", "bob@example.org"}
>>> bob.is_valid()
True
>>> bob.save()

Let’s now declare that they are friends:

alice.friends = {bob}
bob.friends = {alice}
alice.save()
bob.save()

That’s it. Have you seen many IRIs? Only one, for the blog. Let’s look at them:

>>> alice.id
"http://localhost/persons/1#me"
>>> bob.id
"http://localhost/persons/2#me"
>>> bob.types
[u'http://example.org/myvoc#LocalPerson', u'http://xmlns.com/foaf/0.1/Person']

and at some other attributes:

>>> alice.name
"Alice"
>>> bob.emails
set(['bob@example.org', 'bob@localhost'])
>>> bob.short_bio_en
None
>>> bob.short_bio_fr
u"J'ai grandi en ... ."

We can assign an IRI when creating a Resource object:

>>> john_iri = "http://example.org/john#me"
>>> john = lp_model.create(id=john_iri, name="John", emails={"john@example.org"})
>>> john.id
"http://example.org/john#me"

Resource retrieval¶

By default, resource are not cached. We can retrieve Alice and Bob from the data graph as follows:

>>> alice_iri = alice.id
>>> # First person found named Bob
>>> bob = lp_model.get(name="Bob")
>>> alice = lp_model.get(id=alice_iri)

>>> # Or retrieve her as the unique friend of Bob
>>> alice = list(bob.friends)[0]
>>> alice.name
"Alice"

Finds all the persons:

>>> set(lp_model.all())
set([Resource(<http://example.org/john#me>), Resource(<http://localhost/persons/2#me>), Resource(<http://localhost/persons/1#me>)])
>>> # Equivalent to
>>> set(lp_model.filter())
set([Resource(<http://localhost/persons/1#me>), Resource(<http://localhost/persons/2#me>), Resource(<http://example.org/john#me>)])

Serialization¶

JSON:

>>> print alice.to_json()
{
  "emails": [
    "alice@example.org"
  ],
  "friends": [
    "http://localhost/persons/2#me"
  ],
  "id": "http://localhost/persons/1#me",
  "name": "Alice",
  "short_bio_en": "I am ...",
  "types": [
    "http://example.org/myvoc#LocalPerson",
    "http://xmlns.com/foaf/0.1/Person"
  ]
}

JSON-LD:

>>> print john.to_jsonld()
{
  "@context": "https://raw.githubusercontent.com/oldm/OldMan/master/examples/quickstart_context.jsonld",
  "emails": [
    "john@example.org"
  ],
  "id": "http://example.org/john#me",
  "name": "John",
  "types": [
    "http://example.org/myvoc#LocalPerson",
    "http://xmlns.com/foaf/0.1/Person"
  ]
}

Turtle:

>>> print bob.to_rdf("turtle")
@prefix bio: <http://purl.org/vocab/bio/0.1/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix myvoc: <http://example.org/myvoc#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xml: <http://www.w3.org/XML/1998/namespace> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<http://localhost/persons/2#me> a myvoc:LocalPerson,
        foaf:Person ;
    bio:olb "J'ai grandi en ... ."@fr ;
    foaf:knows <http://localhost/persons/1#me> ;
    foaf:mbox "bob@example.org"^^xsd:string,
        "bob@localhost"^^xsd:string ;
    foaf:name "Bob"^^xsd:string ;
    foaf:weblog <http://blog.example.com/> .

Validation¶

Validation is also there:

>>> # Email is required
>>> lp_model.create(name="Jack")
oldman.exception.OMRequiredPropertyError: emails

>>> #Invalid email
>>> bob.emails = {'you_wont_email_me'}
oldman.exception.OMAttributeTypeCheckError: you_wont_email_me is not a valid email (bad format)

>>> # Not a set
>>> bob.emails = "bob@example.com"
oldman.exception.OMAttributeTypeCheckError: A container (<type 'set'>) was expected instead of <type 'str'>

>>> #Invalid name
>>> bob.name = 5
oldman.exception.OMAttributeTypeCheckError: 5 is not a (<type 'str'>, <type 'unicode'>)

Domain logic¶

Here is the declared domain logic that we used:

JSON-LD context https://raw.githubusercontent.com/oldm/OldMan/master/examples/quickstart_context.jsonld:

{
  "@context": {
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "bio": "http://purl.org/vocab/bio/0.1/",
    "myvoc": "http://example.org/myvoc#",
    "Person": "foaf:Person",
    "LocalPerson": "myvoc:LocalPerson",
    "id": "@id",
    "types": "@type",
    "friends": {
      "@id": "foaf:knows",
      "@type": "@id",
      "@container": "@set"
    },
    "short_bio_fr": {
      "@id": "bio:olb",
      "@language": "fr"
    },
    "name": {
      "@id": "foaf:name",
      "@type": "xsd:string"
    },
    "emails": {
      "@id": "foaf:mbox",
      "@type": "xsd:string",
      "@container": "@set"
    },
    "blog": {
      "@id": "foaf:weblog",
      "@type": "@id"
    },
    "short_bio_en": {
      "@id": "bio:olb",
      "@language": "en"
    }
  }
}

Schema (uses the Hydra vocabulary) https://raw.githubusercontent.com/oldm/OldMan/master/examples/quickstart_schema.ttl:

@prefix bio: <http://purl.org/vocab/bio/0.1/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix hydra: <http://www.w3.org/ns/hydra/core#> .
@prefix myvoc: <http://example.org/myvoc#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

# Properties that may be given to a foaf:Person (no requirement)
foaf:Person a hydra:Class ;
    hydra:supportedProperty [ hydra:property foaf:mbox ],
        [ hydra:property foaf:weblog ],
        [ hydra:property foaf:name ],
        [ hydra:property bio:olb ],
        [ hydra:property foaf:knows ].

# Local version of a Person with requirements
myvoc:LocalPerson a hydra:Class ;
    rdfs:subClassOf foaf:Person ;
    hydra:supportedProperty [ hydra:property foaf:mbox ;
            hydra:required true ],
        [ hydra:property foaf:name ;
            hydra:required true ].

Resource¶

A Resource object represents a Web resource identified by a regular IRI (internationalized URI) or or a skolem IRI (if it should treated as a blank node).

In OldMan, Web resources are described in conformance to the Resource Description Framework (RDF). A Resource object may have some attributes that provide the predicate (also called property) and the object terms of RDF triples describing the resource. The resource itself is the subject of the triple. Its attributes have arbitrary short names as defined in the JSON-LD context.

A Resource object access to its attributes through the Model objects to which it relates (through its types). Thus, if it has no type or its types that are not related to a Model object, a Resource object has no “RDF” attribute.

In OldMan, the relation between Resource and Model objects is many-to-many. It differs from traditional ORMs where the relation is one-to-many (the resource is usually an instance of the model and the latter is a Python class in these frameworks). However, we expect that most Resource objects will relate to one Model object, but this is not a requirement. It is common for a resource in RDF to be instance of multiple RDFS classes so OldMan had to be ok with this practise.

Some inherited Python methods may also be provided by the Model objects.

ResourceManager¶

A ResourceManager object is the central object of OldMan.

It creates Model objects (create_model()) and retrieves Resource objects (get(), filter() and sparql_filter()).

It accepts Python method declarations if they happen before the creation of Model objects (declare_method()).

It also provide helper functions to create new Resource objects (create() and new()) but it is usually simpler to use those of a Model object.

For creating the ResourceManager object, the schema graph and the data store (DataStore) must be given.

Basically, the schema graph describes which properties should be expected for a given RDFS class, which are required and what are the constraints.

Model¶

In OldMan, models are not Python classes but Model objects. However, on the RDF side, they correspond to RDFS classes (their class_iri attributes).

Their main role is to provide attributes and methods to Resource objects, as explained above.

Model objects are created by the ResourceManager object.

A model provide some helpers above the ResourceManager object ( get(), filter(), new() and create()) that include the class_iri to the types parameter of these methods.

DataStore¶

A DataStore implements the CRUD operations on Web Resources exposed by the ResourceManager and Model objects.

The vision of OldMan is to include a large choice of data stores. But currently, only SPARQL endpoints are supported.

Non-CRUD operations may also be introduced in the future (in discussion).

Any data store accepts a dogpile.cache.region.CacheRegion object to enable its ResourceCache object. By default the latter is disabled so it does not cache the Resource objects loaded from and stored in the data store.

oldman.attribute module¶

class oldman.attribute.OMAttribute(manager, metadata, value_format)[source]¶

Bases: object

An OMAttribute object corresponds to a JSON-LD term that refers to a RDF property.

Technically, the name of the OMAttribute object is a JSON-LD term, namely “a short-hand string that expands to an IRI or a blank node identifier” (cf. the JSON-LD standard) which corresponds here to a RDF property (see OMProperty).

In JSON-LD, the same RDF property may correspond to multiple JSON-LD terms that have different metadata. For instance, a foaf:Person resource may have two attributes for its bio in English and in French. These attributes have two different languages but use the same property bio:olb. Look at the quickstart example to see it in practice.

An OMAttribute object manages the values of every Resource object that depends on a given Model object.

Each value may be :

• None;
• The Python equivalent for a RDF literal (double, string, date, etc.);
• An IRI;
• A collection (set, list and dict) of these types.

Parameters:	manager – ResourceManager object. metadata – OMAttributeMetadata object. value_format – ValueFormat object that validates the format of values and converts RDF values into regular Python objects.

check_validity(resource, is_end_user=True)[source]¶

Raises an OMEditError exception if the attribute value assigned to a resource is invalid.

Parameters:	resource – Resource object. is_end_user – False when an authorized user (not a regular end-user) wants to force some rights. Defaults to True.

check_value(value)[source]¶

Checks a new when assigned.

Raises an oldman.exception.OMAttributeTypeCheckError exception if the value is invalid.

Parameters:	value – collection or atomic value.

container[source]¶

JSON-LD container (“@set”, “@list”, “@language” or “@index”). May be None.

delete_former_value(resource)[source]¶

Clears the former value that has been replaced.

Parameters:	resource – Resource object.

get(resource)[source]¶

Gets the attribute value of a resource.

Parameters:	resource – Resource object.
Returns:	Atomic value or a generator.

get_former_value(resource)[source]¶

Gets out the former value that has been replaced.

Parameters:	resource – Resource object.
Returns:	its former attribute value or None.

get_lightly(resource)[source]¶

Gets the attribute value of a resource in a lightweight manner.

By default, behaves exactly like get(). See the latter function for further details.

has_new_value(resource)[source]¶

Parameters:	resource – Resource object.

has_value(resource)[source]¶

Tests if the resource attribute has a non-None value.

Parameters:	resource – Resource object.
Returns:	False if the value is None.

is_read_only[source]¶

True if the property cannot be modified by regular end-users.

is_required[source]¶

True if its property is required.

is_valid(resource, is_end_user=True)[source]¶

Tests if the attribute value assigned to a resource is valid.

See check_validity() for further details.

Returns:	False if the value assigned to the resource is invalid and True otherwise.

is_write_only[source]¶

True if the property cannot be accessed by regular end-users.

jsonld_type[source]¶

JSON-LD type (datatype IRI or JSON-LD keyword). May be None.

language[source]¶

Its language if localized.

manager[source]¶

Its ResourceManager object.

name[source]¶

Its name as an attribute.

om_property[source]¶

OMProperty to which it belongs.

other_attributes[source]¶

Other OMAttribute objects of the same property.

reversed[source]¶

True if the object and subject in RDF triples should be reversed.

set(resource, value)[source]¶

Sets the attribute value of a resource.

Parameters:	resource – Resource object. value – Its value for this attribute.

to_nt(resource)[source]¶

Converts its current attribute value to N-Triples (NT) triples.

Relies on value_to_nt().

Parameters:	resource – Resource object.
Returns:	N-Triples serialization of its attribute value.

update_from_graph(resource, sub_graph, initial=False)[source]¶

Updates a resource attribute value by extracting the relevant information from a RDF graph.

Parameters:	resource – Resource object. sub_graph – rdflib.Graph object containing the value to extract. initial – True when the value is directly from the datastore. Defaults to False.

value_format[source]¶

ValueFormat object that validates the format of values and converts RDF values into regular Python objects.

value_to_nt(value)[source]¶

Converts value(s) to N-Triples (NT) triples.

Parameters:	value – Value of property.
Returns:	N-Triples serialization of this value.

class oldman.attribute.OMAttributeMetadata¶

Bases: tuple

OMAttributeMetadata(name, property, language, jsonld_type, container, reversed)

container¶

Alias for field number 4

jsonld_type¶

Alias for field number 3

language¶

Alias for field number 2

name¶

Alias for field number 0

property¶

Alias for field number 1

reversed¶

Alias for field number 5

class oldman.attribute.ObjectOMAttribute(manager, metadata, value_format)[source]¶

Bases: oldman.attribute.OMAttribute

An ObjectOMAttribute object is an OMAttribute object that depends on an owl:ObjectProperty.

get(resource)[source]¶

See get().

Returns:	Resource object or a generator of Resource objects.

get_lightly(resource)[source]¶

Gets the attribute value of a resource in a lightweight manner.

By contrast with get() only IRIs are returned, not Resource objects.

Returns:	An IRI, a list or a set of IRIs or None.

set(resource, value)[source]¶

See set().

Accepts Resource object(s) or IRI(s).

oldman.exception module¶

exception oldman.exception.AlreadyAllocatedModelError[source]¶

Bases: oldman.exception.ModelGenerationError

The class IRI or the short name of a new model is already allocated.

exception oldman.exception.ModelGenerationError[source]¶

Bases: oldman.exception.OMError

Error occured when generating a new model.

exception oldman.exception.OMAccessError[source]¶

Bases: oldman.exception.OMUserError

Error when accessing objects.

exception oldman.exception.OMAlreadyDeclaredDatatypeError[source]¶

Bases: oldman.exception.OMAttributeDefError

At least two different datatypes for the same attribute.

You may check the possible datatype inherited from the property (rdfs:range) and the one specified in the JSON-LD context.

exception oldman.exception.OMAlreadyGeneratedAttributeError[source]¶

Bases: oldman.exception.OMInternalError

Attribute generation occurs only once per SupportedProperty.

You should not try to add metadata or regenerate after that.

exception oldman.exception.OMAttributeAccessError[source]¶

Bases: oldman.exception.OMAccessError

When such an attribute cannot be identified (is not supported or no model has been found).

exception oldman.exception.OMAttributeDefError[source]¶

Bases: oldman.exception.OMSchemaError

Inconsistency in the definition of a model class attribute.

exception oldman.exception.OMAttributeTypeCheckError[source]¶

Bases: oldman.exception.OMEditError

The value assigned to the attribute has wrong type.

exception oldman.exception.OMClassInstanceError[source]¶

Bases: oldman.exception.OMAccessError

The object is not an instance of the expected RDFS class.

exception oldman.exception.OMDataStoreError[source]¶

Bases: oldman.exception.OMError

Error detected in the stored data.

exception oldman.exception.OMDifferentHashlessIRIError[source]¶

Bases: oldman.exception.OMEditError

When creating or updating an object with a different hashless IRI is forbidden.

Blank nodes are not concerned.

exception oldman.exception.OMEditError[source]¶

Bases: oldman.exception.OMUserError

Runtime errors, occuring when editing or creating an object.

exception oldman.exception.OMError[source]¶

Bases: exceptions.Exception

Root of exceptions generated by the oldman package.

exception oldman.exception.OMExpiredMethodDeclarationTimeSlotError[source]¶

Bases: oldman.exception.ModelGenerationError

All methods must be declared before creating a first model.

exception oldman.exception.OMForbiddenSkolemizedIRIError[source]¶

Bases: oldman.exception.OMEditError

When updating a skolemized IRI from the local domain is forbidden.

exception oldman.exception.OMHashIriError[source]¶

Bases: oldman.exception.OMAccessError

A hash IRI has been given instead of a hash-less IRI.

exception oldman.exception.OMInternalError[source]¶

Bases: oldman.exception.OMError

Do not expect it.

exception oldman.exception.OMObjectNotFoundError[source]¶

Bases: oldman.exception.OMAccessError

When the object is not found.

exception oldman.exception.OMPropertyDefError[source]¶

Bases: oldman.exception.OMSchemaError

Inconsistency in the definition of a supported property.

exception oldman.exception.OMPropertyDefTypeError[source]¶

Bases: oldman.exception.OMPropertyDefError

A RDF property cannot be both an ObjectProperty and a DatatypeProperty.

exception oldman.exception.OMReadOnlyAttributeError[source]¶

Bases: oldman.exception.OMEditError

End-users are not allowed to edit this attribute.

exception oldman.exception.OMRequiredHashlessIRIError[source]¶

Bases: oldman.exception.OMEditError

No hash-less IRI has been given.

exception oldman.exception.OMRequiredPropertyError[source]¶

Bases: oldman.exception.OMEditError

A required property has no value.

exception oldman.exception.OMReservedAttributeNameError[source]¶

Bases: oldman.exception.OMAttributeDefError

Some attribute names are reserved and should not be included in the JSON-LD context.

exception oldman.exception.OMSPARQLError[source]¶

Bases: oldman.exception.OMAccessError

Invalid SPARQL query given.

exception oldman.exception.OMSPARQLParseError[source]¶

Bases: oldman.exception.OMInternalError

Invalid SPARQL request.

exception oldman.exception.OMSchemaError[source]¶

Bases: oldman.exception.ModelGenerationError

Error in the schema graph and/or the JSON-LD context.

exception oldman.exception.OMUnauthorizedTypeChangeError[source]¶

Bases: oldman.exception.OMEditError

When updating a resource with new types without explicit authorization.

exception oldman.exception.OMUndeclaredClassNameError[source]¶

Bases: oldman.exception.ModelGenerationError

The name of the model class should be defined in the JSON-LD context.

exception oldman.exception.OMUniquenessError[source]¶

Bases: oldman.exception.OMEditError

Attribute uniqueness violation.

Example: IRI illegal reusing.

exception oldman.exception.OMUserError[source]¶

Bases: oldman.exception.OMError

Error when accessing or editing objects.

exception oldman.exception.OMWrongResourceError[source]¶

Bases: oldman.exception.OMEditError

Not updating the right object.

exception oldman.exception.UnsupportedDataStorageFeatureException[source]¶

Bases: oldman.exception.OMDataStoreError

Feature not supported by the data store.

oldman.iri module¶

class oldman.iri.BlankNodeIriGenerator(hostname=u'localhost')[source]¶

Bases: oldman.iri.PrefixedUUIDIriGenerator

Generates skolem IRIs that denote blank nodes.

Parameters:	hostname – Defaults to “localhost”.

class oldman.iri.IncrementalIriGenerator(prefix, data_store, class_iri, fragment=None)[source]¶

Bases: oldman.iri.IriGenerator

Generates IRIs with short numbers.

Beautiful but slow in concurrent settings. The number generation implies a critical section and a sequence of two SPARQL requests, which represents a significant bottleneck.

Parameters:	prefix – IRI prefix. graph – rdflib.Graph object where to store the counter. class_iri – IRI of the RDFS class of which new Resource objects are instance of. Usually corresponds to the class IRI of the Model object that owns this generator. fragment – IRI fragment to append to the hash-less IRI. Defaults to None.

generate(**kwargs)[source]¶

See oldman.iri.IriGenerator.generate().

reset_counter()[source]¶

For test purposes only

class oldman.iri.IriGenerator[source]¶

Bases: object

An IriGenerator object generates the IRIs of some new Resource objects.

generate(**kwargs)[source]¶

Generates an IRI.

Returns:	Unique IRI (unicode string).

class oldman.iri.PrefixedUUIDIriGenerator(prefix, fragment=None)[source]¶

Bases: oldman.iri.IriGenerator

Uses a prefix, a fragment and a unique UUID1 number to generate IRIs.

Recommended generator because UUID1 is robust and fast (no DB access).

Parameters:	prefix – IRI prefix. fragment – IRI fragment to append to the hash-less IRI. Defaults to None.

generate(**kwargs)[source]¶

See oldman.iri.IriGenerator.generate().

class oldman.iri.UUIDFragmentIriGenerator[source]¶

Bases: oldman.iri.IriGenerator

Generates an hashed IRI from a hash-less IRI.

Its fragment is a unique UUID1 number.

generate(hashless_iri)[source]¶

See oldman.iri.IriGenerator.generate().

oldman.model module¶

class oldman.model.Model(manager, name, class_iri, ancestry_iris, context, om_attributes, id_generator, methods=None)[source]¶

Bases: object

A Model object represents a RDFS class on the Python side.

It gathers OMAttribute objects and Python methods which are made available to Resource objects that are instances of its RDFS class.

It also creates and retrieves Resource objects that are instances of its RDFS class. It manages an IriGenerator object.

Model creation

Model objects are normally created by a ResourceManager object. Please use the oldman.management.manager.ResourceManager.create_model() method for creating new Model objects.

Parameters:

manager – ResourceManager object that has created this model. name – Model name. Usually corresponds to a JSON-LD term or to a class IRI. class_iri – IRI of the RDFS class represented by this Model object. ancestry_iris – ancestry of the attribute class_iri. Each instance of class_iri is also instance of these classes. context – An IRI, a list or a dict that describes the JSON-LD context. See http://www.w3.org/TR/json-ld/#the-context for more details. om_attributes – dict of OMAttribute objects. Keys are their names. id_generator – IriGenerator object that generates IRIs from new Resource objects. methods – dict of Python functions that takes as first argument a Resource object. Keys are the method names. Defaults to {}.

access_attribute(name)[source]¶

Gets an OMAttribute object.

Used by the Resource class but an end-user should not need to call it.

Parameters:	name – Name of the attribute.
Returns:	The corresponding OMAttribute object.

all(limit=None, eager=False)[source]¶

Finds every Resource object that is instance of its RDFS class.

Parameters:	limit – Upper bound on the number of solutions returned (SPARQL LIMIT). Positive integer. Defaults to None. eager – If True loads all the Resource objects within one single SPARQL query. Defaults to False (lazy).
Returns:	A generator of Resource objects.

ancestry_iris[source]¶

IRIs of the ancestry of the attribute class_iri.

class_iri[source]¶

IRI of the class IRI the model refers to.

context[source]¶

An IRI, a list or a dict that describes the JSON-LD context. See http://www.w3.org/TR/json-ld/#the-context for more details.

create(id=None, hashless_iri=None, **kwargs)[source]¶

Creates a new resource and saves it.

See new() for more details.

filter(hashless_iri=None, limit=None, eager=False, pre_cache_properties=None, **kwargs)[source]¶

Finds the Resource objects matching the given criteria.

The class_iri attribute is added to the types.

See oldman.management.finder.ResourceFinder.filter() for further details.

generate_iri(**kwargs)[source]¶

Generates a new IRI.

Used by the Resource class but an end-user should not need to call it.

Returns:	A new IRI.

get(id=None, hashless_iri=None, **kwargs)[source]¶

Gets the first Resource object matching the given criteria.

The class_iri attribute is added to the types. Also looks if reversed attributes should be considered eagerly.

See oldman.management.finder.Finder.get() for further details.

has_reversed_attributes[source]¶

Is True if one of its attributes is reversed.

is_subclass_of(model)[source]¶

Returns True if its RDFS class is a sub-class (rdfs:subClassOf) of the RDFS class of another model.

Parameters:	model – Model object to compare with.
Returns:	True if is a sub-class of the other model, False otherwise.

methods[source]¶

dict of Python functions that takes as first argument a Resource object. Keys are the method names.

name[source]¶

Name attribute.

new(id=None, hashless_iri=None, **kwargs)[source]¶

Creates a new Resource object without saving it.

The class_iri attribute is added to the types.

See new() for more details.

om_attributes[source]¶

dict of OMAttribute objects. Keys are their names.

reset_counter()[source]¶

Resets the counter of the IRI generator.

Please use it only for test purposes.

oldman.model.clean_context(context)[source]¶

Cleans the context.

Context can be an IRI, a list or a dict.

oldman.property module¶

class oldman.property.OMProperty(manager, property_iri, supporter_class_iri, is_required=False, read_only=False, write_only=False, reversed=False, cardinality=None, property_type=None, domains=None, ranges=None)[source]¶

Bases: object

An OMProperty object represents the support of a RDF property by a RDFS class.

It gathers some OMAttribute objects (usually one).

An OMProperty object is in charge of generating its OMAttribute objects according to the metadata that has been extracted from the schema and JSON-LD context.

A property can be reversed: the Resource object to which the OMAttribute objects will be (indirectly) attached is then the object of this property, not its subject (?o ?p ?s).

Consequently, two OMProperty objects can refer to the same RDF property when one is reversed while the second is not.

Parameters:

manager – ResourceManager object. property_iri – IRI of the RDF property. supporter_class_iri – IRI of the RDFS class that supports the property. is_required – If True instances of the supporter class must assign a value to this property for being valid. Defaults to False. read_only – If True, the value of the property cannot be modified by a regular end-user. Defaults to False. write_only – If True, the value of the property cannot be read by a regular end-user. Defaults to False. reversed – If True, the property is reversed. Defaults to False. cardinality – Defaults to None. Not yet supported. property_type – String. In OWL, a property is either a DatatypeProperty or an ObjectProperty. Defaults to None (unknown). domains – Set of class IRIs that are declared as the RDFS domain of the property. Defaults to set(). ranges – Set of class IRIs that are declared as the RDFS range of the property. Defaults to set().

add_attribute_metadata(name, jsonld_type=None, language=None, container=None, reversed=False)[source]¶

Adds metadata about a future OMAttribute object.

Parameters:	name – JSON-LD term representing the attribute. jsonld_type – JSON-LD type (datatype IRI or JSON-LD keyword). Defaults to None. language – Defaults to None. container – JSON-LD container (“@set”, “@list”, “@language” or “@index”). Defaults to None. reversed – True if the object and subject in RDF triples should be reversed. Defaults to False.

add_domain(domain)[source]¶

Declares a RDFS class as part of the domain of the property.

Parameters:	domain – IRI of RDFS class.

add_range(p_range)[source]¶

Declares a RDFS class as part of the range of the property.

Parameters:	p_range – IRI of RDFS class.

declare_is_required()[source]¶

Makes the property be required. Is irreversible.

default_datatype[source]¶

IRI that is the default datatype of the property.

May be None (if not defined or if the property is an owl:ObjectProperty)

domains[source]¶

Set of class IRIs that are declared as the RDFS domain of the property.

generate_attributes(attr_format_selector)[source]¶

Generates its OMAttribute objects.

Can be called only once. When called a second time, raises an OMAlreadyGeneratedAttributeError exception.

Parameters:	attr_format_selector – ValueFormatSelector object.

iri[source]¶

IRI of RDF property.

is_read_only[source]¶

True if the property cannot be modified by regular end-users.

is_required[source]¶

True if the property is required.

is_write_only[source]¶

True if the property cannot be accessed by regular end-users.

om_attributes[source]¶

Set of OMAttribute objects that depends on this property.

ranges[source]¶

Set of class IRIs that are declared as the RDFS range of the property.

reversed[source]¶

True if the property is reversed (?o ?p ?s).

supporter_class_iri[source]¶

IRI of the RDFS class that supports the property.

type[source]¶

The property can be a owl:DatatypeProperty (“datatype”) or an owl:ObjectProperty (“object”). Sometimes its type is unknown (None).

oldman.resource module¶

class oldman.resource.Resource(manager, id=None, types=None, hashless_iri=None, is_new=True, **kwargs)[source]¶

Bases: object

A Resource object is a subject-centric representation of a Web resource. A set of Resource objects is equivalent to a RDF graph.

In RDF, a resource is identified by an IRI (globally) or a blank node (locally). Because blank node support is complex and limited (rdflib.plugins.stores.sparqlstore.SPARQLStore stores do not support them), every Resource object has an IRI.

This IRI is either given or generated by a IriGenerator object. Some generators generate recognizable skolem IRIs that are treated as blank nodes when the resource is serialized into JSON, JSON-LD or another RDF format (for external consumption).

A resource is usually instance of some RDFS classes. These classes are grouped in its attribute types. Model objects are found from these classes, by calling the method oldman.management.manager.ResourceManager.find_models_and_types(). Models give access to Python methods and to OMAttribute objects. Their ordering determines inheritance priorities. The main model is the first one of this list.

Values of OMAttribute objects are accessible and modifiable like ordinary Python attribute values. However, these values are checked so some OMAccessError or OMEditError errors may be raised.

Example:

>>> alice = Resource(manager, types=["http://schema.org/Person"], name=u"Alice")
>>> alice.id
u'http://localhost/persons/1'
>>> alice.name
u'Alice'
>>> alice.save()
>>> alice.name = "Alice A."
>>> print alice.to_jsonld()
{
   "@context": "http://localhost/person.jsonld",
   "id": "http://localhost/persons/1",
   "types": [
              "http://schema.org/Person"
            ],
   "name": "Alice A."
}
>>> alice.name = 5
oldman.exception.OMAttributeTypeCheckError: 5 is not a (<type 'str'>, <type 'unicode'>)

Resource creation

Resource objects are normally created by a Model or a ResourceManager object. Please use the methods oldman.model.Model.create(), oldman.model.Model.new(), oldman.management.manager.ResourceManager.create() or oldman.management.manager.ResourceManager.new() for creating new Resource objects.

Parameters:

manager – ResourceManager object. Gives access to the data_graph (where the triples are stored), the union_graph and the resource_cache. id – IRI of the resource. If not given, this IRI is generated by the main model. Defaults to None. types – IRI list or set of the RDFS classes the resource is instance of. Defaults to set(). hashless_iri – Hash-less IRI that is given to the main model for generating a new IRI if no id is given. The IRI generator may ignore it. Defaults to None. is_new – When is True and id given, checks that the IRI is not already existing in the union_graph. Defaults to True. kwargs – values indexed by their attribute names.

add_type(additional_type)[source]¶

Declares that the resource is instance of another RDFS class.

Note that it may introduce a new model to the list and change its ordering.

Parameters:	additional_type – IRI or JSON-LD term identifying a RDFS class.

check_validity()[source]¶

Checks its validity.

Raises an oldman.exception.OMEditError exception if invalid.

context[source]¶

An IRI, a list or a dict that describes the JSON-LD context.

Derived from oldman.model.Model.context attributes.

delete()[source]¶

Removes the resource from the data_graph and the resource_cache.

Cascade deletion is done for related resources satisfying the test should_delete_resource().

full_update(full_dict, is_end_user=True, allow_new_type=False, allow_type_removal=False, save=True)[source]¶

Updates the resource from a flat dict.

By flat, we mean that sub-resources are only represented by their IRIs: there is no nested sub-object structure.

This dict is supposed to be exhaustive, so absent value is removed. Some sub-resources may thus be deleted like if there were a cascade deletion.

Parameters:

full_dict – Flat dict containing the attribute values to update. is_end_user – False when an authorized user (not a regular end-user) wants to force some rights. Defaults to True. See check_validity() for further details. allow_new_type – If True, new types can be added. Please keep in mind that type change can: Modify the behavior of the resource by changing its model list. Interfere with the SPARQL requests using instance tests. If enabled, this may represent a major security concern. Defaults to False. allow_type_removal – If True, new types can be removed. Same security concerns than above. Defaults to False. save – If True calls save() after updating. Defaults to True.

Returns:

The Resource object itself.

full_update_from_graph(subgraph, initial=False, is_end_user=True, allow_new_type=False, allow_type_removal=False, save=True)[source]¶

Similar to full_update() but with a RDF graph instead of a Python dict.

Parameters:

subgraph – rdflib.Graph object containing the full description of the resource. initial – True when the subgraph comes from the data_graph and is thus used to load Resource object from the triple store. Defaults to False. is_end_user – False when an authorized user (not a regular end-user) wants to force some rights. Defaults to True. See check_validity() for further details. allow_new_type – If True, new types can be added. Defaults to False. See full_update() for explanations about the security concerns. allow_type_removal – If True, new types can be removed. Same security concerns than above. Defaults to False. save – If True calls save() after updating. Defaults to True.

Returns:

The Resource object itself.

hashless_iri[source]¶

Hash-less IRI of the id attribute. Is obtained by removing the fragment from the IRI.

id[source]¶

IRI that identifies the resource.

in_same_document(other_resource)[source]¶

Tests if two resources have the same hash-less IRI.

Returns:	True if these resources are in the same document.

is_blank_node()[source]¶

Tests if id is a skolem IRI and should thus be considered as a blank node.

See is_blank_node() for further details.

Returns:	True if id is a locally skolemized IRI.

is_instance_of(model)[source]¶

Tests if the resource is instance of the RDFS class of the model.

Parameters:	model – Model object.
Returns:	True if the resource is instance of the RDFS class.

is_valid()[source]¶

Tests if the resource is valid.

Returns:	False if the resource is invalid, True otherwise.

classmethod load_from_graph(manager, id, subgraph, is_new=True)[source]¶

Loads a new Resource object from a sub-graph.

Parameters:	manager – ResourceManager object. id – IRI of the resource. subgraph – rdflib.Graph object containing triples about the resource. is_new – When is True and id given, checks that the IRI is not already existing in the union_graph. Defaults to True.
Returns:	The Resource object created.

save(is_end_user=True)[source]¶

Saves it into the data_graph and the resource_cache.

Raises an oldman.exception.OMEditError exception if invalid.

Parameters:	is_end_user – False when an authorized user (not a regular end-user) wants to force some rights. Defaults to True. See check_validity() for further details.
Returns:	The Resource object itself.

to_dict(remove_none_values=True, include_different_contexts=False, ignored_iris=None)[source]¶

Serializes the resource into a JSON-like dict.

Parameters:	remove_none_values – If True, None values are not inserted into the dict. Defaults to True. include_different_contexts – If True local contexts are given to sub-resources. Defaults to False. ignored_iris – List of IRI of resources that should not be included in the dict. Defaults to set().
Returns:	A dict describing the resource.

to_json(remove_none_values=True, ignored_iris=None)[source]¶

Serializes the resource into pure JSON (not JSON-LD).

Parameters:	remove_none_values – If True, None values are not inserted into the dict. Defaults to True. ignored_iris – List of IRI of resources that should not be included in the dict. Defaults to set().
Returns:	A JSON-encoded string.

to_jsonld(remove_none_values=True, include_different_contexts=False, ignored_iris=None)[source]¶

Serializes the resource into JSON-LD.

Parameters:	remove_none_values – If True, None values are not inserted into the dict. Defaults to True. include_different_contexts – If True local contexts are given to sub-resources. Defaults to False. ignored_iris – List of IRI of resources that should not be included in the dict. Defaults to set().
Returns:	A JSON-LD encoded string.

to_rdf(rdf_format='turtle')[source]¶

Serializes the resource into RDF.

Parameters:	rdf_format – content-type or keyword supported by RDFlib. Defaults to “turtle”.
Returns:	A string in the chosen RDF format.

types[source]¶

IRI list of the RDFS classes the resource is instance of.

oldman.resource.is_blank_node(iri)[source]¶

Tests if id is a locally skolemized IRI.

External skolemized blank nodes are not considered as blank nodes.

Parameters:	iri – IRI of the resource.
Returns:	True if is a blank node.

oldman.resource.should_delete_resource(resource)[source]¶

Tests if a resource should be deleted.

Parameters:	resource – Resource object to evaluate.
Returns:	True if it should be deleted.

oldman.vocabulary module¶

?cls <urn:oldman:model:ordering:hasPriority> [
    <urn:oldman:model:ordering:class> ?parent1 ;
    <urn:oldman:model:ordering:priority> 2
].

Sub-packages¶