https://github.com/shazow/apiclient

Framework for making good Python API client libraries using urllib3.
https://github.com/shazow/apiclient

Last synced: 9 days ago
JSON representation

Framework for making good Python API client libraries using urllib3.

• Host: GitHub
• URL: https://github.com/shazow/apiclient
• Owner: shazow
• License: other
• Created: 2011-10-04T00:36:33.000Z (about 13 years ago)
• Default Branch: master
• Last Pushed: 2019-03-21T00:57:42.000Z (over 5 years ago)
• Last Synced: 2024-10-12T00:27:58.439Z (24 days ago)
• Language: Python
• Homepage: http://pypi.python.org/pypi/apiclient
• Size: 20.5 KB
• Stars: 87
• Watchers: 7
• Forks: 21
• Open Issues: 4
• Metadata Files:
  • Readme: README
  • Changelog: CHANGES.rst
  • License: LICENSE.txt

Awesome Lists containing this project

• starred-awesome - apiclient - Framework for making good Python API client libraries using urllib3. (Python)

README

        
Tiny framework for building *good* API client libraries thanks to

`urllib3 `_.

**Status**: `apiclient` is not actively maintained. Please use it as a reference for your own code--it is very small. If you must use it as a dependency, do so at your own risk. :)

Highlights

==========

- Threadsafely reuses connections with Keep-Alive (via urllib3).

- Small and easy to understand codebase perfect for extending and building upon.

- Built-in support for rate limiting and request throttling.

- Functional examples for the

  `Klout API `_

  and the

  `Facebook OpenGraph API `_.

Examples

========

How to make your own super-simple client API library::

    >>> from apiclient import APIClient

    >>> class AcmePublicAPI(APIClient):

    ...    BASE_URL = 'https://localhost:1234/'

    >>> acme_api = AcmePublicAPI()

    >>> acme_api.call('/hello')

    {'what': 'world'}

    >>> acme_api.call('/echo', params={"ping": "pong"})

    {'ping': 'pong'}

How to add rate limiting to your client API library so that we don't exceed 10

requests per minute::

    >>> from apiclient import RateLimiter

    >>> lock = RateLimiter(max_messages=10, every_seconds=60)

    >>> acme_api = AcmePublicAPI(rate_limit_lock=lock)

    >>> # Get the first 100 pages

    >>> for page in xrange(100):

    ...     # Whenever our request rate exceeds the specifications of the API's

    ...     # RateLimiter, the next request will block until the next request window

    ...     r = acme_api.call('/stream', page=str(page))

For more specific API examples, see the

`examples/ `_ directory.

Extending

=========

To handle different calling conventions, ``apiclient`` can be extended through

subclassing.

For example, if an API requires that all arguments be JSON encoded, the

``_compose_url`` method could be implemented like this::

    >>> class JSONArgsAPIClient(APIClient):

    ...     def _compose_url(self, path, params=None):

    ...         if params is not None:

    ...             params = dict((key, json.dumps(val))

    ...                            for (key, val) in params.iteritems())

    ...         return APIClient._compose_url(self, path, params=params)

Or if an API returns YAML instead of JSON, the ``_handle_response`` method

could be overridden::

    >>> class YAMLResponseAPIClient(APIClient):

    ...     def _handle_response(self, response):

    ...         return yaml.load(response.data)

TODO

====

- Tests.

- More documentation.

- More types of API handshakes, like OAuth and OAuth2.

- More examples.

Contributing

============

Any contribution is highly encouraged and desired. :)

#. Fork on Github.

#. Make the changes. Bonus points if changes include documentation and tests.

#. Send a pull request.

If you're unsure if it's a good idea,

`open an Issue `_ or

`contact me `_ to discuss your proposal.

Extra juicy bonus points if you pick off some of the items in the **TODO** list.

License

=======

`MIT `_