Skip to content

Getting Started



python3 -m pip install -U hoist-http
py -m pip install -U hoist-http

From Source

git clone && cd hoist
pip install .

Basic Server

Once Hoist has ben installed, we can run a basic server to make sure everything is working properly.

In your terminal, run the following:

$ hoist serve -t test


The -t flag just specifies the authentication key used by the server. This can be any string that you want, and when left blank, Hoist will automatically create a secure random string for you.

Running this command will start the server on port 5000 by default.

You should see the following in your terminal:

startup: starting server on with token test

Now, open a new Python file and use the following to test that the server is working properly.

import hoist

async def main(server: hoist.Connection) -> None:
    await server.message("hi")

Now, running this file shouldn't have any output, but if we look at the server, it should now look something like this:

connect: connecting to
login: has successfully authenticated
disconnect: no longer receiving from

Congratulations! You have successfully written your first program with Hoist!


In the above code, you may have noticed something different about Hoist. Traditionally, you would instantiate some class and then use that in a context manager. Instead, we used the connect_with decorator. This is one of Hoist's utilities.

Hoist has several utilities to make things nicer for the developer and to minimize boilerplate code. The above is identical to the following code:

import hoist
import asyncio

async def main():
    async with hoist.connect("test") as server:
        await server.message("hi")

if __name__ == '__main__':

Sure, you could use this and it would work just fine, but writing it might waste time or get repetitive over time.

However, high-level utilities like that can have downsides. Something like connect_with only works for that single use case, and isn't very flexible.

There are alternatives for when you need it though. Hoist has a utility called main, which removes asyncio boilerplate:

# also identical to the above
import hoist

async def main():
    async with hoist.connect("test") as server:
        await server.message("hi")

# no need for!

Hoist even does some magic internally to replicate the if __name__ == '__main__'!