Metadata-Version: 1.1
Name: cosmicray
Version: 0.0.13
Summary: Develop a client for your HTTP API and document its quirks and features
Home-page: https://github.com/somerovi/cosmicray
Author: Samir Omerovic
Author-email: somerovi@gmail.com
License: MIT
Description-Content-Type: UNKNOWN
Description: 
        Cosmicray
        =========
        
        ------------------------------------------------------------------------
         Develop a client for any http API and document its quirks and features
        ------------------------------------------------------------------------
        
        Cosmicray is a simple and high level http client API development framework. It provides the basic building blocks for
        defining enpoints, handling a request response and automatically converting the result into to Models.
        
        Motivation:
        
        - Ease of use
        - Configureability and customization on every level
        - Namespace different backends (one client to rule them all)
        - Separate route definitions / response handling from models or "business logic"
        - Ability to validate requests before making them
        - Authenticate each request as needed
        - Ability to associate routes to models
        
        .. warning::
        
           Cosmicray is under development
        
        Install
        -------
        
        .. code::
        
           $ pip install cosmicray
        
        Quick start
        -----------
        
        Create App
        ~~~~~~~~~~
        
        .. code:: python
        
            >>> from cosmicray import Cosmicray
            >>> api = Cosmicray('myapp', domain='http://mydomain.com')
        
        Define routes and response handlers
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Using the app we created, we can now add routes for it and define a response handler for each one. The response handler is simply a regular function that accepts a single argument of type `requests.Response` and returns the processed result.
        
        .. code:: python
        
            >>> @api.route('/v1/dogs/{id}', ['GET', 'POST', 'PUT', 'DELETE'])
            >>> def dogs(response):
            ...     return response.json()
        
        - The decorator `api.route` creates an instance of `cosmicray.Route` named `dogs`
          and stores the given function internally as the response handler.
        
        - Instances of `cosmicray.Route` are callable and accept parameters:
        
          - `model_cls`: Optional: Class that implements `_make(cls, response)` classmethod.
          - `\*\*kwargs`: Keyword arguments.
        
            - `urlargs`: Mapping for url formatting arguments
            - `headers`: Mapping for headers
            - `params`: Mapping for query parameters
            - `data`, `json`, `files`: Request body
            - `authenticator`: Authenticator callback
            - *&rest*: Requests keyword arguments
        
        
        - When and instance of `cosmicray.Route` is called, it returns a `Request` object and with this you can:
        
          - Use functions defined for each http method (ex: `get()`, `post()`, `put()`, `delete()`)
          - Override any parameters passed in (ex: `params`, `headers`, etc.) with setters
          - Automatically validates given parameters against the defined parameters on the `Route`
          - Authenticates the request, if the app was configured with an authenticator
          - After the response is handled by the response handler, the result is automatically mapped to the model class, if one was provided
        
        How to make requests
        ~~~~~~~~~~~~~~~~~~~~
        
        .. code:: python
        
           >>> dogs().get()
           >>> dogs(urlargs={id: 12345}).get()
           >>> dogs(json={'name': 'Manu'}).post()
           >>> dogs(urlargs={'id': 12345}, json={'age': 4}).put()
           >>> dogs(urlargs={'id': 12345}).delete()
        
        To specify request parameters
        
        .. code:: python
        
           >>> dogs(params={'breed': 'husky'},
           ...      headers={'Content-Type': 'application/json'}).get()
        
        Authenticating requests
        ~~~~~~~~~~~~~~~~~~~~~~~
        
        Often you'll need to authenticate requests to access private resource and Cosmicray has a built-in mechanism to perform this step.
        
        .. code:: python
        
            >>> def authenticator(request):
            ...     if not request.is_request_for(login):
            ...         auth = login(json={'username': 'me', 'password': 'mysecret'}).post()
            ...         return request.set_headers({'X-AUTH-TOKEN': auth['token']})
            ...     return request
            ...
            >>> @api.route('/oauth', ['POST'])
            ... def login(response):
            ...     """Get an auth token for the given credentials"""
            ...     return response.json()
            ...
            >>> @api.route('/private/resource', ['GET'])
            ... def private_resource(response):
            ...     """Must be authenticated to access this"""
            ...     return response.json()
            ...
            >>> api.configure(authenticator=authenticator)
            >>> # Now the private resourse will be automatically updated to include auth headers
            >>> private_resource.get()
        
        Models
        ------
        
        Basics
        ~~~~~~
        
        - Cosmicray ships with a built-in Model class
        - This base class is bound to a specific route handler and defines all the fields that would get mapped to a response or be part as the payload for `post` and `put` requests
        - It automatically uses its defined fields as url parameters and as request body
        - Provides functions to make http calls (ex: `get`, `create`, `update`, `delete`)
        - You can override default behavior, such as create/update paylods
        
        .. code:: python
        
            >>> from cosmicray.model import Model
            >>> class Dog(Model):
            ...     __route__ = dogs
            ...     __slots__ = [
            ...         'id',
            ...         'name',
            ...         'breed',
            ...         'age'
            ...     ]
            >>> manu = Dog(name='Manu', age=4).create()
            >>> manu.breed = 'Husky'
            >>> manu.update()
            >>> manu.delete()
            >>> manu = Dog(id=12345).get()
            >>> alldogs = Dog().get()
        
        
        Relationships with other models/routes
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        
        .. code:: python
        
            >>> from cosmicray.model import relationhip, Model, ModelParam
            >>> class Cat(cosmicray.model.Model):
            ...     __route__ = cats
            ...     __slots__ = [
            ...         'id',
            ...         'name',
            ...         'age'
            ...     ]
            ...     friends = relationhip('Friend', urlargs={'id': ModelParam('id')})
        
        
        If you don't want to use `cosmicray.Model` as your base, you can define your own OR
        even use just use `collections.namedtuple` as the model.
        
        .. code:: python
        
            >>> class MyModel(object):
            ...     @classmethod
            ...     def _make(cls, response):
            ...         obj = cls()
            ...         ... do stuff with the response
            ...         return obj
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
