Skip to main content

Write reusable web API interactions

Project description

https://img.shields.io/pypi/v/snug.svg https://img.shields.io/pypi/l/snug.svg https://img.shields.io/pypi/pyversions/snug.svg https://github.com/ariebovenberg/snug/actions/workflows/tests.yml/badge.svg https://img.shields.io/codecov/c/github/ariebovenberg/snug.svg https://img.shields.io/readthedocs/snug.svg https://img.shields.io/codeclimate/maintainability/ariebovenberg/snug.svg https://img.shields.io/badge/dependabot-enabled-brightgreen.svg?longCache=true&logo=dependabot https://img.shields.io/badge/code%20style-black-000000.svg

Snug is a tiny toolkit for writing reusable interactions with web APIs. Key features:

  • Write once, run with different HTTP clients (sync and async)

  • Fits any API architecture (e.g. REST, RPC, GraphQL)

  • Simple, lightweight and versatile

Why?

Writing reusable web API interactions is difficult. Consider a generic example:

import json

def repo(name, owner):
    """get a github repo by owner and name"""
    request = Request(f'https://api.github.com/repos/{owner}/{name}')
    response = my_http_client.send(request)
    return json.loads(response.content)

Nice and simple. But…

  • What about async? Do we write another function for that?

  • How do we write clean unittests for this?

  • What if we want to use another HTTP client or session?

  • How do we use this with different credentials?

Snug allows you to write API interactions independent of HTTP client, credentials, or whether they are run (a)synchronously.

In contrast to most API client toolkits, snug makes minimal assumptions and design decisions for you. Its simple, adaptable foundation ensures you can focus on what makes your API unique. Snug fits in nicely whether you’re writing a full-featured API wrapper, or just making a few API calls.

Quickstart

  1. API interactions (“queries”) are request/response generators.

import snug

def repo(name, owner):
    """get a github repo by owner and name"""
    request = snug.GET(f'https://api.github.com/repos/{owner}/{name}')
    response = yield request
    return json.loads(response.content)
  1. Queries can be executed:

>>> query = repo('Hello-World', owner='octocat')
>>> snug.execute(query)
{"description": "My first repository on Github!", ...}

Features

  1. Effortlessly async. The same query can also be executed asynchronously:

    query = repo('Hello-World', owner='octocat')
    repo = await snug.execute_async(query)
  2. Flexibility. Since queries are just generators, customizing them requires no special glue-code. For example: add validation logic, or use any serialization method:

    from my_types import User, UserSchema
    
    def user(name: str) -> snug.Query[User]:
        """lookup a user by their username"""
        if len(name) == 0:
            raise ValueError('username must have >0 characters')
        request = snug.GET(f'https://api.github.com/users/{name}')
        response = yield request
        return UserSchema().load(json.loads(response.content))
  3. Pluggable clients. Queries are fully agnostic of the HTTP client. For example, to use requests instead of the standard library:

    import requests
    query = repo('Hello-World', owner='octocat')
    snug.execute(query, client=requests.Session())

    Read here how to register your own.

  4. Testability. Queries can easily be run without touching the network. No need for complex mocks or monkeypatching.

    >>> query = repo('Hello-World', owner='octocat')
    >>> next(query).url.endswith('/repos/octocat/Hello-World')
    True
    >>> query.send(snug.Response(200, b'...'))
    StopIteration({"description": "My first repository on Github!", ...})
  5. Swappable authentication. Queries aren’t tied to a session or credentials. Use different credentials to execute the same query:

    def follow(name: str) -> snug.Query[bool]:
        """follow another user"""
        req = snug.PUT('https://api.github.com/user/following/{name}')
        return (yield req).status_code == 204
    
    snug.execute(follow('octocat'), auth=('me', 'password'))
    snug.execute(follow('octocat'), auth=('bob', 'hunter2'))
  6. Related queries. Use class-based queries to create an expressive, chained API for related objects:

    class repo(snug.Query[dict]):
        """a repo lookup by owner and name"""
        def __init__(self, name, owner): ...
    
        def __iter__(self): ...  # query for the repo itself
    
        def issue(self, num: int) -> snug.Query[dict]:
            """retrieve an issue in this repository by its number"""
            r = snug.GET(f'/repos/{self.owner}/{self.name}/issues/{num}')
            return json.loads((yield r).content)
    
    my_issue = repo('Hello-World', owner='octocat').issue(348)
    snug.execute(my_issue)
  7. Pagination. Define paginated queries for (asynchronous) iteration.

    def organizations(since: int=None):
        """retrieve a page of organizations since a particular id"""
        resp = yield snug.GET('https://api.github.com/organizations',
                              params={'since': since} if since else {})
        orgs = json.loads(resp.content)
        next_query = organizations(since=orgs[-1]['id'])
        return snug.Page(orgs, next_query=next_query)
    
    my_query = snug.paginated(organizations())
    
    for orgs in snug.execute(my_query):
        ...
    
    # or, with async
    async for orgs in snug.execute_async(my_query):
        ...
  8. Function- or class-based? You decide. One option to keep everything DRY is to use class-based queries and inheritance:

    class BaseQuery(snug.Query):
        """base github query"""
    
        def prepare(self, request): ...  # add url prefix, headers, etc.
    
        def __iter__(self):
            """the base query routine"""
            request = self.prepare(self.request)
            return self.load(self.check_response((yield request)))
    
        def check_response(self, result): ...  # raise nice errors
    
    class repo(BaseQuery):
        """get a repo by owner and name"""
        def __init__(self, name, owner):
            self.request = snug.GET(f'/repos/{owner}/{name}')
    
        def load(self, response):
            return my_repo_loader(response.content)
    
    class follow(BaseQuery):
        """follow another user"""
        def __init__(self, name):
            self.request = snug.PUT(f'/user/following/{name}')
    
        def load(self, response):
            return response.status_code == 204

    Or, if you’re comfortable with higher-order functions and decorators, make use of gentools to modify query yield, send, and return values:

    from gentools import (map_return, map_yield, map_send,
                          compose, oneyield)
    
    class Repository: ...
    
    def my_repo_loader(...): ...
    
    def my_error_checker(...): ...
    
    def my_request_preparer(...): ...  # add url prefix, headers, etc.
    
    basic_interaction = compose(map_send(my_error_checker),
                                map_yield(my_request_preparer))
    
    @map_return(my_repo_loader)
    @basic_interaction
    @oneyield
    def repo(owner: str, name: str) -> snug.Query[Repository]:
        """get a repo by owner and name"""
        return snug.GET(f'/repos/{owner}/{name}')
    
    @basic_interaction
    def follow(name: str) -> snug.Query[bool]:
        """follow another user"""
        response = yield snug.PUT(f'/user/following/{name}')
        return response.status_code == 204

For more info, check out the tutorial, advanced features, recipes, or examples.

Installation

There are no required dependencies. Installation is easy as:

pip install snug

Although snug includes basic sync and async HTTP clients, you may wish to install requests, httpx, and/or aiohttp.

pip install requests aiohttp httpx

Alternatives

If you’re looking for a less minimalistic API client toolkit, check out uplink or tapioca.

Project details


Download files

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

Source Distribution

snug-2.4.0.tar.gz (17.0 kB view details)

Uploaded Source

Built Distribution

snug-2.4.0-py3-none-any.whl (18.0 kB view details)

Uploaded Python 3

File details

Details for the file snug-2.4.0.tar.gz.

File metadata

  • Download URL: snug-2.4.0.tar.gz
  • Upload date:
  • Size: 17.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.10.5

File hashes

Hashes for snug-2.4.0.tar.gz
Algorithm Hash digest
SHA256 771822da26a2e2cd4154a6e0358c3b2fda8c269925517158d83a3dbb9b913194
MD5 7d4e65191c447dd7a10fce9d0d78c796
BLAKE2b-256 29308d8d4ad1e097888e4fc910d22c697dfc0c4d28d7a9cfdea0eb9c6b8eca23

See more details on using hashes here.

File details

Details for the file snug-2.4.0-py3-none-any.whl.

File metadata

  • Download URL: snug-2.4.0-py3-none-any.whl
  • Upload date:
  • Size: 18.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.10.5

File hashes

Hashes for snug-2.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a5944a0ec113e7e1c8093b7ad6f534feee35647bece1b44620f2f27c578f91a8
MD5 60ef5fb94294ede6adf53ed9c79e5050
BLAKE2b-256 8bc46571c03b23c6a2e65fe16992e67e082f0631d7ed4ed9fc697f8452d051f6

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page