Merge 2abde4a into 6cda59d

docs/api.rst

@@ -25,6 +25,29 @@
 API Docs
 ========
 
-invenio_jsonschemas
--------------------
+.. automodule:: invenio_jsonschemas.ext
+   :members:
 
+Config
+------
+
+.. automodule:: invenio_jsonschemas.config
+   :members:
+
+Errors
+------
+
+.. automodule:: invenio_jsonschemas.errors
+   :members:
+
+JSON resolver
+-------------
+
+.. automodule:: invenio_jsonschemas.jsonresolver
+   :members:
+
+Views
+-------------
+
+.. automodule:: invenio_jsonschemas.views
+   :members:

examples/app.py

@@ -49,7 +49,7 @@
 app = Flask(__name__)
 
 # set the endpoint serving the JSON schemas
-app.config[InvenioJSONSchemas.CONFIG_ENDPOINT] = '/schemas'
+app.config['JSONSCHEMAS_ENDPOINT'] = '/schemas'
 
 # Initialize the application with the InvenioJSONSchema extension.
 # This registers the jsonschemas from examples/samplepkg/jsonschemas as

invenio_jsonschemas/config.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+#
+# This file is part of Invenio.
+# Copyright (C) 2016 CERN.
+#
+# Invenio is free software; you can redistribute it
+# and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version.
+#
+# Invenio is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Invenio; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+# MA 02111-1307, USA.
+#
+# In applying this license, CERN does not
+# waive the privileges and immunities granted to it by virtue of its status
+# as an Intergovernmental Organization or submit itself to any jurisdiction.
+
+"""Default configuration."""
+
+JSONSCHEMAS_HOST = 'localhost'
+"""Default json schema host."""
+
+JSONSCHEMAS_ENDPOINT = '/schemas'
+"""Default schema endpoint."""

invenio_jsonschemas/ext.py

@@ -35,6 +35,7 @@
 from werkzeug.exceptions import HTTPException
 from werkzeug.routing import Map, Rule
 
+from . import config
 from .errors import JSONSchemaDuplicate, JSONSchemaNotFound
 from .views import create_blueprint
 
@@ -91,8 +92,11 @@ def register_schema(self, directory, path):
     def get_schema_dir(self, path):
         """Retrieve the directory containing the given schema.
 
-        :param path: schema path, relative to the directory when it was
-        registered.
+        :param path: Schema path, relative to the directory where it was
+            registered.
+        :raises invenio_jsonschemas.errors.JSONSchemaNotFound: If no schema
+            was found in the specified path.
+        :returns: The schema directory.
         """
         if path not in self.schemas:
             raise JSONSchemaNotFound(path)
@@ -102,6 +106,9 @@ def get_schema_path(self, path):
         """Compute the schema's absolute path from a schema relative path.
 
         :param path: relative path of the schema.
+        :raises invenio_jsonschemas.errors.JSONSchemaNotFound: If no schema
+            was found in the specified path.
+        :returns: The absolute path.
         """
         if path not in self.schemas:
             raise JSONSchemaNotFound(path)
@@ -112,6 +119,9 @@ def get_schema(self, path):
         """Retrieve a schema.
 
         :param path: schema's relative path.
+        :raises invenio_jsonschemas.errors.JSONSchemaNotFound: If no schema
+            was found in the specified path.
+        :returns: The schema in a dictionary form.
         """
         if path not in self.schemas:
             raise JSONSchemaNotFound(path)
@@ -127,7 +137,11 @@ def list_schemas(self):
         return self.schemas.keys()
 
     def url_to_path(self, url):
-        """Convert schema URL to path."""
+        """Convert schema URL to path.
+
+        :param url: The schema URL.
+        :returns: The schema path or ``None`` if the schema can't be resolved.
+        """
         parts = urlsplit(url)
         try:
             loader, args = self.url_map.bind(parts.netloc).match(parts.path)
@@ -138,7 +152,11 @@ def url_to_path(self, url):
             return None
 
     def path_to_url(self, path):
-        """Build URL from a path."""
+        """Build URL from a path.
+
+        :param path: relative path of the schema.
+        :returns: The schema complete URL or ``None`` if not found.
+        """
         if path not in self.schemas:
             return None
         return self.url_map.bind(self.app.config['JSONSCHEMAS_HOST']).build(
@@ -155,16 +173,22 @@ class InvenioJSONSchemas(object):
     fields might not match the Flask application's host and port.
     """
 
-    CONFIG_ENDPOINT = 'JSONSCHEMAS_ENDPOINT'
-
     def __init__(self, app=None, **kwargs):
-        """Extension initialization."""
+        """Extension initialization.
+
+        :param app: The Flask application. (Default: ``None``)
+        """
         self.kwargs = kwargs
         if app:
             self.init_app(app, **kwargs)
 
     def init_app(self, app, entry_point_group=None):
-        """Flask application initialization."""
+        """Flask application initialization.
+
+        :param app: The Flask application.
+        :param entry_point_group: The group entry point to load extensions.
+            (Default: ``invenio_jsonschemas.schemas``)
+        """
         self.init_config(app)
 
         if not entry_point_group:
@@ -183,17 +207,17 @@ def init_app(self, app, entry_point_group=None):
 
         app.register_blueprint(
             create_blueprint(state),
-            url_prefix=app.config[InvenioJSONSchemas.CONFIG_ENDPOINT]
+            url_prefix=app.config['JSONSCHEMAS_ENDPOINT']
         )
 
         self._state = app.extensions['invenio-jsonschemas'] = state
         return state
 
     def init_config(self, app):
         """Initialize configuration."""
-        app.config.setdefault(InvenioJSONSchemas.CONFIG_ENDPOINT,
-                              '/schemas')
-        app.config.setdefault('JSONSCHEMAS_HOST', 'localhost')
+        for k in dir(config):
+            if k.startswith('JSONSCHEMAS_'):
+                app.config.setdefault(k, getattr(config, k))
 
     def __getattr__(self, name):
         """Proxy to state object."""

invenio_jsonschemas/jsonresolver.py

@@ -32,7 +32,7 @@
 
 @jsonresolver.hookimpl
 def jsonresolver_loader(url_map):
-    """JSON resolver plugin.
+    """JSON resolver plugin that loads the schema endpoint.
 
     Injected into Invenio-Records JSON resolver.
     """

invenio_jsonschemas/views.py

@@ -34,8 +34,8 @@
 def create_blueprint(state):
     """Create blueprint serving JSON schemas.
 
-    :param state: py:class:`invenio_jsonschemas.ext.InvenioJSONSchemasState`
-    instance used to retrieve the schemas
+    :param state: :class:`invenio_jsonschemas.ext.InvenioJSONSchemasState`
+       instance used to retrieve the schemas.
     """
     blueprint = Blueprint(
         'invenio_jsonschemas',

tests/test_invenio_jsonschemas.py

@@ -193,7 +193,7 @@ def test_view(app, pkg_factory, mock_entry_points):
 
     entry_point_group = 'invenio_jsonschema_test_entry_point'
     endpoint = '/testschemas'
-    app.config[InvenioJSONSchemas.CONFIG_ENDPOINT] = endpoint
+    app.config['JSONSCHEMAS_ENDPOINT'] = endpoint
     with pkg_factory(schema_files_1) as pkg1, \
             pkg_factory(schema_files_2) as pkg2, \
             pkg_factory(schema_files_3) as pkg3: