From fa197fe27b8a03bbf4504476f842956ece2c76c9 Mon Sep 17 00:00:00 2001 From: Unit 193 Date: Tue, 26 Dec 2023 19:39:06 -0500 Subject: Import Upstream version 1.2 --- Readme.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 Readme.md (limited to 'Readme.md') diff --git a/Readme.md b/Readme.md new file mode 100644 index 0000000..c0058df --- /dev/null +++ b/Readme.md @@ -0,0 +1,140 @@ +# pkb_client + +Unofficial client for the Porkbun API + +--- +[![PyPI](https://img.shields.io/pypi/v/pkb_client)](https://pypi.org/project/pkb-client/) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pkb_client) [![Downloads](https://static.pepy.tech/personalized-badge/pkb-client?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Total%20Downloads)](https://pepy.tech/project/pkb-client) ![GitHub](https://img.shields.io/github/license/infinityofspace/pkb_client) ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/infinityofspace/pkb_client/Publish%20release%20distribution%20to%20PyPI) +--- + +### 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. [Third party notices](#third-party-notices) +5. [License](#license) + +--- + +### About + +*pkb_client* is an unofficial 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://porkbun.com/api/json/v3/documentation). + +### Installation + +This project only works with Python 3, make sure you have at least Python 3.6 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 +pip 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://porkbun.com/api/json/v3/documentation#Authentication). Make sure that you explicitly +activate the API usage for your domain at the end. + +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 -s 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 omit both arguments and *pkb-client* asks for a user +input. + +You can see an overview of all usable API 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 -s 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 -s dns-delete example.com 12345 +``` + +Get all DNS records of the domain `example.com`: + +```commandline +pkb-client -k -s 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 -s 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 -s 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 -s dns-import example.com dns_recods.json clear +``` + +*Note:* The import function uses the record ID to distinguish DNS records. + +### 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) | + +Furthermore, this readme file contains embeddings of [Shields.io](https://github.com/badges/shields) +and [PePy](https://github.com/psincraian/pepy). The tests use [ipify](https://github.com/rdegges/ipify-api). + +### License + +[MIT](https://github.com/infinityofspace/pkb_client/blob/master/License) - Copyright (c) Marvin Heptner -- cgit v1.2.3