dhooks-lite

Another simple class wrapper for interacting with Discord webhooks.

release python pipeline status codecov Documentation Status license pre-commit Code style: black chat

Contents

Overview

dhooks-lite is a library with a set of classes for interacting with Discord webhooks written in Python 3.

This library aims to differentiate itself from similar libraries with the following properties:

  • is fully tested

  • simple to use (only one way of doing things, same name of attributes and objects as in the official Discord documentation)

  • has logging

  • requests are automatically retried and have sensible timeouts

  • works with older Python versions

Functionality

This library provides following functionality:

  • Posting messages in Discord channels via webhooks (synchronous calls only)

  • Attaching Embeds to messages

  • Retrieve send reports and from Discord

  • Retrieve HTTP status and headers from Discord, e.g. for implementing rate limit handling

Examples

Here are some examples on how to use dhooks-lite in your Python scripts.

Note that you also find the source code of all examples in the /examples folder of this repo.

Hello World

Minimal example for posting a message.

from dhooks_lite import Webhook

hook = Webhook(DISCORD_WEBHOOK_URL)
hook.execute('Hello, World!')

example1

Posting with custom avatar

In this example we are setting username and avatar.

from dhooks_lite import Webhook

hook = Webhook(
    DISCORD_WEBHOOK_URL,
    username='Bruce Wayne',
    avatar_url='https://i.imgur.com/thK8erv.png'
)
hook.execute('I am Batman!')

example2

Complete example with embeds

Finally, here is an example for posting a message with two embeds and using all available features (shortened):

import datetime
from dhooks_lite import Webhook, Embed, Footer, Image, Thumbnail, Author, Field

hook = Webhook(DISCORD_WEBHOOK_URL)
e1 = Embed(
    description='Only a few years ago, scientists stumbled upon an electrical current of cosmic proportions.(...)',
    title='Universe\'s highest electric current found',
    url='https://www.newscientist.com/article/mg21028174-900-universes-highest-electric-current-found/',
    timestamp=datetime.datetime.utcnow(),
    color=0x5CDBF0,
    footer=Footer(
        'Science Department',
        'https://i.imgur.com/Bgsv04h.png'
    ),
    image=Image('https://i.imgur.com/eis1Y0P.jpg'),
    thumbnail=Thumbnail('https://i.imgur.com/2A4k28x.jpg'),
    author=Author(
        'John Scientist',
        url='https://en.wikipedia.org/wiki/Albert_Einstein',
        icon_url='https://i.imgur.com/1JoHDw1.png'
    ),
    fields=[
        Field('1st Measurement', 'Failed'),
        Field('2nd Measurement', 'Succeeded')
    ]
)
e2 = Embed(description="TOP SECRET - Do not distribute!")

hook.execute(
    'Checkout this new report from the science department:',
    username='Bruce Wayne',
    avatar_url='https://i.imgur.com/thK8erv.png',
    embeds=[e1, e2],
    wait_for_response=True
)

example2

Installation

You can install this library directly from PyPI:

pip install dhooks-lite

Documentation

For a full documentation of all classes please see the official docs here.

Contribution

We welcome any contribution!

If you found a bug or have a feature request please raise an issue.

If you want to help further improve this library please feel free to issue a merge request. Please adhere to the following requirements in your change:

  • Code should be compliant with PEP8

  • Full overage by unit tests

  • All classes should be immutable

  • All classes and their public methods must have docstring documentation

  • All changes must be documented in the Change Log

API Reference

Another simple class wrapper for interacting with Discord webhooks.

class dhooks_lite.Author(name: str, url: str | None = None, icon_url: str | None = None, proxy_icon_url: str | None = None)

Author in an Embed

asdict() → dict

returns a dict representation of this object

will not include properties that are None

classmethod from_dict(obj_dict: dict)

creates a new object from the given dict

property icon_url: str | None

Return author’s icon URL.

property name: str

Return author name.

property proxy_icon_url: str | None

Return author’s proxy icon URL.

property url: str | None

Return author URL.

class dhooks_lite.Embed(description: str | None = None, title: str | None = None, url: str | None = None, timestamp: datetime | None = None, color: int | None = None, footer: Footer | None = None, image: Image | None = None, thumbnail: Thumbnail | None = None, author: Author | None = None, fields: List[Field] | None = None)

Embedded content for a message.

Initialize an Embed object

Parameters:

  • description – message text for this embed

  • title – title of embed

  • url – url of embed

  • timestamp – timestamp of embed content

  • color – color code of the embed

  • footer – footer information

  • image – image within embed

  • thumbnail – thumbnail for this embed

  • author – author information

  • fields – fields information

Exceptions:

TypeException: when passing variables of wrong type ValueException: when embed size exceeds hard limit

asdict() → dict

returns a dict representation of this object

will not include properties that are None

property author: Author | None

Return embed’s author or None.

property color: int | None

Return embed’s color or None.

property description: str | None

Return embed’s description.

property fields: List[Field] | None

Return embed’s fields or None.

property footer: Footer | None

Return embed’s footer or None.

classmethod from_dict(obj_dict: dict)

creates a new object from the given dict

property image: Image | None

Return embed’s image or None.

property thumbnail: Thumbnail | None

Return embed’s thumbnail or None.

property timestamp: datetime | None

Return embed’s timestamp or None.

property title: str | None

Return embed’s title or None.

property type: str | None

Return embed’s type or None.

property url: str | None

Return embed’s URL or None.

class dhooks_lite.Field(name: str, value: str, inline: bool = True)

Field in an Embed

asdict() → dict

returns a dict representation of this object

will not include properties that are None

classmethod from_dict(obj_dict: dict)

creates a new object from the given dict

property inline: bool | None

Return field inline.

property name: str

Return field name.

property value: str

Return field value.

class dhooks_lite.Footer(text: str, icon_url: str | None = None, proxy_icon_url: str | None = None)

Footer in an Embed

asdict() → dict

returns a dict representation of this object

will not include properties that are None

classmethod from_dict(obj_dict: dict)

creates a new object from the given dict

property icon_url: str | None

Return footer’s icon URL.

property proxy_icon_url: str | None

Return footer’s proxy icon URL.

property text: str

Return Footer text.

class dhooks_lite.Image(url: str, proxy_url: str | None = None, height: int | None = None, width: int | None = None)

Image in an Embed

asdict() → dict

returns a dict representation of this object

will not include properties that are None

classmethod from_dict(obj_dict: dict)

creates a new object from the given dict

property height: int | None

Return image height.

property proxy_url: str | None

Return image’s proxy URL.

property url: str

Return image URL.

property width: int | None

Return image width.

class dhooks_lite.Thumbnail(url: str, proxy_url: str | None = None, height: int | None = None, width: int | None = None)

Thumbnail in an Embed.

asdict() → dict

returns a dict representation of this object

will not include properties that are None

classmethod from_dict(obj_dict: dict)

creates a new object from the given dict

property height: int | None

Return image height.

property proxy_url: str | None

Return image’s proxy URL.

property url: str

Return image URL.

property width: int | None

Return image width.

class dhooks_lite.UserAgent(name: str, url: str, version: str)

Defines the content of the user agent string send to Discord

Parameters:

  • name – Name of the application

  • url – Homepage URL of the application

  • version – Version of the application

property name: str

Return user agent’s name.

property url: str

Return user agent’s URL.

property version: str

Return user agent’s version.

class dhooks_lite.Webhook(url: str, username: str | None = None, avatar_url: str | None = None, user_agent: UserAgent | None = None)

A Discord Webhook

Initialize a Webhook object

Parameters:

  • url – Discord webhook url

  • username – Override default user name of the webhook

  • avatar_url – Override default avatar icon of the webhook with image URL

  • user_agent – User agent to be send with every request to Discord.

property avatar_url: str | None

Return the avatar’s URL for this webhook.

execute(content: str | None = None, embeds: List[Embed] | None = None, tts: bool | None = None, username: str | None = None, avatar_url: str | None = None, wait_for_response: bool | None = False, max_retries: int = 3) → WebhookResponse

Posts a message to this webhook

Parameters:

  • content – Text of this message

  • embeds – List of Embed objects to be attached to this message

  • tts – Whether or not the message will use text-to-speech

  • username – Overrides default user name of the webhook

  • avatar_url – Override default avatar icon of the webhook with image URL

  • wait_for_response – Whether or not to wait for a send report from Discord

  • max_retries – maximum number of retries on errors. 0 turns it off.

Exceptions:

ValueError: on invalid input ConnectionError: on network issues Timeout: if timeouts are exceeded TooManyRedirects: if configured redirect limit is exceeded

Returns:

response from webhook as WebhookResponse object

property url: str

Return URL for this webhook.

property user_agent: UserAgent

Return the user agent for this webhook.

property username: str | None

Return username for this webhook.

class dhooks_lite.WebhookResponse(headers: dict, status_code: int, content: dict | None = None)

response from a Discord Webhook

property content: dict | None

content of the response, e.g. send report

will be empty if not waited for response from Discord

property headers: dict

response headers

property status_code: int

HTTP status code of the response

property status_ok: bool

whether the response was ok based on its HTTP status