[feat,docs]: adapt methods and documentation to v1

Author: null8626

README.md

@@ -9,15 +9,16 @@ The community-maintained Python library for Top.gg.
 - [Usage](#usage)
   - [Getting a bot](#getting-a-bot)
   - [Getting several bots](#getting-several-bots)
-  - [Getting your bot's voters](#getting-your-bots-voters)
-  - [Check if a user has voted for your bot](#check-if-a-user-has-voted-for-your-bot)
+  - [Getting your project's voters](#getting-your-projects-voters)
+  - [Getting your project's vote information of a user](#getting-your-projects-vote-information-of-a-user)
   - [Getting your bot's server count](#getting-your-bots-server-count)
   - [Posting your bot's server count](#posting-your-bots-server-count)
+  - [Posting your bot's application commands list](#posting-your-bots-application-commands-list)
   - [Automatically posting your bot's server count every few minutes](#automatically-posting-your-bots-server-count-every-few-minutes)
   - [Checking if the weekend vote multiplier is active](#checking-if-the-weekend-vote-multiplier-is-active)
   - [Generating widget URLs](#generating-widget-urls)
   - [Webhooks](#webhooks)
-    - [Being notified whenever someone voted for your bot](#being-notified-whenever-someone-voted-for-your-bot)
+    - [Being notified whenever someone voted for your project](#being-notified-whenever-someone-voted-for-your-project)
 
 ## Installation
 
@@ -34,7 +35,6 @@ import topgg
 
 import os
 
-
 async with topgg.Client(os.getenv('TOPGG_TOKEN')) as client:
   # ...
 ```
@@ -46,7 +46,6 @@ import topgg
 
 import os
 
-
 client = topgg.Client(os.getenv('TOPGG_TOKEN'))
 
 # ...
@@ -82,7 +81,7 @@ for bot in bots:
   print(bot)
 ```
 
-### Getting your bot's voters
+### Getting your project's voters
 
 #### First page
 
@@ -102,44 +101,88 @@ for voter in voters:
   print(voter)
 ```
 
-### Check if a user has voted for your bot
+### Getting your project's vote information of a user
+
+#### Discord ID
 
 ```py
-has_voted = await client.has_voted(661200758510977084)
+vote = await client.get_vote(661200758510977084)
+
+if vote:
+  print(f'User has voted: {vote!r}')
+```
+
+#### Top.gg ID
+
+```py
+vote = await client.get_vote(8226924471638491136, source=topgg.UserSource.TOPGG)
+
+if vote:
+  print(f'User has voted: {vote!r}')
 ```
 
 ### Getting your bot's server count
 
 ```py
-posted_server_count = await client.get_server_count()
+posted_server_count = await client.get_bot_server_count()
 ```
 
 ### Posting your bot's server count
 
 ```py
-await client.post_server_count(bot.server_count)
+await client.post_bot_server_count(bot.server_count)
+```
+
+### Posting your bot's application commands list
+
+#### Discord.py/Pycord/Nextcord/Disnake
+
+```py
+app_id = bot.user.id
+commands = await bot.http.get_global_commands(app_id)
+
+await client.post_bot_commands(commands)
+```
+
+#### Hikari
+
+```py
+app_id = ...
+commands = await bot.rest.request('GET', f'/applications/{app_id}/commands')
+
+await client.post_bot_commands(commands)
+```
+
+#### Discord.http
+
+```py
+http = discordhttp.HTTP(f'BOT {os.getenv("BOT_TOKEN")}')
+app_id = ...
+commands = await http.get(f'/applications/{app_id}/commands')
+
+await client.post_bot_commands(commands)
 ```
 
 ### Automatically posting your bot's server count every few minutes
 
 ```py
-@client.autopost_retrieval
+@client.bot_autopost_retrieval
 def get_server_count() -> int:
   return bot.server_count
 
-@client.autopost_success
+@client.bot_autopost_success
 def success(server_count: int) -> None:
   print(f'Successfully posted {server_count} servers to Top.gg!')
 
-@client.autopost_error
+@client.bot_autopost_error
 def error(error: topgg.Error) -> None:
   print(f'Error: {error!r}')
 
-client.start_autoposter()
+client.start_bot_autoposter()
 
 # ...
 
-client.stop_autoposter() # Optional
+client.stop_bot_autoposter() # Optional
 ```
 
 ### Checking if the weekend vote multiplier is active
@@ -176,19 +219,18 @@ widget_url = topgg.widget.social(topgg.WidgetType.DISCORD_BOT, 57465275174577766
 
 ### Webhooks
 
-#### Being notified whenever someone voted for your bot
+#### Being notified whenever someone voted for your project
 
 ```py
 import topgg
 
 import asyncio
 import os
 
-
 webhooks = topgg.Webhooks(os.getenv('MY_TOPGG_WEBHOOK_SECRET'), 8080)
 
 @webhooks.on_vote('/votes')
-def voted(vote: topgg.Vote) -> None:
+def voted(vote: topgg.VoteEvent) -> None:
   print(f'A user with the ID of {vote.voter_id} has voted us on Top.gg!')
 
 async def main() -> None:

docs/client.rst

@@ -4,6 +4,10 @@ Client reference
 .. autoclass:: topgg.client.Client
    :members:
 
+.. autoclass:: topgg.models.UserSource()
+   :members:
+   :undoc-members:
+
 .. autoclass:: topgg.widget.WidgetType()
    :members:
    :undoc-members:
@@ -21,11 +25,11 @@ Client reference
 .. autoclass:: topgg.errors.Ratelimited()
    :members:
 
-.. autodata:: topgg.client.AutopostRetrievalCallback
-.. autodata:: topgg.client.AutopostRetrievalDecorator
+.. autodata:: topgg.client.BotAutopostRetrievalCallback
+.. autodata:: topgg.client.BotAutopostRetrievalDecorator
 
-.. autodata:: topgg.client.AutopostSuccessCallback
-.. autodata:: topgg.client.AutopostSuccessDecorator
+.. autodata:: topgg.client.BotAutopostSuccessCallback
+.. autodata:: topgg.client.BotAutopostSuccessDecorator
 
-.. autodata:: topgg.client.AutopostErrorCallback
-.. autodata:: topgg.client.AutopostErrorDecorator
+.. autodata:: topgg.client.BotAutopostErrorCallback
+.. autodata:: topgg.client.BotAutopostErrorDecorator

docs/data.rst

@@ -7,5 +7,8 @@ Data reference
 .. autoclass:: topgg.models.Vote()
    :members:
 
+.. autoclass:: topgg.models.VoteEvent()
+   :members:
+
 .. autoclass:: topgg.models.Voter()
    :members:

docs/index.rst

@@ -22,7 +22,6 @@ Implicit cleanup
 
    import os
 
-
    async with topgg.Client(os.getenv('TOPGG_TOKEN')) as client:
      # ...
 
@@ -35,7 +34,6 @@ Explicit cleanup
 
    import os
 
-
    client = topgg.Client(os.getenv('TOPGG_TOKEN'))
 
    # ...
@@ -75,8 +73,8 @@ With explicit arguments
    for bot in bots:
      print(bot)
 
-Getting your bot's voters
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Getting your project’s voters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 First page
 ^^^^^^^^^^
@@ -98,49 +96,99 @@ Subsequent pages
    for voter in voters:
      print(voter)
 
-Check if a user has voted for your bot
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Getting your project’s vote information of a user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Discord ID
+^^^^^^^^^^
 
 .. code-block:: python
 
-   has_voted = await client.has_voted(661200758510977084)
+   vote = await client.get_vote(661200758510977084)
+
+   if vote:
+     print(f'User has voted: {vote!r}')
 
-Getting your bot's server count
+Top.gg ID
+^^^^^^^^^
+
+.. code-block:: python
+
+   vote = await client.get_vote(8226924471638491136, source=topgg.UserSource.TOPGG)
+
+   if vote:
+     print(f'User has voted: {vote!r}')
+
+Getting your bot’s server count
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: python
 
-   posted_server_count = await client.get_server_count()
+   posted_server_count = await client.get_bot_server_count()
 
-Posting your bot's server count
+Posting your bot’s server count
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: python
 
-   await client.post_server_count(bot.server_count)
+   await client.post_bot_server_count(bot.server_count)
+
+Posting your bot’s application commands list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Discord.py/Pycord/Nextcord/Disnake
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
 
-Automatically posting your bot's server count every few minutes
+   app_id = bot.user.id
+   commands = await bot.http.get_global_commands(app_id)
+
+   await client.post_bot_commands(commands)
+
+Hikari
+^^^^^^
+
+.. code-block:: python
+
+   app_id = ...
+   commands = await bot.rest.request('GET', f'/applications/{app_id}/commands')
+
+   await client.post_bot_commands(commands)
+
+Discord.http
+^^^^^^^^^^^^
+
+.. code-block:: python
+
+   http = discordhttp.HTTP(f'BOT {os.getenv("BOT_TOKEN")}')
+   app_id = ...
+   commands = await http.get(f'/applications/{app_id}/commands')
+
+   await client.post_bot_commands(commands)
+
+Automatically posting your bot’s server count every few minutes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: python
 
-   @client.autopost_retrieval
+   @client.bot_autopost_retrieval
    def get_server_count() -> int:
      return bot.server_count
 
-   @client.autopost_success
+   @client.bot_autopost_success
    def success(server_count: int) -> None:
      print(f'Successfully posted {server_count} servers to Top.gg!')
 
-   @client.autopost_error
+   @client.bot_autopost_error
    def error(error: topgg.Error) -> None:
      print(f'Error: {error!r}')
 
-   client.start_autoposter()
+   client.start_bot_autoposter()
 
    # ...
 
-   client.stop_autoposter() # Optional
+   client.stop_bot_autoposter() # Optional
 
 Checking if the weekend vote multiplier is active
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -183,8 +231,8 @@ Social
 Webhooks
 ~~~~~~~~
 
-Being notified whenever someone voted for your bot
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Being notified whenever someone voted for your project
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: python
 
@@ -193,11 +241,10 @@ Being notified whenever someone voted for your bot
    import asyncio
    import os
 
-
    webhooks = topgg.Webhooks(os.getenv('MY_TOPGG_WEBHOOK_SECRET'), 8080)
 
    @webhooks.on_vote('/votes')
-   def voted(vote: topgg.Vote) -> None:
+   def voted(vote: topgg.VoteEvent) -> None:
      print(f'A user with the ID of {vote.voter_id} has voted us on Top.gg!')
 
    async def main() -> None:

test.py

@@ -52,10 +52,13 @@ async def run() -> None:
       test_attributes(b)
 
     await asyncio.sleep(1)
-    await tg.post_server_count(2)
+    await tg.post_bot_commands([{'name': 'test', 'description': 'command description'}])
 
     await asyncio.sleep(1)
-    posted_server_count = await tg.get_server_count()
+    await tg.post_bot_server_count(2)
+
+    await asyncio.sleep(1)
+    posted_server_count = await tg.get_bot_server_count()
 
     assert posted_server_count == 2
 
@@ -66,9 +69,10 @@ async def run() -> None:
       test_attributes(voter)
 
     await asyncio.sleep(1)
-    has_voted = await tg.has_voted(661200758510977084)
+    await tg.get_vote(661200758510977084)
 
-    assert isinstance(has_voted, bool)
+    await asyncio.sleep(1)
+    await tg.get_vote(8226924471638491136, source=topgg.UserSource.TOPGG)
 
     await asyncio.sleep(1)
     is_weekend = await tg.is_weekend()