polaris-python 0.0.1.dev3__tar.gz

polaris_python-0.0.1.dev3/LICENSE

@@ -0,0 +1,18 @@
+Tencent is pleased to support the open source community by making polaris-python available.
+
+Copyright (C) 2021 Tencent. All rights reserved.
+
+A polaris-python is licensed under the BSD 3-Clause License. A copy of the BSD 3-Clause License is included in this file.
+
+
+Terms of  BSD 3-Clause License
+---------------------------------------------------
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

polaris_python-0.0.1.dev3/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: polaris-python
+Version: 0.0.1.dev3
+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
+
+Run all offline verifications:
+
+```bash
+./examples/verify_all.sh
+```
+
+Run or inspect a single demo:
+
+```bash
+cd examples/quickstart
+./run.sh --help
+./verify.sh
+./logs.sh --latest --tail 30
+./cleanup.sh --force
+```
+
+Start with [examples/README.md](examples/README.md). Real registry examples require
+`POLARIS_E2E=1`.
+
+## License
+
+[BSD 3-Clause](LICENSE)

polaris_python-0.0.1.dev3/README.md

@@ -0,0 +1,182 @@
+# 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
+
+Run all offline verifications:
+
+```bash
+./examples/verify_all.sh
+```
+
+Run or inspect a single demo:
+
+```bash
+cd examples/quickstart
+./run.sh --help
+./verify.sh
+./logs.sh --latest --tail 30
+./cleanup.sh --force
+```
+
+Start with [examples/README.md](examples/README.md). Real registry examples require
+`POLARIS_E2E=1`.
+
+## License
+
+[BSD 3-Clause](LICENSE)

polaris_python-0.0.1.dev3/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "polaris-python"
+dynamic = ["version"]
+description = "Python SDK for Polaris service governance."
+readme = "README.md"
+license = "BSD-3-Clause"
+authors = [{ name = "evelynwei", email = "evelynwei@tencent.com" }]
+keywords = ["polaris", "service-governance", "service-discovery", "service-mesh", "grpc"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "grpcio>=1.84.0",
+    "protobuf>=7.35.1,<8",
+    "polarismesh-specification==1.9.0.dev4",
+    "PyYAML>=6.0.2,<7",
+    "psutil>=7.0,<8",
+    "prometheus-client>=0.21,<1",
+    "aiohttp>=3.11,<4",
+]
+
+[project.urls]
+Homepage = "https://github.com/polaris-contrib/polaris-python"
+Repository = "https://github.com/polaris-contrib/polaris-python"
+Issues = "https://github.com/polaris-contrib/polaris-python/issues"
+Documentation = "https://github.com/polaris-contrib/polaris-python#readme"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3,<9",
+    "pytest-asyncio>=0.24,<0.25",
+]
+
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = { find = { where = ["src"] } }
+
+[tool.setuptools.dynamic]
+version = { attr = "polaris._version.__version__" }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "e2e: tests requiring a running Polaris service",
+]

polaris_python-0.0.1.dev3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

polaris_python-0.0.1.dev3/src/polaris/__init__.py

@@ -0,0 +1,74 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+from polaris.api.config import (
+    SDKContext,
+    init_context,
+    init_context_by_config,
+    init_context_by_file,
+    init_context_by_stream,
+)
+from polaris.api.consumer import ConsumerAPI, ServiceWatch, create_consumer_by_config, create_consumer_by_file
+from polaris.api.log import LogOptions
+from polaris.api.lossless import LosslessAPI
+from polaris.api.provider import ProviderAPI, create_provider_by_config, create_provider_by_file
+from polaris.api.skill import (
+    SkillAPI,
+    create_skill_by_config,
+    create_skill_by_context,
+    create_skill_by_default_config_file,
+    create_skill_by_file,
+)
+from polaris.pkg.model.service import Instance
+from polaris.pkg.model.event import EventCenter, SDKEvent, SDKEventName, SDKEventType
+from polaris.pkg.model.lossless import InstanceProperties, LosslessActionProvider, LosslessInstance, RegisterStatus
+from polaris.pkg.config.api import Configuration
+from polaris.pkg.model.error import ErrorCode, SDKError
+from polaris._version import __version__
+
+__all__ = [
+    "Configuration",
+    "ConsumerAPI",
+    "ServiceWatch",
+    "ErrorCode",
+    "LogOptions",
+    "LosslessAPI",
+    "LosslessActionProvider",
+    "LosslessInstance",
+    "InstanceProperties",
+    "ProviderAPI",
+    "Instance",
+    "EventCenter",
+    "SDKEvent",
+    "SDKEventName",
+    "SDKEventType",
+    "SkillAPI",
+    "RegisterStatus",
+    "create_skill_by_config",
+    "create_skill_by_context",
+    "create_skill_by_default_config_file",
+    "create_skill_by_file",
+    "SDKContext",
+    "SDKError",
+    "create_consumer_by_config",
+    "create_consumer_by_file",
+    "create_provider_by_config",
+    "create_provider_by_file",
+    "init_context_by_config",
+    "init_context_by_file",
+    "init_context",
+    "init_context_by_stream",
+    "__version__",
+]

polaris_python-0.0.1.dev3/src/polaris/_version.py

@@ -0,0 +1,16 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+__version__ = "0.0.1.dev3"

polaris_python-0.0.1.dev3/src/polaris/api/__init__.py

@@ -0,0 +1,55 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+"""Public Polaris SDK APIs."""
+
+from polaris.api.config import (
+    SDKContext,
+    init_context,
+    init_context_by_config,
+    init_context_by_file,
+    init_context_by_stream,
+)
+from polaris.api.consumer import ConsumerAPI, ServiceWatch, create_consumer_by_config, create_consumer_by_file
+from polaris.api.log import LogOptions
+from polaris.api.provider import ProviderAPI, create_provider_by_config, create_provider_by_file
+from polaris.api.skill import (
+    SkillAPI,
+    create_skill_by_config,
+    create_skill_by_context,
+    create_skill_by_default_config_file,
+    create_skill_by_file,
+)
+
+__all__ = [
+    "ConsumerAPI",
+    "ServiceWatch",
+    "LogOptions",
+    "ProviderAPI",
+    "SkillAPI",
+    "SDKContext",
+    "create_consumer_by_config",
+    "create_consumer_by_file",
+    "create_provider_by_config",
+    "create_provider_by_file",
+    "create_skill_by_config",
+    "create_skill_by_context",
+    "create_skill_by_default_config_file",
+    "create_skill_by_file",
+    "init_context_by_config",
+    "init_context_by_file",
+    "init_context",
+    "init_context_by_stream",
+]