Merge pull request #40 from oldm/new-resource-manager

Separation of the client and store concerns (major change)

docs/conf.py

@@ -58,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/core_concepts.rst

@@ -2,34 +2,36 @@
 Core concepts
 =============
 
+THIS PAGE IS OUT-DATED. TODO: rewrite it.
+
 Resource
 --------
-A :class:`~oldman.resource.Resource` object represents a `Web resource <https://en.wikipedia.org/wiki/Web_resource>`_
+A :class:`~oldman.resource.resource.Resource` object represents a `Web resource <https://en.wikipedia.org/wiki/Web_resource>`_
 identified by a regular `IRI (internationalized URI) <https://en.wikipedia.org/wiki/Internationalized_resource_identifier>`_ or
 or a `skolem IRI <http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/#section-skolemization>`_ (if it should treated
 as a `blank node <https://en.wikipedia.org/wiki/Blank_node>`_).
 
 In OldMan, Web resources are described in conformance to the
 `Resource Description Framework (RDF) <https://en.wikipedia.org/wiki/Resource_Description_Framework>`_.
-A :class:`~oldman.resource.Resource` object may have some attributes that provide the *predicate*
+A :class:`~oldman.resource.resource.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 :class:`~oldman.resource.Resource` object access to its attributes through the
-:class:`~oldman.model.Model` objects to which it relates (through its :attr:`~oldman.resource.Resource.types`).
-Thus, if it has no *type* or its types that are not related to a :class:`~oldman.model.Model` object,
-a :class:`~oldman.resource.Resource` object has no "RDF" attribute.
+A :class:`~oldman.resource.resource.Resource` object access to its attributes through the
+:class:`~oldman.model.model.Model` objects to which it relates (through its :attr:`~oldman.resource.resource.Resource.types`).
+Thus, if it has no *type* or its types that are not related to a :class:`~oldman.model.model.Model` object,
+a :class:`~oldman.resource.resource.Resource` object has no "RDF" attribute.
 
-In OldMan, the relation between :class:`~oldman.resource.Resource` and :class:`~oldman.model.Model` objects
+In OldMan, the relation between :class:`~oldman.resource.resource.Resource` and :class:`~oldman.model.model.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 :class:`~oldman.resource.Resource` objects will relate to one
-:class:`~oldman.model.Model` object, but this is not a requirement.
+However, we expect that most :class:`~oldman.resource.resource.Resource` objects will relate to one
+:class:`~oldman.model.model.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 :class:`~oldman.model.Model` objects.
+Some inherited Python methods may also be provided by the :class:`~oldman.model.model.Model` objects.
 
 
 Features
@@ -79,17 +81,17 @@ ResourceManager
 ---------------
 A :class:`~oldman.management.manager.ResourceManager` object is the central object of OldMan.
 
-It creates :class:`~oldman.model.Model` objects (:func:`~oldman.management.manager.ResourceManager.create_model`)
-and retrieves :class:`~oldman.resource.Resource` objects  (:func:`~oldman.management.manager.ResourceManager.get`,
+It creates :class:`~oldman.model.model.Model` objects (:func:`~oldman.management.manager.ResourceManager.create_model`)
+and retrieves :class:`~oldman.resource.resource.Resource` objects  (:func:`~oldman.management.manager.ResourceManager.get`,
 :func:`~oldman.management.manager.ResourceManager.filter`
 and :func:`~oldman.management.manager.ResourceManager.sparql_filter`).
 
-It accepts Python method declarations if they happen before the creation of :class:`~oldman.model.Model` objects
+It accepts Python method declarations if they happen before the creation of :class:`~oldman.model.model.Model` objects
 (:func:`~oldman.management.manager.ResourceManager.declare_method`).
 
-It also provide helper functions to create new :class:`~oldman.resource.Resource` objects
+It also provide helper functions to create new :class:`~oldman.resource.resource.Resource` objects
 (:func:`~oldman.management.manager.ResourceManager.create` and :func:`~oldman.management.manager.ResourceManager.new`)
-but it is usually simpler to use those of a :class:`~oldman.model.Model` object.
+but it is usually simpler to use those of a :class:`~oldman.model.model.Model` object.
 
 For creating the :class:`~oldman.management.manager.ResourceManager` object, the schema graph
 and the data store (:class:`~oldman.store.datastore.DataStore`) must be given.
@@ -101,25 +103,25 @@ required and what are the constraints.
 Model
 -----
 
-In OldMan, models are not Python classes but :class:`~oldman.model.Model` objects.
+In OldMan, models are not Python classes but :class:`~oldman.model.model.Model` objects.
 However, on the RDF side, they correspond to `RDFS classes <https://en.wikipedia.org/wiki/RDFS>`_ (their
-:attr:`~oldman.model.Model.class_iri` attributes).
+:attr:`~oldman.model.model.Model.class_iri` attributes).
 
-Their main role is to provide attributes and methods to :class:`~oldman.resource.Resource` objects, as explained
+Their main role is to provide attributes and methods to :class:`~oldman.resource.resource.Resource` objects, as explained
 above.
 
-:class:`~oldman.model.Model` objects are created by the :class:`~oldman.management.manager.ResourceManager` object.
+:class:`~oldman.model.model.Model` objects are created by the :class:`~oldman.management.manager.ResourceManager` object.
 
 A model provide some helpers above the :class:`~oldman.management.manager.ResourceManager` object (
-:func:`~oldman.model.Model.get`, :func:`~oldman.model.Model.filter`, :func:`~oldman.model.Model.new` and
-:func:`~oldman.model.Model.create`) that include the :attr:`~oldman.model.Model.class_iri` to the `types`
+:func:`~oldman.model.model.Model.get`, :func:`~oldman.model.model.Model.filter`, :func:`~oldman.model.model.Model.new` and
+:func:`~oldman.model.model.Model.create`) that include the :attr:`~oldman.model.model.Model.class_iri` to the `types`
 parameter of these methods.
 
 DataStore
 ---------
 
 A :class:`~oldman.store.datastore.DataStore` implements the CRUD operations on Web Resources exposed by the
-:class:`~oldman.management.manager.ResourceManager` and :class:`~oldman.model.Model` objects.
+:class:`~oldman.management.manager.ResourceManager` and :class:`~oldman.model.model.Model` objects.
 
 The vision of OldMan is to include a large choice of data stores. But currently, only SPARQL endpoints
 are supported.
@@ -128,7 +130,7 @@ Non-CRUD operations may also be introduced in the future (in discussion).
 
 Any data store accepts a :class:`dogpile.cache.region.CacheRegion` object to enable its
 :class:`~oldman.store.cache.ResourceCache` object.
-By default the latter is disabled so it does not cache the :class:`~oldman.resource.Resource` objects loaded
+By default the latter is disabled so it does not cache the :class:`~oldman.resource.resource.Resource` objects loaded
 from and stored in the data store.
 
 SPARQLDataStore

docs/examples/dbpedia.rst

@@ -90,6 +90,7 @@ Now we extract the film titles and the names of the actors::
                 elif name not in film_actors[film_iri]:
                     film_actors[film_iri].append(unicode(name))
                 break
+
 and display them::
 
     >>> for film_iri in film_titles:
@@ -201,25 +202,30 @@ Let's first create two :class:`~oldman.model.Model` objects: `film_model` and `p
 `context <https://raw.githubusercontent.com/oldm/OldMan/master/examples/dbpedia_film_context.jsonld>`_
 and `schema <https://raw.githubusercontent.com/oldm/OldMan/master/examples/dbpedia_film_schema.ttl>`_::
 
-    from oldman import ResourceManager, SPARQLDataStore
+    from oldman import ClientResourceManager, SPARQLDataStore
     from dogpile.cache import make_region
 
     schema_url = "https://raw.githubusercontent.com/oldm/OldMan/master/examples/dbpedia_film_schema.ttl"
     schema_graph = Graph().parse(schema_url, format="turtle")
 
     context_url = "https://raw.githubusercontent.com/oldm/OldMan/master/examples/dbpedia_film_context.jsonld"
 
-    # In-memory cache
-    cache_region = make_region().configure('dogpile.cache.memory_pickle')
+    data_graph = Graph(SPARQLStore("http://dbpedia.org/sparql", context_aware=False))
 
-    # SPARQL data store
-    data_store = SPARQLDataStore(data_graph, cache_region=cache_region)
+    cache_region = make_region().configure('dogpile.cache.memory_pickle')
 
-    # Resource Manager and Models
-    manager = ResourceManager(schema_graph, data_store)
-    film_model = manager.create_model("http://dbpedia.org/ontology/Film", context_url)
+    # Datastore: SPARQL-aware triple store, with two models
+    data_store = SPARQLDataStore(data_graph, schema_graph=schema_graph, cache_region=cache_region)
+    data_store.create_model("http://dbpedia.org/ontology/Film", context_url)
     # JSON-LD terms can be used instead of IRIs
-    person_model = manager.create_model("Person", context_url)
+    data_store.create_model("Person", context_url)
+
+    # Client resource manager
+    client_manager = ClientResourceManager(data_store)
+    # Re-uses the models of the data store
+    client_manager.use_all_store_models()
+    film_model = client_manager.get_model("http://dbpedia.org/ontology/Film")
+    actor_model = client_manager.get_model("Person")
 
 Please note that we set up a resource cache and reused the `data_graph`.
 

docs/foreword.rst

@@ -79,7 +79,7 @@ Current core features
 Status
 ======
 
-OldMan is a young project **under active development** started in April 2014.
+OldMan is a young project **under development** started in April 2014.
 Feel free to `join us on Github <https://github.com/oldm/OldMan>`_ and to subscribe
 to our mailing list `oldman AT librelist.com`.
 

docs/modules.rst

@@ -0,0 +1,7 @@
+oldman
+======
+
+.. toctree::
+   :maxdepth: 4
+
+   oldman

docs/oldman.model.rst

@@ -0,0 +1,78 @@
+oldman.model package
+====================
+
+Submodules
+----------
+
+oldman.model.ancestry module
+----------------------------
+
+.. automodule:: oldman.model.ancestry
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+oldman.model.attribute module
+-----------------------------
+
+.. automodule:: oldman.model.attribute
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+oldman.model.converter module
+-----------------------------
+
+.. automodule:: oldman.model.converter
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+oldman.model.manager module
+---------------------------
+
+.. automodule:: oldman.model.manager
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+oldman.model.model module
+-------------------------
+
+.. automodule:: oldman.model.model
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+oldman.model.operation module
+-----------------------------
+
+.. automodule:: oldman.model.operation
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+oldman.model.property module
+----------------------------
+
+.. automodule:: oldman.model.property
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+oldman.model.registry module
+----------------------------
+
+.. automodule:: oldman.model.registry
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: oldman.model
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/oldman.parsing.rst

@@ -1,10 +1,24 @@
 oldman.parsing package
 ======================
 
+Subpackages
+-----------
+
 .. toctree::
 
     oldman.parsing.schema
 
+Submodules
+----------
+
+oldman.parsing.operation module
+-------------------------------
+
+.. automodule:: oldman.parsing.operation
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 oldman.parsing.value module
 ---------------------------
 
@@ -13,3 +27,11 @@ oldman.parsing.value module
     :undoc-members:
     :show-inheritance:
 
+
+Module contents
+---------------
+
+.. automodule:: oldman.parsing
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/oldman.parsing.schema.rst

@@ -1,6 +1,9 @@
 oldman.parsing.schema package
 =============================
 
+Submodules
+----------
+
 oldman.parsing.schema.attribute module
 --------------------------------------
 
@@ -25,3 +28,11 @@ oldman.parsing.schema.property module
     :undoc-members:
     :show-inheritance:
 
+
+Module contents
+---------------
+
+.. automodule:: oldman.parsing.schema
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/oldman.resource.rst

@@ -0,0 +1,30 @@
+oldman.resource package
+=======================
+
+Submodules
+----------
+
+oldman.resource.manager module
+------------------------------
+
+.. automodule:: oldman.resource.manager
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+oldman.resource.resource module
+-------------------------------
+
+.. automodule:: oldman.resource.resource
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: oldman.resource
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/oldman.rest.rst

@@ -1,6 +1,17 @@
 oldman.rest package
 ===================
 
+Submodules
+----------
+
+oldman.rest.controller module
+-----------------------------
+
+.. automodule:: oldman.rest.controller
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 oldman.rest.crud module
 -----------------------
 
@@ -9,3 +20,11 @@ oldman.rest.crud module
     :undoc-members:
     :show-inheritance:
 
+
+Module contents
+---------------
+
+.. automodule:: oldman.rest
+    :members:
+    :undoc-members:
+    :show-inheritance: