add docs and example

scikit-hep · kratsg · Mar 23, 2022 · Jan 24, 2022 · Jan 24, 2022 · Jan 24, 2022
commit 6b0573eb1d62b3ad5520f37069677e8d1950a17b
diff --git a/docs/api.rst b/docs/api.rst
@@ -168,12 +168,12 @@ Schema
    :toctree: _generated/
    :nosignatures:
 
+   Schema
    load_schema
    path
    validate
    version
 
-
 Exceptions
 ----------
 

diff --git a/src/pyhf/schema/__init__.py b/src/pyhf/schema/__init__.py
@@ -17,15 +17,48 @@ def __dir__():
 
 
 class Schema(sys.modules[__name__].__class__):
+    """
+    A module-level wrapper around ``pyhf.schema`` which will provide additional functionality for interacting with schemas.
+
+    Example:
+        >>> import pyhf.schema
+        >>> import pathlib
+        >>> curr_path = pyhf.schema.path
+        >>> curr_path # doctest: +ELLIPSIS
+        PosixPath('.../pyhf/schemas')
+        >>> pyhf.schema(pathlib.Path('/home/root/my/new/path'))
+        >>> pyhf.schema.path
+        PosixPath('/home/root/my/new/path')
+        >>> pyhf.schema(curr_path)
+        >>> pyhf.schema.path # doctest: +ELLIPSIS
+        PosixPath('.../pyhf/schemas')
+
+    """
+
     def __call__(self, new_path: pathlib.Path):
+        """
+        Change the local search path for finding schemas locally.
+
+        Args:
+            new_path (pathlib.Path): Path to folder containing the schemas
+
+        Returns:
+            None
+        """
         variables.schemas = new_path
 
     @property
     def path(self):
+        """
+        The local path for schemas.
+        """
         return variables.schemas
 
     @property
     def version(self):
+        """
+        The default version used for finding schemas.
+        """
         return variables.SCHEMA_VERSION
 
 

diff --git a/src/pyhf/schema/loader.py b/src/pyhf/schema/loader.py
@@ -11,7 +11,16 @@
     import importlib_resources as resources
 
 
-def load_schema(schema_id):
+def load_schema(schema_id: str):
+    """
+    Get a schema by relative path from cache, or load it into the cache and return.
+
+    Args:
+        schema_id (str): Relative path to schema from :attr:`pyhf.schema.path`
+
+    Returns:
+        schema (dict): The loaded schema.
+    """
     try:
         return variables.SCHEMA_CACHE[
             f'{Path(variables.SCHEMA_BASE).joinpath(schema_id)}'

diff --git a/src/pyhf/schema/validator.py b/src/pyhf/schema/validator.py
@@ -2,9 +2,25 @@
 import pyhf.exceptions
 from pyhf.schema.loader import load_schema
 from pyhf.schema import variables
+from typing import Union
 
 
-def validate(spec, schema_name, version=None):
+def validate(spec: dict, schema_name: str, version: Union[str, None] = None):
+    """
+    Validate a provided specification against a schema.
+
+    Args:
+        spec (dict): The specification to validate.
+        schema_name (str): The name of the schema to use.
+        version (None or str): The version to use if not the default from :attr:`pyhf.schema.version`.
+
+    Returns:
+        None: schema validated fine
+
+    Raises:
+        pyhf.exceptions.InvalidSpecification: the specification is invalid
+    """
+
     version = version or variables.SCHEMA_VERSION
 
     schema = load_schema(f'{version}/{schema_name}')