Merge pull request #106 from p1c2u/feature/readers-and-readme-update

Readers and README update

Author: p1c2u

README.rst

@@ -33,6 +33,13 @@ Installation
 
     $ pip install openapi-spec-validator
 
+Alternatively you can download the code and install from the repository:
+
+.. code-block:: bash
+
+   $ pip install -e git+https://github.com/p1c2u/openapi-spec-validator.git#egg=openapi_spec_validator
+
+
 Usage
 #####
 
@@ -43,25 +50,25 @@ Straight forward way:
 
 .. code:: bash
 
-    $ openapi-spec-validator some.yaml
+    $ openapi-spec-validator openapi.yaml
 
 pipes way:
 
 .. code:: bash
 
-    $ cat some.yaml | openapi-spec-validator -
+    $ cat openapi.yaml | openapi-spec-validator -
 
 docker way:
 
 .. code:: bash
 
-    $ docker run -v path/to/some.yaml:/some.yaml --rm p1c2u/openapi-spec-validator /some.yaml
+    $ docker run -v path/to/openapi.yaml:/openapi.yaml --rm p1c2u/openapi-spec-validator /openapi.yaml
 
 or more pythonic way:
 
 .. code:: bash
 
-    $ python -m openapi_spec_validator some.yaml
+    $ python -m openapi_spec_validator openapi.yaml
 
 Examples
 ********
@@ -70,34 +77,39 @@ Validate spec:
 
 .. code:: python
 
-
     from openapi_spec_validator import validate_spec
+    from openapi_spec_validator.readers import read_from_filename
+
+    spec_dict, spec_url = read_from_filename('openapi.yaml')
 
+    # If no exception is raised by validate_spec(), the spec is valid.
     validate_spec(spec_dict)
 
-Add ``spec_url`` to validate spec with relative files:
+    validate_spec({})
 
-.. code:: python
+    Traceback (most recent call last):
+        ...
+    OpenAPIValidationError: 'openapi' is a required property
 
+Add ``spec_url`` to validate spec with relative files:
 
-    from openapi_spec_validator import validate_spec
+.. code:: python
 
     validate_spec(spec_dict, spec_url='file:///path/to/spec/openapi.yaml')
 
 You can also validate spec from url:
 
 .. code:: python
 
-
     from openapi_spec_validator import validate_spec_url
 
+    # If no exception is raised by validate_spec_url(), the spec is valid.
     validate_spec_url('http://example.com/openapi.json')
 
 If you want to iterate through validation errors:
 
 .. code:: python
 
-
     from openapi_spec_validator import openapi_v3_spec_validator
 
     errors_iterator = openapi_v3_spec_validator.iter_errors(spec)

openapi_spec_validator/__main__.py

@@ -1,17 +1,12 @@
 import logging
 import argparse
-import os
-try:
-    import pathlib
-except ImportError:
-    import pathlib2 as pathlib
 import sys
 
 from openapi_spec_validator import (
-    openapi_v2_spec_validator, openapi_v3_spec_validator, all_urls_handler,
-    file_object_handler,
+    openapi_v2_spec_validator, openapi_v3_spec_validator,
 )
 from openapi_spec_validator.exceptions import ValidationError
+from openapi_spec_validator.readers import read_from_stdin, read_from_filename
 
 logger = logging.getLogger(__name__)
 logging.basicConfig(
@@ -20,19 +15,6 @@
 )
 
 
-def read_from_stdin(filename):
-    return file_object_handler(sys.stdin), ''
-
-
-def read_from_filename(filename):
-    if not os.path.isfile(filename):
-        raise SystemError("No such file {0}".format(filename))
-
-    filename = os.path.abspath(filename)
-    uri = pathlib.Path(filename).as_uri()
-    return all_urls_handler(uri), uri
-
-
 def main(args=None):
     parser = argparse.ArgumentParser()
     parser.add_argument('filename', help="Absolute or relative path to file")

openapi_spec_validator/readers.py

@@ -0,0 +1,21 @@
+import os
+try:
+    import pathlib
+except ImportError:
+    import pathlib2 as pathlib
+import sys
+
+from openapi_spec_validator import all_urls_handler, file_object_handler
+
+
+def read_from_stdin(filename):
+    return file_object_handler(sys.stdin), ''
+
+
+def read_from_filename(filename):
+    if not os.path.isfile(filename):
+        raise IOError("No such file: {0}".format(filename))
+
+    filename = os.path.abspath(filename)
+    uri = pathlib.Path(filename).as_uri()
+    return all_urls_handler(uri), uri