Metadata-Version: 2.4
Name: topstats
Version: 1.1.1
Summary: A simple API wrapper for topstats.gg written in Python.
Author: null8626
License: MIT
Project-URL: Documentation, https://topstats.readthedocs.io/en/latest/
Project-URL: Raw API Documentation, https://docs.topstats.gg/introduction/introduction/
Project-URL: Repository, https://github.com/top-stats/python-sdk
Project-URL: Support server, https://discord.gg/jjEauJXuZc
Keywords: discord,discord-bot,topgg
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.11.18
Dynamic: license-file

# [topstats][pypi-url] [![pypi][pypi-image]][pypi-url] [![downloads][downloads-image]][pypi-url]

[pypi-image]: https://img.shields.io/pypi/v/topstats.svg?style=flat-square
[pypi-url]: https://pypi.org/project/topstats/
[downloads-image]: https://img.shields.io/pypi/dm/topstats?style=flat-square

A simple API wrapper for [topstats.gg](https://topstats.gg) written in Python.

## Getting started

Make sure you already have an API token handy. See [this page](https://docs.topstats.gg/authentication/tokens) on how to retrieve it.

After that, run the following command in your terminal:

```console
$ pip install topstats
```

## Example

For more information, please read the [documentation](https://topstats.readthedocs.io/en/latest/).

```py
# Import the module.
import topstats

import asyncio
import os


async def main() -> None:
  
  # Declare the client.
  async with topstats.Client(os.getenv('TOPSTATS_TOKEN')) as ts:
    
    # Fetch a bot from its ID.
    bot = await ts.get_bot(432610292342587392)
    
    print(bot)

    # Fetch topstats.gg's top bots.
    bots = await ts.get_top_bots(sort_by=topstats.SortBy.server_count())
    
    for b in bots:
      print(b)
    
    # Search for bots that has the name 'MEE6.'
    mee6_bots = await ts.search_bots(name='MEE6')

    for b in mee6_bots:
      print(b)

    # Search for anime-tagged bots.
    anime_bots = await ts.search_bots(tag='anime')

    for b in anime_bots:
      print(b)
    
    # Fetch a bot's historical server count.
    sc = await ts.get_historical_bot_server_count(432610292342587392)

    for server_count in sc:
      print(server_count)
    
    # Compare two bots' historical server count.
    vs = await ts.compare_bot_server_count(432610292342587392, 437808476106784770)

    for first, second in vs:
      print(first, second)
    
    # Compare up to four bots' historical total vote count.
    vs2 = await ts.compare_bot_total_votes(
      topstats.Period.LAST_YEAR,
      339254240012664832,
      432610292342587392,
      408785106942164992,
      437808476106784770
    )

    for first, second, third, fourth in vs2:
      print(first, second, third, fourth)

if __name__ == '__main__':
  
  # See https://stackoverflow.com/questions/45600579/asyncio-event-loop-is-closed-when-getting-loop
  # for more details.
  if os.name == 'nt':
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
  
  asyncio.run(main())
```
