aiocloudflare 0.2.0b2

A Cloudflare API wrapper for Python with asyncio support

Inspired by the offical python-cloudflare library developed by Cloudflare. This project is created to be compatible with asyncio for non-blocking IO.

For sync code, it is recommanded to use python-cloudflare via pip install python-cloudflare as it is used by hundreds and offically maintained by Cloudflare. This ensure that APIs are always updated according to Cloudflare API release.

NOTE: This library is in Beta, this means fixes and updates are still going on every second. Do not use it in Production unless you have tested on the API route specific to your use case and that would be at your own risk.

Having said that, do submit an issue if you encounter any bug so we can move away from the Alpha stage sooner.

Features

• async http API call using modern http library httpx.

• Autocompletion on IDE.

• Fully type hinted.

Feature Roadmap

• to support cert token

• to support sync API client

These are some alternative use cases that are not in the top of my priority now as I have not received any request for. If you are interested, you may want to submit a pull request to contribute some of these features.

Requirements

• Python 3.9+

Installation

You can install aiocloudflare via pip from PyPI:

$ pip install aiocloudflare

Usage

from aiocloudflare import Cloudflare

async def get_zone():
    async with Cloudflare() as cf:
        response = await cf.zones.get()

Unlike the offical python-cloudflare library, aiocloudflare does not parse and handle http responses.

So the awaited response object will have to be handled just as any http request, response pattern. the Response object is the same as httpx’s Response.

from aiocloudflare import Cloudflare

async def get_zone():
    async with Cloudflare() as cf:
        response = await cf.zones.get()

        # check status code
        if response.status_code == 200:

            # get json data
            resp_json = response.json()

            # Cloudflare API typically store results in a ``result`` key.
            return resp_json["result"]

        else:
            # to get texture data from response
            print(response.text)

Full configuration can be done using Config() class.

from aioCloudflare import Cloudflare, Config

config = Config(email="[e-mail]", token="<secret>")  # for demo only, do not hardcode secrets
async def get_zone():
    async with Cloudflare(config=config) as cf:
        result = await cf.zones.get()

Configuration can also be stored in a .env file for a “global” configuration without needing to create a Config() class. Keys available are:

CF_API_EMAIL=""
CF_API_KEY=""
CF_API_CERTKEY=""
CF_API_URL=""
DEBUG=false
CF_PROFILE=""
USER_AGENT=""

Advance Usage

You may wish to wrap Cloudflare() into you own class for customised settings or requirements. To do that, just provide a __aenter__() and __aexit__() method to your class like so.

class MyCfClient:
    def __init__(self):
        self._config = Config(email="[e-mail]", token="<secret>")  # for demo only, do not hardcode secrets

    async def __aenter__(self):
        self._client = Cloudflare(config=self._config)
        return self

    async def __aexit__(self, exc_type, exc_value, traceback):
        await self._client.aclose()

Then you can call your own class with async context manager.

async with MyCfClient() as own_class:
    await own_class.zones.get()

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, aioCloudflare is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.