Usage

Quickstart

Let’s get started with a trivial example, this usage assumes you are familiar with schematics (v2.x) and somewhat familiar with requests.

Firstly, define models that represent the API you have the fortunate pleasure of communicating with.

from schematics import Model, IntegerType, StringType, BooleanType, ListType, ModelType

class Book(Model):
    title = StringType(required=True, min_length=3)


class Request(Model):
    """
    Represents, as a Python object, the JSON data required by the API.
    """
    in_print = BooleanType()


class Response(Model):
    """
    Represents, as a Python object, the JSON response returned by the API.
    """
    books = ListType(ModelType(Book))

Once you’ve defined models that represent the APIs input/output you then create a class that inherits eater.HTTPEater. Your class must define a url, request_cls and response_cls.

import eater

class BooksAPI(eater.HTTPEater):
    url = 'https://example.com/books/'
    request_cls = Request
    response_cls = Response

You can then consume the API;

api = BooksAPI()
response = api(in_print=True)

for book in response.books:
    print(book.title)

Note that you call the actual instance and can pass in kwargs that are used to create an instance of your Request model.

It’s also possible to pass in an instance of your request model;

request_model = Request({'in_print': True})
response = api(request_model=request_model)

HTTP request type

By default HTTPEater performs a HTTP GET request, you can change this by setting method on your API class;

class BooksAPI(eater.HTTPEater):
    method = 'post'
    ...

Or alternatively at runtime;

api = BooksAPI()
api.method = 'post'

Any request method supported by requests is supported, ie... PUT, DELETE, HEAD, OPTIONS.

Dynamic URL

The url is just a property, thus you can define it dynamically;

class BooksAPI(eater.HTTPEater):

    @property
    def url(self):
        return 'http://path.to.awesome/'

Control Request Parameters

You can control the params, or any kwarg supplied to requests by defining a get_request_kwargs method in your class.

class BooksAPI(eater.HTTPEater):

    def get_request_kwargs(self, request_model: Request, **kwargs) -> dict:
        """
        Retrieve a dict of kwargs to supply to requests.
        """
        kwargs['params'] = {
            'in_print': request_model
        }
        return kwargs

However, a better way of settings kwargs['params'] above would be;

kwargs['params'] = request_model.to_primitive()

Auth, Headers & Sessions

Under the covers HTTPEater automatically creates a requests.Session for you.

When you create an instance of HTTPEater you can pass through kwargs that will be applied to this generated session, or optionally you can pass in a session object of your creation.

api = BooksAPI(auth=('john', 's3cr3t'))

Need to set a custom header?

api = BooksAPI(headers={'EGGS': 'Sausage'})

Or do something really special with your own custom session?

session = requests.Session()
api = BooksAPI(session=session)

Alternatively you can override the create_session method on your BooksAPI class;

class BooksAPI(eater.HTTPEater):
    url = 'https://example.com/books/'
    request_cls = Request
    response_cls = Response

    def create_session(self, auth: tuple=None, headers: requests.structures.CaseInsensitiveDict=None) -> requests.Session:
        """
        Create an instance of a requests Session.
        """
        if self.session is None:
            self.session = requests.Session()
            if auth:
                self.session.auth = auth
            if headers:
                self.session.headers.update(headers)
        return self.session

More Control

You can break into all aspects of eater’s lifecycle, simply by overriding any one of the methods it uses to call and parse the response from your friendly API.

See the Internal Module Reference for more details.