axual-client-python 1.0.0a3

Axual client for Python

Axual Python Client

Python client library that enables interaction with the Axual platform.

Prerequisites

Python 3 is required, Python 3.6 or greater is recommended.

Installation

pip install axual-client-python

Testing

Tests are located in the tests/ directory. To run all of them:

python -m unittest discover tests

Project Overview

Usage

In each application, a client must be instantiated once.

from axualclient import ClientConfig, SslConfig, AxualClient

# Client configuration
conf = ClientConfig(endpoint = "https://url_to_discovery_api", # As provided during onboarding
                    tenant = "tenant",
                    environment = "env",
                    application_id = "groupname", # As defined in self-service
                    ssl_config = SslConfig(certificate_location = "./path/to/certificate/for/application.pem",
                                          private_key_location = "./path/to/private_key/for/application.key",
                                          root_ca_location = "./path/to/certificate/for/rootCAs.pem"),
                    )
# Instantiate the client
client = AxualClient(conf)

See SSL Configuration for more info on the certificates required in SslConfig.

The client can provide multiple producers and consumers to be used in the application, but also periodically calls the discovery API to check if a cluster switchover is required (and if so, makes sure the producers and consumers are switched).

Producer (String / JSON)

import json
p = client.get_producer('TopicName') # TopicName as defined in self-service
p.produce(value = json.dumps(dict(a = 1, b = "banana")))
p.flush() # Flushes producer before ending (triggering callbacks for delivery reports)

Consumer (String / JSON / AVRO)

c = client.get_consumer('TopicName') # TopicName as defined in self-service
## For consuming an AVRO topic, use:
# c = client.getAVROConsumer('TopicName')
for msg in c:
	# msg equals None if no new message
	if msg is not None:
		if msg.error():
			# Error handling
			print(msg.error().code())
		else:
			# Do some processing on the message
			print(msg.value().decode('utf-8'))
			# Commit message offset to the topic
			c.commit(msg)
	if somethinghappens:
		c.pause = True # Causes to break from for loop
# Cleanly unregister from cluster by closing consumer
c.close()

Producer (AVRO)

Producing AVRO messages works if you have the AVRO schema available that was uploaded to self-service. schema_value and schema_key can be either an AVRO schema (string), or the path to a file containing the schema. schema_key is optional and depends on whether the key has to be AVRO-serialized as well.

p = client.get_avro_producer('TopicName', schema_value = "./schema.avsc", schema_key = None)
p.produce(str(dict(a = 1, b = "banana")))
p.flush() # Flushes producer before ending (triggering callbacks for delivery reports)

SSL Configuration

The client configuration requires a correct SSL configuration in order to communicate securely with brokers, the discovery API, and the schema registry.
Each application (as defined in self-service) requires an application certificate (certificate_location in SslConfig) and corresponding private key (private_key_location). The application certificate must match the one uploaded in self-service for that application.
The file with root certificates needs to be created properly: The brokers might be using a root certificate authority different from the authority that signed the certificates for the discovery API and schema registry. The base64-encoded unencrypted versions of these certificates can be pasted into one file to use as certificate that root_ca_location in SslConfig points to. This file would then look like the following example:

-----BEGIN CERTIFICATE-----
MIIQdaGDAksKadksSDKNsdka5sjy8elAMsm3d .....
 ...  more base64-encoded content here ...
..... LKlmsf02mz2EWYnds=
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIPmsd92nNWlasHWdwMOe92nwoa2QNinnNaZ .....
 ...  more base64-encoded content here ...
..... ldFAf02SArubBW7wVFW2i1=
-----END CERTIFICATE-----

Examples

Simple use cases using the client code can be found in the Axual Python Client Examples.

Contributing

Axual is interested in building the community; we would welcome any thoughts or patches. You can reach us here.

See contributing.

License

Axual Python Client is licensed under the Apache License, Version 2.0.