From 3e3ebe586385a83b10c8f1d0b9ba9b67c8b56d2f Mon Sep 17 00:00:00 2001 From: Unit 193 Date: Wed, 20 Nov 2024 01:17:40 -0500 Subject: New upstream version 2.0.0. --- docs/source/usage.rst | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/source/usage.rst (limited to 'docs/source/usage.rst') diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..89abc1e --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,89 @@ +Usage +===== + +Module +++++++ + +The module provides the :class:`PKBClient ` class, which is used to interact with the PKB API. +To use the PKB client, you need to create an instance of the :class:`PKBClient ` class: + +.. code-block:: python + + from pkb_client.client import PKBClient + + pkb = PKBClient( + api_key="", + secret_api_key="", + api_endpoint="https://api.porkbun.com/api/json/v3", + ) + +Whereby the `api_key` and `secret_api_key` are optional and only required if you want to use the PKB API with API endpoints +that require authentication (e.g. to manage dns records of your domains). Moreover the api_endpoint is also optional and +defaults to the latest version of the official PKB API endpoint. + +For example to get the domain pricing, which does not require authentication, you can use the +:func:`get_domain_pricing ` method: + +.. code-block:: python + + from pkb_client.client import PKBClient + + pkb = PKBClient() + domain_pricing = pkb.get_domain_pricing() + print(domain_pricing) + +You can find all available methods in the :class:`PKBClient ` class documentation. + +CLI ++++ + +The module also provides a CLI to interact with the PKB API. For example to get the domain pricing, you can use the `get-domain-pricing` command: + +.. code-block:: bash + + pkb-client domain-pricing + +All available commands can be listed with the `--help` option: + +.. code-block:: bash + + pkb-client --help + +.. code-block:: bash + + usage: pkb-client [-h] [-k KEY] [-s SECRET] [--debug] [--endpoint ENDPOINT] + {ping,create-dns-record,update-dns-record,delete-dns-records,get-dns-records,export-dns-records,export-bind-dns-records,import-dns-records,import-bind-dns-records,get-domain-pricing,get-ssl-bundle,update-dns-servers,get-dns-servers,get-domains,get-url-forwards,create-url-forward,delete-url-forward} + ... + + Python client for the Porkbun API + + positional arguments: + {ping,create-dns-record,update-dns-record,delete-dns-records,get-dns-records,export-dns-records,export-bind-dns-records,import-dns-records,import-bind-dns-records,get-domain-pricing,get-ssl-bundle,update-dns-servers,get-dns-servers,get-domains,get-url-forwards,create-url-forward,delete-url-forward} + Supported API methods + ping Ping the API Endpoint + create-dns-record Create a new DNS record. + update-dns-record Edit an existing DNS record. + delete-dns-records Delete an existing DNS record. + get-dns-records Get all DNS records. + export-dns-records Save all DNS records to a local json file. + export-bind-dns-records + Save all DNS records to a local BIND file. + import-dns-records Restore all DNS records from a local json file. + import-bind-dns-records + Restore all DNS records from a local BIND file. + get-domain-pricing Get the pricing for Porkbun domains. + get-ssl-bundle Retrieve an SSL bundle for given domain. + update-dns-servers Update the DNS servers for a domain. + get-dns-servers Retrieve the DNS servers for a domain. + get-domains List all domains in this account in chunks of 1000. + get-url-forwards Retrieve all URL forwards. + create-url-forward Create a new URL forward. + delete-url-forward Delete an existing URL forward. + + options: + -h, --help show this help message and exit + -k KEY, --key KEY The API key used for Porkbun API calls (usually starts with "pk"). + -s SECRET, --secret SECRET + The API secret used for Porkbun API calls (usually starts with "sk"). + --debug Enable debug mode. + --endpoint ENDPOINT The API endpoint to use. -- cgit v1.2.3