Updates and improved testing

.github/workflows/unit-tests-all.yml

@@ -6,59 +6,79 @@ on:
     branches:
       - "main"
 jobs:
-  tox:
-    name: "Python ${{ matrix.python-version }} -- ${{ matrix.os }} "
+  unit-tests:
+    name: "Unit Tests - Python ${{ matrix.python-version }} -- ${{ matrix.os }}"
     runs-on: ${{ matrix.os }}
-    continue-on-error: ${{ matrix.experimental }}
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.9", "3.10"]
-        experimental: [false]
-        # Include experimental or bleeding-edge releases.
-        # Windows is not included as it can be unreliable, e.g.
-        # psycopg2-binary is only released some time after a Python
-        # major/minor version is formally released.
-        #
-        # Uncomment below (including 'include:') when the next
-        # reasonable test candidate is made available:
-        include:
-          #
-          # Versions list: https://github.com/actions/python-versions/releases
-          # Example formatting: 3.11.0-alpha.1, 3.9.0-beta.8, 3.10.0-rc.3
-          #
-          - os: ubuntu-latest
-            python-version: "3.11.0"
-            experimental: true
-          - os: windows-latest
-            python-version: "3.11.0"
-            experimental: true
+        python-version: ["3.10", "3.11", "3.12"]
     steps:
       - name: "check out repository"
         uses: "actions/checkout@v4"
         with:
           submodules: 'true'
       - name: "set up python ${{ matrix.python-version }}"
-        uses: "actions/setup-python@v4"
+        uses: "actions/setup-python@v5"
         with:
           python-version: "${{ matrix.python-version }}"
-      - name: "get pip cache dir"
-        id: "pip-cache"
+      - name: "cache pip packages"
+        uses: "actions/cache@v4"
+        with:
+          path: ~/.cache/pip
+          key: "${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}"
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: "install dependencies"
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+      - name: "run unit tests"
         run: |
-          echo "{name}={$(pip cache dir)}" >> $GITHUB_OUTPUT
+          pytest -c pytest.ini -m unit --cov=src/koios_api --cov-report=term-missing --cov-report=xml
+      - name: "upload coverage to codecov"
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+  integration-tests:
+    name: "Integration Tests - Python ${{ matrix.python-version }} -- ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    steps:
+      - name: "check out repository"
+        uses: "actions/checkout@v4"
+        with:
+          submodules: 'true'
+      - name: "set up python ${{ matrix.python-version }}"
+        uses: "actions/setup-python@v5"
+        with:
+          python-version: "${{ matrix.python-version }}"
       - name: "cache pip packages"
-        uses: "actions/cache@v3"
+        uses: "actions/cache@v4"
         with:
-          path: "${{ steps.pip-cache.outputs.dir }}"
-          key: "${{ runner.os }}-pip-${{ hashFiles('**/base.txt', '**/local.txt') }}"
+          path: ~/.cache/pip
+          key: "${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}"
           restore-keys: |
             ${{ runner.os }}-pip-
-      - name: "install tox"
+      - name: "install dependencies"
         run: |
           python -m pip install --upgrade pip
-          pip install tox
-      - name: "run tox"
-        env:
-          TOXENV: py3
+          pip install -r requirements.txt
+      - name: "run integration tests"
         run: |
-          tox
+          pytest -c pytest.ini -m integration --cov=src/koios_api --cov-report=term-missing --cov-report=xml
+      - name: "upload coverage to codecov"
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          flags: integrationtests
+          name: codecov-umbrella
+          fail_ci_if_error: false

.gitignore

@@ -1,4 +1,5 @@
 __pycache__
+.env
 .idea
 .pytest_cache
 .ruff_cache

pytest.ini

@@ -1,5 +1,9 @@
 [pytest]
-addopts = -p no:cacheprovider
+addopts = -p no:cacheprovider --cov=src/koios_api --cov-report=term-missing --cov-report=html
+testpaths = tests
+markers =
+    unit: Unit tests that do not require network access (fast, isolated)
+    integration: Integration tests that require the live Koios API (slow, network-dependent)
 
 [pycodestyle]
 ignore =

requirements.txt

@@ -2,5 +2,8 @@ codespell==2.3.0
 pre-commit==3.7.1
 pylint==3.2.3
 pytest==8.2.2
+pytest-cov==5.0.0
+pytest-mock==3.14.0
+responses==0.25.0
 tox==4.15.1
 requests==2.32.3

src/koios_api/__init__.py

@@ -1,12 +1,179 @@
-"""Module initialization"""
-from .__config__ import *
-from .account import *
-from .address import *
-from .asset import *
-from .block import *
-from .epoch import *
-from .network import *
-from .ogmios import *
-from .pool import *
-from .script import *
-from .transactions import *
+"""Koios API Python wrapper for Cardano blockchain data."""
+
+from .__config__ import (
+    API_BASE_URL,
+    API_RESP_COUNT,
+    CARDANO_NET,
+    KOIOS_API_TOKEN,
+    REQUEST_TIMEOUT,
+    SLEEP_TIME,
+)
+from .account import (
+    get_account_addresses,
+    get_account_assets,
+    get_account_history,
+    get_account_info,
+    get_account_info_cached,
+    get_account_list,
+    get_account_rewards,
+    get_account_txs,
+    get_account_updates,
+    get_account_utxos,
+)
+from .address import (
+    get_address_assets,
+    get_address_info,
+    get_address_txs,
+    get_address_utxos,
+    get_credential_txs,
+    get_credential_utxos,
+)
+from .asset import (
+    get_asset_address_list,
+    get_asset_addresses,
+    get_asset_history,
+    get_asset_info,
+    get_asset_list,
+    get_asset_nft_address,
+    get_asset_policy_info,
+    get_asset_summary,
+    get_asset_token_registry,
+    get_asset_txs,
+    get_asset_utxos,
+    get_policy_asset_addresses,
+    get_policy_asset_info,
+    get_policy_asset_list,
+)
+from .block import get_block_info, get_block_txs, get_blocks
+from .epoch import get_epoch_block_protocols, get_epoch_info, get_epoch_params
+from .library import MaxRetriesExceeded
+from .network import (
+    get_genesis,
+    get_param_updates,
+    get_reserve_withdrawals,
+    get_tip,
+    get_totals,
+    get_treasury_withdrawals,
+)
+from .ogmios import get_ogmios
+from .pool import (
+    get_pool_blocks,
+    get_pool_delegators,
+    get_pool_delegators_history,
+    get_pool_history,
+    get_pool_info,
+    get_pool_list,
+    get_pool_metadata,
+    get_pool_registrations,
+    get_pool_relays,
+    get_pool_retirements,
+    get_pool_stake_snapshot,
+    get_pool_updates,
+    get_retiring_pools,
+)
+from .script import (
+    get_datum_info,
+    get_native_script_list,
+    get_plutus_script_list,
+    get_script_info,
+    get_script_redeemers,
+    get_script_utxos,
+)
+from .transactions import (
+    get_tx_info,
+    get_tx_metadata,
+    get_tx_metalabels,
+    get_tx_status,
+    get_utxo_info,
+    submit_tx,
+)
+
+__all__ = [
+    # Config
+    "API_BASE_URL",
+    "API_RESP_COUNT",
+    "CARDANO_NET",
+    "KOIOS_API_TOKEN",
+    "REQUEST_TIMEOUT",
+    "SLEEP_TIME",
+    # Exceptions
+    "MaxRetriesExceeded",
+    # Account
+    "get_account_addresses",
+    "get_account_assets",
+    "get_account_history",
+    "get_account_info",
+    "get_account_info_cached",
+    "get_account_list",
+    "get_account_rewards",
+    "get_account_txs",
+    "get_account_updates",
+    "get_account_utxos",
+    # Address
+    "get_address_assets",
+    "get_address_info",
+    "get_address_txs",
+    "get_address_utxos",
+    "get_credential_txs",
+    "get_credential_utxos",
+    # Asset
+    "get_asset_address_list",
+    "get_asset_addresses",
+    "get_asset_history",
+    "get_asset_info",
+    "get_asset_list",
+    "get_asset_nft_address",
+    "get_asset_policy_info",
+    "get_asset_summary",
+    "get_asset_txs",
+    "get_asset_utxos",
+    "get_asset_token_registry",
+    "get_policy_asset_addresses",
+    "get_policy_asset_info",
+    "get_policy_asset_list",
+    # Block
+    "get_block_info",
+    "get_block_txs",
+    "get_blocks",
+    # Epoch
+    "get_epoch_block_protocols",
+    "get_epoch_info",
+    "get_epoch_params",
+    # Network
+    "get_genesis",
+    "get_param_updates",
+    "get_reserve_withdrawals",
+    "get_tip",
+    "get_totals",
+    "get_treasury_withdrawals",
+    # Ogmios
+    "get_ogmios",
+    # Pool
+    "get_pool_blocks",
+    "get_pool_delegators",
+    "get_pool_delegators_history",
+    "get_pool_history",
+    "get_pool_info",
+    "get_pool_list",
+    "get_pool_metadata",
+    "get_pool_registrations",
+    "get_pool_relays",
+    "get_pool_retirements",
+    "get_pool_stake_snapshot",
+    "get_pool_updates",
+    "get_retiring_pools",
+    # Script
+    "get_datum_info",
+    "get_native_script_list",
+    "get_plutus_script_list",
+    "get_script_info",
+    "get_script_redeemers",
+    "get_script_utxos",
+    # Transactions
+    "get_tx_info",
+    "get_tx_metalabels",
+    "get_tx_metadata",
+    "get_tx_status",
+    "get_utxo_info",
+    "submit_tx",
+]