MagistralPython
MagistralPython is a messaging library written in Python.
Features Requirements Usage
- Features
- Requirements
- Installation
-
Usage
- Intro - Prerequisites, Key-based access
- Connecting - Connecting
- Resources - Topics
- Publish / Subscribe - Publish, Subscribe
- History - History, History for Time Interval
- Access Control - Permissions, Grant permissions, Revoke permissions
Features
- Send / receive data messages
- Replay (Historical data)
- Resource discovery
- Access Control
- TLS-encrypted communication
- Client-side AES-encryption
Requirements
- Python 3.5+
Installation
Python Package Manager
Just run the following command:
$ pip install magistral
Usage
Prerequisites
First of all, to stream data over Magistral Network you need to have an Application created. If you don't have any of them yet, you can easily create one from Customer Management Panel (via start page or in Application Management section).
Also, you need to have at least one topic created, that you can do from Topic Management panel.
Key-based access
Access to the Magistral Network is key-based. There are three keys required to establish connection:
- Publish Key - Application-specific key to publish messages.
- Subscribe Key - Application-specific key to read messages.
- Secret Key - User-specific key to identify user and his permissions.
You can find both Publish Key and Subscribe Key in Application Management section. Select your App in the list and click Clipboard icons in App panel header to copy these keys into the Clipboard.
Secret Key - can be found among user permissions in User Management section. You can copy secret key linked to user permissions into the Clipboard, just clicking right button in the permission list.
Connecting
To establish connection with Magistral Network you need to create Magistral instance and provide pub, sub and secret keys.
from magistral.client.Magistral import Magistral
magistral = Magistral(
pubKey = "pub-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
subKey = "sub-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
secretKey = "s-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
Topics
To discover all available topics and channels you can call:
def callback(meta):
for mi in meta:
for ch in mi.channels():
print("%s:%d", mi.topic(), ch);
magistral.topics(lambda meta : callback(meta))
In case you know the topic name and want to see information about channels:
def callback(meta):
for mi in meta:
for ch in mi.channels():
print("%s:%d", mi.topic(), ch);
magistral.topic("topic", lambda meta : callback(meta))
Publish
You can send data message to Magistral in this way:
topic = "topic"
channel = 0
msg = "Hello from Python SDK!"
def callback(meta):
assert(meta != None)
magistral.publish(topic, bytes(msg, 'utf8'), channel, lambda meta : callback(meta))
Subscribe
This is an example how to subscribe and handle incoming data messages:
topic = "topic"
group = "leader"
channel = 0
def listener(message):
print("Got a message => [%s:%d] index = %d", message.topic(), message.channel(), message.index());
def callback(meta, err):
assert(err is None)
magistral.subscribe(topic, group, channel, lambda message : listener(message), lambda meta, err : callback(meta, err))
History
Magistral allows you to replay data sent via some specific topic and channel. This feature called History. To see last n-messages in the channel:
topic = "topic"
channel = 0
count = 100
def histCallback(h):
assert(h is not None);
assert(len(h) == i);
magistral.history(topic, channel, count, lambda h : histCallback(h))
You can also provide timestamp to start looking messages from:
topic = "topic"
channel = 0
count = 100
timestamp = 1471099313117
def histCallback(h):
assert(h is not None);
assert(len(h) == i);
magistral.history(topic, channel, count, timestamp, lambda h : histCallback(h))
History for Time Interval
Historical data in Magistral can be obtained also for some period of time. You need to specify start and end date:
topic = "topic"
channel = 0
count = 100
start = 1471099313117
end = 1471099313117
def callback(h):
assert(h is not None);
assert(len(h) == i);
magistral.historyIn(topic, channel, start, end, lambda h : callback(h))
Permissions
This is a part of Access Control functionality. First of all, to see the full list of permissions:
def callback(perms):
for mi in meta:
for ch in mi.channels():
print("%s:%d -> (r:w) .. %r:%r", mi.topic(), ch, mi.readable(ch), mi.writable(ch));
magistral.permissions(None, lambda perms : callback(json));
Or if you are interested to get permissions for some specific topic:
def callback(perms):
for mi in meta:
for ch in mi.channels():
print("%s:%d -> (r:w) .. %r:%r", mi.topic(), ch, mi.readable(ch), mi.writable(ch));
magistral.permissions("topic", lambda perms : callback(json));
Grant permissions
You can also grant permissions for other users:
let user = "user"
let topic = "topic"
let channel = 0
let ttl = -1 // permanent permissions
let r = True
let w = True
def callback(perms, err):
assert(err == None)
magistral.grant(user, topic, r, w, ttl, channel, lambda perms, err : callback(perms, err));
You must have super user priveleges to execute this function.
Revoke permissions
In similar way you can revoke user permissions:
let user = "user"
let topic = "topic"
let channel = -1 // all channels
def callback(perms, err):
assert(err == None)
magistral.grant(user, topic, channel, lambda perms, err : callback(perms, err));
You must have super user priveleges to execute this function.
License
Magistral is released under the MIT license. See LICENSE for details.