CalagoAPI

The Python SDK for Calagopus.

CalagoAPI wraps the whole Calagopus API (servers, files, backups, databases, schedules, networking, your account, and full panel administration) in a small, hand-written API that reads like plain Python.

from calagoapi import Panel

panel = Panel(
    url='https://panel.example.com',
    api_key='c7sp_...'
)

server = panel.servers.getServer('abc123')
server.sendCommand('say Hello')
server.restart()

if server.isOnline():
    print(server.getStatus(), server.getRAM(), server.getUptime(formatted=True))

backup = server.createBackup('before-update')

If you have used HungerLib, you already know CalagoAPI. The same objects and method names (Panel, GenericServer, MinecraftServer, getStatus(), isOnline(), createBackup(), listFiles(), ...) work here, backed by Calagopus.

Installation

pip install calagoapi

CalagoAPI needs Python 3.9+ and depends on requests and websockets.

Features

Quick tour

Status and resources

status = server.getStatus()        # 'running', 'offline', 'starting' or 'stopping'

if server.isOnline():
    print(server.getCPU(), '%')
    print(server.getRAM(), '/', server.getRAMLimit(), 'MiB')
    print(server.getUptime(formatted=True))  # '3h 12m'

server.isInstalled()
server.isSuspended()

Every important value has a getter and convenience checks, so you can inspect the exact state or just branch on it.

Live console

for line in server.streamConsole():
    if 'joined the game' in line:
        print(line)

with server.console as console:
    console.sendCommand('save-all')
    console.waitFor('Saved the game')

server.onConsoleLine(print)   # callbacks in a background thread

Async

from calagoapi import AsyncPanel

async with AsyncPanel(url='https://panel.example.com', api_key='c7sp_...') as panel:
    servers = await panel.servers.getServers()
    statuses = await asyncio.gather(*(server.getStatus() for server in servers))

    async for line in servers[0].streamConsole():
        print(line)

Files

for file in server.files.listFiles('/plugins'):
    print(file.getName(), file.getSize(formatted=True))

properties = server.readFile('/server.properties')
server.writeFile('/eula.txt', 'eula=true')
server.files.uploadFile('/plugins', 'build/MyPlugin.jar')
server.files.downloadFile('/world.zip', 'world.zip')

Backups

backup = server.createBackup('before-update')
backup.waitUntilComplete()

if backup.isSuccessful():
    print(backup.getSize(formatted=True))

backup.lock()
backup.restore(truncate_directory=True)

Schedules

from calagoapi import triggers, conditions, actions

server.schedules.createSchedule(
    'Nightly restart',
    triggers=[triggers.cron('0 0 4 * * *')],
    condition=conditions.serverState('running'),
    steps=[
        actions.sendCommand('say Restarting in 1 minute'),
        actions.sleep(60_000),
        actions.createBackup('nightly', foreground=True),
        actions.sendPower('restart'),
    ],
)

Databases

db = server.createDatabase('stats')
print(db.getConnectionString())

db.explorer.createTable('players', [
    {'name': 'id', 'type': 'INT', 'primary_key': True, 'auto_increment': True},
    {'name': 'name', 'type': 'VARCHAR(32)'},
])
db.explorer.insertRow('players', {'name': 'Steve'})
print(db.explorer.query('SELECT COUNT(*) FROM players'))

Minecraft

server = panel.servers.getMinecraftServer('abc123')

server.say('Server update in 5 minutes!')
server.setProperties({'max-players': 100, 'motd': 'Welcome!'})

latest = server.getBuilds('PAPER', '1.21.1', page=1, per_page=1)[0]
server.installVersion(latest)

Administration

user = panel.admin.users.createUser('steve', 'steve@example.com')

server = panel.admin.servers.deployServer(
    'Steve SMP', owner=user, egg=panel.admin.nests.findEgg('Paper'),
    locations=[panel.admin.locations.getLocationByName('Frankfurt')],
    memory=4096, disk=20480,
)

for node in panel.admin.nodes.getNodes():
    print(node.getName(), node.getSystemOverview()['version'])

Errors

from calagoapi import NotFoundError, PermissionDeniedError, CalagoAPIError

try:
    panel.servers.getServer('missing')
except NotFoundError:
    print('No such server')
except CalagoAPIError as e:
    print(e.status_code, e.errors)

Documentation

The docs folder has a guide for every area:

• Getting started
• Servers, Minecraft servers, Live console
• Files, Backups, Databases
• Schedules
• Network, subusers and tunnels
• Account and authentication
• Administration
• Async
• Errors, pagination and utilities
• Migrating from HungerLib
• Architecture

Every public class and method also has a docstring with parameters and an example, so help(server.files) works from a Python shell.

Development

pip install -e .[dev]
pytest

The tests run offline against openapi.json and a fake daemon. See Architecture.

License

GPL-3.0, see LICENSE.