diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/.gitignore | 1 | ||||
| -rw-r--r-- | docs/Makefile | 20 | ||||
| -rw-r--r-- | docs/make.bat | 35 | ||||
| -rw-r--r-- | docs/source/conf.py | 30 | ||||
| -rw-r--r-- | docs/source/index.rst | 29 | ||||
| -rw-r--r-- | docs/source/installation.rst | 17 | ||||
| -rw-r--r-- | docs/source/migration_guide.rst | 54 | ||||
| -rw-r--r-- | docs/source/modules.rst | 7 | ||||
| -rw-r--r-- | docs/source/pkb_client.cli.rst | 21 | ||||
| -rw-r--r-- | docs/source/pkb_client.client.rst | 61 | ||||
| -rw-r--r-- | docs/source/pkb_client.rst | 19 | ||||
| -rw-r--r-- | docs/source/usage.rst | 89 |
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. |