# pkb_client
Python client for the Porkbun API
---
[](https://pypi.org/project/pkb-client/)  [](https://pepy.tech/project/pkb-client)  
---
### Table of Contents
1. [About](#about)
2. [Installation](#installation)
1. [With pip (recommend)](#with-pip-recommend)
2. [From source](#from-source)
3. [Usage](#usage)
4. [Notes](#notes)
5. [Third party notices](#third-party-notices)
6. [Development](#development)
1. [Setup environment](#setup-environment)
2. [Tests](#tests)
3. [Documentation](#documentation)
7. [License](#license)
---
### About
*pkb_client* is a python client for the [Porkbun](https://porkbun.com) API. It supports the v3 of the API. You can
find the official documentation of the Porkbun API [here](https://api.porkbun.com/api/json/v3/documentation).
### Installation
This project only works with Python 3, make sure you have at least Python 3.9 installed.
#### With pip (recommend)
Use the following command to install *pkb_client* with pip:
```commandline
pip3 install pkb_client
```
You can also very easily update to a newer version:
```commandline
pip3 install pkb_client -U
```
#### From source
```commandline
git clone https://github.com/infinityofspace/pkb_client.git
cd pkb_client
pip3 install .
```
### Usage
Each request must be made with the API key and secret. You can easily create them at Porkbun. Just follow
the [official instructions](https://api.porkbun.com/api/json/v3/documentation#Authentication). Make sure that you explicitly
activate the API usage for your domain at the end. There are two ways to use `pkb_client`. The first way is to use it as
a Python module. See the [module documentation](https://infinityofspace.github.io/pkb_client) for more information. The
second way is to use the module from the command line, see below for more information.
After installation *pkb_client* is available under the command `pkb-client`.
You have to specify your API key and secret each time as follows:
```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> ping
```
If you don't want to specify the key and secret in the program call, because for example the command line calls are
logged, and you don't want to log the API access, then you can also set the environment variables `PKB_API_KEY` and
`PKB_API_SECRET`. If you not specify API key and secret in any way, *pkb-client* asks for a user input. The command line
arguments of the API key and secret have the highest priority.
You can see an overview of all usable cli methods via the help:
```commandline
pkb-client -h
```
If you need more help on a supported API method, you can use the following command, for example for the ping method:
```commandline
pkb-client ping -h
```
#### Here are a few usage examples:
Create a new TXT record for the subdomain `test` of the domain `example.com` with the value `porkbun is cool` and a TTL
of `500`:
```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-KEY-SECRET> dns-create example.com TXT "porkbun is cool" --name test --ttl 500
```
The call returns the DNS record id. The record DNS ids are used to distinguish the DNS records and can be used for
editing or deleting records. The ID is only a Porkbun internal identifier and is not publicly available.
Delete the DNS record with the ID `12345` of the domain `example.com`:
```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-delete example.com 12345
```
Get all DNS records of the domain `example.com`:
```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-retrieve example.com
```
Change the TXT DNS record content with the ID `456789` of the domain `example.com` to `the answer is 42`:
```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-edit example.com 456789 TXT "the answer is 42"
```
Exporting all current DNS records of the domain `example.com` to the file `dns_recods.json`:
```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-export example.com dns_recods.json
```
Remove all existing DNS records of the domain `example.com` and restore the DNS records from the file `dns_recods.json`:
```commandline
pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-import example.com dns_recods.json clear
```
*Note:* The `dns-import` function uses the record ID to distinguish DNS records.
### Notes
Currently, TTL smaller than `600` are ignored by the Porkbun API and the minimum value is `600`, although a minimum
value of `300` is [supported](https://api.porkbun.com/api/json/v3/documentation) and allowed by the RFC standard. However,
you can do TTL smaller than `600` via the web dashboard.
### Third party notices
All modules used by this project are listed below:
| Name | License |
|:-----------------------------------------------------:|:-------------------------------------------------------------------------------------------------:|
| [requests](https://github.com/psf/requests) | [Apache 2.0](https://raw.githubusercontent.com/psf/requests/master/LICENSE) |
| [setuptools](https://github.com/pypa/setuptools) | [MIT](https://raw.githubusercontent.com/pypa/setuptools/main/LICENSE) |
| [sphinx](https://github.com/sphinx-doc/sphinx) | [BSD 2 Clause](https://raw.githubusercontent.com/sphinx-doc/sphinx/refs/heads/master/LICENSE.rst) |
| [dnspython](https://github.com/rthalley/dnspython) | [ISC](https://raw.githubusercontent.com/rthalley/dnspython/refs/heads/main/LICENSEc) |
| [responses](https://github.com/getsentry/responses) | [Apache 2.0](https://raw.githubusercontent.com/getsentry/responses/refs/heads/master/LICENSE) |
| [ruff](https://github.com/astral-sh/ruff) | [MIT](https://raw.githubusercontent.com/astral-sh/ruff/refs/heads/main/LICENSE) |
Furthermore, this readme file contains embeddings of [Shields.io](https://github.com/badges/shields)
and [PePy](https://github.com/psincraian/pepy) images.
_This project is not associated with Porkbun LLC._
### Development
#### Setup environment
First get the source code:
```commandline
git clone https://github.com/infinityofspace/pkb_client.git
cd pkb_client
```
Now create a virtual environment, activate it and install all dependencies with the following commands:
```commandline
python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
```
Now you can start developing.
Feel free to contribute to this project by creating a pull request.
Before you create a pull request, make sure that you code meets the following requirements (you can use the specified
commands to check/fulfill the requirements):
- check unit tests: `python -m unittest tests/*.py`
- format the code: `ruff format`
- check linting errors: `ruff check`
#### Tests
You can run the tests with the following command:
```commandline
python -m unittest tests/*.py
```
#### Documentation
To build the documentation you can use the following commands:
```commandline
sphinx-apidoc -f -o docs/source pkb_client
cd docs && make html
```
### License
[MIT](https://github.com/infinityofspace/pkb_client/blob/master/License) - Copyright (c) Marvin Heptner
Raw data
{
"_id": null,
"home_page": "https://github.com/infinityofspace/pkb_client",
"name": "pkb-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "infinityofspace",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/7d/26/5211599ae769a4292149fde1cb03db9372121fa78347db872f956bc447fe/pkb_client-2.0.0.tar.gz",
"platform": null,
"description": "# pkb_client\n\nPython client for the Porkbun API\n\n---\n[](https://pypi.org/project/pkb-client/)  [](https://pepy.tech/project/pkb-client)  \n---\n\n### Table of Contents\n\n1. [About](#about)\n2. [Installation](#installation)\n 1. [With pip (recommend)](#with-pip-recommend)\n 2. [From source](#from-source)\n3. [Usage](#usage)\n4. [Notes](#notes)\n5. [Third party notices](#third-party-notices)\n6. [Development](#development)\n 1. [Setup environment](#setup-environment)\n 2. [Tests](#tests)\n 3. [Documentation](#documentation)\n7. [License](#license)\n\n---\n\n### About\n\n*pkb_client* is a python client for the [Porkbun](https://porkbun.com) API. It supports the v3 of the API. You can\nfind the official documentation of the Porkbun API [here](https://api.porkbun.com/api/json/v3/documentation).\n\n### Installation\n\nThis project only works with Python 3, make sure you have at least Python 3.9 installed.\n\n#### With pip (recommend)\n\nUse the following command to install *pkb_client* with pip:\n\n```commandline\npip3 install pkb_client\n```\n\nYou can also very easily update to a newer version:\n\n```commandline\npip3 install pkb_client -U\n```\n\n#### From source\n\n```commandline\ngit clone https://github.com/infinityofspace/pkb_client.git\ncd pkb_client\npip3 install .\n```\n\n### Usage\n\nEach request must be made with the API key and secret. You can easily create them at Porkbun. Just follow\nthe [official instructions](https://api.porkbun.com/api/json/v3/documentation#Authentication). Make sure that you explicitly\nactivate the API usage for your domain at the end. There are two ways to use `pkb_client`. The first way is to use it as\na Python module. See the [module documentation](https://infinityofspace.github.io/pkb_client) for more information. The\nsecond way is to use the module from the command line, see below for more information.\n\nAfter installation *pkb_client* is available under the command `pkb-client`.\n\nYou have to specify your API key and secret each time as follows:\n\n```commandline\npkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> ping\n```\n\nIf you don't want to specify the key and secret in the program call, because for example the command line calls are\nlogged, and you don't want to log the API access, then you can also set the environment variables `PKB_API_KEY` and\n`PKB_API_SECRET`. If you not specify API key and secret in any way, *pkb-client* asks for a user input. The command line\narguments of the API key and secret have the highest priority.\n\nYou can see an overview of all usable cli methods via the help:\n\n```commandline\npkb-client -h\n```\n\nIf you need more help on a supported API method, you can use the following command, for example for the ping method:\n\n```commandline\npkb-client ping -h\n```\n\n#### Here are a few usage examples:\n\nCreate a new TXT record for the subdomain `test` of the domain `example.com` with the value `porkbun is cool` and a TTL\nof `500`:\n\n```commandline\npkb-client -k <YOUR-API-KEY> -s <YOUR-API-KEY-SECRET> dns-create example.com TXT \"porkbun is cool\" --name test --ttl 500\n```\n\nThe call returns the DNS record id. The record DNS ids are used to distinguish the DNS records and can be used for\nediting or deleting records. The ID is only a Porkbun internal identifier and is not publicly available.\n\nDelete the DNS record with the ID `12345` of the domain `example.com`:\n\n```commandline\npkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-delete example.com 12345\n```\n\nGet all DNS records of the domain `example.com`:\n\n```commandline\npkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-retrieve example.com\n```\n\nChange the TXT DNS record content with the ID `456789` of the domain `example.com` to `the answer is 42`:\n\n```commandline\npkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-edit example.com 456789 TXT \"the answer is 42\"\n```\n\nExporting all current DNS records of the domain `example.com` to the file `dns_recods.json`:\n\n```commandline\npkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-export example.com dns_recods.json\n```\n\nRemove all existing DNS records of the domain `example.com` and restore the DNS records from the file `dns_recods.json`:\n\n```commandline\npkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-import example.com dns_recods.json clear\n```\n\n*Note:* The `dns-import` function uses the record ID to distinguish DNS records.\n\n### Notes\n\nCurrently, TTL smaller than `600` are ignored by the Porkbun API and the minimum value is `600`, although a minimum\nvalue of `300` is [supported](https://api.porkbun.com/api/json/v3/documentation) and allowed by the RFC standard. However,\nyou can do TTL smaller than `600` via the web dashboard.\n\n### Third party notices\n\nAll modules used by this project are listed below:\n\n| Name | License |\n|:-----------------------------------------------------:|:-------------------------------------------------------------------------------------------------:|\n| [requests](https://github.com/psf/requests) | [Apache 2.0](https://raw.githubusercontent.com/psf/requests/master/LICENSE) |\n| [setuptools](https://github.com/pypa/setuptools) | [MIT](https://raw.githubusercontent.com/pypa/setuptools/main/LICENSE) |\n| [sphinx](https://github.com/sphinx-doc/sphinx) | [BSD 2 Clause](https://raw.githubusercontent.com/sphinx-doc/sphinx/refs/heads/master/LICENSE.rst) |\n| [dnspython](https://github.com/rthalley/dnspython) | [ISC](https://raw.githubusercontent.com/rthalley/dnspython/refs/heads/main/LICENSEc) |\n| [responses](https://github.com/getsentry/responses) | [Apache 2.0](https://raw.githubusercontent.com/getsentry/responses/refs/heads/master/LICENSE) |\n| [ruff](https://github.com/astral-sh/ruff) | [MIT](https://raw.githubusercontent.com/astral-sh/ruff/refs/heads/main/LICENSE) |\n\nFurthermore, this readme file contains embeddings of [Shields.io](https://github.com/badges/shields)\nand [PePy](https://github.com/psincraian/pepy) images.\n\n_This project is not associated with Porkbun LLC._\n\n### Development\n\n#### Setup environment\n\nFirst get the source code:\n\n```commandline\ngit clone https://github.com/infinityofspace/pkb_client.git\ncd pkb_client\n```\n\nNow create a virtual environment, activate it and install all dependencies with the following commands:\n\n```commandline\npython3 -m venv venv\nsource venv/bin/activate\npip3 install -r requirements.txt\n```\n\nNow you can start developing.\n\nFeel free to contribute to this project by creating a pull request.\nBefore you create a pull request, make sure that you code meets the following requirements (you can use the specified\ncommands to check/fulfill the requirements):\n\n- check unit tests: `python -m unittest tests/*.py`\n- format the code: `ruff format`\n- check linting errors: `ruff check`\n\n#### Tests\n\nYou can run the tests with the following command:\n\n```commandline\npython -m unittest tests/*.py\n```\n\n#### Documentation\n\nTo build the documentation you can use the following commands:\n\n```commandline\nsphinx-apidoc -f -o docs/source pkb_client\ncd docs && make html\n```\n\n### License\n\n[MIT](https://github.com/infinityofspace/pkb_client/blob/master/License) - Copyright (c) Marvin Heptner\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client for the Porkbun API",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/infinityofspace/pkb_client"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e4caac2f35db7ab86087a7e8f1f11178411400f8ee9b474a6aa291d8cc882493",
"md5": "96ddc0e547cfd9c38b607192b13e2802",
"sha256": "bb3e78ee24299fc894bd08f4b08932cdf261c2cfd83803aa39575443359f65f8"
},
"downloads": -1,
"filename": "pkb_client-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96ddc0e547cfd9c38b607192b13e2802",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 20650,
"upload_time": "2024-11-02T22:55:49",
"upload_time_iso_8601": "2024-11-02T22:55:49.466732Z",
"url": "https://files.pythonhosted.org/packages/e4/ca/ac2f35db7ab86087a7e8f1f11178411400f8ee9b474a6aa291d8cc882493/pkb_client-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7d265211599ae769a4292149fde1cb03db9372121fa78347db872f956bc447fe",
"md5": "c42ed862872ca25e8139f0031afa90b9",
"sha256": "bffb4324783033ff1385cc6ad938e10824985fae27b9ad6040a21367116e4114"
},
"downloads": -1,
"filename": "pkb_client-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c42ed862872ca25e8139f0031afa90b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20419,
"upload_time": "2024-11-02T22:55:51",
"upload_time_iso_8601": "2024-11-02T22:55:51.228758Z",
"url": "https://files.pythonhosted.org/packages/7d/26/5211599ae769a4292149fde1cb03db9372121fa78347db872f956bc447fe/pkb_client-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-02 22:55:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "infinityofspace",
"github_project": "pkb_client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "setuptools",
"specs": [
[
">=",
"39.0.1"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.20.0"
]
]
},
{
"name": "sphinx",
"specs": [
[
"~=",
"7.4"
]
]
},
{
"name": "dnspython",
"specs": [
[
"~=",
"2.7"
]
]
},
{
"name": "responses",
"specs": [
[
"~=",
"0.25.3"
]
]
},
{
"name": "ruff",
"specs": [
[
"~=",
"0.8"
]
]
}
],
"lcname": "pkb-client"
}
JSON
