Metadata-Version: 2.1
Name: pincer
Version: 0.9.2
Summary: Discord API wrapper rebuild from scratch.
Home-page: https://pincer.dev
Author: Sigmanificient, Arthurdw
Author-email: contact@pincer.dev
License: MIT
Project-URL: Github repository, https://github.com/pincer-org/pincer
Project-URL: ReadTheDocs, https://pincer.readthedocs.org
Project-URL: Discord, https://discord.gg/8WkYz3fNFm
Keywords: discord,api,asynchronous,websockets,aiohttp
Platform: unix
Platform: linux
Platform: osx
Platform: cygwin
Platform: windows
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: testing
Provides-Extra: img
License-File: LICENSE

# 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)
![PyPI](https://img.shields.io/pypi/v/Pincer)
![PyPI - Format](https://img.shields.io/pypi/format/Pincer)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/Pincer)
-->

[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/Pincer-org/pincer/badges/quality-score.png?b=main)](https://scrutinizer-ci.com/g/Pincer-org/pincer/?branch=main)
[![Build Status](https://scrutinizer-ci.com/g/Pincer-org/Pincer/badges/build.png?b=main)](https://scrutinizer-ci.com/g/Pincer-org/Pincer/build-status/main)
![GitHub 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](https://img.shields.io/github/license/Pincer-org/Pincer)
![Code Style](https://img.shields.io/badge/code%20style-pep8-green)
![Discord](https://img.shields.io/discord/881531065859190804)

An asynchronous Python API wrapper meant to replace discord.py

## The package is currently within the planning phase

## 📌 Links

> Join the Discord server: <https://discord.gg/8WkYz3fNFm>  
> The PyPI package: <https://pypi.org/project/Pincer>  
> Our website: <https://pincer.dev>  
> ReadTheDocs: <https://pincer.readthedocs.io>

## ☄️ Installation

Use the following command to install Pincer into your Python environment:

```bash
pip install pincer
```

<details>

<summary>
    ⚙️ <i> Didn't work?</i>
</summary>

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

- Python is not in PATH

    ```sh
    path/to/python.exe -m pip install pincer
    ```

- Python is in PATH but pip is not

    ```sh
    python -m pip install pincer
    ```

- Unix systems can use pip3/python3 commands

    ```sh
    pip3 install pincer
    ```

    ```sh
    python3 -m pip install pincer
    ```

- Using multiple Python versions

    ```sh
    py -m pip install pincer
    ```

</details>

## 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.run()
```

**An example on the `on_ready` event**

```py
from time import perf_counter
from pincer.client import Client

client = Client("...")


@client.event
async def on_ready():
    print(f"Logged in as {client.bot} after {perf_counter()} seconds")


client.run()
```

### Inherited client

You have the possibility to use your own class to inherit from the Pincer bot
base.

```py
from pincer import Client, command


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!")
    async def say(self, message: str):
        return message

    @command(description="Add two numbers!")
    async def add(
            self, 
            first: (int, "The first number"), # support arg descriptions
            second: (int, "The second number") # since 0.7.1
    ): 
        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:

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

### 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!_

```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!_

#### 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)
._

## 🏷️ License

`© 2021 copyright Pincer`

This repository is licensed under the MIT License.

See LICENSE for details.


