0
# Nacos SDK Python
1
2
A comprehensive Python SDK for the Nacos service discovery and configuration management platform. This SDK provides both synchronous (v1) and asynchronous (v2) APIs for dynamic service discovery, configuration management, and service registration with Nacos clusters.
3
4
## Package Information
5
6
- **Package Name**: nacos-sdk-python
7
- **Language**: Python
8
- **Installation**: `pip install nacos-sdk-python`
9
- **Minimum Python Version**: Python 3.7+
10
11
## Core Imports
12
13
### Legacy V1 API (Synchronous)
14
15
```python
16
from nacos import NacosClient, NacosException, DEFAULTS, DEFAULT_GROUP_NAME
17
```
18
19
### Modern V2 API (Asynchronous)
20
21
```python
22
from v2.nacos import (
23
ClientConfig, ClientConfigBuilder,
24
NacosConfigService, NacosNamingService,
25
NacosException,
26
ConfigParam,
27
Instance, RegisterInstanceParam, DeregisterInstanceParam,
28
ListInstanceParam, SubscribeServiceParam
29
)
30
```
31
32
## Basic Usage
33
34
### V1 API - Simple Configuration Management
35
36
```python
37
from nacos import NacosClient
38
39
# Create client
40
client = NacosClient(
41
server_addresses="127.0.0.1:8848",
42
namespace="public",
43
username="nacos",
44
password="nacos"
45
)
46
47
# Get configuration
48
config = client.get_config("test-config", "DEFAULT_GROUP")
49
print(config)
50
51
# Publish configuration
52
client.publish_config("test-config", "DEFAULT_GROUP", "config content")
53
54
# Add configuration listener
55
def config_listener(args):
56
print(f"Configuration changed: {args}")
57
58
client.add_config_watcher("test-config", "DEFAULT_GROUP", config_listener)
59
```
60
61
### V2 API - Advanced Async Operations
62
63
```python
64
import asyncio
65
from v2.nacos import ClientConfig, NacosConfigService, ConfigParam
66
67
async def main():
68
# Create client configuration
69
client_config = ClientConfig(
70
server_addresses="127.0.0.1:8848",
71
namespace_id="public",
72
username="nacos",
73
password="nacos"
74
)
75
76
# Create config service
77
config_service = await NacosConfigService.create_config_service(client_config)
78
79
# Get configuration
80
param = ConfigParam(dataId="test-config", group="DEFAULT_GROUP")
81
config = await config_service.get_config(param)
82
print(config)
83
84
# Publish configuration
85
param.content = "new config content"
86
await config_service.publish_config(param)
87
88
# Shutdown
89
await config_service.shutdown()
90
91
asyncio.run(main())
92
```
93
94
## Architecture
95
96
Nacos SDK Python provides a dual-architecture approach:
97
98
- **V1 API (Legacy)**: Synchronous client with threading-based operations, suitable for simple use cases and backward compatibility
99
- **V2 API (Modern)**: Asynchronous client with GRPC support, advanced configuration options, and comprehensive data models
100
101
The V2 API introduces:
102
- **Configuration Service**: Async operations for configuration management with encryption, filtering, and caching
103
- **Naming Service**: Async operations for service discovery, registration, and health monitoring
104
- **Enhanced Models**: Pydantic-based data models for type safety and validation
105
- **GRPC Support**: High-performance communication protocol with connection pooling
106
- **Advanced Features**: KMS encryption, TLS security, batch operations, and comprehensive error handling
107
108
## Capabilities
109
110
### V1 Configuration Management (Synchronous)
111
112
Legacy synchronous API for configuration operations including get, publish, remove, and watch operations with basic authentication and namespace support.
113
114
```python { .api }
115
class NacosClient:
116
def __init__(self, server_addresses=None, endpoint=None, namespace=None,
117
ak=None, sk=None, username=None, password=None, **kwargs): ...
118
def get_config(self, data_id: str, group: str, timeout=None, no_snapshot=None) -> str: ...
119
def publish_config(self, data_id: str, group: str, content: str,
120
app_name=None, config_type=None, timeout=None) -> bool: ...
121
def remove_config(self, data_id: str, group: str, timeout=None) -> bool: ...
122
def add_config_watcher(self, data_id: str, group: str, cb, content=None): ...
123
def remove_config_watcher(self, data_id: str, group: str, cb, remove_all=False): ...
124
```
125
126
[V1 Configuration Management](./v1-config.md)
127
128
### V1 Service Discovery (Synchronous)
129
130
Legacy synchronous API for service registration, discovery, health checks, and subscription operations with basic clustering support.
131
132
```python { .api }
133
class NacosClient:
134
def add_naming_instance(self, service_name: str, ip: str, port: int,
135
cluster_name=None, weight=1.0, metadata=None, **kwargs) -> bool: ...
136
def remove_naming_instance(self, service_name: str, ip: str, port: int,
137
cluster_name=None, ephemeral=True, **kwargs) -> bool: ...
138
def list_naming_instance(self, service_name: str, clusters=None, namespace_id=None,
139
group_name=None, healthy_only=False) -> list: ...
140
def send_heartbeat(self, service_name: str, ip: str, port: int,
141
cluster_name=None, weight=1.0, metadata=None, ephemeral=True, **kwargs) -> dict: ...
142
def subscribe(self, service_name: str, listener_name: str, listener_fn,
143
cluster_names=None, **kwargs): ...
144
def unsubscribe(self, service_name: str, listener_name=None): ...
145
```
146
147
[V1 Service Discovery](./v1-naming.md)
148
149
### V2 Configuration Management (Asynchronous)
150
151
Modern asynchronous API for configuration operations with encryption, filtering, caching, and advanced error handling.
152
153
```python { .api }
154
class NacosConfigService:
155
@staticmethod
156
async def create_config_service(client_config: ClientConfig) -> 'NacosConfigService': ...
157
async def get_config(self, param: ConfigParam) -> str: ...
158
async def publish_config(self, param: ConfigParam) -> bool: ...
159
async def remove_config(self, param: ConfigParam): ...
160
async def add_listener(self, data_id: str, group: str, listener: Callable) -> None: ...
161
async def remove_listener(self, data_id: str, group: str, listener: Callable): ...
162
async def server_health(self) -> bool: ...
163
async def shutdown(self): ...
164
```
165
166
[V2 Configuration Management](./v2-config.md)
167
168
### V2 Service Discovery (Asynchronous)
169
170
Modern asynchronous API for service registration, discovery, batch operations, health monitoring, and subscription management with comprehensive data models.
171
172
```python { .api }
173
class NacosNamingService:
174
@staticmethod
175
async def create_naming_service(client_config: ClientConfig) -> 'NacosNamingService': ...
176
async def register_instance(self, request: RegisterInstanceParam) -> bool: ...
177
async def batch_register_instances(self, request: BatchRegisterInstanceParam) -> bool: ...
178
async def deregister_instance(self, request: DeregisterInstanceParam) -> bool: ...
179
async def list_instances(self, request: ListInstanceParam) -> List[Instance]: ...
180
async def get_service(self, request: GetServiceParam) -> Service: ...
181
async def list_services(self, request: ListServiceParam) -> ServiceList: ...
182
async def subscribe(self, request: SubscribeServiceParam) -> None: ...
183
async def unsubscribe(self, request: SubscribeServiceParam) -> None: ...
184
async def server_health(self) -> bool: ...
185
async def shutdown(self) -> None: ...
186
```
187
188
[V2 Service Discovery](./v2-naming.md)
189
190
### Client Configuration
191
192
Configuration classes for setting up Nacos clients with support for authentication, security, networking, and operational parameters.
193
194
```python { .api }
195
class ClientConfig:
196
def __init__(self, server_addresses=None, endpoint=None, namespace_id='',
197
context_path='', access_key=None, secret_key=None, username=None,
198
password=None, app_name='', app_key='', log_dir='', log_level=None,
199
log_rotation_backup_count=None, app_conn_labels=None, credentials_provider=None): ...
200
201
class ClientConfigBuilder:
202
def server_addresses(self, server_addresses: str) -> 'ClientConfigBuilder': ...
203
def namespace_id(self, namespace_id: str) -> 'ClientConfigBuilder': ...
204
def username(self, username: str) -> 'ClientConfigBuilder': ...
205
def password(self, password: str) -> 'ClientConfigBuilder': ...
206
def build(self) -> ClientConfig: ...
207
```
208
209
[Client Configuration](./client-config.md)
210
211
## Types
212
213
### V2 Data Models
214
215
```python { .api }
216
class Instance(BaseModel):
217
instanceId: str = ''
218
ip: str
219
port: int
220
weight: float = 1.0
221
healthy: bool = True
222
enabled: bool = True
223
ephemeral: bool = True
224
clusterName: str = ''
225
serviceName: str = ''
226
metadata: dict = {}
227
228
class ConfigParam(BaseModel):
229
dataId: str
230
group: str = 'DEFAULT_GROUP'
231
content: str = ''
232
type: str = ''
233
appName: str = ''
234
tag: str = ''
235
md5: str = ''
236
237
class RegisterInstanceParam(BaseModel):
238
ip: str
239
port: int
240
weight: float = 1.0
241
enabled: bool = True
242
healthy: bool = True
243
metadata: Dict[str, str] = {}
244
clusterName: str = ''
245
serviceName: str
246
groupName: str = 'DEFAULT_GROUP'
247
ephemeral: bool = True
248
249
class Service(BaseModel):
250
name: str
251
groupName: str
252
clusters: str
253
cacheMillis: int
254
hosts: List[Instance]
255
lastRefTime: int
256
checksum: str
257
allIPs: bool
258
reachProtectionThreshold: bool
259
260
class ServiceList(BaseModel):
261
count: int
262
services: List[str]
263
```
264
265
### Exception Classes
266
267
```python { .api }
268
class NacosException(Exception):
269
def __init__(self, error_code=None, message="An error occurred"): ...
270
271
# V1 Exception (legacy)
272
class NacosRequestException(NacosException): ...
273
```
274
275
### Constants
276
277
```python { .api }
278
DEFAULT_GROUP_NAME = "DEFAULT_GROUP"
279
DEFAULTS = {
280
"APP_NAME": "Nacos-SDK-Python",
281
"TIMEOUT": 3,
282
"PULLING_TIMEOUT": 30,
283
"PULLING_CONFIG_SIZE": 3000,
284
"CALLBACK_THREAD_NUM": 10,
285
"FAILOVER_BASE": "nacos-data/data",
286
"SNAPSHOT_BASE": "nacos-data/snapshot"
287
}
288
```