Metadata-Version: 2.4
Name: polaris-python
Version: 0.0.1.dev4
Summary: Python SDK for Polaris service governance.
Author-email: evelynwei <evelynwei@tencent.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/polaris-contrib/polaris-python
Project-URL: Repository, https://github.com/polaris-contrib/polaris-python
Project-URL: Issues, https://github.com/polaris-contrib/polaris-python/issues
Project-URL: Documentation, https://github.com/polaris-contrib/polaris-python#readme
Keywords: polaris,service-governance,service-discovery,service-mesh,grpc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio>=1.84.0
Requires-Dist: protobuf<8,>=7.35.1
Requires-Dist: polarismesh-specification==1.9.0.dev4
Requires-Dist: PyYAML<7,>=6.0.2
Requires-Dist: psutil<8,>=7.0
Requires-Dist: prometheus-client<1,>=0.21
Requires-Dist: aiohttp<4,>=3.11
Dynamic: license-file

# Polaris Python SDK

[中文](README-zh.md)

Python client for Polaris service discovery, registration, service governance,
AI Registry resources, observability, and TLS.

The distribution is `polaris-python`; import it as `polaris`.

The categorized documentation index is [docs/README.md](docs/README.md).

## Install

Requires Python 3.12+.

```bash
uv sync --group dev --locked
uv run pytest
```

The project uses a `src` layout. `uv sync` installs `src/polaris/` in editable mode,
so source changes take effect immediately.

See [Version and release](docs/project/version-release.md) for release and development package publishing.

## Configure

```yaml
global:
  serverConnector:
    addresses:
      - ${POLARIS_SERVER_ADDRESS:127.0.0.1:8091}
    token: ${POLARIS_TOKEN:}
```

Use `Configuration.from_file()` for YAML, `Configuration.from_env()` for environment
variables, or `Configuration.from_dict()` for code-owned mappings. Python durations
are integer milliseconds; YAML also accepts values such as `500ms`, `1s`, and `1m30s`.

See:

- [Configuration parameters](docs/config/configuration-reference.md)
- [Minimal YAML example](docs/config/polaris.yaml)
- [Environment variables and precedence](docs/config/environment-variables.md)
- [Minimal file example](examples/sdkconfig/file/polaris.yaml)

## Context

Each `SDKContext` owns its configuration snapshot, client ID, plugins, connections,
caches, tasks, and logs. Reuse one context for APIs that should share that client.

```python
from polaris import Configuration, init_context_by_config

config = Configuration()
config.set_default()
config.get_global().get_server_connector().addresses = ["127.0.0.1:8091"]

context = init_context_by_config(config)
try:
    ...
finally:
    context.destroy()
```

API calls after `destroy()` raise `SDKError`.

## Provider

`ProviderAPI` supports synchronous methods and `async_` counterparts.
`register_instance()` enables SDK-managed heartbeats by default.

```python
from polaris.pkg.model.server import InstanceRegisterRequest

response = provider.register_instance(InstanceRegisterRequest(
    service="demo",
    service_token="service-token",
    namespace="default",
    host="127.0.0.1",
    port=8080,
    ttl=5,
))
```

The service token authorizes register, heartbeat, and deregister. It is different
from `POLARIS_TOKEN`, which authenticates the SDK connection.

Automatic re-registration runs after two consecutive `400202` responses and
`provider.minRegisterInterval`.
Deregistration stops heartbeat tasks before the RPC. Context destruction does not
implicitly deregister instances.

## Consumer

Reuse one `ConsumerAPI` per context. Synchronous calls are `get_one_instance()`,
`get_instances()`, `get_all_instances()`, `get_healthy_instances()`, and
`get_services()`; query methods have `async_` counterparts. `watch_service()` pins a
loaded resource and forwards cache lifecycle events; `unwatch_service()` releases it.

```python
from polaris.pkg.model.service import GetOneInstanceRequest

instance = consumer.get_one_instance(GetOneInstanceRequest(
    namespace="default",
    service="demo",
))
```

After invoking the downstream service, report the result with
`update_service_call_result()` or `async_update_service_call_result()`.

Local cache behavior, idle eviction, disk retries, and restart recovery are covered by
the examples and [configuration reference](docs/config/configuration-reference.md).

## AI Registry

- MCP, A2A, and LangGraph use ordinary `Instance` registration and discovery.
- Service contracts use `report_service_contract()` and `get_service_contract()`.
- `SkillAPI` provides read-only get/list/download operations over an independent connector.
- Skill downloads can fall back to versioned local backups after network errors.

See [AI Registry APIs](docs/guides/ai-registry.md) and:

- [MCP example](examples/mcp/README.md)
- [A2A example](examples/a2a/README.md)
- [Skill example](examples/skill/README.md)

## Plugins

| Kind | Names |
| --- | --- |
| Server connector | `grpc` |
| Local cache | `inmemory`, `file` |
| Service router | `isolatedRouter`, `metadataRouter`, `recoverRouter` |
| Load balancer | `weightedRandom`, `random` |
| Circuit breaker | `composite` |
| Stat reporter | `prometheus` (`pushgateway` chain alias for push mode) |
| Event reporter | `pushgateway` |

Legacy names `wr` and `err_count` normalize to `weightedRandom` and `composite`.
Remote lossless rules are supported. Remote circuit-breaking, routing, rate-limiting and
configuration rules remain disabled, and active health detection is not enabled.

## Observability And Security

Public cloud currently uses Pushgateway as the default supported export path.
Prometheus pull remains available for self-hosted or custom scraping setups.
See [Observability](docs/guides/observability.md).

Each context has an isolated event center for implemented instance-cache and local
circuit-breaker events, with an optional Pushgateway reporter. See
[Events](docs/guides/events.md).

The registry and Skill connectors support independent TLS and mTLS certificates.
Invalid certificate configuration fails startup instead of falling back to plaintext.
See [TLS](docs/guides/tls.md).

## Examples

From the repository root, Quickstart reads its adjacent `polaris.yaml`:

```bash
export POLARIS_SERVER_ADDRESS=127.0.0.1:8091
export POLARIS_TOKEN=
make -C examples run DEMO=quickstart/provider ARGS='--service-token "" --port 0'
# Another terminal with the same environment
make -C examples run DEMO=quickstart/consumer ARGS='--port 18080'
```

`--service-token` is required; an empty string works when service authentication is
disabled. Runs stay in the foreground; use separate terminals or `&`.

```bash
make -C examples logs ARGS='--only quickstart --latest --tail 30'
make -C examples cleanup ARGS='--only quickstart --dry-run'
make -C examples cleanup ARGS='--only quickstart'
```

See [examples/README.md](examples/README.md) for demos, Makefiles and log/cleanup options.

Verification and test artifacts belong to `integration/`:

```bash
./integration/verify.sh --only quickstart
./integration/verify_e2e.sh --only quickstart
```

See the [integration guide](integration/README.md) and
[quickstart tests](integration/scenarios/quickstart/test.md) for checks and test artifacts.

## License

[BSD 3-Clause](LICENSE)
