Connector SDK (Python)

[AVAILABLE], published, parmana-connector-sdk on PyPI. Real, public, installable with a plain pip install parmana-connector-sdk. The Python counterpart to @parmana/connector-sdk — same contract, same design, idiomatic Python: synchronous (not async/await, matching the Python client SDK’s own convention) and typing.Protocol-based instead of interfaces, so a class only needs to match the shape (connector_id, capabilities, execute), not subclass anything.

Purpose

The contract every connector implements (Connector), one hermetic reference implementation for testing (MockConnector), the credential-handle seam (CredentialProvider and its two implementations), and four enterprise-shaped reference mocks. This package intentionally ships no HTTP-calling implementation — see Connector Development Guide for the rationale (identical for both languages) and how little code a real HTTP-based Connector takes to write directly against the contract.

Install

pip install parmana-connector-sdk

Key exports

The contract

Export	Signature
`Connector` (protocol)	`{ connector_id, capabilities, execute(request: ConnectorRequest, context: ConnectorExecutionContext) -> ConnectorResponse }`
`ConnectorRequest`	`{ capability, business_transaction_id, action, target, parameters }` — exactly the authorized operation, never re-derived
`ConnectorExecutionContext`	`{ credential, timeout_ms, requested_at }` — `credential` is an opaque, already-resolved `CredentialHandle`
`ConnectorResponse`	`{ success, metadata }`
`connector_capabilities(list[str])`	Validates each string as `namespace:verb`, raises at construction on a malformed one, not at execution time
`ConnectorFactory` (protocol)	Construction contract a connector factory can implement. No concrete factory ships.
`ConnectorMetadata`, `ConnectorVersion`, `ConnectorHealth`	Registration-time descriptive metadata shapes (dataclasses)

Reference implementation

Export	Purpose
`MockConnector`	Scripted responses (`MockConnectorScript(respond=...)`) or failure injection (`MockConnectorScript(fail_with=...)`) for hermetic testing. `.invocations` records every request received. The only implementation this package ships — see below for why.
`create_sap_connector`, `create_oracle_connector`, `create_workday_connector`, `create_salesforce_connector` (+ matching `*Metadata`)	Reference mocks only, from `parmana_connector_sdk.connectors.*`. Each is a thin `MockConnector` factory under an enterprise-shaped `connector_id` and one realistic capability. None calls a real SAP, Oracle, Workday, or Salesforce system — read them as a template for your own connector’s shape, not as integrations.

No HTTP-calling implementation ships from this package, deliberately — for the identical reason as the TypeScript package: the reference implementation this repository maintains internally enforces that only its own Execution Gateway performs real I/O for a connector. That invariant only constrains this repository’s own tree; it does not constrain a connector you write in your own codebase. See Connector Development Guide for how short a real HTTP-based Connector is to write directly against the contract (the guide’s example is TypeScript; the shape is identical in Python — see this package’s own README for a Python version).

Credential handles

Export	Purpose
`CredentialHandle`	Opaque resolved credential material: `{ provider_id, credential_id, value }`. `value` is never logged or serialized into a Trust Record.
`CredentialProvider` (protocol)	`{ provider_id, resolve(connector_id) -> CredentialHandle }`
`EnvironmentCredentialProvider`	Resolves from a mapped environment variable
`StaticCredentialProvider`	In-memory map — tests and local dev only
`brand_credential_handle`, `is_credential_handle`	Marks/checks that a handle was produced by a real `CredentialProvider`, not a raw value supplied directly

A Connector never resolves its own credentials — resolution happens upstream, inside the Execution Gateway, before a Connector is ever invoked.

Minimal example

from parmana_connector_sdk import MockConnector, MockConnectorOptions, MockConnectorScript, ConnectorResponse, connector_capabilities

mock = MockConnector(
    MockConnectorOptions(
        connector_id="example",
        capabilities=connector_capabilities(["crm:read"]),
        script=MockConnectorScript(
            respond=lambda request, context: ConnectorResponse(
                success=True, metadata={"record_id": "example-1"}
            )
        ),
    )
)

Full worked example, including a real HTTP-based Connector written directly against the contract: this package’s own README.

Connector SDK (TypeScript)

The identical contract, published to npm, for TypeScript/Node connector authors.

Connector Development Guide

Implement, test, and see what reaching the default server actually requires.

Python SDK

The client SDK for calling Parmana’s own API — a different package, for a different audience (callers, not connector authors).

Get Started

Core Concepts

Guides

SDKs

REST API

Security & Deployment

Integrations

Tutorials

Advanced

Support

Changelog

Connector SDK (Python)

Purpose

Install

Key exports

The contract

Reference implementation

Credential handles

Minimal example

Next

Connector SDK (TypeScript)

Connector Development Guide

Python SDK

​Purpose

​Install

​Key exports

​The contract

​Reference implementation

​Credential handles

​Minimal example

​Next

Connector SDK (TypeScript)

Connector Development Guide

Python SDK

Purpose

Install

Key exports

The contract

Reference implementation

Credential handles

Minimal example

Next