Skip to main content

Halcyon is an easy to use matrix library

Reason this release was yanked:

doesn't install right

Project description

Halcyon on and on

The goal of this project is to have an easy to install and use Matrix bot library similar to the Discord or Slack libs. Encryption must be transparent to the user. Check the roadmap in notes.md

Current features

  • A nice command prompt to generate Halcyon tokens
  • Login with token or username/password
  • Fetch for new messages every x seconds using await
  • Event hooks for
    • on_message(self, message)
    • on_message_edit(self, message)
    • on_room_invite(self, room)
    • on_room_leave(self, roomID)
  • Action hooks
    • send_message(self, roomID, body, textFormat=None, replyTo=None, isNotice=False)
    • async def join_room(self, roomID)
  • documentation
  • github whl builder

Getting started

  1. Create an account to use as a bot account
  2. Install using python3 -m pip install halcyon-matrix or using the Releases tab
  3. Generate a token using python3 -m halcyon -s homeserver.xyz -u @user:homeserver.xyz -p yourP@$$w0rd
  4. Start with the demo below

Example bot code

import halcyon
import requests, json

client = halcyon.Client()

@client.event
async def on_room_invite(room):
    """On room invite, autojoin and say hello"""
    print("Someone invited us to join " + room.name)
    await client.join_room(room.id)
    await client.send_message(room.id, body="Hello humans")


@client.event
async def on_message(message):
    """If we see a message with the phrase 'give me random', do a reply message with 32 random characters"""
    if "give me random" in message.content.body:
        body = "This looks random: " + requests.get("https://random.wesring.com").json()["value"]
        await client.send_message(message.room.id, body=body, replyTo=message.event.id)


if __name__ == '__main__':
    client.run(halcyonToken="eyJ0eXAiO...")

CLI usage

halcyon can be called from the CLI to do some managment of the account. See the readme with python3 -m halcyon -h

usage: halcyon [-h] [-s SERVER] [-u USERNAME] [-p PASSWORD] [--include-password] [--decode DECODE] [--pretty] [--revoke REVOKE] [--revoke-all-tokens REVOKE_ALL_TOKENS]

By this, you can generate a halcyonToken for your project, for example python3 -m halcyon -s matrix.org -u @kevin:matrix.org -p on&on&on1337

optional arguments:
  -h, --help            show this help message and exit
  -s SERVER, --server SERVER
                        Homeserver the user belongs to ex: matrix.org
  -u USERNAME, --username USERNAME
                        Your full username ex: @kevin:matrix.org
  -p PASSWORD, --password PASSWORD
                        Your full password for your matrix account
  --include-password    Save your username and password in the token for reauth (Not required right now since matrix tokens do not expire)
  --decode DECODE       Decode an existing token that you pass in
  --pretty              Pretty print the decoded token
  --revoke REVOKE       Revoke an existing token
  --revoke-all-tokens REVOKE_ALL_TOKENS
                        Revoke an all existing token for the account

Have fun creating

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

halcyon-matrix-1.0.2.tar.gz (12.9 kB view details)

Uploaded Source

Built Distribution

halcyon_matrix-1.0.2-py3-none-any.whl (13.3 kB view details)

Uploaded Python 3

File details

Details for the file halcyon-matrix-1.0.2.tar.gz.

File metadata

  • Download URL: halcyon-matrix-1.0.2.tar.gz
  • Upload date:
  • Size: 12.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.22.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.10

File hashes

Hashes for halcyon-matrix-1.0.2.tar.gz
Algorithm Hash digest
SHA256 611472071aefe463a06b3eaaff3b7548a9aa09ae0b1d80e78aab6a31cdce8789
MD5 2f097ea664e3c1a7c139b78ed197700a
BLAKE2b-256 ed776bb2f42bb7d9a58a8f91fb26739ea986989b90165fc10edd0720eb6d5883

See more details on using hashes here.

File details

Details for the file halcyon_matrix-1.0.2-py3-none-any.whl.

File metadata

  • Download URL: halcyon_matrix-1.0.2-py3-none-any.whl
  • Upload date:
  • Size: 13.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.22.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.10

File hashes

Hashes for halcyon_matrix-1.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 68e094978d5dc8577239bff06e5ffd6b9e7921678982831981543a549419d23a
MD5 8614b647f74c45374754defd83fee005
BLAKE2b-256 3b5989467736e5acd13ec121ca8166962509953d60a3122c13864e936675c5ff

See more details on using hashes here.

Supported by

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