Nap

Nap provides convenient way to request HTTP APIs. After coding a few HTTP API wrapper classes, I decided to code Nap. It's is just a small(~150 loc) wrapper around requests. Requests is a superb HTTP library, which supports everything you'll need to get things done in today's web.

Example

from nap.url import Url
api = Url('https://api.github.com/')
# GET https://api.github.com/users
api.get('users')

users = api.join('users')
# GET https://api.github.com/users/kimmobrunfeldt
users.get('kimmobrunfeldt')

# Another way to make the same request as above:
api.get('users/kimmobrunfeldt')

Get started

• Look through examples
• See API documentation
• Dive into code

Install

Python versions 2.7, 3.6, 3.7, 3.8 and PyPy are supported and tested against.

Install latest release with pip:

pip install nap

Install latest development version usin pip:

pip install git+git://github.com/kimmobrunfeldt/nap.git

Install latest development version using setup.py:

git clone [email protected]:kimmobrunfeldt/nap.git
cd nap
python setup.py install

Nap API documentation

See API documentation

Examples

Find gists from GitHub.

from nap.url import Url
api = Url('https://api.github.com/')

# Get gists since May 1st 2014 (will be paginated)
gists = api.get('gists', params={'since': '2014-05-01T00:00:00Z'})
print(gists.json())

You can also specify default keyword arguments to be passed on every request in Url initialization. All authentications supported by requests are automatically supported.

from nap.url import Url
# Keyword arguments given to Url will be given to each request method
# by default for every request.
api = Url('https://api.github.com/', auth=('user', 'pass'))

# Get authenticated user
response = api.get('user')
print(response.json())

# You can also override the default keyword arguments afterwords
response = api.get('users/kimmobrunfeldt', auth=('kimmo', 'password1'))

A bit more complicated example. Automatically convert all JSON responses to Python dict objects. Demonstrate various HTTP methods. Also raise errors from other than 200 OK responses.

from nap.url import Url
import requests

class JsonApi(Url):
    def after_request(self, response):
        if response.status_code != 200:
            response.raise_for_status()

        return response.json()

# Use https://github.com/kennethreitz/httpbin for testing
api = JsonApi('http://httpbin.org/')

# response is dict object containing parsed JSON
response = api.post('post', data={'test': 'Test POST'})
print(response)

response = api.put('put', data={'test': 'Test PUT'})
print(response)

try:
    # httpbin will response with `Method Not Allowed` if we try to do
    # POST http://httpbin.org/get
    api.post('get')
except requests.exceptions.HTTPError as e:
    print('Response was not OK, it was: %s' % e.response.status_code)

Contributing

Documentation for Nap developers