perceptic-core-client 0.6.0

Python client for Perceptic Core

Perceptic Core API - Python Client Package

This directory contains the source code, build configuration, and generation scripts for the perceptic-core-client Python package. This package provides a client library for interacting with the Perceptic Core API.

Note: The actual client code within src/perceptic_core_client/ is automatically generated during the build process from the OpenAPI specification located in the parent perceptic-core-server project (../openapi/) and is not checked into Git.

Generation Process

The Python client code is generated using openapi-generator-cli based on the OpenAPI specification found at ../openapi/openapi.yaml (relative to this directory).

This generation happens automatically as part of the package build process (python -m build) defined in setup.py.

Requirements for Building:

• Python >= 3.9
• setuptools, wheel, build Python packages
• Java Runtime Environment (JRE)
• openapi-generator-cli (Installable via npm: npm install -g @openapitools/openapi-generator-cli)
• The PACKAGE_VERSION environment variable must be set to the desired version string (e.g., 0.5.0) before building.
• The OpenAPI spec file (../openapi/openapi.yaml or .json) must exist, typically generated by the parent Quarkus project's build.

Building Manually (for Development/Testing)

While the primary build and publish mechanism is via GitHub Actions, you can build the package locally for testing:

1. Navigate to this directory (perceptic-core-python-client).
2. Set up environment:

   # Create/activate a virtual environment
   python -m venv .venv
   source .venv/bin/activate # Linux/macOS
   # .venv\Scripts\activate # Windows
   
   # Install build and dev dependencies
   pip install -e ".[dev]"
   

3. Set required environment variables:

   # Bash/Zsh
   export PACKAGE_VERSION="<target-version>" # e.g., 0.5.1.dev0
   # OPENAPI_SPEC_PATH is determined automatically by setup.py now
   
   # Windows CMD
   # set PACKAGE_VERSION=<target-version>
   
   # Windows PowerShell
   # $env:PACKAGE_VERSION = "<target-version>"
   

4. Run build: Ensure the spec file exists at ../openapi/openapi.yaml (or .json).

   python -m build
   

   This will generate the client code in src/ and create distribution files (.whl, .tar.gz) in the dist/ directory.

Publishing

This package is automatically published to GitHub Packages via the GitHub Actions workflow defined in .github/workflows/publish-python-client.yml in the root of the perceptic-core-server repository. Publishing is triggered when a Git tag (e.g., 0.5.0, 1.0.0) is pushed to the repository.

Installation (from GitHub Packages)

To use this client in your Python projects, install it from GitHub Packages.

1. Configure pip: You need to tell pip where to find the package. Add the following lines to your pip.conf / pip.ini file, or configure it using environment variables/command-line arguments. Replace <YOUR_GITHUB_OWNER> with the GitHub username or organization that owns the repository (e.g., perceptic-core).

   [global]
   extra-index-url = [https://pypi.pkg.github.com/](https://pypi.pkg.github.com/)<YOUR_GITHUB_OWNER>/
   

   Alternatively, use --extra-index-url on the command line.

2. Authentication (if repository is private): You may need to authenticate pip to GitHub Packages. The recommended method is using a Personal Access Token (PAT) with the read:packages scope. Configure pip to use your GitHub username and the PAT. Refer to GitHub documentation for the latest authentication methods.

3. Install the package:

   pip install perceptic-core-client
   

   (Specify a version if needed: pip install perceptic-core-client==<version>)

Usage Example

import os
from perceptic_core_client import ApiClient, Configuration, ApiException
from perceptic_core_client.api.user_resource_api import UserResourceApi # Example API
from pprint import pprint

# --- Configuration ---
# Replace with the actual host of your Perceptic Core API instance
API_HOST = os.environ.get("PERCEPTIC_CORE_HOST", "http://localhost:8080")

# Obtain your authentication token separately
# (e.g., from Keycloak, environment variable, another library)
ACCESS_TOKEN = os.environ.get("PERCEPTIC_CORE_TOKEN")

if not ACCESS_TOKEN:
    print("Error: PERCEPTIC_CORE_TOKEN environment variable not set.")
    exit(1)
# ---

print(f"Configuring client for host: {API_HOST}")

# Configure API client
configuration = Configuration(host=API_HOST)
configuration.access_token = ACCESS_TOKEN # Set token for potential internal use

# Initialize API client
api_client = ApiClient(configuration=configuration)

# Explicitly set the Authorization header (recommended)
api_client.set_default_header("Authorization", f"Bearer {ACCESS_TOKEN}")

# --- Example API Call: Get current user info ---
user_api = UserResourceApi(api_client=api_client)

try:
    print("Calling /api/v1/users/me...")
    me_response = user_api.api_v1_users_me_get()
    print("API call successful. User Info:")
    pprint(me_response.to_dict()) # Use to_dict() for cleaner printing

except ApiException as e:
    print(f"API Exception calling UserResourceApi->api_v1_users_me_get: {e}\n")
    # You can inspect e.status, e.reason, e.body, e.headers
except Exception as e:
    print(f"An unexpected error occurred: {e}\n")

# --- Example: Create a Connection (replace with actual details) ---
# from perceptic_core_client.api.connection_resource_api import ConnectionResourceApi
# from perceptic_core_client.models import (
#     CreateConnectionRequest,
#     ConnectionSettingsApiDto,
#     S3ConnectionSettingsApiDto # Example setting type
# )
#
# connection_api = ConnectionResourceApi(api_client=api_client)
#
# try:
#     print("Attempting to create a connection...")
#     connection_request = CreateConnectionRequest(
#         name="my-s3-connection",
#         description="Connection to my S3 bucket",
#         settings=ConnectionSettingsApiDto(
#             actual_instance=S3ConnectionSettingsApiDto(
#                 type="v1/s3",
#                 region="us-east-1", # Replace with actual values
#                 access_key="YOUR_ACCESS_KEY",
#                 secret_key="YOUR_SECRET_KEY",
#                 url="[https://s3.amazonaws.com](https://s3.amazonaws.com)" # Optional endpoint URL
#             )
#         )
#     )
#     create_response = connection_api.api_v1_connections_post(connection_request)
#     print("Connection created successfully:")
#     pprint(create_response.to_dict())
#
# except ApiException as e:
#     print(f"API Exception creating connection: {e}\n")
# except Exception as e:
#     print(f"An unexpected error occurred: {e}\n")