Metadata-Version: 2.4
Name: perceptic-core-client
Version: 0.6.0
Summary: Python client for Perceptic Core
Author-email: Your Name <you@example.com>
License: Proprietary
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: requests; extra == "dev"

# 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:**
    ```bash
    # 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
    # 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`).
    ```bash
    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`).

    ```ini
    [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:**
    ```bash
    pip install perceptic-core-client
    ```
    *(Specify a version if needed: `pip install perceptic-core-client==<version>`)*

## Usage Example

```python
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")
