Skip to content

Commit 06fc8b3

Browse files
franc-istfranc-ist
committed
updated the docstrings and added basic ratelimit handling
1 parent 45e591c commit 06fc8b3

7 files changed

Lines changed: 267 additions & 170 deletions

File tree

‎README.rst‎

Lines changed: 37 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
1-
DBL Python Library
1+
DBL Python Library
22
==================
33
.. image:: https://img.shields.io/pypi/v/dblpy.svg
44
:target: https://pypi.python.org/pypi/dblpy
55
:alt: View on PyPi
66
.. image:: https://img.shields.io/pypi/pyversions/dblpy.svg
77
:target: https://pypi.python.org/pypi/dblpy
8-
:alt: v0.1.3
9-
.. image:: https://readthedocs.org/projects/dblpy/badge/?version=v0.1.3
10-
:target: http://dblpy.readthedocs.io/en/latest/?badge=v0.1.3
8+
:alt: v0.1.4
9+
.. image:: https://readthedocs.org/projects/dblpy/badge/?version=v0.1.4
10+
:target: http://dblpy.readthedocs.io/en/latest/?badge=v0.1.4
1111
:alt: Documentation Status
1212

1313
A simple API wrapper for `discordbots.org`_ written in Python
@@ -25,9 +25,7 @@ Install from source
2525

2626
.. code:: bash
2727
28-
git clone https://github.com/DiscordBotList/DBL-Python-Library
29-
cd DBL-Python-Library
30-
pip install -R requirements.txt
28+
pip install git+https://github.com/DiscordBotList/DBL-Python-Library
3129
3230
Documentation
3331
-------------
@@ -53,28 +51,44 @@ Example
5351

5452
.. code:: py
5553
56-
import dblpy
57-
from dblpy import Client
58-
import asyncio
54+
import dbl
55+
import discord
56+
from discord.ext import commands
57+
5958
import aiohttp
60-
import json
59+
import asyncio
60+
import logging
61+
62+
63+
class DiscordBotsOrgAPI:
64+
"""Handles interactions with the discordbots.org API"""
65+
66+
def __init__(self, bot):
67+
self.bot = bot
68+
self.token = 'dbl_token' # set this to your DBL token
69+
self.dblpy = dbl.Client(self.bot, self.token)
70+
self.bot.loop.create_task(self.update_stats())
6171
62-
dbl = dblpy.Client()
72+
async def update_stats(self):
73+
"""This function runs every 30 minutes to automatically update your server count"""
6374
64-
botid = 264811613708746752 # your bots user id (client id on newer bots)
65-
token = 'abcxyz' # DBL Bot Token. Obtainable from https://discordbots.org/api
75+
while True:
76+
logger.info('attempting to post server count')
77+
try:
78+
await self.dblpy.post_server_count()
79+
logger.info('posted server count ({})'.format(len(self.bot.guilds)))
80+
except Exception as e:
81+
logger.exception('Failed to post server count\n{}: {}'.format(type(e).__name__, e))
82+
await asyncio.sleep(1800)
6683
67-
class Example:
68-
def __init__(bot):
69-
bot = bot
70-
session = aiohttp.ClientSession(loop=bot.loop)
84+
def __unload(self):
85+
self.bot.loop.create_task(self.session.close())
7186
72-
async def poststats():
73-
await dblpy.post_server_count(botid, dbltoken, 65)
7487
75-
async def getstats():
76-
resp = await dblpy.get_server_count(botid)
77-
print(json.dumps(resp))
88+
def setup(bot):
89+
global logger
90+
logger = logging.getLogger('bot')
91+
bot.add_cog(DiscordBotsOrgAPI(bot))
7892
7993
8094
.. _discordbots.org: https://discordbots.org/

‎dbl/__init__.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
__author__ = 'Francis Taylor'
1313
__license__ = 'MIT'
1414
__copyright__ = 'Copyright 2018 Francis Taylor'
15-
__version__ = '0.1.3'
15+
__version__ = '0.1.4'
1616

1717
from collections import namedtuple
1818

@@ -22,4 +22,4 @@
2222

2323
VersionInfo = namedtuple('VersionInfo', 'major minor micro releaselevel serial')
2424

25-
version_info = VersionInfo(major=0, minor=1, micro=3, releaselevel='final', serial=0)
25+
version_info = VersionInfo(major=0, minor=1, micro=4, releaselevel='final', serial=0)

‎dbl/client.py‎

Lines changed: 58 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -30,27 +30,27 @@
3030
from .errors import *
3131
from .http import HTTPClient
3232

33-
BASE = 'https://discordbots.org/api'
34-
3533

3634
class Client:
3735
"""Represents a client connection that connects to discordbots.org.
3836
This class is used to interact with the DBL API.
3937
4038
.. _event loop: https://docs.python.org/3/library/asyncio-eventloops.html
4139
.. _aiohttp session: https://aiohttp.readthedocs.io/en/stable/client_reference.html#client-session
40+
4241
Parameters
43-
----------
42+
==========
43+
4444
token :
45-
An API Token
45+
An API Token
4646
4747
bot :
48-
An instance of a discord.py Bot or Client object
49-
48+
An instance of a discord.py Bot or Client object
5049
**loop : Optional[event loop].
5150
The `event loop`_ to use for asynchronous operations.
5251
Defaults to ``bot.loop``.
53-
**session : Optional
52+
**session : Optional
53+
The aiohttp session to use for requests to the API.
5454
"""
5555

5656
def __init__(self, bot, token, **kwargs):
@@ -60,7 +60,7 @@ def __init__(self, bot, token, **kwargs):
6060
self.http = HTTPClient(token, loop=self.loop, session=kwargs.get('session'))
6161
self._is_closed = False
6262
self.loop.create_task(self.__ainit__())
63-
#print(self.loop.run_until_complete(bot.application_info()).id)
63+
# print(self.loop.run_until_complete(bot.application_info()).id)
6464

6565
async def __ainit__(self):
6666
await self.bot.wait_until_ready()
@@ -73,10 +73,10 @@ def guild_count(self):
7373
return len(self.bot.servers)
7474

7575
async def post_server_count(
76-
self,
77-
shard_count: int = None,
78-
shard_no: int = None
79-
):
76+
self,
77+
shard_count: int = None,
78+
shard_no: int = None
79+
):
8080
"""This function is a coroutine.
8181
8282
Posts the server count to discordbots.org
@@ -86,10 +86,10 @@ async def post_server_count(
8686
Parameters
8787
==========
8888
89-
shard_count: int
90-
(Optional) The total number of shards.
91-
shard_no: int
92-
(Optional) The index of the current shard. DBL uses `0 based indexing`_ for shards.
89+
shard_count: int[Optional]
90+
The total number of shards.
91+
shard_no: int[Optional]
92+
The index of the current shard. DBL uses `0 based indexing`_ for shards.
9393
"""
9494
await self.http.post_server_count(self.bot_id, self.guild_count(), shard_count, shard_no)
9595

@@ -108,8 +108,8 @@ async def get_server_count(self, bot_id: int=None):
108108
Returns
109109
=======
110110
111-
bot info: dict
112-
https://discordbots.org/api/docs#bots
111+
stats: dict
112+
The server count and shards of a bot.
113113
The date object is returned in a datetime.datetime object
114114
115115
"""
@@ -122,20 +122,24 @@ async def get_upvote_info(self, **kwargs):
122122
123123
Gets information about who upvoted a bot from discordbots.org
124124
125-
**Available to the owner of the bot only.**
125+
.. note::
126+
127+
This API endpoint is available to the owner of the bot only.
126128
127129
Parameters
128130
==========
131+
129132
**onlyids: bool[Optional]
130-
Whether to return an array of simple user objects or an array of ids
133+
Whether to return an array of simple user objects or an array of user ids.
131134
Defaults to False
132135
**days: int[Optional]
133136
Limits the votes to ones done within the amount of days you specify.
134137
Defaults to 31
135138
136139
Returns
137140
=======
138-
votes: json
141+
142+
votes: dict
139143
Info about who upvoted your bot.
140144
141145
"""
@@ -159,55 +163,9 @@ async def get_bot_info(self, bot_id: int = None):
159163
Returns
160164
=======
161165
162-
defAvatar: str
163-
The bot_id of the default avatar of the bot.
164-
avatar: str
165-
The bot_id of the bots avatar. Use `https://discordapp.com/assets/{:avatar}.png`
166-
invite: str
167-
The instant invite URL.
168-
github: str
169-
The URL of the Github repository.
170-
website: str
171-
The website of the bot.
172-
intdesc: str
173-
The raw contents of the bots int description.
174-
shortdesc: str
175-
The bots short description.
176-
prefix: str
177-
The prefix of the bot.
178-
lib: str
179-
The library wrapper the bot was written in.
180-
clientid: int
181-
The Client bot_id of the bot. Used in the instant invite URL.
182-
bot_id: int
183-
The bot_id of the bot.
184-
username: str
185-
The name of the bot.
186-
discrim: int
187-
The discriminator of the bot.
188-
date: datetime
189-
The datetime object of when the bot was added to DBL.
190-
server_count: int
191-
The server count of the bot.
192-
shard_count: int
193-
The shard count of the bot.
194-
vanity: str
195-
The DBL vanity URL of the bot (partnered bots only).
196-
support: str
197-
The invite code for the bots support server.
198-
shards: json
199-
JSON object containing information about individual shards and their server count.
200-
points: int
201-
The number of upvotes the bot has.
202-
certifiedBot: bool
203-
Whether the bot is certified.
204-
owners: json
205-
JSON object containing a list of the bot owners.
206-
tags: json
207-
JSON object containing a list of tags.
208-
legacy: bool
209-
Is the bot using the old profile format?
210-
True if the bot hasn't been edited since 2017-12-31.
166+
bot info: dict
167+
Information on the bot you looked up.
168+
https://discordbots.org/api/docs#bots
211169
"""
212170
if bot_id is None:
213171
bot_id = self.bot_id
@@ -221,17 +179,17 @@ async def get_bots(self, limit: int = 50, offset: int = 0):
221179
Parameters
222180
==========
223181
224-
limit: int
225-
(Optional) The number of results you wish to lookup. Defaults to 50.
226-
offset: int
227-
(Optional) The page number to search. Defaults to 0.
182+
limit: int[Optional]
183+
The number of results you wish to lookup. Defaults to 50.
184+
offset: int[Optional]
185+
The page number to search. Defaults to 0.
228186
229187
Returns
230188
=======
231189
232-
bots: json
190+
bots: dict
233191
Returns info on the bots on DBL.
234-
192+
https://discordbots.org/api/docs#bots
235193
"""
236194
return await self.http.get_bots(limit, offset)
237195
#
@@ -281,22 +239,23 @@ async def get_user_info(self, user_id: int):
281239
Returns
282240
=======
283241
284-
user_data: json
242+
user_data: dict
285243
Info about the user.
244+
https://discordbots.org/api/docs#users
286245
"""
287246
return await self.http.get_user_info(user_id)
288247

289248
async def generate_widget_large(
290-
self,
291-
bot_id: int = None,
292-
top: str = '2C2F33',
293-
mid: str = '23272A',
294-
user: str = 'FFFFFF',
295-
cert: str = 'FFFFFF',
296-
data: str = 'FFFFFF',
297-
label: str = '99AAB5',
298-
highlight: str = '2C2F33'
299-
):
249+
self,
250+
bot_id: int = None,
251+
top: str = '2C2F33',
252+
mid: str = '23272A',
253+
user: str = 'FFFFFF',
254+
cert: str = 'FFFFFF',
255+
data: str = 'FFFFFF',
256+
label: str = '99AAB5',
257+
highlight: str = '2C2F33'
258+
):
300259
"""This function is a coroutine.
301260
302261
Generates a custom large widget. Do not add `#` to the color codes (e.g. #FF00FF become FF00FF).
@@ -324,7 +283,7 @@ async def generate_widget_large(
324283
Returns
325284
=======
326285
327-
URL with the widget.
286+
URL of the widget: str
328287
"""
329288
if bot_id is None:
330289
bot_id = self.bot_id
@@ -346,22 +305,22 @@ async def get_widget_large(self, bot_id: int = None):
346305
Returns
347306
=======
348307
349-
URL with the widget.
308+
URL of the widget: str
350309
"""
351310
if bot_id is None:
352311
bot_id = self.bot_id
353312
url = 'https://discordbots.org/api/widget/{0}.png'.format(bot_id)
354313
return url
355314

356315
async def generate_widget_small(
357-
self,
358-
bot_id: int = None,
359-
avabg: str = '2C2F33',
360-
lcol: str = '23272A',
361-
rcol: str = '2C2F33',
362-
ltxt: str = 'FFFFFF',
363-
rtxt: str = 'FFFFFF'
364-
):
316+
self,
317+
bot_id: int = None,
318+
avabg: str = '2C2F33',
319+
lcol: str = '23272A',
320+
rcol: str = '2C2F33',
321+
ltxt: str = 'FFFFFF',
322+
rtxt: str = 'FFFFFF'
323+
):
365324
"""This function is a coroutine.
366325
367326
Generates a custom large widget. Do not add `#` to the color codes (e.g. #FF00FF become FF00FF).
@@ -385,7 +344,7 @@ async def generate_widget_small(
385344
Returns
386345
=======
387346
388-
URL with the widget.
347+
URL of the widget: str
389348
"""
390349
if bot_id is None:
391350
bot_id = self.bot_id
@@ -408,7 +367,7 @@ async def get_widget_small(self, bot_id: int = None):
408367
Returns
409368
=======
410369
411-
URL with the widget.
370+
URL of the widget: str
412371
"""
413372
if bot_id is None:
414373
bot_id = self.bot_id

0 commit comments

Comments
 (0)