Skip to main content

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

Pypi Version License

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, 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

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/

Pypi Version 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

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, 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. with signature fn_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, 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")

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nacos-sdk-python-2.0.7.tar.gz (68.9 kB view details)

Uploaded Source

Built Distribution

nacos_sdk_python-2.0.7-py3-none-any.whl (93.6 kB view details)

Uploaded Python 3

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

Hashes for nacos-sdk-python-2.0.7.tar.gz
Algorithm Hash digest
SHA256 df698f1a6ce9ab7103de07ddbee8f4281a5d13c23ea12062173ea12079645123
MD5 15c21dcb86dd707714fabefe8918f04e
BLAKE2b-256 90e6e8d4205613ef2060de9089d4bf4f4c2064b230cb7905c7cff686c7c5c9dc

See more details on using hashes here.

File details

Details for the file nacos_sdk_python-2.0.7-py3-none-any.whl.

File metadata

File hashes

Hashes for nacos_sdk_python-2.0.7-py3-none-any.whl
Algorithm Hash digest
SHA256 068ec7d524c267438aa407ef243e9d0565309cff229b6fafe878ec50cd884040
MD5 f7795e867348e34c196cda678e101009
BLAKE2b-256 9d56949aad2c738ce1acd465591b8b6eb3949c28d317b56a6b02bd3441e0cb73

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page