@planqk/planqk-api-sdk 1.0.0

package/notebooks/python-sdk.ipynb

@@ -0,0 +1,218 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Python SDK"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "is_executing": true
+    }
+   },
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "from dotenv import load_dotenv\n",
+    "\n",
+    "# Make a copy of .env.example and rename it to .env, place it in the\n",
+    "# root directory, and fill in the values.\n",
+    "\n",
+    "load_dotenv(override=True)\n",
+    "\n",
+    "access_token = os.getenv(\"PLANQK_PERSONAL_ACCESS_TOKEN\", None)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Usage"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Data Pools"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from planqk.api.client import PlanqkApiClient\n",
+    "\n",
+    "client = PlanqkApiClient(access_token=access_token)\n",
+    "\n",
+    "# Create a new data pool\n",
+    "data_pool = client.data_pools.create_data_pool(name=\"Example Data Pool\")\n",
+    "\n",
+    "# Add a file to the data pool\n",
+    "file = client.data_pools.add_data_pool_file(\n",
+    "    id=data_pool.id, filename=\"example.txt\", file=\"Example content of the file.\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "content = client.data_pools.get_data_pool_file(id=data_pool.id, file_id=file.id)\n",
+    "\n",
+    "content_string = \"\"\n",
+    "for chunk in content:\n",
+    "    content_string += chunk.decode(\"utf-8\")\n",
+    "\n",
+    "content_string"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Streaming File Upload\n",
+    "\n",
+    "This example shows how to stream a file from disk and upload it to a data pool."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# First, let's create a sample file to upload\n",
+    "import tempfile\n",
+    "import os\n",
+    "\n",
+    "# Create a temporary file with some content\n",
+    "sample_content = \"\"\"This is a sample file for streaming upload.\n",
+    "It contains multiple lines of text.\n",
+    "Line 3 with some data.\n",
+    "Line 4 with more content.\n",
+    "End of file.\"\"\"\n",
+    "\n",
+    "# Create a temporary file\n",
+    "temp_file = tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".txt\", delete=False)\n",
+    "temp_file.write(sample_content)\n",
+    "temp_file.close()\n",
+    "\n",
+    "print(f\"Created temporary file: {temp_file.name}\")\n",
+    "print(f\"File size: {os.path.getsize(temp_file.name)} bytes\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Upload by opening file and reading in chunks\n",
+    "def stream_file_upload(file_path, data_pool_id, filename):\n",
+    "    \"\"\"\n",
+    "    Stream a file from disk and upload it to a data pool\n",
+    "    \"\"\"\n",
+    "    with open(file_path, \"rb\") as file_handle:\n",
+    "        # Upload the file using the file handle\n",
+    "        uploaded_file = client.data_pools.add_data_pool_file(\n",
+    "            id=data_pool_id, filename=filename, file=file_handle\n",
+    "        )\n",
+    "    return uploaded_file\n",
+    "\n",
+    "\n",
+    "# Upload the temporary file\n",
+    "streamed_file = stream_file_upload(temp_file.name, data_pool.id, \"streamed_sample.txt\")\n",
+    "\n",
+    "print(f\"Uploaded file: {streamed_file.name}\")\n",
+    "print(f\"File ID: {streamed_file.id}\")\n",
+    "print(f\"Content length: {streamed_file.content_length}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Verify the uploaded files by downloading and checking content\n",
+    "def download_and_verify(data_pool_id, file_id, expected_content=None):\n",
+    "    \"\"\"\n",
+    "    Download a file and optionally verify its content\n",
+    "    \"\"\"\n",
+    "    print(f\"Downloading file {file_id}...\")\n",
+    "\n",
+    "    # Get the file content as Iterator[bytes]\n",
+    "    content_stream = client.data_pools.get_data_pool_file(\n",
+    "        id=data_pool_id, file_id=file_id\n",
+    "    )\n",
+    "\n",
+    "    # Read all chunks and combine\n",
+    "    content_bytes = b\"\"\n",
+    "    for chunk in content_stream:\n",
+    "        content_bytes += chunk\n",
+    "\n",
+    "    # Decode to string\n",
+    "    content_string = content_bytes.decode(\"utf-8\")\n",
+    "\n",
+    "    print(f\"Downloaded content ({len(content_bytes)} bytes):\")\n",
+    "    print(content_string[:100] + \"...\" if len(content_string) > 100 else content_string)\n",
+    "\n",
+    "    if expected_content and content_string.strip() == expected_content.strip():\n",
+    "        print(\"✅ Content verification passed!\")\n",
+    "    elif expected_content:\n",
+    "        print(\"❌ Content verification failed!\")\n",
+    "\n",
+    "    return content_string\n",
+    "\n",
+    "\n",
+    "download_and_verify(data_pool.id, streamed_file.id, sample_content)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Remove the temporary file\n",
+    "try:\n",
+    "    os.unlink(temp_file.name)\n",
+    "    print(f\"Cleaned up temporary file: {temp_file.name}\")\n",
+    "except OSError as e:\n",
+    "    print(f\"Error cleaning up temporary file: {e}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "planqk-api-sdk",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@planqk/planqk-api-sdk",
+  "version": "1.0.0",
+  "description": "SDK to interact with official PLANQK API.",
+  "author": "Kipu Quantum GmbH",
+  "contributors": [
+    "Wurster, Michael <michael.wurster@kipu-quantum.com>"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/planqk-foss/planqk-api-sdk.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "shx rm -rf dist && tsc -b",
+    "lint": "eslint",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "form-data": "^4",
+    "form-data-encoder": "^4",
+    "formdata-node": "^6",
+    "js-base64": "^3",
+    "node-fetch": "^3",
+    "qs": "^6",
+    "readable-stream": "^4",
+    "url-join": "^5"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/node-fetch": "^2",
+    "@types/qs": "^6",
+    "@types/url-join": "^4",
+    "dotenv": "^16",
+    "eslint": "^9",
+    "shx": "^0.3.4",
+    "typescript": "^5",
+    "typescript-eslint": "^8",
+    "vitest": "^3"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "readme": "./README-node.md"
+}

package/planqk/api/__init__.py

@@ -0,0 +1 @@
+from ._version import __version__

package/planqk/api/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

package/planqk/api/client.py

@@ -0,0 +1,19 @@
+import os
+from typing import Optional
+
+from planqk.api.credentials import DefaultCredentialsProvider
+from planqk.api.sdk import PlanqkApi
+from planqk.api.sdk.data_pools.client import DataPoolsClient
+
+_PLANQK_API_BASE_URL_NAME = "PLANQK_API_BASE_URL"
+
+
+class PlanqkApiClient:
+    def __init__(self, access_token: Optional[str] = None):
+        base_url = os.environ.get(_PLANQK_API_BASE_URL_NAME, "https://platform.planqk.de/qc-catalog")
+        credentials_provider = DefaultCredentialsProvider(access_token)
+        self._api = PlanqkApi(base_url=base_url, api_key=credentials_provider.get_access_token())
+
+    @property
+    def data_pools(self) -> DataPoolsClient:
+        return self._api.data_pools

package/planqk/api/credentials.py

@@ -0,0 +1,103 @@
+import json
+import os
+import platform
+from abc import ABC, abstractmethod
+from json import JSONDecodeError
+
+_PERSONAL_ACCESS_TOKEN_NAME = "PLANQK_PERSONAL_ACCESS_TOKEN"
+_CONFIG_FILE_PATH = "PLANQK_CONFIG_FILE_PATH"
+
+
+class CredentialUnavailableError(Exception):
+    """
+    Exception raised when credentials are unavailable for authentication.
+    """
+
+    def __init__(self, message=None):
+        if message is None:
+            message = f"Credentials not found. Please set your personal access token as parameter, in the environment, or use 'planqk login' to authenticate."
+        super().__init__(message)
+
+
+class CredentialProvider(ABC):
+
+    @abstractmethod
+    def get_access_token(self) -> str:
+        pass
+
+
+class EnvironmentCredential(CredentialProvider):
+
+    def get_access_token(self) -> str:
+        access_token = os.environ.get(_PERSONAL_ACCESS_TOKEN_NAME)
+
+        if not access_token:
+            raise CredentialUnavailableError(f"Environment variable {_PERSONAL_ACCESS_TOKEN_NAME} is not set")
+
+        return access_token
+
+
+def get_config_file_path():
+    config_file_path = os.environ.get(_CONFIG_FILE_PATH, None)
+    if not config_file_path:
+        if platform.system() == "Windows":
+            config_dir = os.path.join(os.getenv("LOCALAPPDATA"), "planqk")
+        else:
+            config_dir = os.path.join(os.path.expanduser("~"), ".config", "planqk")
+        config_file_path = os.path.join(config_dir, "config.json")
+    return config_file_path
+
+
+class ConfigFileCredential(CredentialProvider):
+    def __init__(self):
+        self.config_file = get_config_file_path()
+
+    def get_access_token(self) -> str:
+        if not self.config_file:
+            raise CredentialUnavailableError("Config file location not set")
+        if not os.path.isfile(self.config_file):
+            raise CredentialUnavailableError(f"Config file at {self.config_file} does not exist")
+        try:
+            access_token = ConfigFileCredential.parse_file(self.config_file)
+        except JSONDecodeError:
+            raise CredentialUnavailableError("Failed to parse config file: Invalid JSON")
+        except KeyError as e:
+            raise CredentialUnavailableError(f"Failed to parse config file: Missing expected value - {str(e)}")
+        except Exception as e:
+            raise CredentialUnavailableError(f"Failed to parse config file: {str(e)}")
+        return access_token
+
+    @staticmethod
+    def parse_file(path) -> str:
+        with open(path, "r") as file:
+            data = json.load(file)
+            return data["auth"]["value"]
+
+
+class StaticCredential(CredentialProvider):
+    def __init__(self, access_token=None):
+        self.access_token = access_token
+
+    def get_access_token(self) -> str:
+        if not self.access_token:
+            raise CredentialUnavailableError(f"Access token not set")
+        return self.access_token
+
+
+class DefaultCredentialsProvider(CredentialProvider):
+    def __init__(self, access_token=None):
+        self.credentials = [
+            StaticCredential(access_token),
+            EnvironmentCredential(),
+            ConfigFileCredential(),
+        ]
+
+    def get_access_token(self) -> str:
+        for credential in self.credentials:
+            try:
+                return credential.get_access_token()
+            except CredentialUnavailableError:
+                # ignore and try the next credential provider
+                pass
+
+        raise CredentialUnavailableError()

package/planqk/api/sdk/__init__.py

@@ -0,0 +1,25 @@
+# This file was auto-generated by Fern from our API Definition.
+
+# isort: skip_file
+
+from .types import DataPoolDto, DataPoolDtoCurrentUserPermission, DataPoolFileDto, OauthScope
+from .errors import BadRequestError, ForbiddenError, InternalServerError, NotFoundError, UnauthorizedError
+from . import data_pools
+from .client import AsyncPlanqkApi, PlanqkApi
+from .environment import PlanqkApiEnvironment
+
+__all__ = [
+    "AsyncPlanqkApi",
+    "BadRequestError",
+    "DataPoolDto",
+    "DataPoolDtoCurrentUserPermission",
+    "DataPoolFileDto",
+    "ForbiddenError",
+    "InternalServerError",
+    "NotFoundError",
+    "OauthScope",
+    "PlanqkApi",
+    "PlanqkApiEnvironment",
+    "UnauthorizedError",
+    "data_pools",
+]

package/planqk/api/sdk/client.py

@@ -0,0 +1,153 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import httpx
+from .core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from .data_pools.client import AsyncDataPoolsClient, DataPoolsClient
+from .environment import PlanqkApiEnvironment
+
+
+class PlanqkApi:
+    """
+    Use this class to access the different functions within the SDK. You can instantiate any number of clients with different configuration that will propagate to these functions.
+
+    Parameters
+    ----------
+    base_url : typing.Optional[str]
+        The base url to use for requests from the client.
+
+    environment : PlanqkApiEnvironment
+        The environment to use for requests from the client. from .environment import PlanqkApiEnvironment
+
+
+
+        Defaults to PlanqkApiEnvironment.DEFAULT
+
+
+
+    api_key : str
+    headers : typing.Optional[typing.Dict[str, str]]
+        Additional headers to send with every request.
+
+    timeout : typing.Optional[float]
+        The timeout to be used, in seconds, for requests. By default the timeout is 60 seconds, unless a custom httpx client is used, in which case this default is not enforced.
+
+    follow_redirects : typing.Optional[bool]
+        Whether the default httpx client follows redirects or not, this is irrelevant if a custom httpx client is passed in.
+
+    httpx_client : typing.Optional[httpx.Client]
+        The httpx client to use for making requests, a preconfigured client is used by default, however this is useful should you want to pass in any custom httpx configuration.
+
+    Examples
+    --------
+    from planqk import PlanqkApi
+
+    client = PlanqkApi(
+        api_key="YOUR_API_KEY",
+    )
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: typing.Optional[str] = None,
+        environment: PlanqkApiEnvironment = PlanqkApiEnvironment.DEFAULT,
+        api_key: str,
+        headers: typing.Optional[typing.Dict[str, str]] = None,
+        timeout: typing.Optional[float] = None,
+        follow_redirects: typing.Optional[bool] = True,
+        httpx_client: typing.Optional[httpx.Client] = None,
+    ):
+        _defaulted_timeout = (
+            timeout if timeout is not None else 60 if httpx_client is None else httpx_client.timeout.read
+        )
+        self._client_wrapper = SyncClientWrapper(
+            base_url=_get_base_url(base_url=base_url, environment=environment),
+            api_key=api_key,
+            headers=headers,
+            httpx_client=httpx_client
+            if httpx_client is not None
+            else httpx.Client(timeout=_defaulted_timeout, follow_redirects=follow_redirects)
+            if follow_redirects is not None
+            else httpx.Client(timeout=_defaulted_timeout),
+            timeout=_defaulted_timeout,
+        )
+        self.data_pools = DataPoolsClient(client_wrapper=self._client_wrapper)
+
+
+class AsyncPlanqkApi:
+    """
+    Use this class to access the different functions within the SDK. You can instantiate any number of clients with different configuration that will propagate to these functions.
+
+    Parameters
+    ----------
+    base_url : typing.Optional[str]
+        The base url to use for requests from the client.
+
+    environment : PlanqkApiEnvironment
+        The environment to use for requests from the client. from .environment import PlanqkApiEnvironment
+
+
+
+        Defaults to PlanqkApiEnvironment.DEFAULT
+
+
+
+    api_key : str
+    headers : typing.Optional[typing.Dict[str, str]]
+        Additional headers to send with every request.
+
+    timeout : typing.Optional[float]
+        The timeout to be used, in seconds, for requests. By default the timeout is 60 seconds, unless a custom httpx client is used, in which case this default is not enforced.
+
+    follow_redirects : typing.Optional[bool]
+        Whether the default httpx client follows redirects or not, this is irrelevant if a custom httpx client is passed in.
+
+    httpx_client : typing.Optional[httpx.AsyncClient]
+        The httpx client to use for making requests, a preconfigured client is used by default, however this is useful should you want to pass in any custom httpx configuration.
+
+    Examples
+    --------
+    from planqk import AsyncPlanqkApi
+
+    client = AsyncPlanqkApi(
+        api_key="YOUR_API_KEY",
+    )
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: typing.Optional[str] = None,
+        environment: PlanqkApiEnvironment = PlanqkApiEnvironment.DEFAULT,
+        api_key: str,
+        headers: typing.Optional[typing.Dict[str, str]] = None,
+        timeout: typing.Optional[float] = None,
+        follow_redirects: typing.Optional[bool] = True,
+        httpx_client: typing.Optional[httpx.AsyncClient] = None,
+    ):
+        _defaulted_timeout = (
+            timeout if timeout is not None else 60 if httpx_client is None else httpx_client.timeout.read
+        )
+        self._client_wrapper = AsyncClientWrapper(
+            base_url=_get_base_url(base_url=base_url, environment=environment),
+            api_key=api_key,
+            headers=headers,
+            httpx_client=httpx_client
+            if httpx_client is not None
+            else httpx.AsyncClient(timeout=_defaulted_timeout, follow_redirects=follow_redirects)
+            if follow_redirects is not None
+            else httpx.AsyncClient(timeout=_defaulted_timeout),
+            timeout=_defaulted_timeout,
+        )
+        self.data_pools = AsyncDataPoolsClient(client_wrapper=self._client_wrapper)
+
+
+def _get_base_url(*, base_url: typing.Optional[str] = None, environment: PlanqkApiEnvironment) -> str:
+    if base_url is not None:
+        return base_url
+    elif environment is not None:
+        return environment.value
+    else:
+        raise Exception("Please pass in either base_url or environment to construct the client")

package/planqk/api/sdk/core/__init__.py

@@ -0,0 +1,52 @@
+# This file was auto-generated by Fern from our API Definition.
+
+# isort: skip_file
+
+from .api_error import ApiError
+from .client_wrapper import AsyncClientWrapper, BaseClientWrapper, SyncClientWrapper
+from .datetime_utils import serialize_datetime
+from .file import File, convert_file_dict_to_httpx_tuples, with_content_type
+from .http_client import AsyncHttpClient, HttpClient
+from .http_response import AsyncHttpResponse, HttpResponse
+from .jsonable_encoder import jsonable_encoder
+from .pydantic_utilities import (
+    IS_PYDANTIC_V2,
+    UniversalBaseModel,
+    UniversalRootModel,
+    parse_obj_as,
+    universal_field_validator,
+    universal_root_validator,
+    update_forward_refs,
+)
+from .query_encoder import encode_query
+from .remove_none_from_dict import remove_none_from_dict
+from .request_options import RequestOptions
+from .serialization import FieldMetadata, convert_and_respect_annotation_metadata
+
+__all__ = [
+    "ApiError",
+    "AsyncClientWrapper",
+    "AsyncHttpClient",
+    "AsyncHttpResponse",
+    "BaseClientWrapper",
+    "FieldMetadata",
+    "File",
+    "HttpClient",
+    "HttpResponse",
+    "IS_PYDANTIC_V2",
+    "RequestOptions",
+    "SyncClientWrapper",
+    "UniversalBaseModel",
+    "UniversalRootModel",
+    "convert_and_respect_annotation_metadata",
+    "convert_file_dict_to_httpx_tuples",
+    "encode_query",
+    "jsonable_encoder",
+    "parse_obj_as",
+    "remove_none_from_dict",
+    "serialize_datetime",
+    "universal_field_validator",
+    "universal_root_validator",
+    "update_forward_refs",
+    "with_content_type",
+]

package/planqk/api/sdk/core/api_error.py

@@ -0,0 +1,23 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from typing import Any, Dict, Optional
+
+
+class ApiError(Exception):
+    headers: Optional[Dict[str, str]]
+    status_code: Optional[int]
+    body: Any
+
+    def __init__(
+        self,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        status_code: Optional[int] = None,
+        body: Any = None,
+    ) -> None:
+        self.headers = headers
+        self.status_code = status_code
+        self.body = body
+
+    def __str__(self) -> str:
+        return f"headers: {self.headers}, status_code: {self.status_code}, body: {self.body}"