Documentation

Never hesitate to take a look at the sources in case of confusion ! 😉

 

• Page
  • Attributes
  • Page()
  • link()
  • parent_of()
  • root_of()
  • get_message()
  • get_embed()
  • reactions()
  • need_user_input()
  • next_link()
• PageType
• Link
  • Attributes
  • Link()
  • page()
• ReactLink (Link)
  • Attributes
  • ReactLink()
• MsgLink (Link)
  • Attributes
  • MsgLink()
• RootLink(Link)
  • Attributes
  • RootLink()
• Help
  • Attributes
  • Help()
  • display()

 

Page

Class representing a page of the help system. A page is displayed to the user, and the user can navigate through pages using reactions or messages.

Attributes

Name	Type	Description
msg	str	Message to send to the user when displaying the page.
links	list of Link	List of links associated to this page. These are the possible path to navigate to another page.
msg_link	MsgLink	MsgLink if there is one. It's not part of the link list because there can't be several MsgLink associated to a given page.
parent	Link	Link to the parent page.
root	Link	Link to the root page.
sep	str	String used to separate the message and the links description. Used only for formatting messages to send to user.
links_sep	str	String used to separate each link description. Used only for formatting messages to send to user.
type	PageType	Type of the page. Can be PageType.MESSAGE or PageType.EMBED.
embed_kwargs	dict	Others keywords arguments, used to initialize the Embed for display. Only used if the type of the page is PageType.EMBED.

 

Page()

Constructor. All links are set to None or empty list.

def __init__(self, msg='', sep='\n\n', links_sep='\n')

Argument	Type	Default	Description
msg	str	''	Message to send to user when displaying this page.
sep	str	'\n\n'	String used to separate the message and the links description while formatting the message to send.
links_sep	str	'\n'	String used to separate each links description while formatting the message to send.
embed	bool	'\n'	If set to True, create a page of type PageType.EMBED, if False the page type is PageType.MESSAGE. Defaults to True.
embed_kwargs	dict	{}	Others keywords arguments, used to initialize the Embed for display. Only used if the type of the page is PageType.EMBED.

 

link()

Create a link between the current page and the given page(s). This method is used to construct the tree.

def link(self, pages, reaction=None, description=None, callbacks=[], user_input=False, is_parent=True, parent_reaction='🔙')

Argument	Type	Default	Description
pages	list of Page or Page	Required	Pages to associate to this link.
reaction	str	None	Reaction emoji needed by the user to take that link. If None is given, use a default reaction (digits 1 ~ 9).
description	str	None	Description of the link, to explain to user where this link will bring him.
callbacks	list	[]	List of functions to call when taking this link.
user_input	bool	False	Boolean indicating if this is a MsgLink. If True, a MsgLink is created, ignoring the reaction parameter.
is_parent	bool	True	Boolean indicating if the current page should be the parent of the linked pages. If True a link will be created between pages to the current page as a parent link.
parent_reaction	str or list of str	🔙	Emoji to use for the pages to go back to their parent : the current page. Used only if is_parent is True. Please use this only for advanced customization. To go even further, you can specify a list of string, where each string is the emoji to use for each page of the list of pages given.

Throws :

• IndexError : Only the 9 first links are provided with default reactions (digit 1 ~ 9). If you try to create more link with default reaction, this exception will be thrown.
• ValueError : The number of parent reactions given does not match the number of child pages.

 

parent_of()

Link a list of pages to the current page as a parent. This method is used to construct the tree, in order to set specific parent for some pages.

def parent_of(self, pages, parent_reaction='🔙')

Argument	Type	Default	Description
pages	list of Page or Page	Required	Given pages will have the current page as a parent.
parent_reaction	str or list of str	🔙	Emoji to use for the pages to go back to their parent : the current page. Please use this only for advanced customization. To go even further, you can specify a list of string, where each string is the emoji to use for each page of the list of pages given.

Throws :

• ValueError : The number of parent reactions given does not match the number of child pages.

 

root_of()

Link a list of pages to the current page as root. This method is used to construct the tree, in order to set the root for some pages.

def root_of(self, pages, root_reaction='🔝')

Argument	Type	Default	Description
pages	list of Page or Page	Required	Given pages will have the current page as root.
root_reaction	str or list of str	'🔝'	Emoji to use for the pages to go back to the root : the current page. Please use this only for advanced customization. To go even further, you can specify a list of string, where each string is the emoji to use for each page of the list of pages given.

Throws :

• ValueError : The number of root reactions given does not match the number of pages given.

 

get_message()

This method is called by the Help if the page is a PageType.MESSAGE.
It returns the formatted content of the Page as a string. This will display the main message of the Page, as well as the message describing each Link of the Page.
This method simply construct the string to send to the channel.

def get_message(self)

Returns :

• str : The content to display to user.

 

get_embed()

This method is called by the Help if the page is a PageType.EMBED.
It returns an Embed object, representing the formatted page. This will display the main message of the Page, as well as the message describing each Link of the Page.

def get_embed(self)

Returns :

• Embed : Embed to display to user.

 

reactions()

Method used by the Help, to retrieve the list of reactions that the user can use when visualizing the current page, to interact with the Help.

def reactions(self)

Returns :

• list of str : List of reactions that the user can use for this page.

 

need_user_input()

Method used by the Help to know if a user can input something when using this page, or should only use reactions.

def need_user_input(self)

Returns :

• bool : Return True if a MsgLink is associated to this page, False otherwise.

 

next_link()

Method used by the Help to access the next Link based on the reaction given. If the reaction is None, retrieve the MsgLink. If the reaction is not valid (no link associated to this reaction), None is returned.

def next_link(self, reaction=None)

Argument	Type	Default	Description
reaction	str	None	Reaction chosen by the user, representing a Link. If None, the link returned is a MsgLink.

Returns :

• Link : The next Link to display, based on the reaction of the user, or None if the choice of the user is not valid.

 

PageType

Enum representing the existing type of page. The type of a page define how this page will be displayed.

• PageType.MESSAGE
• PageType.EMBED

 

Link

Base class representing all type of link. Links are the branches of the help tree. All links can have callbacks, and a description. Links also have a list of child pages.

Most of the time, we want a simple link, so the link have a single child, which is displayed if the link is taken. But sometimes we want something more complex, displaying different pages depending on the callbacks. It's multiple choices link. In that case, a link can have several child pages.

By default, if callbacks don't change this behavior, the first page of the list is selected.

Attributes

Name	Type	Description
pages	list of Page	List of pages associated to this link.
description	str	Descripton of this link, to explain to user the effect of this link.
callbacks	list	List of functions to call when taking this link.
path	int	Which child page will be displayed. Default to 0 (the first Page of the list).

 

Link()

Constructor. Create a Link. Default path is 0.

def __init__(self, pages, description=None, callbacks=[])

Argument	Type	Default	Description
pages	list of Page or Page	Required	List of pages associated to this link. If a single Page is given, it will create the list for you.
description	str	None	Description of this link, to explain to user the effect of this link.
callbacks	list	[]	List of functions to call when taking this link.

 

page()

Method called by the Help, after calling the callbacks. So the path was updated (or not) to select the right page, and this method return the appropriate page.

def page(self)

Returns :

• Page : The page selected by callbacks (or default choice).

 

ReactLink (Link)

Class for link using reaction to navigate to next page. Subclass of Link.

Attributes

Name	Type	Description
...	...	...
reaction	str	Reaction needed by the link to display the next page.

 

ReactLink()

Constructor. Create a ReactLink.

def __init__(self, reaction, pages, description=None, callbacks=[])

Argument	Type	Default	Description
reaction	str	Required	Reaction needed by the link to display the page.
pages	list of Page or Page	Required	List of pages associated to this link. If a single Page is given, it will create the list for you.
description	str	None	Description of this link, to explain to user the effect of this link.
callbacks	list	[]	List of functions to call when taking this link.

 

MsgLink (Link)

Class for link using message from user to navigate to next page. Subclass of Link.

Attributes

Name	Type	Description
...	...	...

 

MsgLink()

Constructor. Create a MsgLink.

def __init__(self, pages, description=None, callbacks=[])

Argument	Type	Default	Description
pages	list of Page or Page	Required	List of pages associated to this link. If a single Page is given, it will create the list for you.
description	str	None	Description of this link, to explain to user the effect of this link.
callbacks	list	[]	List of functions to call when taking this link.

 

RootLink (Link)

Class for the first link of the tree : the root link. Subclass of Link.

Attributes

Name	Type	Description
...	...	...

 

RootLink()

Constructor. Create a RootLink.

There is no need of description, because this kind of links can never be described to user.

def __init__(self, pages, callbacks=[])

Argument	Type	Default	Description
pages	list of Page or Page	Required	List of pages associated to this link. If a single Page is given, it will create the list for you.
callbacks	list	[]	List of functions to call when taking this link.

 

Help

Class representing the whole Help system. It's through this class that you can display the help system, and interact with the user.

Attributes

Name	Type	Description
client	Discord.Client	Client Discord (from the python Discord API) used to send message, react, etc...
tree	RootLink	First link of the tree, representing the whole help system.
quit_react	str	Reaction used to leave the help system.

 

Help()

Constructor. Create a the Help object. It also creates the RootLink as starting point.

def __init__(self, client, pages, callbacks=[], quit_react='❌')

Argument	Type	Default	Description
client	Discord.Client	Required	Discord client used to send message, react, etc...
pages	list of Page or Page	Required	List of pages representing the starting point of the help system.
callbacks	list	[]	List of functions to call when taking this link.
quit_react	str	'❌'	Reaction used to leave the help system.

 

display()

Main function of the object : when a user request help, simply call this function. It will display the first message of the help system, and then wait the user to react. Depending on the reaction, it will display the next page, etc...

It finishes when the user quit the help system.

Note : This function is asynchronous. Be sure to call it like this : await h.display(...)

async def display(self, member)

Argument	Type	Default	Description
member	Discord.Member	Required	Discord member who requested help. Help will be displayed as a private message to him. You can obtain the member from a message like this : member = message.author