+
+

pagination

+
+
+exception EmptyPaginatorEmbedError[source]
+

Bases: Exception

+

Raised when attempting to paginate with empty contents.

+
+ +
+
+class LinePaginator(prefix='```', suffix='```', max_size=4000, scale_to_size=4000, max_lines=None, linesep='\\n')[source]
+

Bases: Paginator

+

A class that aids in paginating code blocks for Discord messages.

+
+
Parameters:
+
    +

  • pagination_emojis (PaginationEmojis) – The emojis used to navigate pages.

    • +

  • prefix (str) – The prefix inserted to every page. e.g. three backticks.

    • +

  • suffix (str) – The suffix appended at the end of every page. e.g. three backticks.

    • +

  • max_size (int) – The maximum amount of codepoints allowed in a page.

    • +

  • scale_to_size (int) – The maximum amount of characters a single line can scale up to.

    • +

  • max_lines (int) – The maximum amount of lines allowed in a page.

    • +
+
+
+
+
+__init__(prefix='```', suffix='```', max_size=4000, scale_to_size=4000, max_lines=None, linesep='\\n')[source]
+

This function overrides the Paginator.__init__ from inside discord.ext.commands.

+

It overrides in order to allow us to configure the maximum number of lines per page.

+
+ +
+
+add_line(line='', *, empty=False)[source]
+

Adds a line to the current page.

+

If a line on a page exceeds max_size characters, then max_size will go up to +scale_to_size for a single line before creating a new page for the overflow words. If it +is still exceeded, the excess characters are stored and placed on the next pages unti +there are none remaining (by word boundary). The line is truncated if scale_to_size is +still exceeded after attempting to continue onto the next page.

+

In the case that the page already contains one or more lines and the new lines would cause +max_size to be exceeded, a new page is created. This is done in order to make a best +effort to avoid breaking up single lines across pages, while keeping the total length of the +page at a reasonable size.

+

This function overrides the Paginator.add_line from inside discord.ext.commands.

+

It overrides in order to allow us to configure the maximum number of lines per page.

+
+
Parameters:
+
    +

  • line (str) – The line to add to the paginated content.

    • +

  • empty (bool) – Indicates whether an empty line should be added at the end.

    • +
+
+
Return type:
+

None

+
+
+
+ +
+
+async classmethod paginate(pagination_emojis, lines, ctx, embed, *, prefix='', suffix='', max_lines=None, max_size=500, scale_to_size=4000, empty=True, restrict_to_user=None, timeout=300, footer_text=None, url=None, exception_on_empty_embed=False, reply=False, allowed_roles=None)[source]
+

Use a paginator and set of reactions to provide pagination over a set of lines.

+

The reactions are used to switch page, or to finish with pagination.

+

When used, this will send a message using ctx.send() and apply a set of reactions to it. These reactions may +be used to change page, or to remove pagination from the message.

+

Pagination will also be removed automatically if no reaction is added for five minutes (300 seconds).

+

The interaction will be limited to restrict_to_user (ctx.author by default) or +to any user with a moderation role.

+
+
Parameters:
+
    +

  • pagination_emojis (PaginationEmojis) – The emojis used to navigate pages.

    • +

  • lines (list[str]) – A list of lines to be added to the paginated content.

    • +

  • ctx (discord.ext.commands.Context) – The context in which the pagination is needed.

    • +

  • embed (discord.Embed) – The embed that holds the content, it serves as the page.

    • +

  • prefix (str) – The prefix inserted to every page. e.g. three backticks.

    • +

  • suffix (str) – The suffix appended at the end of every page. e.g. three backticks.

    • +

  • max_lines (int) – The maximum amount of lines allowed in a page.

    • +

  • max_size (int) – The maximum amount of codepoints allowed in a page.

    • +

  • scale_to_size (int) – The maximum amount of characters a single line can scale up to.

    • +

  • empty (bool) – Indicates whether an empty line should be added to each provided line.

    • +

  • restrict_to_user (discord.User) – The user to whom interaction with the pages should be restricted.

    • +

  • timeout (int) – The timeout after which users cannot change pages anymore.

    • +

  • footer_text (str) – Text to be added as a footer for each page.

    • +

  • url (str) – The url to be set for the pagination embed.

    • +

  • exception_on_empty_embed (bool) – Indicates whether to raise an exception when no lines are provided.

    • +

  • reply (bool) – Indicates whether to send the page as a reply to the context’s message.

    • +

  • allowed_roles (Sequence[int]) – A list of role ids that are allowed to change pages.

    • +
+
+
Return type:
+

Message | None

+
+
+

Example: +>>> embed = discord.Embed() +>>> embed.set_author(name=”Some Operation”, url=url, icon_url=icon) +>>> await LinePaginator.paginate(pagination_emojis, [line for line in lines], ctx, embed)

+
+ +
+ +
+
+class PaginationEmojis(**data)[source]
+

Bases: BaseModel

+

The emojis that will be used for pagination.

+
+
+__class_vars__: ClassVar[set[str]] = {}
+

The names of the class variables defined on the model.

+
+ +
+
+__private_attributes__: ClassVar[Dict[str, ModelPrivateAttr]] = {}
+

Metadata about the private attributes of the model.

+
+ +
+
+__pydantic_complete__: ClassVar[bool] = True
+

Whether model building is completed, or if there are still undefined fields.

+
+ +
+
+__pydantic_computed_fields__: ClassVar[Dict[str, ComputedFieldInfo]] = {}
+

A dictionary of computed field names and their corresponding [ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects.

+
+ +
+
+__pydantic_core_schema__: ClassVar[CoreSchema] = {'cls': <class 'pydis_core.utils.pagination.PaginationEmojis'>, 'config': {'title': 'PaginationEmojis'}, 'custom_init': False, 'metadata': {'pydantic_js_functions': [<bound method BaseModel.__get_pydantic_json_schema__ of <class 'pydis_core.utils.pagination.PaginationEmojis'>>]}, 'ref': 'pydis_core.utils.pagination.PaginationEmojis:94045799114080', 'root_model': False, 'schema': {'computed_fields': [], 'fields': {'delete': {'metadata': {}, 'schema': {'default': '<:trashcan:637136429717389331>', 'schema': {'type': 'str'}, 'type': 'default'}, 'type': 'model-field'}, 'first': {'metadata': {}, 'schema': {'default': '⏮', 'schema': {'type': 'str'}, 'type': 'default'}, 'type': 'model-field'}, 'last': {'metadata': {}, 'schema': {'default': '⏭', 'schema': {'type': 'str'}, 'type': 'default'}, 'type': 'model-field'}, 'left': {'metadata': {}, 'schema': {'default': '⬅', 'schema': {'type': 'str'}, 'type': 'default'}, 'type': 'model-field'}, 'right': {'metadata': {}, 'schema': {'default': '➡', 'schema': {'type': 'str'}, 'type': 'default'}, 'type': 'model-field'}}, 'model_name': 'PaginationEmojis', 'type': 'model-fields'}, 'type': 'model'}
+

The core schema of the model.

+
+ +
+
+__pydantic_custom_init__: ClassVar[bool] = False
+

Whether the model has a custom __init__ method.

+
+ +
+
+__pydantic_decorators__: ClassVar[_decorators.DecoratorInfos] = DecoratorInfos(validators={}, field_validators={}, root_validators={}, field_serializers={}, model_serializers={}, model_validators={}, computed_fields={})
+

Metadata containing the decorators defined on the model. +This replaces Model.__validators__ and Model.__root_validators__ from Pydantic V1.

+
+ +
+
+__pydantic_extra__: dict[str, Any] | None
+

A dictionary containing extra values, if [extra][pydantic.config.ConfigDict.extra] is set to ‘allow’.

+
+ +
+
+__pydantic_fields__: ClassVar[Dict[str, FieldInfo]] = {'delete': FieldInfo(annotation=str, required=False, default='<:trashcan:637136429717389331>'), 'first': FieldInfo(annotation=str, required=False, default='⏮'), 'last': FieldInfo(annotation=str, required=False, default='⏭'), 'left': FieldInfo(annotation=str, required=False, default='⬅'), 'right': FieldInfo(annotation=str, required=False, default='➡')}
+

A dictionary of field names and their corresponding [FieldInfo][pydantic.fields.FieldInfo] objects. +This replaces Model.__fields__ from Pydantic V1.

+
+ +
+
+__pydantic_fields_set__: set[str]
+

The names of fields explicitly set during instantiation.

+
+ +
+
+__pydantic_generic_metadata__: ClassVar[_generics.PydanticGenericMetadata] = {'args': (), 'origin': None, 'parameters': ()}
+

Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these.

+
+ +
+
+__pydantic_parent_namespace__: ClassVar[Dict[str, Any] | None] = None
+

Parent namespace of the model, used for automatic rebuilding of models.

+
+ +
+
+__pydantic_post_init__: ClassVar[None | Literal['model_post_init']] = None
+

The name of the post-init method for the model, if defined.

+
+ +
+
+__pydantic_private__: dict[str, Any] | None
+

Values of private attributes set on the model instance.

+
+ +
+
+__pydantic_serializer__: ClassVar[SchemaSerializer] = SchemaSerializer(serializer=Model(     ModelSerializer {         class: Py(             0x00005588be72e560,         ),         serializer: Fields(             GeneralFieldsSerializer {                 fields: {                     "first": SerField {                         key_py: Py(                             0x00007f2265bf47b0,                         ),                         alias: None,                         alias_py: None,                         serializer: Some(                             WithDefault(                                 WithDefaultSerializer {                                     default: Default(                                         Py(                                             0x00007f2261018300,                                         ),                                     ),                                     serializer: Str(                                         StrSerializer,                                     ),                                 },                             ),                         ),                         required: true,                     },                     "right": SerField {                         key_py: Py(                             0x00007f2265b797b0,                         ),                         alias: None,                         alias_py: None,                         serializer: Some(                             WithDefault(                                 WithDefaultSerializer {                                     default: Default(                                         Py(                                             0x00007f2261018350,                                         ),                                     ),                                     serializer: Str(                                         StrSerializer,                                     ),                                 },                             ),                         ),                         required: true,                     },                     "delete": SerField {                         key_py: Py(                             0x00007f2265f60eb0,                         ),                         alias: None,                         alias_py: None,                         serializer: Some(                             WithDefault(                                 WithDefaultSerializer {                                     default: Default(                                         Py(                                             0x00007f22610183f0,                                         ),                                     ),                                     serializer: Str(                                         StrSerializer,                                     ),                                 },                             ),                         ),                         required: true,                     },                     "left": SerField {                         key_py: Py(                             0x00007f2265b797f0,                         ),                         alias: None,                         alias_py: None,                         serializer: Some(                             WithDefault(                                 WithDefaultSerializer {                                     default: Default(                                         Py(                                             0x00007f22610182b0,                                         ),                                     ),                                     serializer: Str(                                         StrSerializer,                                     ),                                 },                             ),                         ),                         required: true,                     },                     "last": SerField {                         key_py: Py(                             0x00007f2265bd2170,                         ),                         alias: None,                         alias_py: None,                         serializer: Some(                             WithDefault(                                 WithDefaultSerializer {                                     default: Default(                                         Py(                                             0x00007f22610183a0,                                         ),                                     ),                                     serializer: Str(                                         StrSerializer,                                     ),                                 },                             ),                         ),                         required: true,                     },                 },                 computed_fields: Some(                     ComputedFields(                         [],                     ),                 ),                 mode: SimpleDict,                 extra_serializer: None,                 filter: SchemaFilter {                     include: None,                     exclude: None,                 },                 required_fields: 5,             },         ),         has_extra: false,         root_model: false,         name: "PaginationEmojis",     }, ), definitions=[])
+

The pydantic-core SchemaSerializer used to dump instances of the model.

+
+ +
+
+__pydantic_validator__: ClassVar[SchemaValidator | PluggableSchemaValidator] = SchemaValidator(title="PaginationEmojis", validator=Model(     ModelValidator {         revalidate: Never,         validator: ModelFields(             ModelFieldsValidator {                 fields: [                     Field {                         name: "first",                         lookup_key: Simple {                             key: "first",                             py_key: Py(                                 0x00007f2262a65eb0,                             ),                             path: LookupPath(                                 [                                     S(                                         "first",                                         Py(                                             0x00007f2262b73030,                                         ),                                     ),                                 ],                             ),                         },                         name_py: Py(                             0x00007f2265bf47b0,                         ),                         validator: WithDefault(                             WithDefaultValidator {                                 default: Default(                                     Py(                                         0x00007f2261018300,                                     ),                                 ),                                 on_error: Raise,                                 validator: Str(                                     StrValidator {                                         strict: false,                                         coerce_numbers_to_str: false,                                     },                                 ),                                 validate_default: false,                                 copy_default: false,                                 name: "default[str]",                                 undefined: Py(                                     0x00007f226444a460,                                 ),                             },                         ),                         frozen: false,                     },                     Field {                         name: "left",                         lookup_key: Simple {                             key: "left",                             py_key: Py(                                 0x00007f226170a8f0,                             ),                             path: LookupPath(                                 [                                     S(                                         "left",                                         Py(                                             0x00007f22616c4b70,                                         ),                                     ),                                 ],                             ),                         },                         name_py: Py(                             0x00007f2265b797f0,                         ),                         validator: WithDefault(                             WithDefaultValidator {                                 default: Default(                                     Py(                                         0x00007f22610182b0,                                     ),                                 ),                                 on_error: Raise,                                 validator: Str(                                     StrValidator {                                         strict: false,                                         coerce_numbers_to_str: false,                                     },                                 ),                                 validate_default: false,                                 copy_default: false,                                 name: "default[str]",                                 undefined: Py(                                     0x00007f226444a460,                                 ),                             },                         ),                         frozen: false,                     },                     Field {                         name: "right",                         lookup_key: Simple {                             key: "right",                             py_key: Py(                                 0x00007f225be71870,                             ),                             path: LookupPath(                                 [                                     S(                                         "right",                                         Py(                                             0x00007f225be72970,                                         ),                                     ),                                 ],                             ),                         },                         name_py: Py(                             0x00007f2265b797b0,                         ),                         validator: WithDefault(                             WithDefaultValidator {                                 default: Default(                                     Py(                                         0x00007f2261018350,                                     ),                                 ),                                 on_error: Raise,                                 validator: Str(                                     StrValidator {                                         strict: false,                                         coerce_numbers_to_str: false,                                     },                                 ),                                 validate_default: false,                                 copy_default: false,                                 name: "default[str]",                                 undefined: Py(                                     0x00007f226444a460,                                 ),                             },                         ),                         frozen: false,                     },                     Field {                         name: "last",                         lookup_key: Simple {                             key: "last",                             py_key: Py(                                 0x00007f225be71770,                             ),                             path: LookupPath(                                 [                                     S(                                         "last",                                         Py(                                             0x00007f225be73eb0,                                         ),                                     ),                                 ],                             ),                         },                         name_py: Py(                             0x00007f2265bd2170,                         ),                         validator: WithDefault(                             WithDefaultValidator {                                 default: Default(                                     Py(                                         0x00007f22610183a0,                                     ),                                 ),                                 on_error: Raise,                                 validator: Str(                                     StrValidator {                                         strict: false,                                         coerce_numbers_to_str: false,                                     },                                 ),                                 validate_default: false,                                 copy_default: false,                                 name: "default[str]",                                 undefined: Py(                                     0x00007f226444a460,                                 ),                             },                         ),                         frozen: false,                     },                     Field {                         name: "delete",                         lookup_key: Simple {                             key: "delete",                             py_key: Py(                                 0x00007f225be71b70,                             ),                             path: LookupPath(                                 [                                     S(                                         "delete",                                         Py(                                             0x00007f225be71970,                                         ),                                     ),                                 ],                             ),                         },                         name_py: Py(                             0x00007f2265f60eb0,                         ),                         validator: WithDefault(                             WithDefaultValidator {                                 default: Default(                                     Py(                                         0x00007f22610183f0,                                     ),                                 ),                                 on_error: Raise,                                 validator: Str(                                     StrValidator {                                         strict: false,                                         coerce_numbers_to_str: false,                                     },                                 ),                                 validate_default: false,                                 copy_default: false,                                 name: "default[str]",                                 undefined: Py(                                     0x00007f226444a460,                                 ),                             },                         ),                         frozen: false,                     },                 ],                 model_name: "PaginationEmojis",                 extra_behavior: Ignore,                 extras_validator: None,                 strict: false,                 from_attributes: false,                 loc_by_alias: true,             },         ),         class: Py(             0x00005588be72e560,         ),         generic_origin: None,         post_init: None,         frozen: false,         custom_init: false,         root_model: false,         undefined: Py(             0x00007f226444a460,         ),         name: "PaginationEmojis",     }, ), definitions=[], cache_strings=True)
+

The pydantic-core SchemaValidator used to validate instances of the model.

+
+ +
+
+__signature__: ClassVar[Signature] = <Signature (*, first: str = '⏮', left: str = '⬅', right: str = '➡', last: str = '⏭', delete: str = '<:trashcan:637136429717389331>') -> None>
+

The synthesized __init__ [Signature][inspect.Signature] of the model.

+
+ +
+
+model_config: ClassVar[ConfigDict] = {}
+

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

+
+ +
+ +
+ +