ludeeus / pycfdns

Update Cloudflare DNS records.

Manage DNS Records hosted by Cloudflare

Cloudflare DNS API Python Wrapper.

Quick start

Installation

python3 -m pip install pycfdns

Example usage

...
import aiohttp
from pycfdns import Client
...
    async with aiohttp.ClientSession() as client_session:
        client = Client(api_token="abc123", client_session=client_session)
        zones = await client.list_zones()
        print(zones)
...

API

Below is a quick overview of the classes and methods that are available in this package.

This package uses mypy to ensure it is strictly typed, and all API modesl are created as TypedDict objects.

Anything that is not exported in the base of the module (in the __init__.py file) are considered internal to this package and will change wihtout any notice, yoo should consider not using anything not found there.

Client

The Client class is your entrypoint to this package, this is what's providing the methods described below.

This method accepts the folowing arguments:

Argument	Type	Description
api_token	str	This is your personal API token to interface with the Cloudflare API, you can generate this token here: https://developers.cloudflare.com/api/tokens/create
client_session	ClientSession	This neesd to be an instance of ClientSession from the aiohttp pacakge.
timeout	int | None	This determines how long an API call can use (in seconds) before it times out, the default is 10 seconds.

List Zones

The Client.list_zones method can be used to list all zones available with the api_token passed to the Client object.

This method takes no arguments.

...
client = Client(session=session, api_token="abc123")
zones = await client.list_zones()
...

The zones variable in this example will be a list of ZoneModel objects.

List Records

The Client.list_dns_records method can be used to list all records within a zone.

This method accepts the folowing arguments:

Argument	Type	Description
zone_id	str	The ID of the zone to list records for.
name	str | None	If this is passed in it will only match record matching the name.
type	str | None	If this is passed in it will only match record matching the type.

...
client = Client(api_token="abc123", client_session=client_session)
records = await client.list_dns_records()
...

The records variable in this example will be a list of RecordModel objects.

Update Record

The Client.update_dns_record method can be used to update a record in a zone.

This method accepts the folowing arguments:

Argument	Type	Description
zone_id	str	The ID of the zone the record exist in.
record_id	str	The ID of the record to list records for.
record_name	str	The name of the record.
record_type	str	The type of the record.
record_content	str	The content of the record.
record_comment	str | None	The comment of the record.
record_proxied	bool | None	The proxied state of the record.
record_tags	list[str] | None	The tags of the record.
record_ttl	int | None	The TTL value of the record.

...
client = Client(api_token="abc123", client_session=client_session)
record = await client.update_dns_record(zone_id="abc123", record_id="abc123", record_name="abc", record_content="1.1.1.1", record_type="A")
...

The record variable in this example will be a RecordModel object representing the updated record.

Exceptions

This package have 2 defined exceptions:

• AuthenticationException, this will be raised when the Cloudflare API returns a status code assosiated with authentication issues.
• ComunicationException, this will be raised when there are issues communicating with the Cloudflare API.

Versioning

This package follows the SemVer framework to determine how to set the version.

Publishing

This package is published to PyPI when a new GitHub release is made.

The publishing itself is handled in GitHub actions with this workflow.

A history of release actions can be found here.

There is no fixed schedule for when a new version is published.

Disclaimer

This Python wrapper for the Cloudflare API is an independent project and is not endorsed, sponsored, or affiliated with Cloudflare, Inc. The use of Cloudflare's name, trademarks, and other intellectual property is for descriptive purposes only. All rights to Cloudflare's name, trademarks, and other intellectual property belong to Cloudflare, Inc. Use this wrapper at your own risk and ensure that you abide by Cloudflare's terms of service and API usage guidelines.

pycfdns's Issues

Allow configurable GET_EXT_IP_URL or other default providers

Unfortunately ipifiy doesnt handle X-Fowarded-For headers very well.

Which means if your using any proxy tunneling, ipify detects the wrong IP address.

Funny enough I'm having issues while using cloudflare WARP, with an addon thats meant to be updating cloudflare records.. kinda funny.

It's been a long term known issue with ipify: #5, #19

In order to resolve the issue supposedly ipify is going to have to undertake a core redisgn which I doubt will happen anytime soon.

I hope by allowing a configurable GET_EXT_IP_URL, this will then trickle into the home assistant addon.. which will eventually solve my problem.

If this is way to much effort, I get it.. I'll just have to come up with another solution.

AAAA support

Is there a specific reason to limit it to only A records?

Cloudflare API tokens are not supported

The library's only supported authentication method is using an account's API Key, but support for API Tokens should be added so the api permissions can be limited.

From the cloudflare api docs

API Tokens provide a new way to authenticate with the Cloudflare API. They allow for scoped and permissioned access to resources and use the RFC compliant Authorization Bearer Token Header.

The token needs to be added to the configuration methods and set as a Bearer token for the Authentication header on the api http requests instead of using the X-Auth-Key and X-Auth-Email headers.