📝 Added example content + pypi docs

docs/PYPI.md

@@ -1,4 +1,4 @@
-# Pincer
+# <img src="../assets/svg/pincer.svg" height="24px" alt="Pincer Logo"> Pincer
 
 <!--
 ![PyPI - Downloads](https://img.shields.io/badge/dynamic/json?label=downloads&query=%24.total_downloads&url=https%3A%2F%2Fapi.pepy.tech%2Fapi%2Fprojects%2FPincer)](https://pypi.org/project/Pincer)
@@ -18,14 +18,15 @@
 
 An asynchronous Python API wrapper meant to replace discord.py
 
-## The package is currently within the planning phase
+| :exclamation: | The package is currently within the planning phase |
+| ------------- | :------------------------------------------------- |
 
-## 📌 Links
+## :pushpin: Links
 
-> Join the Discord server: <https://discord.gg/8WkYz3fNFm>  
-> The PyPI package: <https://pypi.org/project/Pincer>  
-> Our website: <https://pincer.dev>  
-> ReadTheDoc: <https://pincer.readthedocs.io>
+> <img src="../assets/svg/discord.svg" width="16px" alt="Discord Logo"> ｜Join the Discord server: https://discord.gg/8WkYz3fNFm <br>
+> <img src="../assets/svg/pypi.svg" width="16px" alt="PyPI Logo"> ｜The PyPI package: https://pypi.org/project/Pincer <br>
+> <img src="../assets/svg/pincer.svg" width="16px" alt="Pincer Logo"> ｜Our website: https://pincer.dev <br>
+> 📝 | ReadTheDoc: https://pincer.readthedocs.io
 
 ## ☄️ Installation
 
@@ -41,7 +42,8 @@ pip install pincer
     ⚙️ <i> Didn't work?</i>
 </summary>
 
-Depending on your Python installation, you might need to use one of the following:
+Depending on your Python installation, you might need to use one of the
+following:
 
 - Python is not in PATH
 
@@ -76,12 +78,10 @@ Depending on your Python installation, you might need to use one of the followin
 ## Current Features
 
 - Dispatcher
-- Logging
+- Logging _Improved_
 - HTTP Client
 - Client base class
-- Basic events
-
-*The documentation has been improved!*
+- Basic events _Improved_
 
 **Client base class example:**
 
@@ -112,17 +112,28 @@ client.run()
 
 ### Inherited client
 
-You have the possibility to use your own class to inherit from the Pincer bot base.
+You have the possibility to use your own class to inherit from the Pincer bot
+base.
 
 ```py
-class Bot(Client):
+from pincer import Client, command
+
 
+class Bot(Client):
     def __init__(self) -> None:
-        super(Bot, self).__init__(token='...')
+        super(Bot, self).__init__(token="...")
 
     @Client.event
     async def on_ready(self) -> None:
         ...
+
+    @command(description="Say something as the bot!")
+    async def say(self, message: str):
+        return message
+
+    @command(description="Add two numbers!")
+    async def add(self, first: int, second: int):
+        return f"The addition of `{first}` and `{second}` is `{first + second}`"
 ```
 
 See an advanced bot implementation:
@@ -131,73 +142,36 @@ See an advanced bot implementation:
 
 ### Advanced Usage
 
-__Warning: These features are meant for advanced developers to make early experimentation with Pincer.__
+__Warning: These features are meant for advanced developers to make early
+experimentation with Pincer.__
 
 #### Enable the debug mode
 
-_If you want to see everything that is happening under the hood,
-either out of curiosity or to get a deeper insight into the implementation
-of some features, we provide debug logging!_
+_If you want to see everything that is happening under the hood, either out of
+curiosity or to get a deeper insight into the implementation of some features,
+we provide debug logging!_
 
 ```py
 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!_
 
+**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
-_Within the version 0.4.0-dev, the middleware system has been re-created,
-and now advanced users can utilize them; however, it should be done carefully._
-
-A /say command early implementation using middleware
-
-> https://gist.github.com/Arthurdw/e110ebbdafca388722f25ddb79c1dfb8
-
-## .5.x versions
-
-*The 0.5.x version don't add any new features, 
-but implement the discord.py classes within the package.
-Those will be very useful for the next versions*
-
-### Classes
-`APIObject`,
-`Application commands`, 
-`Application`, 
-`Attachment`,
-`AuditLog`, 
-`Ban`,
-`Button`,
-`Channel`, 
-`ChannelMention`, 
-`Emoji`,
-`FollowedChannels`,
-`GuidMember`, 
-`Guild`, 
-`GuildWidget`, 
-`Interactions`, 
-`Invite`,
-`Member`, 
-`Message`,
-`MessageReference`, 
-`Overwrite`, 
-`Reaction`,
-`Role`, 
-`Select Menu`, 
-`Select Option`
-`StageInstance`,
-`Sticker`, 
-`StickerItem`, 
-`StickerPack`, 
-`Thread`, 
-`User`, 
-`VoiceRegion`, 
-`VoiceState`, 
-`Webhook`,
-`WelcomeScreen`, 
 
+_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)
+._
 
 ## 🏷️ License
 

examples/chat_commands_class_based.py

@@ -1,4 +1,5 @@
 from pincer import Client, command
+from pincer.objects import Message, InteractionFlags
 
 
 class Bot(Client):
@@ -15,6 +16,10 @@ async def say(self, message: str):
     async def add(self, first: int, second: int):
         return f"The addition of `{first}` and `{second}` is `{first + second}`"
 
+    @command(guild=1324567890)
+    async def private_say(self, message: str):
+        return Message(message, flags=InteractionFlags.EPHEMERAL)
+
 
 if __name__ == "__main__":
     Bot("XXXYOURBOTTOKENHEREXXX").run()

examples/chat_commands_function_based.py

@@ -1,4 +1,5 @@
 from pincer import command, Client
+from pincer.objects import Message, InteractionFlags
 
 
 @Client.event
@@ -17,5 +18,10 @@ async def add(first: int, second: int):
     return f"The addition of `{first}` and `{second}` is `{first + second}`"
 
 
+@command(guild=1324567890)
+async def private_say(message: str):
+    return Message(message, flags=InteractionFlags.EPHEMERAL)
+
+
 if __name__ == "__main__":
     Client("XXXYOURBOTTOKENHEREXXX").run()