Skip to content
This repository has been archived by the owner on Dec 26, 2022. It is now read-only.

Pincer-org/Pincer

Repository files navigation

Pincer Logo

PyPI - Downloads PyPI PyPI - Format PyPI - Python Version Scrutinizer Code Quality Build Status Documentation Status codecov Lines of code Repo Size GitHub last commit GitHub commit activity GitHub Discord Code style: black gitmoji

Pincer Logo Pincer

The snappy asynchronous Discord API wrapper written with aiohttp.

❗ The package has been discontinued as of December 26, 2022

Thanks for the contributions and the support!

πŸ“Œ Links

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:

pip install pincer

To install our version with Aiohttp Speedup, use:

pip install pincer[speed]
βš™οΈ Didn't work?

Depending on your Python installation, you might need to use one of the following:

  • Python is not in PATH

    path/to/python.exe -m pip install pincer
  • Python is in PATH but pip is not

    python -m pip install pincer
  • Unix systems can use pip3/python3 commands

    pip3 install pincer
    python3 -m pip install pincer
  • Using multiple Python versions

    py -m pip install pincer

Client base class example:

from pincer.client import Bot

# Note that both `Bot` and `Client` are valid!
bot = Bot("YOUR_TOKEN_HERE")
bot.run()

An example on the on_ready event

Pincer bots are required to inherit from the Client.

from time import perf_counter
from pincer import Client

marker = perf_counter()


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()

Interactions

Pincer makes developing application commands intuitive and fast.

from typing import Annotated  # python 3.9+
from typing_extensions import Annotated  # python 3.8

from pincer import Client
from pincer.commands import command, CommandArg, Description
from pincer.objects import UserMessage, User


class Bot(Client):
    @Client.event
    async def on_ready(self) -> None:
        ...

    @command(description="Say something as the bot!")
    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: Annotated[int, Description("The first number")],
        second: Annotated[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:

https://github.com/Pincer-org/Pincer-bot

You can also read the interactions guide for more information:

https://docs.pincer.dev/en/latest/interactions.html

Advanced Usage

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!

import logging

logging.basicConfig(level=logging.DEBUG)

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. .

🏷️ License

Β© 2022 copyright Pincer

This repository is licensed under the MIT License.

See LICENSE for details.