Moobius Platform SDK
Project description
Welcome to Moobius Python SDK (Version 1.0.0)!
Quick Start (Requires Python 3.10+)
Setup your account
Register an account on Moobius. You have to enter an email and password to use this SDK. Third-party logins are not supported.
Install Moobius
If you just want to use the platform pip install moobius
is suffficient. However, the SDK is in Beta so it may be desirable to install it in editable mode:
git clone
or manually download the sdk-public source code.cd
into the the src directory (./src
with respect to this file).pip install -e .
. Note the lack of a "moobius" argument!
The e
indicates "editable" and it will install the local package in the given folder to the PYTHONPATH
instead of pulling from the PyPy site. The file src/setup.py
tells pip that the name is "Moobius".
Test Moobius
Test Moobius by creating a channel, running a Demo feature-suite servicing, and testing the features.
- In the browser, create a channel on Moobius. It will tell you it's unique
channel_id
. cd
intoprojects/demo
(or a copy of this folder).- Rename
./config/(example service).json
toservice.json
and./config/(example agent).json
toagent.json
- Enter your credentials and the
channel_id
you obtained intoservice.json
. - (Optional) create an alt-account and enter those credentials into
agent.json
. - Add the lines
*/config/service.json
and*/config/agent.json
to your.gitignore
to keep these secrets safe! cd
into the folde andpython main.py
. Make sure it continues to run and does not spew excessive amounts of errors.- In the browser, navigate to the channel you created. Hit refresh a few times until you see a list of buttons ("Swap Stage", "Channels", "Commands", etc). It should take around 30 seconds to fully load.
- Test the various buttons to make sure the button options either work (or give a warning message that they are expiremental).
- Press "Commands" to see a message with commands to run. Test these commands. Some need to be sent to the "service" instead of the "all" to work. Note that Agent features will only work if the Agent has been setup.
Expriement!
Congratulations! Now you have your first Moobius Service. The demo contains service.py
and agent.py
which together test most SDK features. Each one overrides the base MoobiusClient
class. The code is driven by async callbacks which can in turn send commands up to the service to i.e. send particular messages to particular users.
Glossery / Reference
-
Tutorials: In
projects/demo
there areDemoServiceTutorial.md
andDemoAgentTutorial.md
walkthroughs. -
Service: The Service handles most of the interaction with the platform SDK. This includes sending and responding to messages, controlling the look and feel, and uploading assets. Callbacks have the format
on_xyz
and actuators have the formatsend_xyz
. JSON is automatically converted to and from dataclasses withintypes.py
. -
Agent: Like service, the agent overrides the
MoobiusClient
class and is constructed withis_agent
set to True. However, the agent is more limited in it's functionality: it cannot do much besides sending and recieving messages and modifying itself. Most other functions will generate an error. To use an agent under a given account requires knowing the secret credentials. Services callsend_message_down
while users and agents callsend_message_up
. -
Databases: Databases are client-side and represented as
MoobiusStorage
instances. The structure is determined by a configuration file (usually./config/db.json
). Each element has aname
that is directly written instance's attributes. Each element also contains animplementation
which determines the database engine; currently "json" and "redis" is supported. The Demo by default will only run "redis" on Linux and Mac. -
Logging: Logging uses Loguru, a colorful, comprehensive logging system. Simply replace
print
withlogging.info()
,logging.error()
, orlogging.error()
for a thread-safe logging that also saves to the disk. It has plenty of other features as well. -
Wand: The
MoobiusWand
class launches and manages one or more services. The services can either run on the Wand's process (recommended for simple tasks) or on a seperate process withbackground=True
. Using a background service requires moving initialization of unpickable objects toon_start()
. Usewand.spell()
orawait wand.aspell()
to have the wand interact with the service by calling theon_spell()
callback.
Database Details
As mentioned before, databases allow persistant storage and support redis. Each custom attribute of a MoobiusStorage
instance is a CachedDict
which in turn implements __getitem__
, __setitem__
, and __delitem__
. This means that it can be used as a dict and will automatically save whenever it is modified. However, the value itself may be in turn a mutable data structure. In which case CachedDict
will not be aware of this change and a call to cached_dict.save(key)
is needed to serialize and save the value to the database.
Custom database engines can be implemented by following these steps:
- Inherit the
DatabaseInterface
class and specifying the engine. - Choose a name.
- Add the name to the
get_engine
function in storage.py. - Use the name in the database config file.
In addition to name
and implementation
, each database field defined in the configuration has load
and clear
booleans. Usually load
is True and clear
is False. (Experimental) load
can be False to not load everything at once for optimization. If clear
is True, the databasse will be cleared from the disk on init and load
does not matter.
File and Class Organization Details
The code is divided into the core logic, the database, and the network.
projects/demo
: The Demo example Service and Agent. If desired, other Services and/or agents can be put into the projects folder.
src/moobius
: The source code itself.
core/
: The core logic of the SDK including Services, Agents, and databases.sdk.py
: DefinesMoobiusClient
which integrates database and high-level commonly used helper methods. It is the base class of a Service or Agent.storage.py
: DefinesMoobiusStorage
which acts as a container of backed-up dictionaries (CachedDict
instances)wand.py
: DefinesMoobiusWand
which handles all the multiprocessing and remote control magic.
database/
: The infrastructure ofMoobiusStorage
.database_interface.py
: DefinesDatabaseInterface
, an abstract base class used by each of the below implementations.null_database.py
: DefinesNullDatabase
which is likedev/null
.json_database.py
: DefinesJSONDatabase
which uses json files and stores plaintext.redis_database.py
: DefinesRedisDatabase
which requires a running Redis server to function.magical_storage.py
: Defines several classes.CachedDict
is used like a dictionary but has a database under the hood.MagicalStorage
is built onCachedDict
and supports customized on-the-flyCachedDict
containers.
network/
: Network communication with the Platform.http_api_wrapper.py
: DefinesHTTPAPIWrapper
which mirrors the Platform's low-level HTTP API. Used byMoobiusClient
instances.ws_client.py
: DefinesWSClient
which mirrors the Platform's low-level Socket API. Used byMoobiusClient
instances.
types.py
: Defines the dataclasses:ButtonArgument
andButton
,ButtonClickArgument
andButtonClick
,Stage
,View
,Group
,MessageContext
andMessageBody
,Action
,ChannelInfo
,Copy
andPayload
andCharacterContext
andCharacter
. Each class is a very simple data-structure and is easily converted to/from a dict.utils.py
: DefinesEnhancedJSONEncoder
which allows certain classes to be JSON encoded.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.