API reference
Storage
Save data between runs. Variables for small values, databases for tables, Mongo for big or nested data, and locks.
A command forgets everything when it finishes. To keep data, like coins, levels or warnings, save it with one of these.
| Use | For | Example |
|---|---|---|
server_var | One value for the whole server | A counter, a "giveaway is open" flag |
member_var | One value per member | Coins, XP, warnings |
temp_var | A value kept in memory only | A short-lived flag |
load_database | A table you made on the dashboard | A shop, a list of tickets |
SlashMongo | Big or nested data | Inventories, leaderboards, logs |
Not sure which to use? Read Saving data.
server_var#
Reads a server variable. Returns default when the variable does not exist.
server_var(name, default=None)count = int(server_var("counter", 0))Variables come back as text
Saved values are stored as text. "5" + 1 fails. Turn the value into a number first with int(...) or float(...).
You can also see and edit server variables on the dashboard under Variables.
update_server_var#
Saves a server variable. Makes it when it does not exist.
update_server_var(name, value)count = int(server_var("counter", 0)) + 1
update_server_var("counter", count)
set_content(f"This command was used {count} times.")member_var#
Reads a variable saved for one member. Returns default when it does not exist.
member_var(name, default=None, member=None)With no member, it uses the person who ran the command or caused the event.
coins = int(member_var("coins", 0))
set_content(f"You have {coins} coins.")update_member_var#
Saves a variable for one member.
update_member_var(name, value, member=None)coins = int(member_var("coins", 0, member=target))
update_member_var("coins", coins + 100, member=target)temp_var#
Reads a value kept in the bot's memory. Returns default when it is not set.
temp_var(name, default=None)Note
Temp values are lost when the bot restarts. A value of 0, "" or False also gives back default.
set_temp_var#
Keeps a value in memory for this server.
set_temp_var(name, value)load_database#
Opens a table you made on the dashboard under Variables → Databases.
db = load_database(database_id)The database ID is on the dashboard. A wrong ID stops the script with "Database not found."
Each row is a dictionary. It has an id and one key per column. Columns you do not fill in get their default value.
db.find#
Returns every row that matches, as a list.
db.find(where=None, sort=None)db.find_first#
Returns the first row that matches, or None.
db.find_first(where=None, sort=None)db.insert#
Adds a row. Returns the new row with its id.
db.insert(data)db.update#
Changes every row that matches. Returns {"updated": count}.
db.update(where, data)db.delete#
Deletes every row that matches. Returns {"deleted": count}.
db.delete(where)Filters#
where is a dictionary. Give a value to match it exactly, or a dictionary of filters.
| Filter | Matches when the column… |
|---|---|
gt, gte | is more than, or at least, the value |
lt, lte | is less than, or at most, the value |
not | is not the value |
contains, not_contains | has the text or item in it, or not |
startswith, endswith | starts or ends with the text |
in, not_in | is one of the values in a list, or not |
has_all, has_any | is a list that has all, or any, of the values |
sort is a dictionary of column names and "asc" or "desc".
Example: a shop
shop = load_database("shop_items")
cheap = shop.find(where={"price": {"lte": 500}}, sort={"price": "asc"})
set_content(listify([f"{item['name']}: {item['price']} coins" for item in cheap]))
shop.insert({"name": "Golden Hat", "price": 1200})
shop.update({"name": "Golden Hat"}, {"price": 999})
shop.delete({"name": "Golden Hat"})SlashMongo#
Opens a MongoDB collection for this server. Use it for big or nested data. Each server has its own databases, so names never clash with other servers.
col = SlashMongo(db_name, collection_name="main")Every method needs await.
| Method | What it does |
|---|---|
await col.insert_one(data) | Adds one document. |
await col.insert_many(list) | Adds many documents. |
await col.find_one(filter) | Returns the first match, or None. |
await col.find(filter) | Returns every match, as a list. |
await col.update_one(filter, change) | Changes the first match. |
await col.update_many(filter, change) | Changes every match. |
await col.delete_one(filter) | Deletes the first match. |
await col.delete_many(filter) | Deletes every match. |
await col.count(filter=None) | Counts matches. With no filter, counts all. |
await col.aggregate(pipeline) | Runs a MongoDB aggregation. |
Filters and changes use normal MongoDB syntax, like {"$inc": {"coins": 10}}.
Example: an inventory
inv = SlashMongo("economy", "inventory")
await inv.update_one(
{"user_id": str(user.id)},
{"$push": {"items": "Golden Hat"}},
upsert=True,
)
doc = await inv.find_one({"user_id": str(user.id)})
set_content(f"Your items: {', '.join(doc['items'])}")find and aggregate return at most 10,000 documents on free servers and 500,000 on premium.
You can look at Mongo data on the dashboard under Mongo Databases.
acquire_lock#
Stops the same thing running twice at once. When the lock is already taken, the script stops with an error.
acquire_lock(key, count=1, error=None)| Argument | What it does |
|---|---|
key | A name for the lock. |
count | How many runs may hold it at the same time. |
error | The message to show when the lock is taken. |
release_lock#
Frees a lock so the next run can take it.
release_lock(key)Example: one purchase at a time per member
key = f"buy-{user.id}"
acquire_lock(key, error="Your last purchase is still going. Wait a moment.")
coins = int(member_var("coins", 0))
update_member_var("coins", coins - 100)
release_lock(key)Watch out
Always release the lock. When the script stops between the two calls, for example with set_error, the lock stays taken until the bot restarts.