Nacos Python SDK

Warnings

• breaking `nacos-sdk-python` 3.x clients are designed to be compatible with Nacos server 3.x and later. Older Nacos server versions (e.g., 0.x, 1.x, or 2.x) are generally not compatible with 3.x clients, and the Nacos server 3.2.0 removed legacy v1/v2 HTTP APIs.
  Fix: Ensure your Nacos server instance is running version 3.x or above when using `nacos-sdk-python` 3.x. Consult the Nacos official documentation for server upgrade guides.
• breaking The Nacos Python SDK 3.x introduced 'v2 API support', implying changes from previous API patterns, especially for configuration and service management. Direct imports from `nacos` vs. `v2.nacos` differentiate between simplified usage and explicit V2 API features.
  Fix: Review the official documentation and migration guides for `nacos-sdk-python` 3.x to understand API changes, particularly when migrating from 2.x. Use `from v2.nacos import ...` for explicit V2 API interactions or advanced configurations like `ClientConfigBuilder`.
• gotcha For production deployments, always configure `NacosClient` with `access_key` and `secret_key` (or `username`/`password`) for authentication with the Nacos server. Relying solely on a public namespace without authentication can lead to security vulnerabilities.
  Fix: Pass `ak` and `sk` parameters during `NacosClient` initialization, ideally sourced from secure environment variables or a secret management system. E.g., `client = nacos.NacosClient(..., ak=os.environ.get('NACOS_ACCESS_KEY'), sk=os.environ.get('NACOS_SECRET_KEY'))`.
• gotcha When configuring the Nacos server, modifying `nacos.server.contextPath` from its default value can sometimes cause service registration failures or other communication issues with the Python client.
  Fix: If experiencing registration issues, verify that `nacos.server.contextPath` is set correctly on your Nacos server, or revert it to its default if custom paths are not strictly necessary.

Install

• pip install nacos-sdk-python Install latest version

Imports

• NacosClient

  import nacos
  client = nacos.NacosClient(...)

  This is the primary client for general configuration and naming services in a simplified manner.
• NacosConfigService

  from v2.nacos import NacosConfigService, ClientConfigBuilder

  For explicit use of the Nacos V2 API for configuration management, especially with `ClientConfigBuilder` for advanced settings, import from `v2.nacos`. The direct `nacos.client` path for these V2-specific services might be incorrect or lead to older API versions.
• NacosNamingService

  from v2.nacos import NacosNamingService, ClientConfigBuilder

  For explicit use of the Nacos V2 API for naming and service discovery, import from `v2.nacos`.

Quickstart

This quickstart demonstrates how to initialize the `NacosClient` and perform basic configuration publishing/retrieval and service registration/discovery. It's recommended to configure Nacos server addresses, namespace, and authentication credentials via environment variables for flexible deployment. For Nacos server 3.x and above, ensure the Nacos server is running and accessible.

import os
import nacos

# Configure Nacos server address and optional namespace/auth via environment variables
SERVER_ADDRESSES = os.environ.get('NACOS_SERVER_ADDR', '127.0.0.1:8848')
NAMESPACE_ID = os.environ.get('NACOS_NAMESPACE_ID', '') # e.g., 'public'
ACCESS_KEY = os.environ.get('NACOS_ACCESS_KEY', '')
SECRET_KEY = os.environ.get('NACOS_SECRET_KEY', '')

# Initialize Nacos Client
# For production, ensure access_key and secret_key are provided for authentication.
client = nacos.NacosClient(
    SERVER_ADDRESSES,
    namespace=NAMESPACE_ID,
    ak=ACCESS_KEY,
    sk=SECRET_KEY
)

# --- Configuration Service Example ---
data_id = "example_config"
group = "DEFAULT_GROUP"

# Publish a configuration
success = client.publish_config(data_id, group, "Hello from nacos-sdk-python!")
print(f"Published config: {success}")

# Get a configuration
config_content = client.get_config(data_id, group)
print(f"Retrieved config: {config_content}")

# --- Naming Service Example ---
service_name = "example_service"
service_ip = "127.0.0.1"
service_port = 8080

# Register an instance
registered = client.add_naming_instance(service_name, service_ip, service_port)
print(f"Registered service instance: {registered}")

# Query instances
instances = client.get_naming_instance(service_name, group_name=group)
print(f"Discovered instances: {instances}")

# Deregister an instance
deregistered = client.remove_naming_instance(service_name, service_ip, service_port)
print(f"Deregistered service instance: {deregistered}")