Skip to main content

Python client for the Porkbun API

Project description

pkb_client

Python client for the Porkbun API


PyPI PyPI - Python Version Downloads GitHub GitHub Workflow Status

Table of Contents

  1. About
  2. Installation
    1. With pip (recommend)
    2. From source
  3. Usage
  4. Notes
  5. Third party notices
  6. Development
    1. Setup environment
    2. Tests
    3. Documentation
  7. License

About

pkb_client is a python client for the Porkbun API. It supports the v3 of the API. You can find the official documentation of the Porkbun API here.

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:

pip3 install pkb_client

You can also very easily update to a newer version:

pip3 install pkb_client -U

From source

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. 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 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:

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:

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:

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:

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:

pkb-client -k <YOUR-API-KEY> -s <YOUR-API-SECRET> dns-delete example.com 12345

Get all DNS records of the domain example.com:

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:

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:

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:

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 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 Apache 2.0
setuptools MIT
sphinx BSD 2 Clause
dnspython ISC
responses Apache 2.0
ruff MIT

Furthermore, this readme file contains embeddings of Shields.io and PePy images.

This project is not associated with Porkbun LLC.

Development

Setup environment

First get the source code:

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:

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:

python -m unittest tests/*.py

Documentation

To build the documentation you can use the following commands:

sphinx-apidoc -f -o docs/source pkb_client
cd docs && make html

License

MIT - Copyright (c) Marvin Heptner

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pkb_client-2.0.0.tar.gz (20.4 kB view details)

Uploaded Source

Built Distribution

pkb_client-2.0.0-py3-none-any.whl (20.6 kB view details)

Uploaded Python 3

File details

Details for the file pkb_client-2.0.0.tar.gz.

File metadata

  • Download URL: pkb_client-2.0.0.tar.gz
  • Upload date:
  • Size: 20.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for pkb_client-2.0.0.tar.gz
Algorithm Hash digest
SHA256 bffb4324783033ff1385cc6ad938e10824985fae27b9ad6040a21367116e4114
MD5 c42ed862872ca25e8139f0031afa90b9
BLAKE2b-256 7d265211599ae769a4292149fde1cb03db9372121fa78347db872f956bc447fe

See more details on using hashes here.

File details

Details for the file pkb_client-2.0.0-py3-none-any.whl.

File metadata

  • Download URL: pkb_client-2.0.0-py3-none-any.whl
  • Upload date:
  • Size: 20.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for pkb_client-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 bb3e78ee24299fc894bd08f4b08932cdf261c2cfd83803aa39575443359f65f8
MD5 96ddc0e547cfd9c38b607192b13e2802
BLAKE2b-256 e4caac2f35db7ab86087a7e8f1f11178411400f8ee9b474a6aa291d8cc882493

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page