Blist API Wrapper for Python
Table of contents
Getting started
This is the documentation for the Blist API wrapper written in Python. You'll want to make sure to check out the table of contents for information on installing and getting the Blist API wrapper working correctly. You need to be using discord.py and be using the bot commands extension in your project to be able to use this API wrapper.
Installing
It is assumed that you have basic knowledge of using the command line and using PyPi (pip).
- Create a virtual environment for installing the package and then proceed to activate the virtual environment.
- Run
pip install -U blistpy. This will install everything required to make the package work. - Congratulations, you've completed the installation of the Blist API wrapper.
Creating a Blist instance
Import the Blist wrapper by putting import blist at the top of your main bot file. This will import the wrapper into the file so you can start using it.
Once you have imported the wrapper, you need to create an instance of Blist. Blist takes a Bot or AutoShardedBot instance and your Blist API token. It should look something like below. You can omit token="your blist token" if you don't need to make any authorized requests.
import blist
blist_api = blist.Blist(bot, token="your blist token")It's time to begin making requests. Check out the reference for a full list of methods.
Using webhooks
In Blist, webhooks are used to send a request to your server whenever your bot is upvoted. This can be utilized in many ways, usually for vote locking without having to constantly poll the server to see if someone has upvoted the bot.
You can easily setup a webhook server by using the included server. The code below creates an instance of WebhookServer and runs it. Once you run it, whenever a user upvotes your bot, an on_blist_vote event will be fired containing the user ID of the user and the time they upvoted it.
Run webhook server
import blist
blist_api = blist.Blist(bot, token="your blist token")
webhook = blist.WebhookServer(blist_api)
await webhook.run()Receive vote event
# Outside of a cog
@bot.event
async def on_blist_vote(user_id, time):
# process upvote
pass
# Inside of a cog
@commands.Cog.listener()
async def on_blist_vote(self, user_id, time):
# process upvote
passClose webhook server
import blist
blist_api = blist.Blist(bot, token="your blist token")
webhook = blist.WebhookServer(blist_api)
await webhook.run()
await webhook.close()Reference
blist.Blist(bot, token=None)
Client interface for interacting with the entire Blist API.
Parameters
-
bot (
commands.Bot) — Discord bot instance to be used with the API. -
token (Optional[
str]) — Blist API token. This isn't required if you do not need authorization.
await blist.Blist.fetch_bot(bot_id=None)
This method is a coroutine.
Fetches information about a bot. Does not require authorization.
Parameters
-
bot_id (Optional[
int]) — The ID of the bot to fetch information about. Defaults to the current bot.
Raises
blist.errors.UnknownBot — The bot was not found on the list.
Returns
| Attribute | Type | Description |
|---|---|---|
| id | int |
Bot ID |
| name | str |
Name of the bot |
| main_owner | int |
ID of the main owner of the bot |
| owners | str |
The secondary bot owner IDs |
| library | str |
The library the bot was programmed in |
| website | str |
Link to the bot's website |
| github | str |
Link to the bot's GitHub repository |
| short_description | str |
Short description of the bot |
| long_description | str |
Long description of the bot |
| prefix | str |
The bot's prefix |
| invite_url | str |
Link to the invite URL of the bot |
| support_server | str |
The bot's support guild invite code |
| tags | List[str] |
List of the bot's tags on the Blist website |
| monthly_votes | int |
Amount of votes the bot has gotten within a month |
| total_votes | int |
Amount of votes the bot has gotten in all time |
| certified | bool |
Whether the bot is certified on the Blist website |
| vanity_url | str |
The vanity URL to the bot on the Blist website |
| server_count | int |
Amount of guilds the bot is in |
| shard_count | int |
Amount of shards the bot is using |
| add_date | datetime.datetime |
The date the bot was added to the Blist website |
| invites | int |
Amount of times the bot has been invited from the Blist website |
| page_views | int |
Amount of views the bot's page has received |
| donate_url | str |
Link to the bot's donate page |
| avatar_hash | str |
The bot's avatar hash |
| privacy_policy_url | str |
Link to the bot's privacy policy URL |
| status | str |
The bot's current status |
Return Type
blist.models.Bot
await blist.Blist.post_bot_stats()
This method is a coroutine.
Posts bot statistics to the Blist website. Requires authorization.
Raises
blist.errors.InvalidData — Invalid guild or shard count sent to the server. Normally, you will not receive this.
blist.errors.InvalidAuthorization — Invalid token provided or you did not specify a token.
blist.errors.UnknownBot — The bot was not found on the list.
await blist.Blist.fetch_user_info(user_id)
This method is a coroutine.
Fetches information about a user. Does not require authorization.
Parameters
-
user_id (
int) — The ID of the user to fetch information about.
Raises
blist.errors.InvalidData — The user ID must be an int.
blist.errors.UnknownUser — The user's account was not found on the list.
Returns
| Attribute | Type | Description |
|---|---|---|
| id | int |
User ID |
| bio | str |
User's biography |
| staff | bool |
Whether the user is staff |
| joined_at | datetime.datetime |
The date the user created an account on the Blist website |
str |
The user's Reddit username | |
| snapchat | str |
The user's Snapchat username |
str |
The user's Instagram username | |
str |
The user's Twitter handle | |
| github | str |
The user's GitHub username |
| website | str |
Link to the user's website |
| bots | int |
Amount of bots the user has on the Blist website |
Return Type
blist.models.User
await blist.Blist.fetch_bot_votes()
This method is a coroutine.
Fetches monthly and total votes. This also returns users who have voted for your bot. Requires authorization.
Raises
blist.errors.InvalidAuthorization — Invalid token provided or you did not specify a token.
blist.errors.UnknownBot — The bot was not found on the list.
Returns
blist.models.Votes
| Attribute | Type | Description |
|---|---|---|
| monthly | int |
Amount of votes the bot has gotten within a month |
| total | int |
Amount of votes the bot has gotten in all time |
| votes | List[blist.models.Vote] |
List of users who have voted for your bot and the time they did so |
blist.models.Vote
| Attribute | Type | Description |
|---|---|---|
| userid | int |
The ID of the user who voted |
| time | datetime.datetime |
The timestamp of when the user voted |
Return Type
blist.models.Votes
await blist.Blist.fetch_bot_reviews()
This method is a coroutine.
Fetches the reviews a bot has recieved. Requires authorization.
Raises
blist.errors.InvalidAuthorization — Invalid token provided or you did not specify a token.
blist.errors.UnknownBot — The bot was not found on the list.
Returns
blist.models.Reviews
| Attribute | Type | Description |
|---|---|---|
| reviews | List[blist.models.Review] |
List of reviews on the bot. Contains the feedback, whether it is recommended and the time |
blist.models.Review
| Attribute | Type | Description |
|---|---|---|
| feedback | str |
The way the reviewing user felt about the bot |
| recommended | bool |
Whether the reviewing user recommends the bot to other users |
| time | datetime.datetime |
The timestamp of when the user left the review |
Return Type
blist.models.Reviews
await blist.Blist.close()
This method is a coroutine.
Disallows the blist.Blist instance from being used to make anymore requests to the API.
Note: You must run this when stopping your bot.
blist.WebhookServer(blist, port=8000)
This method has been disabled until further notice.
Server for receiving upvote events and dispatching them.
Parameters
-
blist (
blist.Blist) — An instance ofBlist. You must have an API token specified. -
port (
int) — The port to run the server on. Defaults to8000.
Dispatch Event
on_blist_vote
Dispatch Parameters
-
user_id (
int) — The ID of the user who upvoted the bot. -
time (
datetime.datetime) — The timestamp of when the user upvoted the bot.
await blist.WebhookServer.run()
This method has been disabled until further notice.
This method is a coroutine.
Starts the webhook server and allows it to serve requests.
Note: You do not need to run this method in a task, everything is handled for you.
await blist.WebhookServer.close()
This method has been disabled until further notice.
This method is a coroutine.
Stops the webhook server and disallows it from serving requests.
Note: You must run this when stopping your bot if the server is currently running.
