flow — Structured Discussions Entities#

Objects representing Structured Discussions entities.

Structured Discussions was formerly known as Flow. Flow was renamed in 2017 as the focus was scoped to user-to-user discussions.

Caution

Structured Discussions support previously known as Flow is no longer tested because the test environment was disabled. Please use this module with care.

Deprecated since version 9.4: Structured Discussions extension is not maintained and will be removed. Users are encouraged to stop using it. (T371180)

Removed in version 10.0: (T381551)

See also

class flow.Board(source, title='')[source]#

Bases: FlowPage

A Flow discussion board.

Parameters:

  • source (PageSourceType) – A Flow-enabled site or a Link or Page on such a site

  • title (str) – normalized title of the page

Raises:

  • TypeError – incorrect use of parameters

  • ValueError – use of non-Flow-enabled Site

new_topic(title, content, content_format='wikitext')[source]#

Create and return a Topic object for a new topic on this Board.

Parameters:

  • title (str) – The title of the new topic (must be in plaintext)

  • content (str) – The content of the topic’s initial post

  • content_format (str) – The content format of the supplied content; either ‘wikitext’ or ‘html’

Returns:

The new topic

Return type:

Topic

topics(limit='[deprecated name of total]', *, content_format='wikitext', total=None, sort_by='newest', offset=None, offset_uuid='', reverse=False, include_offset=False, toc_only=False)[source]#

Load this board’s topics.

Changed in version 8.0: The total parameter was added as a per request limit. All parameters are keyword only parameters.

Deprecated since version 8.0: The limit parameter. Use -step global option or config.step instead.

Parameters:

  • content_format (str) – The content format to request the data in; must be either ‘wikitext’, ‘html’, or ‘fixed-html’

  • total (int | None) – The number of topics to fetch.

  • sort_by (str) – Algorithm to sort topics by; must be either ‘newest’ or ‘updated’

  • offset (str | datetime.datetime | None) – The timestamp to start at (when sortby is ‘updated’).

  • offset_uuid (str) – The UUID to start at (when sortby is ‘newest’).

  • reverse (bool) – Whether to reverse the topic ordering.

  • include_offset (bool) – Whether to include the offset topic.

  • toc_only (bool) – Whether to only include information for the TOC.

Yield:

A generator of this board’s topics.

class flow.FlowPage(source, title='')[source]#

Bases: BasePage, ABC

The base page meta class for the Flow extension.

Defines Flow page-like object for Board and Topic. It cannot be instantiated directly.

Parameters:

  • source (PageSourceType) – A Flow-enabled site or a Link or Page on such a site

  • title (str) – normalized title of the page

Raises:

  • TypeError – incorrect use of parameters

  • ValueError – use of non-Flow-enabled Site

get(force=False, get_redirect=False)[source]#

Get the page’s content.

Parameters:

  • force (bool)

  • get_redirect (bool)

Return type:

dict[str, Any]

property uuid: str#

Return the UUID of the page.

Returns:

UUID of the page

class flow.Post(page, uuid)[source]#

Bases: object

A post to a Flow discussion topic. This is a non-page-like object.

Parameters:

  • page (Topic) – Flow topic

  • uuid (str) – UUID of a Flow post

Raises:

TypeError – incorrect types of parameters

property creator: User#

The creator of this post.

delete(reason)[source]#

Delete this post through the Flow moderation system.

Parameters:

reason (str) – The reason for deleting this post.

Return type:

None

classmethod fromJSON(page, post_uuid, data)[source]#

Create a Post object using the data returned from the API call.

Parameters:

  • page (Topic) – A Flow topic

  • post_uuid (str) – The UUID of the post

  • data (dict[str, Any]) – The JSON data returned from the API

Returns:

A Post object

Raises:

  • TypeError – data is not a dict

  • ValueError – data is missing required entries

Return type:

Post

get(content_format='wikitext', force=False)[source]#

Return the contents of the post in the given format.

Parameters:

  • force (bool) – Whether to reload from the API instead of using the cache

  • content_format (str) – Content format to return contents in

Returns:

The contents of the post in the given content format

Return type:

str

hide(reason)[source]#

Hide this post.

Parameters:

reason (str) – The reason for hiding this post.

Return type:

None

property is_moderated: bool#

Whether this post is moderated.

property page: Topic#

Return the page associated with the post.

Returns:

Page associated with the post

replies(content_format='wikitext', force=False)[source]#

Return this post’s replies.

Parameters:

  • content_format (str) – Content format to return contents in; must be ‘wikitext’, ‘html’, or ‘fixed-html’

  • force (bool) – Whether to reload from the API instead of using the cache

Returns:

This post’s replies

Return type:

list[Post]

reply(content, content_format='wikitext')[source]#

Reply to this post.

Parameters:

  • content (str) – The content of the new post

  • content_format (str) – The format of the given content; must be ‘wikitext’ or ‘html’

Returns:

The new reply post

Return type:

Post

restore(reason)[source]#

Restore this post.

Parameters:

reason (str) – The reason for restoring this post.

Return type:

None

property site: BaseSite#

Return the site associated with the post.

Returns:

Site associated with the post

suppress(reason)[source]#

Suppress this post.

Parameters:

reason (str) – The reason for suppressing this post.

Return type:

None

thank()[source]#

Thank the user who made this post.

Return type:

None

property uuid: str#

Return the UUID of the post.

Returns:

UUID of the post

class flow.Topic(source, title='')[source]#

Bases: FlowPage

A Flow discussion topic.

Parameters:

  • source (PageSourceType) – A Flow-enabled site or a Link or Page on such a site

  • title (str) – normalized title of the page

Raises:

  • TypeError – incorrect use of parameters

  • ValueError – use of non-Flow-enabled Site

classmethod create_topic(board, title, content, content_format='wikitext')[source]#

Create and return a Topic object for a new topic on a Board.

Parameters:

  • board (Board) – The topic’s parent board

  • title (str) – The title of the new topic (must be in plaintext)

  • content (str) – The content of the topic’s initial post

  • content_format (str) – The content format of the supplied content; either ‘wikitext’ or ‘html’

Returns:

The new topic

Return type:

Topic

delete_mod(reason)[source]#

Delete this topic through the Flow moderation system.

Parameters:

reason (str) – The reason for deleting this topic.

Return type:

None

classmethod from_topiclist_data(board, root_uuid, topiclist_data)[source]#

Create a Topic object from API data.

Parameters:

  • board (Board) – The topic’s parent Flow board

  • root_uuid (str) – The UUID of the topic and its root post

  • topiclist_data (dict[str, Any]) – The data returned by view-topiclist

Returns:

A Topic object derived from the supplied data

Raises:

  • TypeError – any passed parameters have wrong types

  • ValueError – the passed topiclist_data is missing required data

Return type:

Topic

hide(reason)[source]#

Hide this topic.

Parameters:

reason (str) – The reason for hiding this topic.

Return type:

None

property is_locked: bool#

Whether this topic is locked.

property is_moderated: bool#

Whether this topic is moderated.

lock(reason)[source]#

Lock this topic.

Parameters:

reason (str) – The reason for locking this topic

Return type:

None

replies(content_format='wikitext', force=False)[source]#

A list of replies to this topic’s root post.

Parameters:

  • content_format (str) – Content format to return contents in; must be ‘wikitext’, ‘html’, or ‘fixed-html’

  • force (bool) – Whether to reload from the API instead of using the cache

Returns:

The replies of this topic’s root post

Return type:

list[Post]

reply(content, content_format='wikitext')[source]#

A convenience method to reply to this topic’s root post.

Parameters:

  • content (str) – The content of the new post

  • content_format (str) – The format of the given content; must be ‘wikitext’ or ‘html’)

Returns:

The new reply to this topic’s root post

Return type:

Post

restore(reason)[source]#

Restore this topic.

Parameters:

reason (str) – The reason for restoring this topic.

Return type:

None

property root: Post#

The root post of this topic.

summarize(summary)[source]#

Summarize this topic.

Parameters:

summary (str) – The summary that will be added to the topic.

Return type:

None

summary()[source]#

Get this topic summary, if any.

Returns:

summary or None

Return type:

str | None

suppress(reason)[source]#

Suppress this topic.

Parameters:

reason (str) – The reason for suppressing this topic.

Return type:

None

unlock(reason)[source]#

Unlock this topic.

Parameters:

reason (str) – The reason for unlocking this topic

Return type:

None