Python client for Nacos.
Project description
nacos-sdk-python v2
A Python implementation of Nacos OpenAPI.
see: https://nacos.io/zh-cn/docs/open-API.html
Supported Python version:
Python 3.7+
Supported Nacos version
Supported Nacos version over 2.x
Installation
pip install nacos-sdk-python
Client Configuration
from v2.nacos import NacosNamingService, ClientConfigBuilder, GRPCConfig, Instance, SubscribeServiceParam, \
RegisterInstanceParam, DeregisterInstanceParam, BatchRegisterInstanceParam, GetServiceParam, ListServiceParam, \
ListInstanceParam, NacosConfigService, ConfigParam
client_config = (ClientConfigBuilder()
.access_key(os.getenv('NACOS_ACCESS_KEY'))
.secret_key(os.getenv('NACOS_SECRET_KEY'))
.server_address(os.getenv('NACOS_SERVER_ADDR', 'localhost:8848'))
.log_level('INFO')
.grpc_config(GRPCConfig(grpc_timeout=5000))
.build())
- server_address - required - Nacos server address
- access_key - The aliyun accessKey to authenticate.
- secret_key - The aliyun secretKey to authenticate.
- credentials_provider - The custom access key manager.
- username - The username to authenticate.
- password - The password to authenticate.
- log_level - Log level | default:
logging.INFO
- cache_dir - cache dir path. | default:
~/nacos/cache
- log_dir - log dir path. | default:
~/logs/nacos
- namespace_id - namespace id. | default: ``
- grpc_config - grpc config.
- max_receive_message_length - max receive message length in grpc. | default: 100 * 1024 * 1024
- max_keep_alive_ms - max keep alive ms in grpc. | default: 60 * 1000
- initial_window_size - initial window size in grpc. | default: 10 * 1024 * 1024
- initial_conn_window_size - initial connection window size in grpc. | default: 10 * 1024 * 1024
- grpc_timeout - grpc timeout in milliseconds. default: 3000
- tls_config - tls config
- enabled - whether enable tls.
- ca_file - ca file path.
- cert_file - cert file path.
- key_file - key file path.
- kms_config - aliyun kms config
- enabled - whether enable aliyun kms.
- endpoint - aliyun kms endpoint.
- access_key - aliyun accessKey.
- secret_key - aliyun secretKey.
- password - aliyun kms password.
Config Client
config_client = await NacosConfigService.create_config_service(client_config)
config client common parameters
param: ConfigParam
param
data_id Data id.param
group Group, useDEFAULT_GROUP
if no group specified.param
content Config content.param
tag Config tag.param
app_name Application name.param
beta_ips Beta test ip address.param
cas_md5 MD5 check code.param
type Config type.param
src_user Source user.param
encrypted_data_key Encrypted data key.param
kms_key_id Kms encrypted data key id.param
usage_type Usage type.
Get Config
content = await config_client.get_config(ConfigParam(
data_id=data_id,
group=group
))
param
ConfigParam config client common parameters. When getting configuration, it is necessary to specify the required data_id and group in param.return
Config content if success or an exception will be raised.
Get value of one config item following priority:
-
Step 1 - Get from local failover dir.
-
Step 2 - Get from one server until value is got or all servers tried.
- Content will be saved to snapshot dir after got from server.
-
Step 3 - Get from snapshot dir.
Add Listener
async def config_listener(tenant, data_id, group, content):
print("listen, tenant:{} data_id:{} group:{} content:{}".format(tenant, data_id, group, content))
await config_client.add_listener(dataID, groupName, config_listener)
param
ConfigParam config client common parameters.listener
listener Configure listener, defined by the namespace_id、group、data_id、content.return
Add Listener to a specified config item.
- Once changes or deletion of the item happened, callback functions will be invoked.
- If the item is already exists in server, callback functions will be invoked for once.
- Callback functions are invoked from current process.
Remove Listener
await client.remove_listener(dataID, groupName, config_listener)
param
ConfigParam config client common parameters.return
True if success or an exception will be raised.
Remove watcher from specified key.
Publish Config
res = await client.publish_config(ConfigParam(
data_id=dataID,
group=groupName,
content="Hello world")
)
param
ConfigParam config client common parameters. When publishing configuration, it is necessary to specify the required data_id, group and content in param.return
True if success or an exception will be raised.
Publish one congfig data item to Nacos.
- If the data key is not exist, create one first.
- If the data key is exist, update to the content specified.
- Content can not be set to None, if there is need to delete config item, use function remove instead.
Remove Config
res = await client.remove_config(ConfigParam(
data_id=dataID,
group=groupName
))
param
ConfigParam config client common parameters.When removing configuration, it is necessary to specify the required data_id and group in param.return
True if success or an exception will be raised.
Remove one config data item from Nacos.
Stop Config Client
await client.shutdown()
Naming Client
naming_client = await NacosNamingService.create_naming_service(client_config)
Register Instance
response = await client.register_instance(
request=RegisterInstanceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', ip='1.1.1.1',
port=7001, weight=1.0, cluster_name='c1', metadata={'a': 'b'},
enabled=True,
healthy=True, ephemeral=True))
Batch Register Instance
param1 = RegisterInstanceParam(service_name='nacos.test.1',
group_name='DEFAULT_GROUP',
ip='1.1.1.1',
port=7001,
weight=1.0,
cluster_name='c1',
metadata={'a': 'b'},
enabled=True,
healthy=True,
ephemeral=True
)
param2 = RegisterInstanceParam(service_name='nacos.test.1',
group_name='DEFAULT_GROUP',
ip='1.1.1.1',
port=7002,
weight=1.0,
cluster_name='c1',
metadata={'a': 'b'},
enabled=True,
healthy=True,
ephemeral=True
)
param3 = RegisterInstanceParam(service_name='nacos.test.1',
group_name='DEFAULT_GROUP',
ip='1.1.1.1',
port=7003,
weight=1.0,
cluster_name='c1',
metadata={'a': 'b'},
enabled=True,
healthy=False,
ephemeral=True
)
response = await client.batch_register_instances(
request=BatchRegisterInstanceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP',
instances=[param1, param2, param3]))
Deregister Instance
response = await client.deregister_instance(
request=DeregisterInstanceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', ip='1.1.1.1',
port=7001, cluster_name='c1', ephemeral=True)
)
Update Instance
response = await client.update_instance(
request=RegisterInstanceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', ip='1.1.1.1',
port=7001, weight=2.0, cluster_name='c1', metadata={'a': 'b'},
enabled=True,
healthy=True, ephemeral=True))
Get Service
service = await client.get_service(
GetServiceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', cluster_name='c1'))
List Service
service_list = await client.list_services(ListServiceParam())
List Instance
instance_list = await client.list_instances(ListInstanceParam(service_name='nacos.test.1', healthy_only=True))
instance_list = await client.list_instances(ListInstanceParam(service_name='nacos.test.1', healthy_only=False))
instance_list = await client.list_instances(ListInstanceParam(service_name='nacos.test.1', healthy_only=None))
Subscribe
async def cb(instance_list: List[Instance]):
print('received subscribe callback', str(instance_list))
await client.subscribe(
SubscribeServiceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', subscribe_callback=cb))
Unsubscribe
async def cb(instance_list: List[Instance]):
print('received subscribe callback', str(instance_list))
await client.unsubscribe(
SubscribeServiceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', subscribe_callback=cb))
nacos-sdk-python 1.0
A Python implementation of Nacos OpenAPI.
see: https://nacos.io/docs/latest/guide/user/open-api/
Supported Python version:
Python 2.7 Python 3.6 Python 3.7
Supported Nacos version
Nacos 0.8.0+ Nacos 1.x Nacos 2.x with http protocol
Installation
pip install nacos-sdk-python
Getting Started
import nacos
# Both HTTP/HTTPS protocols are supported, if not set protocol prefix default is HTTP, and HTTPS with no ssl check(verify=False)
# "192.168.3.4:8848" or "https://192.168.3.4:443" or "http://192.168.3.4:8848,192.168.3.5:8848" or "https://192.168.3.4:443,https://192.168.3.5:443"
SERVER_ADDRESSES = "server addresses split by comma"
NAMESPACE = "namespace id"
# no auth mode
client = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE)
# auth mode
# client = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE, ak="{ak}", sk="{sk}")
# get config
data_id = "config.nacos"
group = "group"
print(client.get_config(data_id, group))
Configuration
client = NacosClient(server_addresses, namespace=your_ns, ak=your_ak, sk=your_sk)
- server_addresses - required - Nacos server address, comma separated if more than 1.
- namespace - Namespace. | default:
None
- ak - The accessKey to authenticate. | default: null
- sk - The secretKey to authentication. | default: null
- credentials_provider - The custom access key manager | default: null
- log_level - Log level. | default: null
- log_rotation_backup_count - The number of log files to keep. | default:
7
Extra Options
Extra option can be set by set_options
, as following:
client.set_options({key}={value})
# client.set_options(proxies={"http":"192.168.3.50:809"})
Configurable options are:
- default_timeout - Default timeout for get config from server in seconds.
- pulling_timeout - Long polling timeout in seconds.
- pulling_config_size - Max config items number listened by one polling process.
- callback_thread_num - Concurrency for invoking callback.
- failover_base - Dir to store failover config files.
- snapshot_base - Dir to store snapshot config files.
- no_snapshot - To disable default snapshot behavior, this can be overridden by param no_snapshot in get method.
- proxies - Dict proxy mapping, some environments require proxy access, so you can set this parameter, this way http requests go through the proxy.
API Reference
Get Config
NacosClient.get_config(data_id, group, timeout, no_snapshot)
-
param
data_id Data id. -
param
group Group, useDEFAULT_GROUP
if no group specified. -
param
timeout Timeout for requesting server in seconds. -
param
no_snapshot Whether to use local snapshot while server is unavailable. -
return
W Get value of one config item following priority: -
Step 1 - Get from local failover dir(default:
${cwd}/nacos-data/data
).- Failover dir can be manually copied from snapshot dir(default:
${cwd}/nacos-data/snapshot
) in advance. - This helps to suppress the effect of known server failure.
- Failover dir can be manually copied from snapshot dir(default:
-
Step 2 - Get from one server until value is got or all servers tried.
- Content will be save to snapshot dir after got from server.
-
Step 3 - Get from snapshot dir.
Add Watchers
NacosClient.add_config_watchers(data_id, group, cb_list)
param
data_id Data id.param
group Group, useDEFAULT_GROUP
if no group specified.param
cb_list List of callback functions to add.return
Add watchers to a specified config item.
- Once changes or deletion of the item happened, callback functions will be invoked.
- If the item is already exists in server, callback functions will be invoked for once.
- Multiple callbacks on one item is allowed and all callback functions are invoked concurrently by
threading.Thread
. - Callback functions are invoked from current process.
Remove Watcher
NacosClient.remove_config_watcher(data_id, group, cb, remove_all)
param
data_id Data id.param
group Group, use "DEFAULT_GROUP" if no group specified.param
cb Callback function to delete.param
remove_all Whether to remove all occurrence of the callback or just once.return
Remove watcher from specified key.
Publish Config
NacosClient.publish_config(data_id, group, content, timeout)
param
data_id Data id.param
group Group, use "DEFAULT_GROUP" if no group specified.param
content Config value.param
timeout Timeout for requesting server in seconds.return
True if success or an exception will be raised.
Publish one data item to Nacos.
- If the data key is not exist, create one first.
- If the data key is exist, update to the content specified.
- Content can not be set to None, if there is need to delete config item, use function remove instead.
Remove Config
NacosClient.remove_config(data_id, group, timeout)
param
data_id Data id.param
group Group, use "DEFAULT_GROUP" if no group specified.param
timeout Timeout for requesting server in seconds.return
True if success or an exception will be raised.
Remove one data item from Nacos.
Register Instance
NacosClient.add_naming_instance(service_name, ip, port, cluster_name, weight, metadata, enable, healthy,ephemeral,group_name,heartbeat_interval)
param
service_name required Service name to register to.param
ip required IP of the instance.param
port required Port of the instance.param
cluster_name Cluster to register to.param
weight A float number for load balancing weight.param
metadata Extra info in JSON string format or dict formatparam
enable A bool value to determine whether instance is enabled or not.param
healthy A bool value to determine whether instance is healthy or not.param
ephemeral A bool value to determine whether instance is ephemeral or not.param
heartbeat_interval Auto daemon heartbeat interval in seconds.return
True if success or an exception will be raised.
Deregister Instance
NacosClient.remove_naming_instance(service_name, ip, port, cluster_name)
param
service_name required Service name to deregister from.param
ip required IP of the instance.param
port required Port of the instance.param
cluster_name Cluster to deregister from.param
ephemeral A bool value to determine whether instance is ephemeral or not.return
True if success or an exception will be raised.
Modify Instance
NacosClient.modify_naming_instance(service_name, ip, port, cluster_name, weight, metadata, enable)
param
service_name required Service name.param
ip required IP of the instance.param
port required Port of the instance.param
cluster_name Cluster name.param
weight A float number for load balancing weight.param
metadata Extra info in JSON string format or dict format.param
enable A bool value to determine whether instance is enabled or not.param
ephemeral A bool value to determine whether instance is ephemeral or not.return
True if success or an exception will be raised.
Query Instances
NacosClient.list_naming_instance(service_name, clusters, namespace_id, group_name, healthy_only)
param
service_name required Service name to query.param
clusters Cluster names separated by comma.param
namespace_id Customized group name, defaultblank
.param
group_name Customized group name , defaultDEFAULT_GROUP
.param
healthy_only A bool value for querying healthy instances or not.return
Instance info list if success or an exception will be raised.
Query Instance Detail
NacosClient.get_naming_instance(service_name, ip, port, cluster_name)
param
service_name required Service name.param
ip required IP of the instance.param
port required Port of the instance.param
cluster_name Cluster name.return
Instance info if success or an exception will be raised.
Send Instance Beat
NacosClient.send_heartbeat(service_name, ip, port, cluster_name, weight, metadata)
param
service_name required Service name.param
ip required IP of the instance.param
port required Port of the instance.param
cluster_name Cluster to register to.param
weight A float number for load balancing weight.param
ephemeral A bool value to determine whether instance is ephemeral or not.param
metadata Extra info in JSON string format or dict format.return
A JSON object include server recommended beat interval if success or an exception will be raised.
Subscribe Service Instances Changed
NacosClient.subscribe(listener_fn, listener_interval=7, *args, **kwargs)
param
listener_fn required Customized listener function. with signaturefn_listener1(event, instance)->None
param
listener_interval Listen interval , default 7 second.param
service_name required Service name which subscribes.param
clusters Cluster names separated by comma.param
namespace_id Customized group name, defaultblank
.param
group_name Customized group name , defaultDEFAULT_GROUP
.param
healthy_only A bool value for querying healthy instances or not.return
Unsubscribe Service Instances Changed
NacosClient.unsubscribe(service_name, listener_name)
param
service_name required Service name to subscribed.param
listener_name listener_name which is customized.return
Stop All Service Subscribe
NacosClient.stop_subscribe()
return
Debugging Mode
Debugging mode if useful for getting more detailed log on console.
Debugging mode can be set by:
client = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE, username=USERNAME, password=PASSWORD,log_level="DEBUG")
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file nacos-sdk-python-2.0.7.tar.gz
.
File metadata
- Download URL: nacos-sdk-python-2.0.7.tar.gz
- Upload date:
- Size: 68.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.0.0 CPython/3.9.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
df698f1a6ce9ab7103de07ddbee8f4281a5d13c23ea12062173ea12079645123
|
|
MD5 |
15c21dcb86dd707714fabefe8918f04e
|
|
BLAKE2b-256 |
90e6e8d4205613ef2060de9089d4bf4f4c2064b230cb7905c7cff686c7c5c9dc
|
File details
Details for the file nacos_sdk_python-2.0.7-py3-none-any.whl
.
File metadata
- Download URL: nacos_sdk_python-2.0.7-py3-none-any.whl
- Upload date:
- Size: 93.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.0.0 CPython/3.9.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
068ec7d524c267438aa407ef243e9d0565309cff229b6fafe878ec50cd884040
|
|
MD5 |
f7795e867348e34c196cda678e101009
|
|
BLAKE2b-256 |
9d56949aad2c738ce1acd465591b8b6eb3949c28d317b56a6b02bd3441e0cb73
|