Use yaml.safe_load in README and minor refinements to docstrings

Signed-off-by: Graeme Watt <Graeme.Watt@durham.ac.uk>

README.rst

@@ -99,15 +99,15 @@ To validate data files, instantiate a ``DataFileValidator`` object:
 
 
 Optionally, if you have already loaded the YAML object, then you can pass it through
-as a data object. You must also pass through the ``file_path`` since this is used as a key
+as a ``data`` object. You must also pass through the ``file_path`` since this is used as a key
 for the error message lookup map.
 
 .. code:: python
 
     from hepdata_validator.data_file_validator import DataFileValidator
     import yaml
     
-    file_contents = yaml.load(open('data.yaml', 'r'))
+    file_contents = yaml.safe_load(open('data.yaml', 'r'))
     data_file_validator = DataFileValidator()
     
     data_file_validator.validate(file_path='data.yaml', data=file_contents)

hepdata_validator/__init__.py

@@ -37,9 +37,9 @@
 
 class Validator(object):
     """
-    Provides a general 'interface' for Validator in HEPdata
+    Provides a general 'interface' for Validator in HEPData
     which validates schema files created with the
-    JSONschema syntax http://json-schema.org/
+    JSON Schema syntax http://json-schema.org/
     """
     __metaclass__ = abc.ABCMeta
 
@@ -67,6 +67,7 @@ def _get_schema_filepath(self, schema_filename):
     def validate(self, **kwargs):
         """
         Validates a file.
+
         :param file_path: path to file to be loaded.
         :param data: pre loaded YAML object (optional).
         :return: true if valid, false otherwise
@@ -76,6 +77,7 @@ def has_errors(self, file_name):
         """
         Returns true if the provided file name has error messages
         associated with it, false otherwise.
+
         :param file_name:
         :return: boolean
         """
@@ -85,6 +87,7 @@ def get_messages(self, file_name=None):
         """
         Return messages for a file (if file_name provided).
         If file_name is none, returns all messages as a dict.
+
         :param file_name:
         :return: array if file_name is provided, dict otherwise.
         """
@@ -99,14 +102,16 @@ def get_messages(self, file_name=None):
 
     def clear_messages(self):
         """
-        Removes all error messages
+        Removes all error messages.
+
         :return:
         """
         self.messages = {}
 
     def add_validation_message(self, message):
         """
-        Adds a message to the messages dict
+        Adds a message to the messages dict.
+
         :param message:
         """
         if message.file not in self.messages:
@@ -116,7 +121,7 @@ def add_validation_message(self, message):
 
     def print_errors(self, file_name):
         """
-        Prints the errors observed for a file
+        Prints the errors observed for a file.
         """
         for error in self.get_messages(file_name):
             print('\t', error.__unicode__())

hepdata_validator/data_file_validator.py

@@ -40,7 +40,7 @@
 
 class DataFileValidator(Validator):
     """
-    Validates the Data file YAML/JSON file
+    Validates the YAML/JSON data file.
     """
     base_path = os.path.dirname(__file__)
     schema_name = 'data_schema.json'
@@ -52,14 +52,16 @@ def __init__(self, *args, **kwargs):
 
     def _get_major_version(self):
         """
-        Parses the major version of the validator
+        Parses the major version of the validator.
+
         :return: integer corresponding to the validator major version
         """
         return int(self.schema_version.split('.')[0])
 
     def load_custom_schema(self, type, schema_file_path=None):
         """
-        Loads a custom schema, or will used a stored version for the given type if available
+        Loads a custom schema, or will use a stored version for the given type if available.
+
         :param type: e.g. histfactory
         :return:
         """
@@ -86,7 +88,7 @@ def load_custom_schema(self, type, schema_file_path=None):
 
     def validate(self, **kwargs):
         """
-        Validates a data file
+        Validates a data file.
 
         :param file_path: path to file to be loaded.
         :param file_type: file data type (optional).

hepdata_validator/schema_downloader.py

@@ -57,7 +57,7 @@ def get_schema_spec(self, schema_name):
     @abstractmethod
     def get_schema_type(self, schema_name):
         """
-        Builds the data type of the file given its schema name
+        Builds the data type of the file given its schema name.
 
         :param schema_name: str.
         :return: str.
@@ -68,7 +68,7 @@ def get_schema_type(self, schema_name):
     @abstractmethod
     def save_locally(self, schema_name, schema_spec, overwrite):
         """
-        Saves the remote schema in the local file system
+        Saves the remote schema in the local file system.
 
         :param schema_name: str.
         :param schema_spec: str.
@@ -81,7 +81,7 @@ def save_locally(self, schema_name, schema_spec, overwrite):
 
 class HTTPSchemaDownloader(SchemaDownloaderInterface):
     """
-    Object to download schemas using HTTP / HTTPS
+    Object to download schemas using HTTP / HTTPS.
     Used to validate schemas available across the internet.
     """
 
@@ -132,7 +132,7 @@ def _parse_remote_url(self, url):
 
     def _build_local_path(self, *paths):
         """
-        Builds the schemas local saving path
+        Builds the schemas local saving path.
 
         :param paths: str.
         """
@@ -156,7 +156,7 @@ def get_schema_spec(self, schema_name):
 
     def get_schema_type(self, schema_name):
         """
-        Builds the data type of the file given its schema name
+        Builds the data type of the file given its schema name.
 
         :param schema_name: str.
         :return: str.
@@ -169,7 +169,7 @@ def get_schema_type(self, schema_name):
 
     def save_locally(self, schema_name, schema_spec, overwrite=False):
         """
-        Saves the remote schema in the local file system
+        Saves the remote schema in the local file system.
 
         :param schema_name: str.
         :param schema_spec: dict.

hepdata_validator/schema_resolver.py

@@ -38,15 +38,15 @@
 class SchemaResolverInterface(object):
     """
     Interface for the schema resolver objects.
-    Used to resolve $ref within the defined schemas
+    Used to resolve $ref within the defined schemas.
     """
 
     __metaclass__ = ABCMeta
 
     @abstractmethod
     def resolve(self, schema_uri):
         """
-        Resolves and entire JSON-LD schema
+        Resolves an entire JSON schema.
 
         :param schema_uri: str.
         :return: dict.
@@ -56,11 +56,11 @@ def resolve(self, schema_uri):
 
 
 class DummySchemaResolver(SchemaResolverInterface):
-    """ Dummy object to resolve schemas using `requests` as references fetcher """
+    """ Dummy object to resolve schemas using `requests` as references fetcher. """
 
     def resolve(self, schema_uri):
         """
-        Gets the schema content (dummy)
+        Gets the schema content (dummy).
 
         :param schema_uri: str.
         :return: dict.
@@ -81,7 +81,7 @@ class JsonSchemaResolver(SchemaResolverInterface):
 
     def __init__(self, schemas_uri):
         """
-        Initializes the inner $ref `jsonschema` resolver
+        Initializes the inner $ref `jsonschema` resolver.
 
         :param schemas_uri: str.
         """
@@ -94,7 +94,7 @@ def __init__(self, schemas_uri):
 
     def _walk_dict(self, obj, ref):
         """
-        Iterates a dictionary within the schema resolving every $ref
+        Iterates a dictionary within the schema resolving every $ref.
 
         :param obj: dict.
         :param ref: str.
@@ -121,7 +121,7 @@ def _walk_dict(self, obj, ref):
 
     def _walk_list(self, seq, ref):
         """
-        Iterates a sequence within the schema resolving every $ref
+        Iterates a sequence within the schema resolving every $ref.
 
         :param seq: list.
         :param ref: str.
@@ -141,7 +141,7 @@ def _walk_list(self, seq, ref):
 
     def resolve(self, schema_uri):
         """
-        Resolves a JSON-LD schema either from a remote or a local URI.
+        Resolves a JSON schema either from a remote or a local URI.
 
         :param schema_uri: str.
         :return: dict.

hepdata_validator/submission_file_validator.py

@@ -17,7 +17,7 @@
 
 class SubmissionFileValidator(Validator):
     """
-    Validates the Submission file YAML/JSON file
+    Validates the Submission file YAML/JSON file.
     """
     base_path = os.path.dirname(__file__)
     submission_filename = 'submission_schema.json'
@@ -30,7 +30,7 @@ def __init__(self, *args, **kwargs):
 
     def validate(self, **kwargs):
         """
-        Validates a submission file
+        Validates a submission file.
 
         :param file_path: path to file to be loaded.
         :param data: pre loaded YAML object (optional).