x402 support (#89)

Author: Gallaecio

.github/workflows/test.yml

@@ -16,7 +16,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        include:
+        - python-version: "3.9"
+          tox: min
+        - python-version: "3.9"
+        - python-version: "3.10"
+          tox: min-x402
+        - python-version: "3.10"
+        - python-version: "3.11"
+        - python-version: "3.12"
+        - python-version: "3.13"
+        - python-version: "3.13"
+          tox: x402
 
     steps:
     - uses: actions/checkout@v4
@@ -30,7 +41,7 @@ jobs:
         python -m pip install tox
     - name: tox
       run: |
-        tox -e py
+        tox -e ${{ matrix.tox || 'py' }}
     - name: coverage
       if: ${{ success() }}
       uses: codecov/[email protected]

CHANGES.rst

@@ -1,6 +1,11 @@
 Changes
 =======
 
+0.8.0 (unreleased)
+------------------
+
+* Added :ref:`x402 support <x402>`.
+
 0.7.1 (2025-06-05)
 ------------------
 

README.rst

@@ -35,14 +35,22 @@ Installation
 
     pip install zyte-api
 
-.. note:: Python 3.9+ is required.
+Or, to use x402_:
+
+.. _x402: https://www.x402.org/
+
+.. code-block:: shell
+
+    pip install zyte-api[x402]
+
+.. note:: Python 3.9+ is required; Python 3.10+ if using x402.
 
 .. install-end
 
 Basic usage
 ===========
 
-.. basic-start
+.. basic-key-start
 
 Set your API key
 ----------------
@@ -54,6 +62,9 @@ After you `sign up for a Zyte API account
 <https://app.zyte.com/o/zyte-api/api-access>`_.
 
 .. key-get-end
+.. basic-key-end
+
+.. basic-start
 
 
 Use the command-line client

docs/conf.py

@@ -183,6 +183,11 @@
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ["search.html"]
 
+# -- Smart quotes ------------------------------------------------------------
+# Disabled so that, in the CLI reference, ``--api-key` and similar options are
+# not turned into –api-key in descriptions.
+smartquotes = False
+
 
 # -- Extension configuration -------------------------------------------------
 

docs/index.rst

@@ -18,6 +18,7 @@ python-zyte-api
    :maxdepth: 1
 
    use/key
+   use/x402
    use/cli
    use/api
 

docs/intro/basic.rst

@@ -4,6 +4,14 @@
 Basic usage
 ===========
 
+.. include:: /../README.rst
+   :start-after: basic-key-start
+   :end-before: basic-key-end
+
+To use x402_ instead, see :ref:`x402`.
+
+.. _x402: https://www.x402.org/
+
 .. include:: /../README.rst
    :start-after: basic-start
    :end-before: basic-end

docs/use/api.rst

@@ -6,8 +6,9 @@
 Python client library
 =====================
 
-Once you have :ref:`installed python-zyte-api <install>` and :ref:`configured
-your API key <api-key>`, you can use one of its APIs from Python code:
+Once you have :ref:`installed python-zyte-api <install>` and configured your
+:ref:`API key <api-key>` or :ref:`Ethereum private key <x402>`, you can use one
+of its APIs from Python code:
 
 -   The :ref:`sync API <sync>` can be used to build simple, proof-of-concept or
     debugging Python scripts.

docs/use/cli.rst

@@ -4,8 +4,9 @@
 Command-line client
 ===================
 
-Once you have :ref:`installed python-zyte-api <install>` and :ref:`configured
-your API key <api-key>`, you can use the ``zyte-api`` command-line client.
+Once you have :ref:`installed python-zyte-api <install>` and configured your
+:ref:`API key <api-key>` or :ref:`Ethereum private key <x402>`, you can use the
+``zyte-api`` command-line client.
 
 To use ``zyte-api``, pass an :ref:`input file <input-file>` as the first
 parameter and specify an :ref:`output file <output-file>` with ``--output``.

docs/use/x402.rst

@@ -0,0 +1,66 @@
+.. _x402:
+
+====
+x402
+====
+
+It is possible to use :ref:`Zyte API <zyte-api>` without a Zyte API account by 
+using the x402_ protocol to handle payments:
+
+#.  Read the `Zyte Terms of Service`_. By using Zyte API, you are accepting
+    them.
+
+    .. _Zyte Terms of Service: https://www.zyte.com/terms-policies/terms-of-service/
+
+#.  During :ref:`installation <install>`, make sure to install the ``x402`` extra.
+
+#.  :ref:`Configure <eth-key>` the *private* key of your Ethereum_ account to
+    authorize payments.
+
+    .. _Ethereum: https://ethereum.org/
+
+
+.. _eth-key:
+
+Configuring your Ethereum private key
+=====================================
+
+It is recommended to configure your Ethereum private key through an environment
+variable, so that it can be picked by both the :ref:`command-line client
+<command_line>` and the :ref:`Python client library <api>`:
+
+-  On Windows’ CMD:
+
+   .. code-block:: shell
+
+        > set ZYTE_API_ETH_KEY=YOUR_ETH_PRIVATE_KEY
+
+-  On macOS and Linux:
+
+   .. code-block:: shell
+
+        $ export ZYTE_API_ETH_KEY=YOUR_ETH_PRIVATE_KEY
+
+Alternatively, you may pass your Ethereum private key to the clients directly:
+
+-   To pass your Ethereum private key directly to the command-line client, use
+    the ``--eth-key`` switch:
+
+    .. code-block:: shell
+
+        zyte-api --eth-key YOUR_ETH_PRIVATE_KEY …
+
+-   To pass your Ethereum private key directly to the Python client classes,
+    use the ``eth_key`` parameter when creating a client object:
+
+    .. code-block:: python
+
+        from zyte_api import ZyteAPI
+
+        client = ZyteAPI(eth_key="YOUR_ETH_PRIVATE_KEY")
+
+    .. code-block:: python
+
+        from zyte_api import AsyncZyteAPI
+
+        client = AsyncZyteAPI(eth_key="YOUR_ETH_PRIVATE_KEY")

pyproject.toml

@@ -154,6 +154,9 @@ ignore = [
 "zyte_api/errors.py" = ["UP007"]
 "zyte_api/stats.py" = ["UP007"]
 
+[tool.ruff.lint.flake8-pytest-style]
+parametrize-values-type = "tuple"
+
 [tool.ruff.lint.flake8-type-checking]
 runtime-evaluated-decorators = ["attr.s"]