diff --git a/docs/PYPI.md b/docs/PYPI.md index 807a2d44..e0686fd8 100644 --- a/docs/PYPI.md +++ b/docs/PYPI.md @@ -11,30 +11,33 @@ ![Lines of code](https://tokei.rs/b1/github/pincer-org/pincer?category=code&path=pincer) ![Repo Size](https://img.shields.io/github/repo-size/Pincer-org/Pincer) ![GitHub last commit](https://img.shields.io/github/last-commit/Pincer-org/Pincer) -![GitHub commit activity](https://img.shields.io/github/commit-activity/m/Pincer-org/Pincer) +![GitHub commit activity](https://img.shields.io/github/commit-activity/m/Pincer-org/Pincer?label=commits) ![GitHub](https://img.shields.io/github/license/Pincer-org/Pincer) ![Discord](https://img.shields.io/discord/881531065859190804) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) +![gitmoji](https://img.shields.io/badge/gitmoji-%20πŸš€%20πŸ’€-FFDD67.svg) -An asynchronous Python API wrapper meant to replace discord.py +## :pushpin: Links -## The package is currently within the pre-alpha phase - -## πŸ“Œ Links - -> Join the Discord server: -> The PyPI package: -> Our website: -> ReadTheDocs: +> Discord Logo ｜Join the Discord server: https://discord.gg/pincer
+> PyPI Logo ｜The PyPI package: https://pypi.org/project/Pincer
+> Pincer Logo ｜Our website: https://pincer.dev
+> πŸ“ | ReadTheDocs: https://pincer.readthedocs.io ## β˜„οΈ Installation Use the following command to install Pincer into your Python environment: -```bash +```sh pip install pincer ``` +To install our version with Aiohttp Speedup, use: + +```sh +pip install pincer[speed] +``` +
@@ -74,61 +77,49 @@ following:
-## Current Features - -- Discord Gateway communication -- logging -- Http Client -- Events -- Event middleware -- Commands -- Command arguments *(for types: str, int, float, bool, User, Channel, Role)* -- Command argument choices -- Command argument descriptions -- Command cool downs (Using WindowSliding technique) -- Tasks -- Cogs - **Client base class example:** ```py from pincer.client import Bot # Note that both `Bot` and `Client` are valid! -bot = Bot("...") +bot = Bot("YOUR_TOKEN_HERE") bot.run() ``` **An example on the `on_ready` event** +Pincer bots are required to inherit from the Client. + ```py from time import perf_counter -from pincer.client import Client +from pincer import Client -client = Client("...") +marker = perf_counter() -@client.event -async def on_ready(): - print(f"Logged in as {client.bot} after {perf_counter()} seconds") +class Bot(Client): + @Client.event + async def on_ready(): + print(f"Logged in as {client.bot} after {perf_counter() - marker} seconds") + +client = Bot("YOUR_TOKEN_HERE") client.run() ``` -### Inherited client +### Interactions -You have the possibility to use your own class to inherit from the Pincer bot -base. +Pincer makes developing application commands intuitive and fast. ```py from pincer import Client from pincer.commands import command, CommandArg, Description +from pincer.objects import UserMessage, User -class Bot(Client): - def __init__(self) -> None: - super(Bot, self).__init__(token="...") +class Bot(Client): @Client.event async def on_ready(self) -> None: ... @@ -137,20 +128,33 @@ class Bot(Client): async def say(self, message: str): return message + @user_command + async def user_command(self, user: User): + return f"The user is {user}" + + @message_command(name="Message command") + async def message_command(self, message: UserMessage): + return f"The message read '{message.content}'" + @command(description="Add two numbers!") async def add( - self, - first: CommandArg[int, Description["The first number"]], - second: CommandArg[int, Description["The second number"]] + self, + first: CommandArg[int, Description["The first number"]], + second: CommandArg[int, Description["The second number"]] ): return f"The addition of `{first}` and `{second}` is `{first + second}`" + + ``` -For more examples you can take a look at the examples folder or check out our -bot on GitHub: +For more examples, you can take a look at the examples folder or check out our +bot: > +You can also read the interactions guide for more information: +> + ### Advanced Usage #### Enable the debug mode @@ -165,20 +169,16 @@ import logging logging.basicConfig(level=logging.DEBUG) ``` -**Note:** _A lot of printing can happen, including sensitive information, so -make sure to be aware of what you're doing if you're enabling it!_ - #### Middleware -_From version 0.4.0-dev, the middleware system has been introduced. This system -gives you the full freedom to remove the already existing middleware which has -been created by the developers and create custom events. Your custom middleware -directly receives the payload from Discord. You can't really do anything wrong -without accessing the `override` attribute, but if you access this attribute the -Pincer team will not provide any support for weird behavior. So in short, only -use this if you know what you're doing. An example of using this with a custom -`on_ready` event can be found -[in our docs](https://pincer.readthedocs.io/en/latest/pincer.html#pincer.client.middleware) +_The middleware system was introduced in version `0.4.0-dev`. This system gives you the +freedom to create custom events and remove the already existing middleware created by +the developers. Your custom middleware directly receives the payload from +Discord. You can't do anything wrong without accessing the `override` attribute, but if +you do access it, the Pincer team will not provide any support for weird behavior. +So, in short, only use this if you know what you're doing. An example of using +the middleware system with a custom `on_ready` event can be found +[in our docs](https://pincer.readthedocs.io/en/latest/pincer.html#pincer.client.middleware). ._ ## 🏷️ License diff --git a/docs/README.md b/docs/README.md index 15f4da9e..7e5a4027 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,11 +15,13 @@ ![GitHub](https://img.shields.io/github/license/Pincer-org/Pincer) ![Discord](https://img.shields.io/discord/881531065859190804) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) +![gitmoji](https://img.shields.io/badge/gitmoji-%20πŸš€%20πŸ’€-FFDD67.svg) # Pincer Logo Pincer -The snappy asynchronous discord api wrapper API wrapper written with aiohttp. -| :exclamation: | The package is currently within Pre-Alpha phase | +The snappy asynchronous Discord API wrapper written with aiohttp. + +| :exclamation: | The package is currently within the Alpha phase | | ------------- | :---------------------------------------------- | ## :pushpin: Links @@ -37,7 +39,7 @@ Use the following command to install Pincer into your Python environment: pip install pincer ``` -To install our version with Aiohttp Speedup do: +To install our version with Aiohttp Speedup, use: ```sh pip install pincer[speed] @@ -82,93 +84,84 @@ following: -## Current Features - -- Discord Gateway communication -- logging -- Http Client -- Events -- Event middleware -- Commands -- Command arguments *(for types: str, int, float, bool, User, Channel, Role)* -- Command argument choices -- Command argument descriptions -- Command cool downs (Using WindowSliding technique) -- Tasks -- Cogs - **Client base class example:** ```py from pincer.client import Bot # Note that both `Bot` and `Client` are valid! -bot = Bot("...") +bot = Bot("YOUR_TOKEN_HERE") bot.run() ``` **An example on the `on_ready` event** +Pincer bots are required to inherit from the Client. + ```py from time import perf_counter -from pincer.client import Client +from pincer import Client -client = Client("...") +marker = perf_counter() -@client.event -async def on_ready(): - print(f"Logged in as {client.bot} after {perf_counter()} seconds") +class Bot(Client): + + @Client.event + async def on_ready(): + print(f"Logged in as {client.bot} after {perf_counter() - marker} seconds") +client = Bot("YOUR_TOKEN_HERE") client.run() ``` -### Inherited client +### Interactions -You have the possibility to use your own class to inherit from the Pincer bot -base. +Pincer makes developing application commands intuitive and fast. ```py from pincer import Client from pincer.commands import command, CommandArg, Description +from pincer.objects import UserMessage, User class Bot(Client): - def __init__(self) -> None: - super(Bot, self).__init__(token="...") - @Client.event async def on_ready(self) -> None: ... @command(description="Say something as the bot!") - # Pincer uses type hints to specify the argument type - # str - String - # int - Integer - # bool - Boolean - # float - Number - # pincer.objects.User - User - # pincer.objects.Channel - Channel - # pincer.objects.Role - Role - # pincer.objects.Mentionable - Mentionable async def say(self, message: str): return message + @user_command + async def user_command(self, user: User): + return f"The user is {user}" + + @message_command(name="Message command") + async def message_command(self, message: UserMessage): + return f"The message read '{message.content}'" + @command(description="Add two numbers!") async def add( - self, - first: CommandArg[int, Description["The first number"]], - second: CommandArg[int, Description["The second number"]] + self, + first: CommandArg[int, Description["The first number"]], + second: CommandArg[int, Description["The second number"]] ): return f"The addition of `{first}` and `{second}` is `{first + second}`" + + ``` -For more examples you can take a look at the examples folder or check out our +For more examples, you can take a look at the examples folder or check out our bot: > +You can also read the interactions guide for more information: +> + ### Advanced Usage #### Enable the debug mode @@ -183,20 +176,16 @@ import logging logging.basicConfig(level=logging.DEBUG) ``` -**Note:** _A lot of printing can happen, including sensitive information, so -make sure to be aware of what you're doing if you're enabling it!_ - #### Middleware -_From version 0.4.0-dev, the middleware system has been introduced. This system -gives you the full freedom to remove the already existing middleware which has -been created by the developers and create custom events. Your custom middleware -directly receives the payload from Discord. You can't really do anything wrong -without accessing the `override` attribute, but if you access this attribute the -Pincer team will not provide any support for weird behavior. So in short, only -use this if you know what you're doing. An example of using this with a custom -`on_ready` event can be found -[in our docs](https://pincer.readthedocs.io/en/latest/pincer.html#pincer.client.middleware) +_The middleware system was introduced in version `0.4.0-dev`. This system gives you the +freedom to create custom events and remove the already existing middleware created by +the developers. Your custom middleware directly receives the payload from +Discord. You can't do anything wrong without accessing the `override` attribute, but if +you do access it, the Pincer team will not provide any support for weird behavior. +So, in short, only use this if you know what you're doing. An example of using +the middleware system with a custom `on_ready` event can be found +[in our docs](https://pincer.readthedocs.io/en/latest/pincer.html#pincer.client.middleware). ._ ## 🏷️ License