Skip to content

BlistBotList/blist.py

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

21 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Blist API Wrapper for Python

Table of contents

  1. Getting started
  2. Installing
  3. Creating a Blist instance
  4. Using webhooks
  5. Reference

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).

  1. Create a virtual environment for installing the package and then proceed to activate the virtual environment.
  2. Run pip install -U blistpy. This will install everything required to make the package work.
  3. 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
    pass

Close 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
reddit str The user's Reddit username
snapchat str The user's Snapchat username
instagram str The user's Instagram username
twitter 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 of Blist. You must have an API token specified.
  • port (int) — The port to run the server on. Defaults to 8000.

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.