Upgrade python client generator to v7

Author: Tommel71

.gitignore

@@ -96,3 +96,7 @@ local
 tests/test_loki_generated.py
 tests/loki_generated_calls.json
 tests/migration_timing_report.json
+clients/python/MIGRATION_ISSUES.md
+CRITICAL_ISSUES_SUMMARY.md
+COMPATIBILITY_ANALYSIS.md
+clients/python/COMPATIBILITY_QUICK_REFERENCE.md

Makefile

@@ -11,7 +11,7 @@ NUM_THREADS ?= 1
 
 # Migration test settings
 OLD_SERVER_PORT ?= 9001
-NEW_SERVER_PORT ?= 9003  # Note: adev uses OLD_SERVER_PORT+1 for aux/livereload server
+NEW_SERVER_PORT ?= 9000  # Note: adev uses OLD_SERVER_PORT+1 for aux/livereload server
 MIGRATION_BASE_REF ?= master
 WORKTREE_DIR ?= ../.graphsense-rest-old
 

…python/templates/partial_header.mustache …python-templates/partial_header.mustacheclients/python/templates/partial_header.mustache renamed to clients/python-templates/partial_header.mustache clients/python/templates/partial_header.mustache renamed to clients/python-templates/partial_header.mustache

@@ -0,0 +1,34 @@
+# NOTE: This file is auto generated by OpenAPI Generator.
+# URL: https://openapi-generator.tech
+#
+# ref: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: graphsense Python package
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r test-requirements.txt
+      - name: Test with pytest
+        run: |
+          pytest --cov=graphsense

clients/python/.github/workflows/python.yml

@@ -33,3 +33,4 @@ setup.cfg
 requirements.txt
 test-requirements.txt
 setup.py
+pyproject.toml

clients/python/.openapi-generator-ignore

@@ -1,17 +1,20 @@
 -include .env
 
 OPENAPI_URL ?= http://localhost:9000/openapi.json
+GENERATOR_VERSION ?= v7.19.0
+TEMPLATES_DIR ?= ../python-templates
 
-generate-openapi-client:
+# Legacy v5.2.1 generator (for comparison/rollback)
+generate-openapi-client-v5:
 	@echo "Downloading openapi.json from $(OPENAPI_URL)..."
 	curl -s $(OPENAPI_URL) > openapi.json.tmp
 	@echo "Modifying server URL to production..."
 	python scripts/openapi_spec_add_auth.py openapi.json.tmp https://api.ikna.io > openapi.json.modified
-# 	jq '.servers[0].url = "https://api.ikna.io"' openapi.json.tmp > openapi.json.modified
-	@echo "Generating client..."
+	@echo "Generating client with v5.2.1..."
 	docker run --rm \
+		--user $(shell id -u):$(shell id -g) \
 		-v "${PWD}:/build:Z" \
-		-v "${PWD}/templates:/templates:Z" \
+		-v "${PWD}/$(TEMPLATES_DIR):/templates:Z" \
 		openapitools/openapi-generator-cli:v5.2.1 \
 		generate -i /build/openapi.json.modified \
 		-g python \
@@ -22,7 +25,39 @@ generate-openapi-client:
 	@echo "Cleaning up temporary files..."
 	rm -f openapi.json.tmp openapi.json.modified
 
+# v7 generator with backward compatibility patches
+generate-openapi-client:
+	@echo "Downloading openapi.json from $(OPENAPI_URL)..."
+	curl -s $(OPENAPI_URL) > openapi.json.tmp
+	@echo "Modifying server URL to production..."
+	python scripts/openapi_spec_add_auth.py openapi.json.tmp https://api.ikna.io > openapi.json.modified
+	@API_VERSION=$$(jq -r '.info.version' openapi.json.tmp) && \
+	echo "Generating client with $(GENERATOR_VERSION) (API version: $$API_VERSION)..." && \
+	docker run --rm \
+		--user $(shell id -u):$(shell id -g) \
+		-v "${PWD}:/build:Z" \
+		-v "${PWD}/$(TEMPLATES_DIR):/templates:Z" \
+		openapitools/openapi-generator-cli:$(GENERATOR_VERSION) \
+		generate -i /build/openapi.json.modified \
+		-g python \
+		-t /templates \
+		-o /build \
+		--additional-properties=packageName=graphsense \
+		--additional-properties=projectName=graphsense-python \
+		--additional-properties=packageVersion=$$API_VERSION \
+		--additional-properties=library=urllib3
+	@echo "Applying backward compatibility patches..."
+	python scripts/patch_compat.py .
+	@echo "Verifying backward compatibility..."
+	python scripts/test_compat.py
+	@echo "Cleaning up temporary files..."
+	rm -f openapi.json.tmp openapi.json.modified
+
+# Just run the compatibility tests (useful during development)
+test-compat:
+	python scripts/test_compat.py
+
 run-examples:
 	API_KEY=$(API_KEY) python test_examples.py
 
-.PHONY: generate-openapi-client run-examples
+.PHONY: generate-openapi-client generate-openapi-client-v5 test-compat run-examples

clients/python/Makefile

@@ -5,20 +5,22 @@ This Python package is automatically generated by the [OpenAPI Generator](https:
 
 - API version: 1.16.0rc2
 - Package version: 1.16.0rc2
+- Generator version: 7.19.0
 - Build package: org.openapitools.codegen.languages.PythonClientCodegen
 
 ## Requirements.
 
-Python >= 3.6
+Python 3.9+
 
 ## Installation & Usage
 ### pip install
 
 If the python package is hosted on a repository, you can install directly using:
 
 ```sh
-pip install git+https://github.com/graphsense/graphsense-REST.git#subdirectory=clients/python
+pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git
 ```
+(you may need to run `pip` with root permission: `sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git`)
 
 Then import the package:
 ```python
@@ -39,25 +41,20 @@ Then import the package:
 import graphsense
 ```
 
+### Tests
+
+Execute `pytest` to run the tests.
+
 ## Getting Started
 
 Please follow the [installation procedure](#installation--usage) and then run the following:
 
 ```python
 
-import time
 import graphsense
+from graphsense.rest import ApiException
 from pprint import pprint
-from graphsense.api import addresses_api
-from graphsense.model.address import Address
-from graphsense.model.address_tags import AddressTags
-from graphsense.model.address_txs import AddressTxs
-from graphsense.model.entity import Entity
-from graphsense.model.height import Height
-from graphsense.model.links import Links
-from graphsense.model.neighbor_addresses import NeighborAddresses
-from graphsense.model.related_addresses import RelatedAddresses
-from graphsense.model.tag_summary import TagSummary
+
 # Defining the host is optional and defaults to https://api.ikna.io
 # See configuration.py for a list of all supported configuration parameters.
 configuration = graphsense.Configuration(
@@ -70,7 +67,7 @@ configuration = graphsense.Configuration(
 # satisfies your auth use case.
 
 # Configure API key authorization: api_key
-configuration.api_key['api_key'] = 'YOUR_API_KEY'
+configuration.api_key['api_key'] = os.environ["API_KEY"]
 
 # Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
 # configuration.api_key_prefix['api_key'] = 'Bearer'
@@ -79,17 +76,19 @@ configuration.api_key['api_key'] = 'YOUR_API_KEY'
 # Enter a context with an instance of the API client
 with graphsense.ApiClient(configuration) as api_client:
     # Create an instance of the API class
-    api_instance = addresses_api.AddressesApi(api_client)
-    currency = "btc" # str | The cryptocurrency code (e.g., btc)
-    address = "1Archive1n2C579dMsAu3iC6tWzuQJz8dN" # str | The cryptocurrency address
-    include_actors = True # bool | Whether to include information about the actor behind the address (optional) (default to True)
+    api_instance = graphsense.AddressesApi(api_client)
+    currency = 'currency_example' # str | The cryptocurrency code (e.g., btc)
+    address = 'address_example' # str | The cryptocurrency address
+    include_actors = True # bool | Whether to include actor information (optional) (default to True)
 
     try:
         # Get an address
         api_response = api_instance.get_address(currency, address, include_actors=include_actors)
+        print("The response of AddressesApi->get_address:\n")
         pprint(api_response)
-    except graphsense.ApiException as e:
+    except ApiException as e:
         print("Exception when calling AddressesApi->get_address: %s\n" % e)
+
 ```
 
 ## Documentation for API Endpoints
@@ -107,44 +106,42 @@ Class | Method | HTTP request | Description
 *AddressesApi* | [**list_related_addresses**](docs/AddressesApi.md#list_related_addresses) | **GET** /{currency}/addresses/{address}/related_addresses | Get related addresses to the input address
 *AddressesApi* | [**list_tags_by_address**](docs/AddressesApi.md#list_tags_by_address) | **GET** /{currency}/addresses/{address}/tags | Get attribution tags for a given address
 *BlocksApi* | [**get_block**](docs/BlocksApi.md#get_block) | **GET** /{currency}/blocks/{height} | Get a block by its height
-*BlocksApi* | [**get_block_by_date**](docs/BlocksApi.md#get_block_by_date) | **GET** /{currency}/block_by_date/{date} | Get the closest blocks given a timestamp
+*BlocksApi* | [**get_block_by_date**](docs/BlocksApi.md#get_block_by_date) | **GET** /{currency}/block_by_date/{date} | Get block by date
 *BlocksApi* | [**list_block_txs**](docs/BlocksApi.md#list_block_txs) | **GET** /{currency}/blocks/{height}/txs | Get block transactions
 *BulkApi* | [**bulk_csv**](docs/BulkApi.md#bulk_csv) | **POST** /{currency}/bulk.csv/{operation} | Get data as CSV in bulk
 *BulkApi* | [**bulk_json**](docs/BulkApi.md#bulk_json) | **POST** /{currency}/bulk.json/{operation} | Get data as JSON in bulk
 *EntitiesApi* | [**get_entity**](docs/EntitiesApi.md#get_entity) | **GET** /{currency}/entities/{entity} | Get an entity
 *EntitiesApi* | [**list_address_tags_by_entity**](docs/EntitiesApi.md#list_address_tags_by_entity) | **GET** /{currency}/entities/{entity}/tags | Get address tags for a given entity
 *EntitiesApi* | [**list_entity_addresses**](docs/EntitiesApi.md#list_entity_addresses) | **GET** /{currency}/entities/{entity}/addresses | Get an entity's addresses
 *EntitiesApi* | [**list_entity_links**](docs/EntitiesApi.md#list_entity_links) | **GET** /{currency}/entities/{entity}/links | Get transactions between two entities
-*EntitiesApi* | [**list_entity_neighbors**](docs/EntitiesApi.md#list_entity_neighbors) | **GET** /{currency}/entities/{entity}/neighbors | Get an entity's direct neighbors
+*EntitiesApi* | [**list_entity_neighbors**](docs/EntitiesApi.md#list_entity_neighbors) | **GET** /{currency}/entities/{entity}/neighbors | Get an entity's neighbors in the entity graph
 *EntitiesApi* | [**list_entity_txs**](docs/EntitiesApi.md#list_entity_txs) | **GET** /{currency}/entities/{entity}/txs | Get all transactions an entity has been involved in
-*EntitiesApi* | [**search_entity_neighbors**](docs/EntitiesApi.md#search_entity_neighbors) | **GET** /{currency}/entities/{entity}/search | Search deeply for matching neighbors
+*EntitiesApi* | [**search_entity_neighbors**](docs/EntitiesApi.md#search_entity_neighbors) | **GET** /{currency}/entities/{entity}/search | Search neighbors of an entity
 *GeneralApi* | [**get_statistics**](docs/GeneralApi.md#get_statistics) | **GET** /stats | Get statistics of supported currencies
 *GeneralApi* | [**search**](docs/GeneralApi.md#search) | **GET** /search | Returns matching addresses, transactions and labels
-*RatesApi* | [**get_exchange_rates**](docs/RatesApi.md#get_exchange_rates) | **GET** /{currency}/rates/{height} | Returns exchange rate for a given height
-*TagsApi* | [**get_actor**](docs/TagsApi.md#get_actor) | **GET** /tags/actors/{actor} | Returns an actor given its unique id or (unique) label
-*TagsApi* | [**get_actor_tags**](docs/TagsApi.md#get_actor_tags) | **GET** /tags/actors/{actor}/tags | Returns the address tags for a given actor
-*TagsApi* | [**list_address_tags**](docs/TagsApi.md#list_address_tags) | **GET** /tags | Returns address tags associated with a given label
-*TagsApi* | [**list_concepts**](docs/TagsApi.md#list_concepts) | **GET** /tags/taxonomies/{taxonomy}/concepts | Returns the supported concepts of a taxonomy
-*TagsApi* | [**list_taxonomies**](docs/TagsApi.md#list_taxonomies) | **GET** /tags/taxonomies | Returns the supported taxonomies
-*TagsApi* | [**report_tag**](docs/TagsApi.md#report_tag) | **POST** /tags/report-tag | Users can use this endpoint to report a missing annotation.
-*TokensApi* | [**list_supported_tokens**](docs/TokensApi.md#list_supported_tokens) | **GET** /{currency}/supported_tokens | Returns a list of supported token (sub)currencies
-*TxsApi* | [**get_spending_txs**](docs/TxsApi.md#get_spending_txs) | **GET** /{currency}/txs/{tx_hash}/spending | Returns in which other transaction's outputs the asked transaction spent. Think backwards references is the transaction graph. This endpoint is only available for utxo like currencies.
-*TxsApi* | [**get_spent_in_txs**](docs/TxsApi.md#get_spent_in_txs) | **GET** /{currency}/txs/{tx_hash}/spent_in | Returns in which other transactions, outputs from the asked transaction are spent. Think forward references in the transaction graph. This endpoint is only available for utxo like currencies.
-*TxsApi* | [**get_tx**](docs/TxsApi.md#get_tx) | **GET** /{currency}/txs/{tx_hash} | Returns details of a specific transaction identified by its hash
-*TxsApi* | [**get_tx_conversions**](docs/TxsApi.md#get_tx_conversions) | **GET** /{currency}/txs/{tx_hash}/conversions | Returns conversion information (swaps or bridging txs) extracted from a specific transaction
-*TxsApi* | [**get_tx_io**](docs/TxsApi.md#get_tx_io) | **GET** /{currency}/txs/{tx_hash}/{io} | Returns input/output values of a specific transaction identified by its hash
+*RatesApi* | [**get_exchange_rates**](docs/RatesApi.md#get_exchange_rates) | **GET** /{currency}/rates/{height} | Get exchange rates for a given block height
+*TagsApi* | [**get_actor**](docs/TagsApi.md#get_actor) | **GET** /tags/actors/{actor} | Get an actor by ID
+*TagsApi* | [**get_actor_tags**](docs/TagsApi.md#get_actor_tags) | **GET** /tags/actors/{actor}/tags | Get tags associated with an actor
+*TagsApi* | [**list_address_tags**](docs/TagsApi.md#list_address_tags) | **GET** /tags | Get address tags by label
+*TagsApi* | [**list_concepts**](docs/TagsApi.md#list_concepts) | **GET** /tags/taxonomies/{taxonomy}/concepts | List concepts for a taxonomy
+*TagsApi* | [**list_taxonomies**](docs/TagsApi.md#list_taxonomies) | **GET** /tags/taxonomies | List all taxonomies
+*TagsApi* | [**report_tag**](docs/TagsApi.md#report_tag) | **POST** /tags/report-tag | Report a new tag
+*TokensApi* | [**list_supported_tokens**](docs/TokensApi.md#list_supported_tokens) | **GET** /{currency}/supported_tokens/ | Get supported tokens for a currency
+*TxsApi* | [**get_spending_txs**](docs/TxsApi.md#get_spending_txs) | **GET** /{currency}/txs/{tx_hash}/spending | Get transactions that this transaction is spending from
+*TxsApi* | [**get_spent_in_txs**](docs/TxsApi.md#get_spent_in_txs) | **GET** /{currency}/txs/{tx_hash}/spent_in | Get transactions that spent outputs from this transaction
+*TxsApi* | [**get_tx**](docs/TxsApi.md#get_tx) | **GET** /{currency}/txs/{tx_hash} | Get a transaction by its hash
+*TxsApi* | [**get_tx_conversions**](docs/TxsApi.md#get_tx_conversions) | **GET** /{currency}/txs/{tx_hash}/conversions | Get DeFi conversions for a transaction
+*TxsApi* | [**get_tx_io**](docs/TxsApi.md#get_tx_io) | **GET** /{currency}/txs/{tx_hash}/{io} | Get transaction inputs or outputs
 *TxsApi* | [**list_token_txs**](docs/TxsApi.md#list_token_txs) | **GET** /{currency}/token_txs/{tx_hash} | Returns all token transactions in a given transaction
-*TxsApi* | [**list_tx_flows**](docs/TxsApi.md#list_tx_flows) | **GET** /{currency}/txs/{tx_hash}/flows | Returns all asset flows / Internal txs and token flows within a given transaction
+*TxsApi* | [**list_tx_flows**](docs/TxsApi.md#list_tx_flows) | **GET** /{currency}/txs/{tx_hash}/flows | Get asset flows within a transaction
 
 
 ## Documentation For Models
 
  - [Actor](docs/Actor.md)
  - [ActorContext](docs/ActorContext.md)
- - [Actors](docs/Actors.md)
  - [Address](docs/Address.md)
  - [AddressTag](docs/AddressTag.md)
- - [AddressTagAllOf](docs/AddressTagAllOf.md)
  - [AddressTags](docs/AddressTags.md)
  - [AddressTx](docs/AddressTx.md)
  - [AddressTxUtxo](docs/AddressTxUtxo.md)
@@ -156,13 +153,14 @@ Class | Method | HTTP request | Description
  - [Entity](docs/Entity.md)
  - [EntityAddresses](docs/EntityAddresses.md)
  - [ExternalConversion](docs/ExternalConversion.md)
- - [Height](docs/Height.md)
+ - [HTTPValidationError](docs/HTTPValidationError.md)
  - [LabelSummary](docs/LabelSummary.md)
  - [LabeledItemRef](docs/LabeledItemRef.md)
- - [LabeledItemRefs](docs/LabeledItemRefs.md)
  - [Link](docs/Link.md)
  - [LinkUtxo](docs/LinkUtxo.md)
  - [Links](docs/Links.md)
+ - [LinksInner](docs/LinksInner.md)
+ - [LocationInner](docs/LocationInner.md)
  - [NeighborAddress](docs/NeighborAddress.md)
  - [NeighborAddresses](docs/NeighborAddresses.md)
  - [NeighborEntities](docs/NeighborEntities.md)
@@ -173,8 +171,6 @@ Class | Method | HTTP request | Description
  - [RelatedAddresses](docs/RelatedAddresses.md)
  - [SearchResult](docs/SearchResult.md)
  - [SearchResultByCurrency](docs/SearchResultByCurrency.md)
- - [SearchResultLabels](docs/SearchResultLabels.md)
- - [SearchResultLeaf](docs/SearchResultLeaf.md)
  - [SearchResultLevel1](docs/SearchResultLevel1.md)
  - [SearchResultLevel2](docs/SearchResultLevel2.md)
  - [SearchResultLevel3](docs/SearchResultLevel3.md)
@@ -188,54 +184,33 @@ Class | Method | HTTP request | Description
  - [Taxonomy](docs/Taxonomy.md)
  - [TokenConfig](docs/TokenConfig.md)
  - [TokenConfigs](docs/TokenConfigs.md)
- - [TokenValues](docs/TokenValues.md)
  - [Tx](docs/Tx.md)
  - [TxAccount](docs/TxAccount.md)
  - [TxRef](docs/TxRef.md)
  - [TxSummary](docs/TxSummary.md)
  - [TxUtxo](docs/TxUtxo.md)
  - [TxValue](docs/TxValue.md)
- - [TxValues](docs/TxValues.md)
- - [Txs](docs/Txs.md)
- - [TxsAccount](docs/TxsAccount.md)
  - [UserReportedTag](docs/UserReportedTag.md)
  - [UserTagReportResponse](docs/UserTagReportResponse.md)
+ - [ValidationError](docs/ValidationError.md)
  - [Values](docs/Values.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
 
-## api_key
+Authentication schemes defined for the API:
+<a id="api_key"></a>
+### api_key
 
 - **Type**: API key
 - **API key parameter name**: Authorization
 - **Location**: HTTP header
 
 
-## Examples
-
-In `./examples` you can find example Python scripts and [Jupyter](https://jupyter.org/) notebooks demonstrating how to use the GraphSense Python API. Please Follow these setup instructions to run them:
-
-Setup a Python environment with [Anaconda](https://www.anaconda.com/products/distribution):
-
-    conda env create -f environment.yml
-    conda activate graphsense-python
+## Author
 
-Copy the config temp file and enter your Iknaio API key
+contact@ikna.io
 
-    cp config.json.tmp config.json
-    vi config.json
 
-Run the jupyter notebooks
-
-    jupyter notebook
-
-
-## Generation from OpenAPI specification
-
-This python package has been generated from [Graphsense's OpenAPI specification](https://api.ikna.io) hosted by [Iknaio Cryptoasset Analytics GmbH](https://ikna.io) using this command:
-
-```
-make generate-openapi-client
-```