discord-styled-text¶

A small library to style text for Discord without having to remember any syntax

Installation¶

discord-styled-text requires Python 3.6 at minimum. Install by running:

$ pip install discord-styled-text

Example Usage¶

>>> from discord_styler import *

>>> bold_text = Bold("Here's some bold text")
>>> italic_text = Italic("and here's some", Underline("italic text"), "with nested styles!")
>>> text = StyledText("We can combine them:", bold_text, italic_text)
>>> str(text)
"We can combine them: **Here's some bold text** *and here's some __italic text__ with nested styles!*"

>>> quoted = StyledText(BlockQuote(text), "and we can do quotes too")
>>> str(quoted)
"> We can combine them: **Here's some bold text** *and here's some __italic text__ with nested styles!*\n and we can do quotes too"

>>> question = StyledText(
...     UserMention(200102491231092736),
...     f"will you be free at {TimeStamp(1618953630, TimeStyle.LongDateTime)}?",
...     f"I'll be doing code review in {ChannelMention(656893570711814145)} if you wanna join")
>>> str(question)
"<@200102491231092736> will you be free at <t:1618953630:F>? I'll be doing code review in <#656893570711814145> if you wanna join"

>>> link = NonEmbeddingURL("https://github.com/miaowware/discord-styled-text/pull/1")
>>> str(link)
'<https://github.com/miaowware/discord-styled-text/pull/1>'

>>> code = StyledText(
...     "What do you think of this?\n",
...     CodeBlock('def __str__(self) -> str:\n        return "||" + super().__str__() + "||"', lang="py"))
>>> str(code)
'What do you think of this?\n ```py\ndef __str__(self) -> str:\n        return "||" + super().__str__() + "||"\n```'

_images/discord_screenshot.png

API¶

All classes are directly stringifiable.

See the Discord Documentation on Message Formatting and Discord Help on Markdown for more information on the formatting this library abstracts.

Text Styles¶

class discord_styler.StyledText(*objects, sep=' ')¶

Container for styled text

Strignifies and concatenates all given objects to simplify style composition. All subclasses follow the same logic while adding their markup.

Parameters

objects (Any) – Objects to style
sep (str) – The separator to use, defaults to a space

class discord_styler.Italic(*objects, sep=' ')¶

Applies italic formatting to the objects using StyledText logic

Takes the same parameters as StyledText.

class discord_styler.Bold(*objects, sep=' ')¶

Applies bold formatting to the objects using StyledText logic

Takes the same parameters as StyledText.

class discord_styler.Underline(*objects, sep=' ')¶

Applies underline formatting to the objects using StyledText logic

Takes the same parameters as StyledText.

class discord_styler.Strikethrough(*objects, sep=' ')¶

Applies strikethrough formatting to the objects using StyledText logic

Takes the same parameters as StyledText.

class discord_styler.InlineCode(*objects, sep=' ')¶

Applies inline code block formatting to the objects using StyledText logic

Takes the same parameters as StyledText.

class discord_styler.Spoiler(*objects, sep=' ')¶

Applies spoiler formatting to the objects using StyledText logic

Takes the same parameters as StyledText.

class discord_styler.BlockQuote(*objects, sep=' ')¶

Applies block quote styling to the objects using StyledText logic

All newlines will be appended with a > and a space. The inner text will be prepended with a > and space and appended with a \n.

Takes the same parameters as StyledText.

Code Blocks¶

class discord_styler.CodeBlock(code, lang=None)¶

Wraps the given code in a code block, optionally with language highlighting

Parameters

code (str) – The contents of the code block
lang (Optional[str]) – The language code of the code block, left unspecified in the generated markup if absent

URLs¶

class discord_styler.TitledURL(title, url)¶

URL with title

This only works inside embeds.

Parameters

title (Union[str, StyledText]) – The text to use as the link title
url (str) – The URL. Must be http or https protocol

class discord_styler.NonEmbeddingURL(url)¶

Non-embedding URL

URL which Discord will not generate an embed for.

Parameters: url (str) – The URL. Must be http or https protocol

Mentions¶

class discord_styler.MentionABC(id)¶

Abstract base class for mention ID formatters

Cannot be directly instantiated. Subclasses must implement __str__().

Parameters: id (int) – The ID to mention

class discord_styler.UserMention(id, nickname=False)¶

User mention formatter

Creates a user mention for the given ID. If using this library in a discord.py bot/client, we recommend using User.mention when possible.

Parameters

id (int) – The ID to mention
nickname (bool) – Whether to use the “nickname” format instead. Currently, this changes nothing in the client and always renders the nickname if it exists

class discord_styler.RoleMention(id)¶

Role mention formatter

Creates a role mention for the given ID. If using this library in a discord.py bot/client, we recommend using Role.mention when possible.

Parameters: id (int) – The ID to mention

class discord_styler.ChannelMention(id)¶

Channel mention formatter

Creates a channel mention for the given ID. If using this library in a discord.py bot/client, we recommend using GuildChannel.mention when possible.

Parameters: id (int) – The ID to mention

Timestamps¶

class discord_styler.TimeStamp(time, style=None)¶

Creates a smart timestamp

Renders on the client according to the selected style and the client’s locale and timezone. The style used when left unspecified and the specifics of each styles are entirely controlled by Discord.

Timestamp Styles (Discord API Docs)

Parameters

time (Union[int, datetime]) – The UNIX timestamp (in seconds)
style (Optional[TimeStyle]) – The smart timestamp style to use

enum discord_styler.TimeStyle(value)¶

Timestamp styles for TimeStamp

Valid values are as follows:

ShortTime¶

LongTime¶

ShortDate¶

LongDate¶

ShortDateTime¶

LongDateTime¶

Relative¶

Utility Functions¶

Note

Escaping of markdown titled URLs (like this example below) in text is not yet supported!

[title](https://example.com)

discord_styler.escape_everything(text, *, esc_timestamps=True, esc_channels=True)¶

Utility function to escape all special formatting and mentions

Exactly the same as running both escape_markdown() and escape_mentions(). Provided as a convenience shortcut.

Parameters

text (str) – the text to escape
esc_timestamps (bool) – whether to escape timestamp formatting in the text
esc_channels (bool) – whether to escape channel mentions in the text

Return type

str

discord_styler.escape_markdown(text, *, esc_timestamps=True)¶

Utility function to escape markdown-like formatting in a string

Parameters

text (str) – the text to escape
esc_timestamps (bool) – whether to escape timestamp formatting in the text

Return type

str

discord_styler.escape_mentions(text, *, esc_channels=True)¶

Utility function to escape all mentions in the text

Escapes user, role, everyone/here, and optionally, channel mentions. Escaping done by adding a non-breaking space (\u200b) between the mention symbol (@/@!/@&/#) and the identifier (ID/everyone/here).

Parameters

text (str) – the text to escape
esc_channels (bool) – whether to escape channel mentions in the text

Return type

str

License¶

Copyright 2021 classabbyamp, 0x5c

Released under the BSD 3-Clause License. See LICENSE for the full license text.