Update upstream source from tag 'upstream/2.0.0'

Update to upstream version '2.0.0'
with Debian dir a538d4b69c2b9e7ec310387046aa40f0e2499b5f

12 files changed, 383 insertions, 0 deletions

diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..378eac2
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+build
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d0c3cbf
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..dc1312a
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..7a07b51
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,30 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import sys
+
+sys.path.append("..")
+
+project = "pkb_client"
+copyright = "2023-2024, infinityofspace"
+author = "infinityofspace"
+release = "v2.0.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.githubpages"]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..46f8eb1
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,29 @@
+Welcome to pkb_client's documentation!
+======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   usage
+   modules
+   migration_guide
+
+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>`_.
+
+Link to the source code: `Github <https://github.com/infinityofspace/pkb_client>`_
+
+*Note:* This project is not associated with Porkbun LLC.
+
+
+Indices and tables
+++++++++++++++++++
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
new file mode 100644
index 0000000..6e52bbf
--- /dev/null
+++ b/docs/source/installation.rst
@@ -0,0 +1,17 @@
+Installation
+============
+
+You can either install the package from the Python Package Index (PyPI) using pip:
+
+.. code-block:: bash
+
+   pip3 install pkb_client
+
+
+or you can install the package from the source code:
+
+.. code-block:: bash
+
+   git clone https://github.com/infinityofspace/pkb_client.git
+   cd pkb_client
+   pip3 install .
diff --git a/docs/source/migration_guide.rst b/docs/source/migration_guide.rst
new file mode 100644
index 0000000..0fea446
--- /dev/null
+++ b/docs/source/migration_guide.rst
@@ -0,0 +1,54 @@
+Migration Guide
+===============
+
+From v1 to v2
++++++++++++++
+
+The version 2 of the package is a major release that introduces a lot of changes. The main changes are:
+
+- support for new API methods
+- package is now a proper Python package with focus on usage as a library (in general more object oriented):
+    - return types are now objects instead of tuples or dictionaries (except domain pricing method)
+    - improved and more consistent error handling
+    - fixed method signatures/no more additional keyworded arguments
+
+These changes are not backward compatible with the version 1 of the package. If you are using the version 1 of the
+package, you will need to update your code to work with the version 2.
+
+To migrate your code from the version 1 to the version 2, follow these steps:
+
+1. Update the package to the version 2 or higher:
+    - if you are using the package from PyPI, run the following command:
+        .. code-block:: bash
+
+           pip3 install --upgrade pkb_client
+    - if you are using the package from the source code, run the following commands:
+        .. code-block:: bash
+
+           git fetch
+           git checkout v2.0.0 # or any later tag
+           pip3 install .
+2. Remove any additional keyworded arguments from all `PKBClient` methods. The methods now have fixed signatures.
+3. Refactor the usage of the following methods:
+    - `PKBClient.dns_create`:
+        - renamed to `PKBClient.create_dns_record`
+        - the method argument `record_type` needs to be enum of :class:`DNSRecordType <pkb_client.client.dns.DNSRecordType>`
+    - `PKBClient.dns_edit`:
+        - renamed to `PKBClient.update_dns_record`
+        - the method argument `record_type` needs to be enum of :class:`DNSRecordType <pkb_client.client.dns.DNSRecordType>`
+    - `PKBClient.dns_delete`:
+        - renamed to `PKBClient.delete_dns_records`
+    - `PKBClient.dns_retrieve`:
+        - renamed to `PKBClient.get_dns_records`
+        - return type is now a list of :class:`DNSRecord <pkb_client.client.dns.DNSRecord>`
+    - `PKBClient.dns_export`:
+        - renamed to `PKBClient.export_dns_records`
+        - the methods argument `filename` is renamed to `filepath`
+    - `PKBClient.dns_import`:
+        - renamed to `PKBClient.import_dns_records`
+        - the methods argument `filename` is renamed to `filepath`
+    - `PKBClient.get_domain_pricing`:
+        - method is not static anymore, you need to create an instance of `PKBClient` to use it
+    - `PKBClient.ssl_retrieve`:
+        - renamed to `PKBClient.get_ssl_bundle`
+        - return type is now :class:`SSLCertificate <pkb_client.client.ssl_cert.SSLCertBundle>`
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
new file mode 100644
index 0000000..c1ae0f3
--- /dev/null
+++ b/docs/source/modules.rst
@@ -0,0 +1,7 @@
+pkb_client
+==========
+
+.. toctree::
+   :maxdepth: 4
+
+   pkb_client
diff --git a/docs/source/pkb_client.cli.rst b/docs/source/pkb_client.cli.rst
new file mode 100644
index 0000000..29fc20f
--- /dev/null
+++ b/docs/source/pkb_client.cli.rst
@@ -0,0 +1,21 @@
+pkb\_client.cli package
+=======================
+
+Submodules
+----------
+
+pkb\_client.cli.cli module
+--------------------------
+
+.. automodule:: pkb_client.cli.cli
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: pkb_client.cli
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/pkb_client.client.rst b/docs/source/pkb_client.client.rst
new file mode 100644
index 0000000..fd677b1
--- /dev/null
+++ b/docs/source/pkb_client.client.rst
@@ -0,0 +1,61 @@
+pkb\_client.client package
+==========================
+
+Submodules
+----------
+
+pkb\_client.client.bind\_file module
+------------------------------------
+
+.. automodule:: pkb_client.client.bind_file
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pkb\_client.client.client module
+--------------------------------
+
+.. automodule:: pkb_client.client.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pkb\_client.client.dns module
+-----------------------------
+
+.. automodule:: pkb_client.client.dns
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pkb\_client.client.domain module
+--------------------------------
+
+.. automodule:: pkb_client.client.domain
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pkb\_client.client.forwarding module
+------------------------------------
+
+.. automodule:: pkb_client.client.forwarding
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pkb\_client.client.ssl\_cert module
+-----------------------------------
+
+.. automodule:: pkb_client.client.ssl_cert
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: pkb_client.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/pkb_client.rst b/docs/source/pkb_client.rst
new file mode 100644
index 0000000..161588e
--- /dev/null
+++ b/docs/source/pkb_client.rst
@@ -0,0 +1,19 @@
+pkb\_client package
+===================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pkb_client.cli
+   pkb_client.client
+
+Module contents
+---------------
+
+.. automodule:: pkb_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
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.