# nacos-sdk-python
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 2.7
Python 3.6
Python 3.7
### Supported Nacos version
Nacos 0.8.0 ~ 1.3.2
## 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
#### 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)`
* `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.
* `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:
```
NacosClient.set_debugging()
# only effective within the current process
```
Raw data
{
"_id": null,
"home_page": "https://github.com/nacos-group/nacos-sdk-python",
"name": "nacos-sdk-python-xing",
"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/79/ad/7a816e068d52024af2807fdfe0c779f4067ff620138d6e883f3ff9483bb4/nacos_sdk_python_xing-0.1.15.tar.gz",
"platform": null,
"description": "\r\n# nacos-sdk-python\r\nA Python implementation of Nacos OpenAPI.\r\n\r\nsee: https://nacos.io/zh-cn/docs/open-API.html\r\n\r\n[](https://badge.fury.io/py/nacos-sdk-python)\r\n[](https://github.com/nacos-group/nacos-sdk-python/blob/master/LICENSE)\r\n\r\n\r\n### Supported Python version\uff1a\r\n\r\nPython 2.7\r\nPython 3.6\r\nPython 3.7\r\n\r\n### Supported Nacos version\r\nNacos 0.8.0 ~ 1.3.2\r\n\r\n\r\n## Installation\r\n```shell\r\npip install nacos-sdk-python\r\n```\r\n\r\n## Getting Started\r\n```python\r\nimport nacos\r\n\r\n# Both HTTP/HTTPS protocols are supported, if not set protocol prefix default is HTTP, and HTTPS with no ssl check(verify=False)\r\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\"\r\nSERVER_ADDRESSES = \"server addresses split by comma\"\r\nNAMESPACE = \"namespace id\"\r\n\r\n# no auth mode\r\nclient = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE)\r\n# auth mode\r\n#client = nacos.NacosClient(SERVER_ADDRESSES, namespace=NAMESPACE, ak=\"{ak}\", sk=\"{sk}\")\r\n\r\n# get config\r\ndata_id = \"config.nacos\"\r\ngroup = \"group\"\r\nprint(client.get_config(data_id, group))\r\n```\r\n\r\n## Configuration\r\n```\r\nclient = NacosClient(server_addresses, namespace=your_ns, ak=your_ak, sk=your_sk)\r\n```\r\n\r\n* *server_addresses* - **required** - Nacos server address, comma separated if more than 1.\r\n* *namespace* - Namespace. | default: `None`\r\n* *ak* - The accessKey to authenticate. | default: null\r\n* *sk* - The secretKey to authentication. | default: null\r\n\r\n#### Extra Options\r\nExtra option can be set by `set_options`, as following:\r\n\r\n```\r\nclient.set_options({key}={value})\r\n# client.set_options(proxies={\"http\":\"192.168.3.50:809\"})\r\n```\r\n\r\nConfigurable options are:\r\n\r\n* *default_timeout* - Default timeout for get config from server in seconds.\r\n* *pulling_timeout* - Long polling timeout in seconds.\r\n* *pulling_config_size* - Max config items number listened by one polling process.\r\n* *callback_thread_num* - Concurrency for invoking callback.\r\n* *failover_base* - Dir to store failover config files.\r\n* *snapshot_base* - Dir to store snapshot config files.\r\n* *no_snapshot* - To disable default snapshot behavior, this can be overridden by param *no_snapshot* in *get* method.\r\n* *proxies* - Dict proxy mapping, some environments require proxy access, so you can set this parameter, this way http requests go through the proxy.\r\n\r\n## API Reference\r\n \r\n### Get Config\r\n>`NacosClient.get_config(data_id, group, timeout, no_snapshot)`\r\n\r\n* `param` *data_id* Data id.\r\n* `param` *group* Group, use `DEFAULT_GROUP` if no group specified.\r\n* `param` *timeout* Timeout for requesting server in seconds.\r\n* `param` *no_snapshot* Whether to use local snapshot while server is unavailable.\r\n* `return` \r\nW\r\nGet value of one config item following priority:\r\n\r\n* Step 1 - Get from local failover dir(default: `${cwd}/nacos-data/data`).\r\n * Failover dir can be manually copied from snapshot dir(default: `${cwd}/nacos-data/snapshot`) in advance.\r\n * This helps to suppress the effect of known server failure.\r\n \r\n* Step 2 - Get from one server until value is got or all servers tried.\r\n * Content will be save to snapshot dir after got from server.\r\n\r\n* Step 3 - Get from snapshot dir.\r\n\r\n### Add Watchers\r\n>`NacosClient.add_config_watchers(data_id, group, cb_list)`\r\n\r\n* `param` *data_id* Data id.\r\n* `param` *group* Group, use `DEFAULT_GROUP` if no group specified.\r\n* `param` *cb_list* List of callback functions to add.\r\n* `return`\r\n\r\nAdd watchers to a specified config item.\r\n* Once changes or deletion of the item happened, callback functions will be invoked.\r\n* If the item is already exists in server, callback functions will be invoked for once.\r\n* Multiple callbacks on one item is allowed and all callback functions are invoked concurrently by `threading.Thread`.\r\n* Callback functions are invoked from current process.\r\n\r\n### Remove Watcher\r\n>`NacosClient.remove_config_watcher(data_id, group, cb, remove_all)`\r\n\r\n* `param` *data_id* Data id.\r\n* `param` *group* Group, use \"DEFAULT_GROUP\" if no group specified.\r\n* `param` *cb* Callback function to delete.\r\n* `param` *remove_all* Whether to remove all occurrence of the callback or just once.\r\n* `return`\r\n\r\nRemove watcher from specified key.\r\n\r\n### Publish Config\r\n>`NacosClient.publish_config(data_id, group, content, timeout)`\r\n\r\n* `param` *data_id* Data id.\r\n* `param` *group* Group, use \"DEFAULT_GROUP\" if no group specified.\r\n* `param` *content* Config value.\r\n* `param` *timeout* Timeout for requesting server in seconds.\r\n* `return` True if success or an exception will be raised.\r\n\r\nPublish one data item to Nacos.\r\n* If the data key is not exist, create one first.\r\n* If the data key is exist, update to the content specified.\r\n* Content can not be set to None, if there is need to delete config item, use function **remove** instead.\r\n\r\n### Remove Config\r\n>`NacosClient.remove_config(data_id, group, timeout)`\r\n* `param` *data_id* Data id.\r\n* `param` *group* Group, use \"DEFAULT_GROUP\" if no group specified.\r\n* `param` *timeout* Timeout for requesting server in seconds.\r\n* `return` True if success or an exception will be raised.\r\n\r\nRemove one data item from Nacos.\r\n\r\n### Register Instance\r\n>`NacosClient.add_naming_instance(service_name, ip, port, cluster_name, weight, metadata, enable, healthy)`\r\n* `param` *service_name* **required** Service name to register to.\r\n* `param` *ip* **required** IP of the instance.\r\n* `param` *port* **required** Port of the instance.\r\n* `param` *cluster_name* Cluster to register to.\r\n* `param` *weight* A float number for load balancing weight.\r\n* `param` *metadata* Extra info in JSON string format or dict format\r\n* `param` *enable* A bool value to determine whether instance is enabled or not.\r\n* `param` *healthy* A bool value to determine whether instance is healthy or not.\r\n* `param` *ephemeral* A bool value to determine whether instance is ephemeral or not.\r\n* `return` True if success or an exception will be raised.\r\n\r\n### Deregister Instance\r\n>`NacosClient.remove_naming_instance(service_name, ip, port, cluster_name)`\r\n* `param` *service_name* **required** Service name to deregister from.\r\n* `param` *ip* **required** IP of the instance.\r\n* `param` *port* **required** Port of the instance.\r\n* `param` *cluster_name* Cluster to deregister from.\r\n* `param` *ephemeral* A bool value to determine whether instance is ephemeral or not.\r\n* `return` True if success or an exception will be raised.\r\n\r\n### Modify Instance\r\n>`NacosClient.modify_naming_instance(service_name, ip, port, cluster_name, weight, metadata, enable)`\r\n* `param` *service_name* **required** Service name.\r\n* `param` *ip* **required** IP of the instance.\r\n* `param` *port* **required** Port of the instance.\r\n* `param` *cluster_name* Cluster name.\r\n* `param` *weight* A float number for load balancing weight.\r\n* `param` *metadata* Extra info in JSON string format or dict format.\r\n* `param` *enable* A bool value to determine whether instance is enabled or not.\r\n* `param` *ephemeral* A bool value to determine whether instance is ephemeral or not.\r\n* `return` True if success or an exception will be raised.\r\n\r\n### Query Instances\r\n>`NacosClient.list_naming_instance(service_name, clusters, namespace_id, group_name, healthy_only)`\r\n* `param` *service_name* **required** Service name to query.\r\n* `param` *clusters* Cluster names separated by comma.\r\n* `param` *namespace_id* Customized group name, default `blank`.\r\n* `param` *group_name* Customized group name , default `DEFAULT_GROUP`.\r\n* `param` *healthy_only* A bool value for querying healthy instances or not.\r\n* `return` Instance info list if success or an exception will be raised.\r\n\r\n### Query Instance Detail\r\n>`NacosClient.get_naming_instance(service_name, ip, port, cluster_name)`\r\n* `param` *service_name* **required** Service name.\r\n* `param` *ip* **required** IP of the instance.\r\n* `param` *port* **required** Port of the instance.\r\n* `param` *cluster_name* Cluster name.\r\n* `return` Instance info if success or an exception will be raised.\r\n\r\n### Send Instance Beat\r\n>`NacosClient.send_heartbeat(service_name, ip, port, cluster_name, weight, metadata)`\r\n* `param` *service_name* **required** Service name.\r\n* `param` *ip* **required** IP of the instance.\r\n* `param` *port* **required** Port of the instance.\r\n* `param` *cluster_name* Cluster to register to.\r\n* `param` *weight* A float number for load balancing weight.\r\n* `param` *ephemeral* A bool value to determine whether instance is ephemeral or not.\r\n* `param` *metadata* Extra info in JSON string format or dict format.\r\n* `return` A JSON object include server recommended beat interval if success or an exception will be raised.\r\n\r\n### Subscribe Service Instances Changed\r\n>`NacosClient.subscribe(listener_fn, listener_interval=7, *args, **kwargs)`\r\n* `param` *listener_fn* **required** Customized listener function.\r\n* `param` *listener_interval* Listen interval , default 7 second.\r\n* `param` *service_name* **required** Service name which subscribes.\r\n* `param` *clusters* Cluster names separated by comma.\r\n* `param` *namespace_id* Customized group name, default `blank`.\r\n* `param` *group_name* Customized group name , default `DEFAULT_GROUP`.\r\n* `param` *healthy_only* A bool value for querying healthy instances or not.\r\n* `return`\r\n\r\n### Unsubscribe Service Instances Changed\r\n>`NacosClient.unsubscribe(service_name, listener_name)`\r\n* `param` *service_name* **required** Service name to subscribed.\r\n* `param` *listener_name* listener_name which is customized.\r\n* `return`\r\n\r\n### Stop All Service Subscribe \r\n>`NacosClient.stop_subscribe()`\r\n* `return`\r\n\r\n## Debugging Mode\r\nDebugging mode if useful for getting more detailed log on console.\r\n\r\nDebugging mode can be set by:\r\n```\r\nNacosClient.set_debugging()\r\n# only effective within the current process\r\n```\r\n\r\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Python client for Nacos.",
"version": "0.1.15",
"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": "486604b208eae999a9d28871a6456f13654a4dd1f05a22679961c000a58f90f4",
"md5": "18a1c4e1d38bb69d85be775766508407",
"sha256": "081595cd49781d5e47d765e6f401ba17f30935d87207cfc2ae42d181d1678380"
},
"downloads": -1,
"filename": "nacos_sdk_python_xing-0.1.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18a1c4e1d38bb69d85be775766508407",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22710,
"upload_time": "2024-06-20T10:30:19",
"upload_time_iso_8601": "2024-06-20T10:30:19.249986Z",
"url": "https://files.pythonhosted.org/packages/48/66/04b208eae999a9d28871a6456f13654a4dd1f05a22679961c000a58f90f4/nacos_sdk_python_xing-0.1.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "79ad7a816e068d52024af2807fdfe0c779f4067ff620138d6e883f3ff9483bb4",
"md5": "d2737d83fabd30217c05a59f311e447a",
"sha256": "e74641f129bbb58be47f34eda0efe8981eea74627f1f90b4edfe44e4a74a84c0"
},
"downloads": -1,
"filename": "nacos_sdk_python_xing-0.1.15.tar.gz",
"has_sig": false,
"md5_digest": "d2737d83fabd30217c05a59f311e447a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24210,
"upload_time": "2024-06-20T10:30:21",
"upload_time_iso_8601": "2024-06-20T10:30:21.873499Z",
"url": "https://files.pythonhosted.org/packages/79/ad/7a816e068d52024af2807fdfe0c779f4067ff620138d6e883f3ff9483bb4/nacos_sdk_python_xing-0.1.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-20 10:30:21",
"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,
"lcname": "nacos-sdk-python-xing"
}
JSON
