> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connector SDK (Python)

> Python connector authoring contracts and reference implementations: the Connector protocol, MockConnector, credential handles, and four enterprise-shaped reference mocks.

<Info>
  **\[AVAILABLE]**, **published**, [`parmana-connector-sdk` on
  PyPI](https://pypi.org/project/parmana-connector-sdk/0.1.0/). Real, public,
  installable with a plain `pip install parmana-connector-sdk`. The Python
  counterpart to [`@parmana/connector-sdk`](/reference/connector-sdk) — same
  contract, same design, idiomatic Python: synchronous (not `async`/`await`,
  matching the [Python client SDK](/sdks/python)'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.
</Info>

## 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](/integrations/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

```bash theme={null}
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](/integrations/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

```python theme={null}
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](https://pypi.org/project/parmana-connector-sdk/0.1.0/).

## Next

<CardGroup cols={2}>
  <Card title="Connector SDK (TypeScript)" icon="js" href="/reference/connector-sdk">
    The identical contract, published to npm, for TypeScript/Node connector
    authors.
  </Card>

  <Card title="Connector Development Guide" icon="plug" href="/integrations/connector-development-guide">
    Implement, test, and see what reaching the default server actually requires.
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python">
    The client SDK for calling Parmana's own API — a different package, for a
    different audience (callers, not connector authors).
  </Card>
</CardGroup>