Update upstream source from tag 'upstream/2.0.0'

Update to upstream version '2.0.0'
with Debian dir a538d4b69c2b9e7ec310387046aa40f0e2499b5f

1 files changed, 89 insertions, 0 deletions

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 <pkb_client.client.client.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 <pkb_client.client.client.PKBClient>` class:
+
+.. code-block:: python
+
+    from pkb_client.client import PKBClient
+
+    pkb = PKBClient(
+        api_key="<your-api-key>",
+        secret_api_key="<your-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 <pkb_client.client.client.PKBClient.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 <pkb_client.client.client.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.