Merge branch 'development' into packaging

lakesuperior/env_setup.py

@@ -2,8 +2,15 @@ from lakesuperior.config_parser import config
 from lakesuperior.globals import AppGlobals
 from lakesuperior.env import env
 
-'''
-Import this module to initialize the configuration for a production setup.
-'''
+__doc__="""
+Default configuration.
+
+Import this module to initialize the configuration for a production setup::
+
+    >>>from lakesuperior import env_setup
+
+Will load the default configuration.
+"""
+
 env.config = config
 env.app_globals = AppGlobals(config)

lakesuperior/globals.py

@@ -5,25 +5,48 @@ from importlib import import_module
 
 from lakesuperior.dictionaries.namespaces import ns_collection as nsc
 
-'''
-Constants used in messaging to identify an event type.
-'''
 RES_CREATED = '_create_'
+"""A resource was created."""
 RES_DELETED = '_delete_'
+"""A resource was deleted."""
 RES_UPDATED = '_update_'
+"""A resource was updated."""
 
 ROOT_UID = '/'
+"""Root node UID."""
 ROOT_RSRC_URI = nsc['fcres'][ROOT_UID]
+"""Internal URI of root resource."""
 
 
 class AppGlobals:
-    '''
+    """
     Application Globals.
 
-    This class sets up all connections and exposes them across the application
-    outside of the Flask app context.
-    '''
+    This class is instantiated and used as a carrier for all connections and
+    various global variables outside of the Flask app context.
+
+    The variables are set on initialization by passing a configuration dict.
+    Usually this is done when starting an application. The instance with the
+    loaded variables is then assigned to the :data:`lakesuperior.env.env`
+    global variable.
+
+    You can either load the default configuration::
+
+        >>>from lakesuperior import env_setup
+
+    Or set up an environment with a custom configuration::
+
+        >>>from lakesuperior.env import env
+        >>>from lakesuperior.app_globals import AppGlobals
+        >>>my_config = {'name': 'value', '...': '...'}
+        >>>env.config = my_config
+        >>>env.app_globals = AppGlobals(my_config)
+
+    """
     def __init__(self, conf):
+        """
+        Generate global variables from configuration.
+        """
         from lakesuperior.messaging.messenger import Messenger
 
         app_conf = conf['application']
@@ -53,18 +76,45 @@ class AppGlobals:
 
     @property
     def rdfly(self):
+        """
+        Current RDF layout.
+
+        This is an instance of
+        :class:`~lakesuperior.store.ldp_rs.rsrc_centric_layout.RsrcCentricLayout`.
+
+        *TODO:* Update class reference when interface will be separated from
+        implementation.
+        """
         return self._rdfly
 
     @property
     def rdf_store(self):
+        """
+        Current RDF low-level store.
+
+        This is an instance of
+        :class:`~lakesuperior.store.ldp_rs.lmdb_store.LmdbStore`.
+        """
         return self._rdfly.store
 
     @property
     def nonrdfly(self):
         return self._nonrdfly
+        """
+        Current non-RDF (binary contents) layout.
+
+        This is an instance of
+        :class:`~lakesuperior.store.ldp_nr.base_non_rdf_layout.BaseNonRdfLayout`.
+        """
 
     @property
     def messenger(self):
+        """
+        Current message handler.
+
+        This is an instance of
+        :class:`~lakesuperior.messaging.messenger.Messenger`.
+        """
         return self._messenger
 
     @property
@@ -73,9 +123,9 @@ class AppGlobals:
 
 
     def camelcase(self, word):
-        '''
+        """
         Convert a string with underscores to a camel-cased one.
 
         Ripped from https://stackoverflow.com/a/6425628
-        '''
+        """
         return ''.join(x.capitalize() or '_' for x in word.split('_'))

lakesuperior/migrator.py

@@ -48,24 +48,24 @@ class Migrator:
     regular intervals.
     """
 
-    """
-    LMDB database parameters.
-
-    See :meth:`lmdb.Environment.__init__`
-    """
     db_params = {
         'map_size': 1024 ** 4,
         'metasync': False,
         'readahead': False,
         'meminit': False,
     }
+    """
+    LMDB database parameters.
+
+    See :meth:`lmdb.Environment.__init__`
+    """
 
-    """List of predicates to ignore when looking for links."""
     ignored_preds = (
         nsc['fcrepo'].hasParent,
         nsc['fcrepo'].hasTransactionProvider,
         nsc['fcrepo'].hasFixityService,
     )
+    """List of predicates to ignore when looking for links."""
 
 
     def __init__(
@@ -138,11 +138,11 @@ class Migrator:
         data set contained in a folder from an LDP repository.
 
         :param start_pts: List of starting points to retrieve
-        :type start_pts: tuple or list
             resources from. It would typically be the repository root in case
             of a full dump or one or more resources in the repository for a
             partial one.
-        :param str listf_ile: path to a local file containing a list of URIs,
+        :type start_pts: tuple or list
+        :param str list_file: path to a local file containing a list of URIs,
             one per line.
         """
         from lakesuperior.api import resource as rsrc_api

lakesuperior/store/ldp_rs/lmdb_store.py

@@ -168,7 +168,8 @@ class LmdbStore(Store):
     - ``c:spo`` (context → triple association; dupsort, dupfixed)
     - ``ns:pfx`` (pickled namespace: prefix; 1:1)
 
-    The default graph is defined in :data:``RDFLIB_DEFAULT_GRAPH_URI``. Adding
+    The default graph is defined in
+    :data:`rdflib.graph.RDFLIB_DEFAULT_GRAPH_URI`. Adding
     triples without context will add to this graph. Looking up triples without
     context (also in a SPARQL query) will look in the  union graph instead of
     in the default graph. Also, removing triples without specifying a context