Skip to main content

Develop a client for your HTTP API and document its quirks and features

Project description

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.


  • 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


Cosmicray is under development


$ pip install cosmicray

Quick start

Create App

>>> from cosmicray import Cosmicray
>>> api = Cosmicray('myapp', domain='')

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.

>>> @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

>>> 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

>>> 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.

>>> 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()



  • 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
>>> 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

>>> 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.

>>> class MyModel(object):
...     @classmethod
...     def _make(cls, response):
...         obj = cls()
...         ... do stuff with the response
...         return obj

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cosmicray, version 0.0.13
Filename, size File type Python version Upload date Hashes
Filename, size cosmicray-0.0.13-py2.py3-none-any.whl (18.7 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size cosmicray-0.0.13.tar.gz (16.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page