# nacos-sdk-python
A Python implementation of Nacos OpenAPI.
see: https://nacos.io/docs/latest/guide/user/open-api/
[](https://badge.fury.io/py/nacos-sdk-python)
[](https://github.com/nacos-group/nacos-sdk-python/blob/master/LICENSE)
### 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
```shell
pip install nacos-sdk-python
```
## Getting Started
```python
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, use `DEFAULT_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.
* 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, use `DEFAULT_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 format
* `param` *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, default `blank`.
* `param` *group_name* Customized group name , default `DEFAULT_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.
* `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, default `blank`.
* `param` *group_name* Customized group name , default `DEFAULT_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")
```
# nacos-sdk-python v2
A Python implementation of Nacos OpenAPI.
see: https://nacos.io/zh-cn/docs/open-API.html
[](https://badge.fury.io/py/nacos-sdk-python)
[](https://github.com/nacos-group/nacos-sdk-python/blob/master/LICENSE)
### Supported Python version：
Python 3.7+
### Supported Nacos version
Supported Nacos version over 2.x
## Installation
```shell
pip install nacos-sdk-python==2.0.0b5
```
## 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, use `DEFAULT_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
```angular2html
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
```angular2html
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
```angular2html
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
```angular2html
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
```angular2html
service = await client.get_service(
GetServiceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', cluster_name='c1'))
```
### List Service
```angular2html
service_list = await client.list_services(ListServiceParam())
```
### List Instance
```angular2html
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
```angular2html
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
```angular2html
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))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/nacos-group/nacos-sdk-python",
"name": "nacos-sdk-python",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "nacos, nacos-sdk-python",
"author": "nacos",
"author_email": "755063194@qq.com",
"download_url": "https://files.pythonhosted.org/packages/9d/e4/c9506551fe699e1f0bc194a9024cc8fb18c8d4ee4f004dfdd5861db07b2d/nacos-sdk-python-2.0.1.tar.gz",
"platform": null,
"description": "\n# nacos-sdk-python\n\nA Python implementation of Nacos OpenAPI.\n\nsee: https://nacos.io/docs/latest/guide/user/open-api/\n\n[](https://badge.fury.io/py/nacos-sdk-python)\n[](https://github.com/nacos-group/nacos-sdk-python/blob/master/LICENSE)\n\n### Supported Python version\uff1a\n\nPython 2.7\nPython 3.6\nPython 3.7\n\n### Supported Nacos version\n\nNacos 0.8.0+\nNacos 1.x\nNacos 2.x with http protocol\n\n## Installation\n\n```shell\npip install nacos-sdk-python\n```\n\n## Getting Started\n\n```python\nimport nacos\n\n# Both HTTP/HTTPS protocols are supported, if not set protocol prefix default is HTTP, and HTTPS with no ssl check(verify=False)\n# \"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\"\nSERVER_ADDRESSES = \"server addresses split by comma\"\nNAMESPACE = \"namespace id\"\n\n# no auth mode\nclient = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE)\n# auth mode\n# client = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE, ak=\"{ak}\", sk=\"{sk}\")\n\n# get config\ndata_id = \"config.nacos\"\ngroup = \"group\"\nprint(client.get_config(data_id, group))\n```\n\n## Configuration\n\n```\nclient = NacosClient(server_addresses, namespace=your_ns, ak=your_ak, sk=your_sk)\n```\n\n* *server_addresses* - **required** - Nacos server address, comma separated if more than 1.\n* *namespace* - Namespace. | default: `None`\n* *ak* - The accessKey to authenticate. | default: null\n* *sk* - The secretKey to authentication. | default: null\n* *credentials_provider* - The custom access key manager | default: null\n* *log_level* - Log level. | default: null\n* *log_rotation_backup_count* - The number of log files to keep. | default: `7`\n\n#### Extra Options\n\nExtra option can be set by `set_options`, as following:\n\n```\nclient.set_options({key}={value})\n# client.set_options(proxies={\"http\":\"192.168.3.50:809\"})\n```\n\nConfigurable options are:\n\n* *default_timeout* - Default timeout for get config from server in seconds.\n* *pulling_timeout* - Long polling timeout in seconds.\n* *pulling_config_size* - Max config items number listened by one polling process.\n* *callback_thread_num* - Concurrency for invoking callback.\n* *failover_base* - Dir to store failover config files.\n* *snapshot_base* - Dir to store snapshot config files.\n* *no_snapshot* - To disable default snapshot behavior, this can be overridden by param *no_snapshot* in *get* method.\n* *proxies* - Dict proxy mapping, some environments require proxy access, so you can set this parameter, this way http\n requests go through the proxy.\n\n## API Reference\n\n### Get Config\n\n> `NacosClient.get_config(data_id, group, timeout, no_snapshot)`\n\n* `param` *data_id* Data id.\n* `param` *group* Group, use `DEFAULT_GROUP` if no group specified.\n* `param` *timeout* Timeout for requesting server in seconds.\n* `param` *no_snapshot* Whether to use local snapshot while server is unavailable.\n* `return`\n W\n Get value of one config item following priority:\n\n\n* Step 1 - Get from local failover dir(default: `${cwd}/nacos-data/data`).\n * Failover dir can be manually copied from snapshot dir(default: `${cwd}/nacos-data/snapshot`) in advance.\n * This helps to suppress the effect of known server failure.\n\n* Step 2 - Get from one server until value is got or all servers tried.\n * Content will be save to snapshot dir after got from server.\n\n* Step 3 - Get from snapshot dir.\n\n### Add Watchers\n\n> `NacosClient.add_config_watchers(data_id, group, cb_list)`\n\n* `param` *data_id* Data id.\n* `param` *group* Group, use `DEFAULT_GROUP` if no group specified.\n* `param` *cb_list* List of callback functions to add.\n* `return`\n\nAdd watchers to a specified config item.\n\n* Once changes or deletion of the item happened, callback functions will be invoked.\n* If the item is already exists in server, callback functions will be invoked for once.\n* Multiple callbacks on one item is allowed and all callback functions are invoked concurrently by `threading.Thread`.\n* Callback functions are invoked from current process.\n\n### Remove Watcher\n\n> `NacosClient.remove_config_watcher(data_id, group, cb, remove_all)`\n\n* `param` *data_id* Data id.\n* `param` *group* Group, use \"DEFAULT_GROUP\" if no group specified.\n* `param` *cb* Callback function to delete.\n* `param` *remove_all* Whether to remove all occurrence of the callback or just once.\n* `return`\n\nRemove watcher from specified key.\n\n### Publish Config\n\n> `NacosClient.publish_config(data_id, group, content, timeout)`\n\n* `param` *data_id* Data id.\n* `param` *group* Group, use \"DEFAULT_GROUP\" if no group specified.\n* `param` *content* Config value.\n* `param` *timeout* Timeout for requesting server in seconds.\n* `return` True if success or an exception will be raised.\n\nPublish one data item to Nacos.\n\n* If the data key is not exist, create one first.\n* If the data key is exist, update to the content specified.\n* Content can not be set to None, if there is need to delete config item, use function **remove** instead.\n\n### Remove Config\n\n> `NacosClient.remove_config(data_id, group, timeout)`\n\n* `param` *data_id* Data id.\n* `param` *group* Group, use \"DEFAULT_GROUP\" if no group specified.\n* `param` *timeout* Timeout for requesting server in seconds.\n* `return` True if success or an exception will be raised.\n\nRemove one data item from Nacos.\n\n### Register Instance\n\n>\n`NacosClient.add_naming_instance(service_name, ip, port, cluster_name, weight, metadata, enable, healthy,ephemeral,group_name,heartbeat_interval)`\n\n* `param` *service_name* **required** Service name to register to.\n* `param` *ip* **required** IP of the instance.\n* `param` *port* **required** Port of the instance.\n* `param` *cluster_name* Cluster to register to.\n* `param` *weight* A float number for load balancing weight.\n* `param` *metadata* Extra info in JSON string format or dict format\n* `param` *enable* A bool value to determine whether instance is enabled or not.\n* `param` *healthy* A bool value to determine whether instance is healthy or not.\n* `param` *ephemeral* A bool value to determine whether instance is ephemeral or not.\n* `param` *heartbeat_interval* Auto daemon heartbeat interval in seconds.\n* `return` True if success or an exception will be raised.\n\n### Deregister Instance\n\n> `NacosClient.remove_naming_instance(service_name, ip, port, cluster_name)`\n\n* `param` *service_name* **required** Service name to deregister from.\n* `param` *ip* **required** IP of the instance.\n* `param` *port* **required** Port of the instance.\n* `param` *cluster_name* Cluster to deregister from.\n* `param` *ephemeral* A bool value to determine whether instance is ephemeral or not.\n* `return` True if success or an exception will be raised.\n\n### Modify Instance\n\n> `NacosClient.modify_naming_instance(service_name, ip, port, cluster_name, weight, metadata, enable)`\n\n* `param` *service_name* **required** Service name.\n* `param` *ip* **required** IP of the instance.\n* `param` *port* **required** Port of the instance.\n* `param` *cluster_name* Cluster name.\n* `param` *weight* A float number for load balancing weight.\n* `param` *metadata* Extra info in JSON string format or dict format.\n* `param` *enable* A bool value to determine whether instance is enabled or not.\n* `param` *ephemeral* A bool value to determine whether instance is ephemeral or not.\n* `return` True if success or an exception will be raised.\n\n### Query Instances\n\n> `NacosClient.list_naming_instance(service_name, clusters, namespace_id, group_name, healthy_only)`\n\n* `param` *service_name* **required** Service name to query.\n* `param` *clusters* Cluster names separated by comma.\n* `param` *namespace_id* Customized group name, default `blank`.\n* `param` *group_name* Customized group name , default `DEFAULT_GROUP`.\n* `param` *healthy_only* A bool value for querying healthy instances or not.\n* `return` Instance info list if success or an exception will be raised.\n\n### Query Instance Detail\n\n> `NacosClient.get_naming_instance(service_name, ip, port, cluster_name)`\n\n* `param` *service_name* **required** Service name.\n* `param` *ip* **required** IP of the instance.\n* `param` *port* **required** Port of the instance.\n* `param` *cluster_name* Cluster name.\n* `return` Instance info if success or an exception will be raised.\n\n### Send Instance Beat\n\n> `NacosClient.send_heartbeat(service_name, ip, port, cluster_name, weight, metadata)`\n\n* `param` *service_name* **required** Service name.\n* `param` *ip* **required** IP of the instance.\n* `param` *port* **required** Port of the instance.\n* `param` *cluster_name* Cluster to register to.\n* `param` *weight* A float number for load balancing weight.\n* `param` *ephemeral* A bool value to determine whether instance is ephemeral or not.\n* `param` *metadata* Extra info in JSON string format or dict format.\n* `return` A JSON object include server recommended beat interval if success or an exception will be raised.\n\n### Subscribe Service Instances Changed\n\n> `NacosClient.subscribe(listener_fn, listener_interval=7, *args, **kwargs)`\n\n* `param` *listener_fn* **required** Customized listener function.\n* `param` *listener_interval* Listen interval , default 7 second.\n* `param` *service_name* **required** Service name which subscribes.\n* `param` *clusters* Cluster names separated by comma.\n* `param` *namespace_id* Customized group name, default `blank`.\n* `param` *group_name* Customized group name , default `DEFAULT_GROUP`.\n* `param` *healthy_only* A bool value for querying healthy instances or not.\n* `return`\n\n### Unsubscribe Service Instances Changed\n\n> `NacosClient.unsubscribe(service_name, listener_name)`\n\n* `param` *service_name* **required** Service name to subscribed.\n* `param` *listener_name* listener_name which is customized.\n* `return`\n\n### Stop All Service Subscribe\n\n> `NacosClient.stop_subscribe()`\n\n* `return`\n\n## Debugging Mode\n\nDebugging mode if useful for getting more detailed log on console.\n\nDebugging mode can be set by:\n\n```\nclient = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE, username=USERNAME, password=PASSWORD,log_level=\"DEBUG\")\n```\n\n# nacos-sdk-python v2\n\nA Python implementation of Nacos OpenAPI.\n\nsee: https://nacos.io/zh-cn/docs/open-API.html\n\n[](https://badge.fury.io/py/nacos-sdk-python)\n[](https://github.com/nacos-group/nacos-sdk-python/blob/master/LICENSE)\n\n### Supported Python version\uff1a\n\nPython 3.7+\n\n### Supported Nacos version\n\nSupported Nacos version over 2.x\n\n## Installation\n\n```shell\n pip install nacos-sdk-python==2.0.0b5 \n```\n\n## Client Configuration\n\n```\nfrom v2.nacos import NacosNamingService, ClientConfigBuilder, GRPCConfig, Instance, SubscribeServiceParam, \\\n RegisterInstanceParam, DeregisterInstanceParam, BatchRegisterInstanceParam, GetServiceParam, ListServiceParam, \\\n ListInstanceParam, NacosConfigService, ConfigParam\n\nclient_config = (ClientConfigBuilder()\n .access_key(os.getenv('NACOS_ACCESS_KEY'))\n .secret_key(os.getenv('NACOS_SECRET_KEY'))\n .server_address(os.getenv('NACOS_SERVER_ADDR', 'localhost:8848'))\n .log_level('INFO')\n .grpc_config(GRPCConfig(grpc_timeout=5000))\n .build())\n```\n\n* *server_address* - **required** - Nacos server address\n* *access_key* - The aliyun accessKey to authenticate.\n* *secret_key* - The aliyun secretKey to authenticate.\n* *credentials_provider* - The custom access key manager.\n* *username* - The username to authenticate.\n* *password* - The password to authenticate.\n* *log_level* - Log level | default: `logging.INFO`\n* *cache_dir* - cache dir path. | default: `~/nacos/cache`\n* *log_dir* - log dir path. | default: `~/logs/nacos`\n* *namespace_id* - namespace id. | default: ``\n* *grpc_config* - grpc config.\n * *max_receive_message_length* - max receive message length in grpc. | default: 100 * 1024 * 1024\n * *max_keep_alive_ms* - max keep alive ms in grpc. | default: 60 * 1000\n * *initial_window_size* - initial window size in grpc. | default: 10 * 1024 * 1024\n * *initial_conn_window_size* - initial connection window size in grpc. | default: 10 * 1024 * 1024\n * *grpc_timeout* - grpc timeout in milliseconds. default: 3000\n* *tls_config* - tls config\n * *enabled* - whether enable tls.\n * *ca_file* - ca file path.\n * *cert_file* - cert file path.\n * *key_file* - key file path.\n* *kms_config* - aliyun kms config \n * *enabled* - whether enable aliyun kms.\n * *endpoint* - aliyun kms endpoint.\n * *access_key* - aliyun accessKey.\n * *secret_key* - aliyun secretKey.\n * *password* - aliyun kms password.\n\n## Config Client\n\n```\n\nconfig_client = await NacosConfigService.create_config_service(client_config)\n\n```\n\n### config client common parameters\n\n> `param: ConfigParam`\n\n* `param` *data_id* Data id.\n* `param` *group* Group, use `DEFAULT_GROUP` if no group specified.\n* `param` *content* Config content.\n* `param` *tag* Config tag.\n* `param` *app_name* Application name.\n* `param` *beta_ips* Beta test ip address.\n* `param` *cas_md5* MD5 check code.\n* `param` *type* Config type.\n* `param` *src_user* Source user.\n* `param` *encrypted_data_key* Encrypted data key.\n* `param` *kms_key_id* Kms encrypted data key id.\n* `param` *usage_type* Usage type.\n\n### Get Config\n\n```\ncontent = await config_client.get_config(ConfigParam(\n data_id=data_id,\n group=group\n ))\n```\n\n* `param` *ConfigParam* config client common parameters. When getting configuration, it is necessary to specify the\n required data_id and group in param.\n* `return` Config content if success or an exception will be raised.\n\nGet value of one config item following priority:\n\n* Step 1 - Get from local failover dir.\n\n* Step 2 - Get from one server until value is got or all servers tried.\n * Content will be saved to snapshot dir after got from server.\n\n* Step 3 - Get from snapshot dir.\n\n### Add Listener\n\n```\nasync def config_listener(tenant, data_id, group, content):\n print(\"listen, tenant:{} data_id:{} group:{} content:{}\".format(tenant, data_id, group, content))\n\nawait config_client.add_listener(dataID, groupName, config_listener)\n```\n\n* `param` *ConfigParam* config client common parameters.\n* `listener` *listener* Configure listener, defined by the namespace_id\u3001group\u3001data_id\u3001content.\n* `return`\n\nAdd Listener to a specified config item.\n\n* Once changes or deletion of the item happened, callback functions will be invoked.\n* If the item is already exists in server, callback functions will be invoked for once.\n* Callback functions are invoked from current process.\n\n### Remove Listener\n\n```\nawait client.remove_listener(dataID, groupName, config_listener)\n```\n\n* `param` *ConfigParam* config client common parameters.\n* `return` True if success or an exception will be raised.\n\nRemove watcher from specified key.\n\n### Publish Config\n\n```\nres = await client.publish_config(ConfigParam(\n data_id=dataID,\n group=groupName,\n content=\"Hello world\")\n )\n```\n\n* `param` *ConfigParam* config client common parameters. When publishing configuration, it is necessary to specify the\n required data_id, group and content in param.\n* `return` True if success or an exception will be raised.\n\nPublish one congfig data item to Nacos.\n\n* If the data key is not exist, create one first.\n* If the data key is exist, update to the content specified.\n* Content can not be set to None, if there is need to delete config item, use function **remove** instead.\n\n### Remove Config\n\n```\nres = await client.remove_config(ConfigParam(\n data_id=dataID,\n group=groupName\n ))\n```\n* `param` *ConfigParam* config client common parameters.When removing configuration, it is necessary to specify the\n required data_id and group in param.\n* `return` True if success or an exception will be raised.\n\nRemove one config data item from Nacos.\n\n### Stop Config Client\n\n```\nawait client.shutdown()\n```\n\n## Naming Client\n\n```\n\nnaming_client = await NacosNamingService.create_naming_service(client_config)\n\n```\n\n### Register Instance\n\n```angular2html\nresponse = await client.register_instance(\n request=RegisterInstanceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', ip='1.1.1.1',\n port=7001, weight=1.0, cluster_name='c1', metadata={'a': 'b'},\n enabled=True,\n healthy=True, ephemeral=True))\n```\n\n### Batch Register Instance\n```angular2html\nparam1 = RegisterInstanceParam(service_name='nacos.test.1',\n group_name='DEFAULT_GROUP',\n ip='1.1.1.1',\n port=7001,\n weight=1.0,\n cluster_name='c1',\n metadata={'a': 'b'},\n enabled=True,\n healthy=True,\n ephemeral=True\n )\nparam2 = RegisterInstanceParam(service_name='nacos.test.1',\n group_name='DEFAULT_GROUP',\n ip='1.1.1.1',\n port=7002,\n weight=1.0,\n cluster_name='c1',\n metadata={'a': 'b'},\n enabled=True,\n healthy=True,\n ephemeral=True\n )\nparam3 = RegisterInstanceParam(service_name='nacos.test.1',\n group_name='DEFAULT_GROUP',\n ip='1.1.1.1',\n port=7003,\n weight=1.0,\n cluster_name='c1',\n metadata={'a': 'b'},\n enabled=True,\n healthy=False,\n ephemeral=True\n )\nresponse = await client.batch_register_instances(\n request=BatchRegisterInstanceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP',\n instances=[param1, param2, param3]))\n```\n\n### Deregister Instance\n\n```angular2html\nresponse = await client.deregister_instance(\n request=DeregisterInstanceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', ip='1.1.1.1',\n port=7001, cluster_name='c1', ephemeral=True)\n )\n```\n\n### Update Instance\n```angular2html\nresponse = await client.update_instance(\n request=RegisterInstanceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', ip='1.1.1.1',\n port=7001, weight=2.0, cluster_name='c1', metadata={'a': 'b'},\n enabled=True,\n healthy=True, ephemeral=True))\n```\n\n### Get Service\n```angular2html\nservice = await client.get_service(\n GetServiceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', cluster_name='c1'))\n```\n\n### List Service\n```angular2html\n\nservice_list = await client.list_services(ListServiceParam())\n\n```\n\n### List Instance\n\n```angular2html\n\ninstance_list = await client.list_instances(ListInstanceParam(service_name='nacos.test.1', healthy_only=True))\ninstance_list = await client.list_instances(ListInstanceParam(service_name='nacos.test.1', healthy_only=False))\ninstance_list = await client.list_instances(ListInstanceParam(service_name='nacos.test.1', healthy_only=None))\n\n```\n\n### Subscribe\n\n```angular2html\nasync def cb(instance_list: list[Instance]):\n print('received subscribe callback', str(instance_list))\n\nawait client.subscribe(\n SubscribeServiceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', subscribe_callback=cb))\n```\n\n\n### Unsubscribe\n\n```angular2html\nasync def cb(instance_list: list[Instance]):\n print('received subscribe callback', str(instance_list))\n\nawait client.unsubscribe(\n SubscribeServiceParam(service_name='nacos.test.1', group_name='DEFAULT_GROUP', subscribe_callback=cb))\n```\n\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Python client for Nacos.",
"version": "2.0.1",
"project_urls": {
"Documentation": "https://github.com/nacos-group/nacos-sdk-python",
"Homepage": "https://github.com/nacos-group/nacos-sdk-python",
"Nacos Open API Guide": "https://nacos.io/en-us/docs/open-api.html",
"Source": "https://github.com/nacos-group/nacos-sdk-python"
},
"split_keywords": [
"nacos",
" nacos-sdk-python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e614269a08582090ac1d16ff2c491455a22d4a4c4f47337eb0b142957a93ea0a",
"md5": "dc8ef5aaf918360270abc2bf861ea56b",
"sha256": "623cfc4645adb44f21c8613d6c0e6f1c41a0110318ce0899d57942009b626044"
},
"downloads": -1,
"filename": "nacos_sdk_python-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc8ef5aaf918360270abc2bf861ea56b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 93265,
"upload_time": "2025-01-13T14:37:17",
"upload_time_iso_8601": "2025-01-13T14:37:17.808694Z",
"url": "https://files.pythonhosted.org/packages/e6/14/269a08582090ac1d16ff2c491455a22d4a4c4f47337eb0b142957a93ea0a/nacos_sdk_python-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9de4c9506551fe699e1f0bc194a9024cc8fb18c8d4ee4f004dfdd5861db07b2d",
"md5": "941ab9af64844ea8c9338abe32854e80",
"sha256": "29fa1dd14f771824b65ae0edd208bb4d20737655ae8b809685194e2f6358c2a7"
},
"downloads": -1,
"filename": "nacos-sdk-python-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "941ab9af64844ea8c9338abe32854e80",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 68582,
"upload_time": "2025-01-13T14:37:22",
"upload_time_iso_8601": "2025-01-13T14:37:22.981312Z",
"url": "https://files.pythonhosted.org/packages/9d/e4/c9506551fe699e1f0bc194a9024cc8fb18c8d4ee4f004dfdd5861db07b2d/nacos-sdk-python-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-13 14:37:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nacos-group",
"github_project": "nacos-sdk-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "aiofiles",
"specs": [
[
">=",
"24.1.0"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.10.11"
]
]
},
{
"name": "alibabacloud_kms20160120",
"specs": [
[
">=",
"2.2.3"
]
]
},
{
"name": "alibabacloud_tea_openapi",
"specs": [
[
">=",
"0.3.12"
]
]
},
{
"name": "grpcio",
"specs": [
[
">=",
"1.66.1"
]
]
},
{
"name": "protobuf",
"specs": [
[
">=",
"3.20.3"
]
]
},
{
"name": "psutil",
"specs": [
[
">=",
"5.9.6"
]
]
},
{
"name": "pycryptodome",
"specs": [
[
">=",
"3.19.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.10.4"
]
]
}
],
"lcname": "nacos-sdk-python"
}
JSON
