Docs fire 130

docs/cookbook.rst

@@ -1,16 +1,16 @@
-Firetail Cookbook
+FireTail Cookbook
 ==================
 
 This section aims to be a cookbook of possible solutions for specific
-use cases of Firetail.
+use cases of FireTail.
 
 Wildcard path parameters
 ------------------------
 
-Path parameters cannot contain slashes by default, but sometimes it's useful
-to have a path parameter which takes the full remainder of the HTTP path
-including slashes, e.g. to allow parsing "my/deep/path" from
-"/pages/my/deep/path". Firetail supports parsing such path remainders
+By default, path parameters cannot contain slashes, but sometimes it's useful
+to have a path parameter that takes the full remainder of the HTTP path
+including slashes, for example, to allow parsing "my/deep/path" from
+"/pages/my/deep/path". FireTail supports parsing such path remainders
 by using ``format: path``:
 
 .. code-block:: yaml
@@ -31,16 +31,16 @@ by using ``format: path``:
 Custom type format
 ------------------
 
-It is possible to define custom type formats that are going to be used
-by the Firetail payload validation on request parameters and response
+It is possible to define custom type formats that will be used
+by the FireTail payload validation on request parameters and response
 payloads of your API.
 
-Let's say your API deals with Products and you want to define a field
+For example, if your API deals with Products and you want to define a field
 `price_label` that has a "money" format value. You can create a format
 checker function and register that to be used to validate values of
 the "money" format.
 
-Example of a possible schema of Product having an attribute with
+Below is an example of a possible schema of Product having an attribute with the
 "money" format that would be defined in your OpenAPI specification:
 
 .. code-block:: yaml
@@ -67,15 +67,15 @@ Then we create a format checker function for that type of value:
             return True
         return MONEY_RE.match(val)
 
-The format checker function is expected to return `True` when the
-value matches the expected format and return `False` when it
-doesn't. Also is important to verify if the type of the value you are
-trying to validate is compatible with the format. In our example we
+The format checker function returns `True` when the
+value matches the expected format and returns `False` when it
+doesn't. Also, it is important to verify if the type of the value you are
+trying to validate is compatible with the format. In our example, we
 check if the `val` is of type "string" before performing any further
 checking.
 
-The final step to make it work is registering our `is_money` function
-to the format "money" in json_schema library. For that, we can use the
+The final step is registering our `is_money` function
+to the format "money" in the json_schema library. For that, we can use the
 draft4 format checker decorator.
 
 .. code-block:: python
@@ -87,7 +87,7 @@ draft4 format checker decorator.
         ...
 
 This is all you need to have validation for that format in your
-Firetail application. Keep in mind that the format checkers should be
+FireTail application. Keep in mind that the format checkers should be
 defined and registered before you run your application server. A full
 example can be found at
 https://gist.github.com/rafaelcaricio/6e67286a522f747405a7299e6843cd93
@@ -96,7 +96,7 @@ https://gist.github.com/rafaelcaricio/6e67286a522f747405a7299e6843cd93
 CORS Support
 ------------
 
-CORS_ (Cross-origin resource sharing) is not built into Firetail, but you can use the `flask-cors`_ library
+CORS_ (Cross-origin resource sharing) is not built into FireTail, but you can use the `flask-cors`_ library
 to set CORS headers:
 
 .. code-block:: python
@@ -120,9 +120,9 @@ to set CORS headers:
 Logging
 ------------
 
-You can customize logging accessing the `_flask-logger` directly
-or configuring the logger via dictConfig.
-Remember that you should configure logging for your project as soon
+You can customize logging by accessing the `_flask-logger` directly
+or configuring the logger using dictConfig.
+Remember to configure logging for your project as soon
 as possible when the program starts or you'll get the default configuration.
 
 .. code-block:: python

docs/exceptions.rst

@@ -2,18 +2,18 @@ Exception Handling
 ==================
 Rendering Exceptions through the Flask Handler
 ----------------------------------------------
-Flask by default contains an exception handler, which firetail's app can proxy
-to with the ``add_error_handler`` method. You can hook either on status codes
+By default, Flask contains an exception handler, which FireTail's app can proxy
+to with the ``add_error_handler`` method. You can either hook on status codes
 or on a specific exception type.
 
-Firetail is moving from returning flask responses on errors to throwing exceptions
+FireTail is moving from returning flask responses on errors to throwing exceptions
 that are a subclass of ``firetail.problem``. So far exceptions thrown in the OAuth
 decorator have been converted.
 
 Flask Error Handler Example
 ---------------------------
 
-The goal here is to make the api returning the 404 status code
+The goal here is to make the API returning the 404 status code
 when there is a NotFoundException (instead of 500)
 
 .. code-block:: python
@@ -24,7 +24,7 @@ when there is a NotFoundException (instead of 500)
         assert response.status_code == 404
 
 
-Firstly, it's possible to declare what Exception must be handled
+Firstly, it's possible to declare what Exception must be handled:
 
 .. code-block:: python
 
@@ -88,7 +88,7 @@ and we know the API will return 404 status code.
 
 Default Exception Handling
 --------------------------
-By default firetail exceptions are JSON serialized according to
+By default, FireTail exceptions are JSON serialized according to
 `Problem Details for HTTP APIs`_
 
 Application can return errors using ``firetail.problem`` or exceptions that inherit from both
@@ -106,8 +106,8 @@ exception
 
 Examples of Custom Rendering Exceptions
 ---------------------------------------
-To custom render an exception when you boot your firetail application you can hook into a custom
-exception and render it in some sort of custom format. For example
+To custom render an exception when you boot your FireTail application you can hook into a custom
+exception and render it in some sort of custom format. For example:
 
 
 .. code-block:: python
@@ -124,23 +124,24 @@ exception and render it in some sort of custom format. For example
 
 Custom Exceptions
 -----------------
-There are several exception types in firetail that contain extra information to help you render appropriate
+There are several exception types in FireTail that contain extra information to help you render appropriate
 messages to your user beyond the default description and status code:
 
 OAuthProblem
 ^^^^^^^^^^^^
-This exception is thrown when there is some sort of validation issue with the Authorisation Header
+This exception is thrown when there is some sort of validation issue with the Authorisation Header.
 
 OAuthResponseProblem
 ^^^^^^^^^^^^^^^^^^^^
 This exception is thrown when there is a validation issue from your OAuth 2 Server. It contains a
-``token_response`` property which contains the full http response from the OAuth 2 Server
+``token_response`` property which contains the full http response from the OAuth 2 Server.
 
 OAuthScopeProblem
 ^^^^^^^^^^^^^^^^^
 This scope indicates the OAuth 2 Server did not generate a token with all the scopes required. This
-contains 3 properties
-- ``required_scopes`` - The scopes that were required for this endpoint
-- ``token_scopes`` - The scopes that were granted for this endpoint
+contains 3 properties:
+
+- ``required_scopes`` - The scopes that were required for this endpoint.
+- ``token_scopes`` - The scopes that were granted for this endpoint.
 
 

docs/index.rst

@@ -3,22 +3,22 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Firetail's documentation!
+Welcome to FireTail's documentation!
 =====================================
 
-Firetail is a framework on top of Flask_ that automagically handles
+FireTail is a framework on top of Flask_ that automagically handles
 HTTP requests defined using `OpenAPI`_ (formerly known
 as Swagger), supporting both `v2.0`_ and `v3.0`_ of the specification. 
 
-Firetail allows you to write these specifications, then maps the
+FireTail allows you to write these specifications, then maps the
 endpoints to your Python functions. This is what makes it unique from
 other tools that generate the specification based on your Python
 code. You are free to describe your REST API with as much detail as
-you want and then Firetail guarantees that it will work as
-you specified. We built Firetail this way in order to:
+you want and then FireTail guarantees that it will work as
+you specified. We built FireTail this way in order to:
 
-- Simplify the development process
-- Reduce misinterpretation about what an API is going to look like
+- Simplify the development process.
+- Reduce misinterpretation about what an API is going to look like.
 
 Contents:
 

docs/request.rst

@@ -1,6 +1,6 @@
 Request Handling
 ================
-Firetail validates incoming requests for conformance with the schemas
+FireTail validates incoming requests for conformance with the schemas
 described in swagger specification.
 
 Request parameters will be provided to the handler functions as keyword
@@ -13,12 +13,12 @@ Request Validation
 Both the request body and parameters are validated against the specification,
 using `jsonschema`_.
 
-If the request doesn't match the specification firetail will return a 400
+If the request doesn't match the specification FireTail will return a 400
 error.
 
 Automatic Parameter Handling
 ----------------------------
-Firetail automatically maps the parameters defined in your endpoint
+FireTail automatically maps the parameters defined in your endpoint
 specification to arguments of your Python views as named parameters
 and with value casting whenever possible. All you need to do is define
 the endpoint's parameters with matching names with your views arguments.
@@ -48,11 +48,11 @@ And the view function:
         # do something
         return 'You send the message: {}'.format(message), 200
 
-In this example Firetail will automatically identify that your view
+In this example FireTail will automatically identify that your view
 function expects an argument named `message` and will assign the value
 of the endpoint parameter `message` to your view function.
 
-Firetail will also use default values if they are provided.
+FireTail will also use default values if they are provided.
 
 If you want to use a parameter name that collides with a Python built-in,
 you can enable the `pythonic_params` option:
@@ -62,7 +62,7 @@ you can enable the `pythonic_params` option:
     app = firetail.FlaskApp(__name__)
     app.add_api('api.yaml', ..., pythonic_params=True)
 
-With this option enabled, Firetail firstly converts *CamelCase* names
+With this option enabled, FireTail firstly converts *CamelCase* names
 to *snake_case*. Secondly it looks to see if the name matches a known built-in
 and if it does it appends an underscore to the name.
 
@@ -117,7 +117,7 @@ And the view function:
 
 Type casting
 ^^^^^^^^^^^^
-Whenever possible Firetail will try to parse your argument values and
+Whenever possible FireTail will try to parse your argument values and
 do type casting to related Python natives values. The current
 available type castings are:
 
@@ -146,13 +146,13 @@ available type castings are:
 
 In the `OpenAPI 2.0 Specification`_ if you use the ``array`` type,
 you can define the ``collectionFormat`` to set the deserialization behavior.
-Firetail currently supports "pipes" and "csv" as collection formats.
+FireTail currently supports "pipes" and "csv" as collection formats.
 The default format is "csv".
 
-Firetail is opinionated about how the URI is parsed for ``array`` types.
+FireTail is opinionated about how the URI is parsed for ``array`` types.
 The default behavior for query parameters that have been defined multiple
-times is to join them all together. For example, if you provide a URI with
-the the query string ``?letters=a,b,c&letters=d,e,f``, firetail will set
+times is to join them all together. For example, if you provide a URI with 
+the query string ``?letters=a,b,c&letters=d,e,f``, firetail will set
 ``letters = ['a', 'b', 'c', 'd', 'e', 'f']``.
 
 You can override this behavior by specifying the URI parser in the app or
@@ -203,7 +203,7 @@ There are a handful of URI parsers included with connection.
 Parameter validation
 ^^^^^^^^^^^^^^^^^^^^
 
-Firetail can apply strict parameter validation for query and form data
+FireTail can apply strict parameter validation for query and form data
 parameters.  When this is enabled, requests that include parameters not defined
 in the swagger spec return a 400 error.  You can enable it when adding the API
 to your application:
@@ -218,7 +218,7 @@ Nullable parameters
 
 Sometimes your API should explicitly accept `nullable parameters`_. However
 OpenAPI specification currently does `not support`_ officially a way to serve
-this use case, Firetail adds the `x-nullable` vendor extension to parameter
+this use case, FireTail adds the `x-nullable` vendor extension to parameter
 definitions. Its usage would be:
 
 .. code-block:: yaml
@@ -231,7 +231,7 @@ definitions. Its usage would be:
            x-nullable: true
            required: true
 
-It is supported by Firetail in all parameter types: `body`, `query`,
+It is supported by FireTail in all parameter types: `body`, `query`,
 `formData`, and `path`. Nullable values are the strings `null` and `None`.
 
 .. warning:: Be careful on nullable parameters for sensitive data where the

docs/response.rst

@@ -5,19 +5,19 @@ Response Serialization
 ----------------------
 If the endpoint returns a `Response` object this response will be used as is.
 
-Otherwise, and by default and if the specification defines that an endpoint
-produces only JSON, firetail will automatically serialize the return value
-for you and set the right content type in the HTTP header.
+Otherwise, by default and if the specification defines that an endpoint
+produces only JSON, FireTail automatically serializes the return value
+for you and sets the right content type in the HTTP header.
 
-If the endpoint produces a single non-JSON mimetype then Firetail will
-automatically set the right content type in the HTTP header.
+If the endpoint produces a single non-JSON mimetype then FireTail
+automatically sets the right content type in the HTTP header.
 
 Customizing JSON encoder
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Firetail allows you to customize the `JSONEncoder` class in the Flask app
-instance `json_encoder` (`firetail.App:app`). If you wanna reuse the
-Firetail's date-time serialization, inherit your custom encoder from
+FireTail allows you to customize the `JSONEncoder` class in the Flask app
+instance `json_encoder` (`firetail.App:app`). If you want to reuse the
+FireTail's date-time serialization, inherit your custom encoder from
 `firetail.apps.flask_app.FlaskJSONProvider`.
 
 For more information on the `JSONEncoder`, see the `Flask documentation`_.
@@ -30,7 +30,9 @@ There are two ways of returning a specific status code.
 
 One way is to return a `Response` object that will be used unchanged.
 
-The other is returning it as a second return value in the response. For example
+The other is returning it as a second return value in the response. 
+
+For example:
 
 .. code-block:: python
 
@@ -44,9 +46,9 @@ There are two ways to return headers from your endpoints.
 One way is to return a `Response` object that will be used unchanged.
 
 The other is returning a dict with the header values as the third return value
-in the response:
+in the response.
 
-For example
+For example:
 
 .. code-block:: python
 
@@ -56,7 +58,7 @@ For example
 
 Response Validation
 -------------------
-While, by default Firetail doesn't validate the responses it's possible to
+By default FireTail doesn't validate the responses it's possible to
 do so by opting in when adding the API:
 
 .. code-block:: python
@@ -67,7 +69,7 @@ do so by opting in when adding the API:
     app.add_api('my_api.yaml', validate_responses=True)
     app.run(port=8080)
 
-This will validate all the responses using `jsonschema` and is specially useful
+This validates all the responses using `jsonschema` and is specially useful
 during development.
 
 
@@ -89,7 +91,7 @@ the validation, you can override the default class with:
 
 Error Handling
 --------------
-By default firetail error messages are JSON serialized according to
+By default FireTail error messages are JSON serialized according to
 `Problem Details for HTTP APIs`_
 
 Application can return errors using ``firetail.problem``.