| Name | pycfdns JSON |
| Version |
3.0.0
JSON |
| download |
| home_page | https://github.com/ludeeus/pycfdns |
| Summary | Cloudflare DNS API Python Wrapper |
| upload_time | 2023-11-03 21:10:24 |
| maintainer | Ludeeus |
| docs_url | None |
| author | Ludeeus |
| requires_python | >=3.11,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Manage DNS Records hosted by Cloudflare
_[Cloudflare] DNS API Python Wrapper._
## Quick start
### Installation
```bash
python3 -m pip install pycfdns
```
### Example usage
```python
...
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`](pycfdns/__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][Client] 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][list_zones_method] can be used to list all zones available with the `api_token` passed to the [`Client` object][Client].
This method takes no arguments.
```python
...
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][ZoneModel].
#### List Records
The [`Client.list_dns_records` method][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.
```python
...
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][RecordModel].
#### Update Record
The [`Client.update_dns_record` method][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.
```python
...
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][RecordModel] 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][release_workflow].
[A history of release actions can be found here][release_history].
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._
<!-- Links -->
[Cloudflare]: https://www.cloudflare.com/
[Cloudflare API]: https://developers.cloudflare.com/api/
[`mypy`]: https://www.mypy-lang.org/
[`aiohttp`]: https://docs.aiohttp.org/en/stable/
[`TypedDict`]: https://peps.python.org/pep-0589/
[SemVer]: https://semver.org/
[PyPi]: https://pypi.org/project/pycfdns/
[GitHub]: https://github.com/
[GitHub actions]: https://github.com/features/actions
[release_workflow]: https://github.com/ludeeus/pycfdns/blob/main/.github/workflows/publish.yml
[release_history]: https://github.com/ludeeus/pycfdns/actions/workflows/publish.yml
[Client]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3AClient+path%3Apycfdns%2Fclient.py&type=code
[list_zones_method]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3Alist_zones+path%3Apycfdns%2Fclient.py&type=code
[list_dns_records_method]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3Alist_dns_records+path%3Apycfdns%2Fclient.py&type=code
[update_dns_record_method]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3Aupdate_dns_record+path%3Apycfdns%2Fclient.py&type=code
[`AuthenticationException`]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3AAuthenticationException+path%3Apycfdns%2Fexceptions.py&type=code
[`ComunicationException`]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3AComunicationException+path%3Apycfdns%2Fexceptions.py&type=code
[ZoneModel]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3AZoneModel+path%3Apycfdns%2Fmodels.py&type=code
[RecordModel]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3ARecordModel+path%3Apycfdns%2Fmodels.py&type=code
Raw data
{
"_id": null,
"home_page": "https://github.com/ludeeus/pycfdns",
"name": "pycfdns",
"maintainer": "Ludeeus",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "ludeeus@ludeeus.dev",
"keywords": "",
"author": "Ludeeus",
"author_email": "ludeeus@ludeeus.dev",
"download_url": "https://files.pythonhosted.org/packages/0f/0b/1ef21394173292e6cf827f3072de54e3c5a92205dcdb7f44628bb21cb8fc/pycfdns-3.0.0.tar.gz",
"platform": null,
"description": "# Manage DNS Records hosted by Cloudflare\n\n_[Cloudflare] DNS API Python Wrapper._\n\n## Quick start\n\n### Installation\n\n```bash\npython3 -m pip install pycfdns\n```\n\n### Example usage\n\n```python\n...\nimport aiohttp\nfrom pycfdns import Client\n...\n async with aiohttp.ClientSession() as client_session:\n client = Client(api_token=\"abc123\", client_session=client_session)\n zones = await client.list_zones()\n print(zones)\n...\n```\n\n## API\n\nBelow is a quick overview of the classes and methods that are available in this package.\n\nThis package uses [`mypy`] to ensure it is strictly typed, and all API modesl are created as [`TypedDict`] objects.\n\nAnything that is not exported in the base of the module (in the [`__init__.py`](pycfdns/__init__.py) file) are considered internal to this package and will change wihtout any notice, yoo should consider not using anything not found there.\n\n### Client\n\nThe [`Client` class][Client] is your entrypoint to this package, this is what's providing the methods described below.\n\nThis method accepts the folowing arguments:\n\nArgument | Type |\u00a0Description\n--|--|--\n`api_token` | `str` |\u00a0This is your personal API token to interface with the [Cloudflare API], you can generate this token here: <https://developers.cloudflare.com/api/tokens/create>\n`client_session` | `ClientSession` |\u00a0This neesd to be an instance of `ClientSession` from the [`aiohttp`] pacakge.\n`timeout` | `int \\| None` |\u00a0This determines how long an API call can use (in seconds) before it times out, the default is `10` seconds.\n\n#### List Zones\n\nThe [`Client.list_zones` method][list_zones_method] can be used to list all zones available with the `api_token` passed to the [`Client` object][Client].\n\nThis method takes no arguments.\n\n```python\n...\nclient = Client(session=session, api_token=\"abc123\")\nzones = await client.list_zones()\n...\n```\n\nThe `zones` variable in this example will be a list of [`ZoneModel` objects][ZoneModel].\n\n#### List Records\n\nThe [`Client.list_dns_records` method][list_dns_records_method] can be used to list all records within a zone.\n\nThis method accepts the folowing arguments:\n\nArgument | Type |\u00a0Description\n--|--|--\n`zone_id` | `str` |\u00a0The ID of the zone to list records for.\n`name` | `str \\| None` |\u00a0If this is passed in it will only match record matching the name.\n`type` | `str \\| None` |\u00a0If this is passed in it will only match record matching the type.\n\n\n```python\n...\nclient = Client(api_token=\"abc123\", client_session=client_session)\nrecords = await client.list_dns_records()\n...\n```\n\nThe `records` variable in this example will be a list of [`RecordModel` objects][RecordModel].\n\n#### Update Record\n\nThe [`Client.update_dns_record` method][update_dns_record_method] can be used to update a record in a zone.\n\nThis method accepts the folowing arguments:\n\nArgument | Type|\u00a0Description\n--|--|--\n`zone_id` | `str` |\u00a0The ID of the zone the record exist in.\n`record_id` | `str` |\u00a0The ID of the record to list records for.\n`record_name` | `str` |\u00a0The name of the record.\n`record_type` | `str` |\u00a0The type of the record.\n`record_content` | `str` |\u00a0The content of the record.\n`record_comment` | `str \\| None` |\u00a0The comment of the record.\n`record_proxied` | `bool \\| None` |\u00a0The proxied state of the record.\n`record_tags` | `list[str] \\| None` |\u00a0The tags of the record.\n`record_ttl` | `int \\| None` |\u00a0The TTL value of the record.\n\n```python\n...\nclient = Client(api_token=\"abc123\", client_session=client_session)\nrecord = await client.update_dns_record(zone_id=\"abc123\", record_id=\"abc123\", record_name=\"abc\", record_content=\"1.1.1.1\", record_type=\"A\")\n...\n```\n\nThe `record` variable in this example will be a [`RecordModel` object][RecordModel] representing the updated record.\n\n\n### Exceptions\n\nThis package have 2 defined exceptions:\n\n- [`AuthenticationException`], this will be raised when the Cloudflare API returns a status code assosiated with authentication issues.\n- [`ComunicationException`], this will be raised when there are issues communicating with the [Cloudflare API].\n\n\n## Versioning\n\nThis package follows the [SemVer] framework to determine how to set the version.\n\n## Publishing\n\nThis package is published to [PyPI] when a new [GitHub] release is made.\n\nThe publishing itself is handled in [GitHub actions] with [this workflow][release_workflow].\n\n[A history of release actions can be found here][release_history].\n\nThere is no fixed schedule for when a new version is published.\n\n\n## Disclaimer\n\n_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._\n\n<!-- Links -->\n[Cloudflare]: https://www.cloudflare.com/\n[Cloudflare API]: https://developers.cloudflare.com/api/\n[`mypy`]: https://www.mypy-lang.org/\n[`aiohttp`]: https://docs.aiohttp.org/en/stable/\n[`TypedDict`]: https://peps.python.org/pep-0589/\n[SemVer]: https://semver.org/\n[PyPi]: https://pypi.org/project/pycfdns/\n[GitHub]: https://github.com/\n[GitHub actions]: https://github.com/features/actions\n\n[release_workflow]: https://github.com/ludeeus/pycfdns/blob/main/.github/workflows/publish.yml\n[release_history]: https://github.com/ludeeus/pycfdns/actions/workflows/publish.yml\n\n[Client]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3AClient+path%3Apycfdns%2Fclient.py&type=code\n[list_zones_method]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3Alist_zones+path%3Apycfdns%2Fclient.py&type=code\n[list_dns_records_method]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3Alist_dns_records+path%3Apycfdns%2Fclient.py&type=code\n[update_dns_record_method]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3Aupdate_dns_record+path%3Apycfdns%2Fclient.py&type=code\n\n[`AuthenticationException`]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3AAuthenticationException+path%3Apycfdns%2Fexceptions.py&type=code\n[`ComunicationException`]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3AComunicationException+path%3Apycfdns%2Fexceptions.py&type=code\n\n[ZoneModel]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3AZoneModel+path%3Apycfdns%2Fmodels.py&type=code\n[RecordModel]: https://github.com/search?q=repo%3Aludeeus%2Fpycfdns+symbol%3ARecordModel+path%3Apycfdns%2Fmodels.py&type=code\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Cloudflare DNS API Python Wrapper",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/ludeeus/pycfdns",
"Repository": "https://github.com/ludeeus/pycfdns"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0089e5528dd621acc729a73d1a70b93354d5bc591f6a4c8ecf147964d05d2d83",
"md5": "335ea52c9fc8ad21a2c609a0edace752",
"sha256": "2af8446bcb0941d2594b8aaae04329b772eeaed0909bf4f250552aaac885a2e7"
},
"downloads": -1,
"filename": "pycfdns-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "335ea52c9fc8ad21a2c609a0edace752",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 7173,
"upload_time": "2023-11-03T21:10:23",
"upload_time_iso_8601": "2023-11-03T21:10:23.120278Z",
"url": "https://files.pythonhosted.org/packages/00/89/e5528dd621acc729a73d1a70b93354d5bc591f6a4c8ecf147964d05d2d83/pycfdns-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0f0b1ef21394173292e6cf827f3072de54e3c5a92205dcdb7f44628bb21cb8fc",
"md5": "4c3c88e96ef871b18ad68de05a33ccb9",
"sha256": "bddfb66ea169c298fdf6052cd14aeccd4c5776efe113e66f72108901574423af"
},
"downloads": -1,
"filename": "pycfdns-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "4c3c88e96ef871b18ad68de05a33ccb9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 6106,
"upload_time": "2023-11-03T21:10:24",
"upload_time_iso_8601": "2023-11-03T21:10:24.857521Z",
"url": "https://files.pythonhosted.org/packages/0f/0b/1ef21394173292e6cf827f3072de54e3c5a92205dcdb7f44628bb21cb8fc/pycfdns-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-03 21:10:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ludeeus",
"github_project": "pycfdns",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycfdns"
}
