Python Installation Instructions

General Instructions

One of the following (with python3):

1. pip install corelink

Usage Instructions

API reference

API Documentation

Setting up Corelink

First, import Corelink:

import corelink

Environment

The corelink module runs on the async protocol, so all calls must be run in an async context. What this means is that you should define an asynchronous function, such as async def foo():, and put all the code there, and then run that function with corelink.run(foo()) in order to initialize the asyncio process.

Additionally, all corelink function calls should be made using the await keyword for them to work properly.

Control stream

Now, in your async context manager (like the foo() esxample above) you should run corelink.connect with the necessary parameters: * username is your username * password is your password * host is the host address of the server to connecting to * port is the server port to connect to

This function will connect to the server and initialize the control stream. If the authentication to the server fails, corelink will raise an error.

Various control functions can now be called to request information from or make changes to the server, as are detailed here.

Sending data

To send data over Corelink, you should first call create_sender with the necessary parameters: * workspace, protocol: str = "tcp", streamID="", data_type='', metadata='', sender="", ip="", port="" * workspace is the Corelink workspace you want to send data in. * protocol is the internet protocol you want to send over; currently, TCP ['tcp'] and UDP ['udp'] are supported. If omitted, tcp is selected by default. * Optional parameters: * streamID can be used to update an existing sender with these new settings as opposed to creating a new one. * data_type will specify a data type, so that receivers can 'subscribe' to only a particular type. * metadata is an optional parameter to give some metadata. * sender can be passed a name for the sender. * ip is the user's ip. * port is the user's port.

A connection will then be established with the server, if all goes well, and the sender's streamID will be returned to the user. This ID is used to call any functions on this stream, so don't lose it. But if you do, you can call active_streams to return a list of all the active streams' IDs.

After all this si set up, data can be sent using the send function with: * the streamID you want to send from * the data you want to send, which should be either a str or bytes object * an optional user_header to pass a dict with some header information.

That's it!

Receiving data

If you want to receive data, you should first create the necessary async callback function for data. It should expect data: bytes, streamID: int, header: dict and do whatever you want to do with the data. After defining that function, it should be passed into the set_data_callback function.

Then you should similarly call create_receiver with workspace, protocol, data_type, metadata, receiver_id, ip, port as explained above, and some more optional parameters: * stream_ids can be passed a list of streamIDs from which to receive data. * alert can be passed True to let the client know if a new stream of its type is created. * echo can be passed True to receive streams sent from the same username.

You should then begin receiving whatever data might come your way.

Sever control functions

The server also sometimes sends messages to you over the control channel. You can handle these messages by writing async callbacks expecting a message: dict from the server and key: str identifying the type of message received, and then passing that callback into set_server_callback along with the appropriate key. Details on these server messages can be found here.

Finishing up

When you're done, Corelink will automatically destroy all active streams and close down your connection. You can also initiate this process with a Keyboard Interrupt.

Lastly

Full simple examples can be found here, and the client documentation is available here