SubredditWidgetsModeration

class praw.models.SubredditWidgetsModeration(subreddit: praw.models.Subreddit, reddit: praw.Reddit)

Class for moderating a Subreddit’s widgets.

Get an instance of this class from SubredditWidgets.mod.

Example usage:

styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
reddit.subreddit("test").widgets.mod.add_text_area(
    short_name="My title", text="**bold text**", styles=styles
)

Note

To use this class’s methods, the authenticated user must be a moderator with appropriate permissions.

__init__(subreddit: praw.models.Subreddit, reddit: praw.Reddit): Initialize a SubredditWidgetsModeration instance.

add_button_widget(*, buttons: List[Dict[str, Union[Dict[str, str], str, int, Dict[str, Union[str, int]]]]], description: str, short_name: str, styles: Dict[str, str], **other_settings) → praw.models.ButtonWidget

Add and return a ButtonWidget.

Parameters

buttons –

A list of dictionaries describing buttons, as specified in Reddit docs. As of this writing, the format is:

Each button is either a text button or an image button. A text button looks like this:

{
    "kind": "text",
    "text": a string no longer than 30 characters,
    "url": a valid URL,
    "color": a 6-digit rgb hex color, e.g., `#AABBCC`,
    "textColor": a 6-digit rgb hex color, e.g., `#AABBCC`,
    "fillColor": a 6-digit rgb hex color, e.g., `#AABBCC`,
    "hoverState": {...}
}

An image button looks like this:

{
    "kind": "image",
    "text": a string no longer than 30 characters,
    "linkUrl": a valid URL,
    "url": a valid URL of a Reddit-hosted image,
    "height": an integer,
    "width": an integer,
    "hoverState": {...}
}

Both types of buttons have the field hoverState. The field does not have to be included (it is optional). If it is included, it can be one of two types: "text" or "image". A text hoverState looks like this:

{
    "kind": "text",
    "text": a string no longer than 30 characters,
    "color": a 6-digit rgb hex color, e.g., `#AABBCC`,
    "textColor": a 6-digit rgb hex color, e.g., `#AABBCC`,
    "fillColor": a 6-digit rgb hex color, e.g., `#AABBCC`
}

An image hoverState looks like this:

{
    "kind": "image",
    "url": a valid URL of a Reddit-hosted image,
    "height": an integer,
    "width": an integer
}

Note

The method upload_image() can be used to upload images to Reddit for a url field that holds a Reddit-hosted image.

Note

An image hoverState may be paired with a text widget, and a text hoverState may be paired with an image widget.

description – Markdown text to describe the widget.
short_name – A name for the widget, no longer than 30 characters.
styles – A dictionary with keys "backgroundColor" and "headerColor", and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Returns

The created ButtonWidget.

Example usage:

widget_moderation = reddit.subreddit("test").widgets.mod
my_image = widget_moderation.upload_image("/path/to/pic.jpg")
buttons = [
    {
        "kind": "text",
        "text": "View source",
        "url": "https://github.com/praw-dev/praw",
        "color": "#FF0000",
        "textColor": "#00FF00",
        "fillColor": "#0000FF",
        "hoverState": {
            "kind": "text",
            "text": "ecruos weiV",
            "color": "#FFFFFF",
            "textColor": "#000000",
            "fillColor": "#0000FF",
        },
    },
    {
        "kind": "image",
        "text": "View documentation",
        "linkUrl": "https://praw.readthedocs.io",
        "url": my_image,
        "height": 200,
        "width": 200,
        "hoverState": {"kind": "image", "url": my_image, "height": 200, "width": 200},
    },
]
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
new_widget = widget_moderation.add_button_widget(
    short_name="Things to click",
    description="Click some of these *cool* links!",
    buttons=buttons,
    styles=styles,
)

add_calendar(*, configuration: Dict[str, Union[bool, int]], google_calendar_id: str, requires_sync: bool, short_name: str, styles: Dict[str, str], **other_settings) → praw.models.Calendar

Add and return a Calendar widget.

Parameters

configuration –

A dictionary as specified in Reddit docs. For example:

{
    "numEvents": 10,
    "showDate": True,
    "showDescription": False,
    "showLocation": False,
    "showTime": True,
    "showTitle": True,
}

google_calendar_id – An email-style calendar ID. To share a Google Calendar, make it public, then find the “Calendar ID”.
requires_sync – Whether the calendar needs synchronization.
short_name – A name for the widget, no longer than 30 characters.
styles – A dictionary with keys "backgroundColor" and "headerColor", and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Returns

The created Calendar.

Example usage:

widget_moderation = reddit.subreddit("test").widgets.mod
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
config = {
    "numEvents": 10,
    "showDate": True,
    "showDescription": False,
    "showLocation": False,
    "showTime": True,
    "showTitle": True,
}
calendar_id = "y6nm89jy427drk8l71w75w9wjn@group.calendar.google.com"
new_widget = widget_moderation.add_calendar(
    short_name="Upcoming Events",
    google_calendar_id=calendar_id,
    requires_sync=True,
    configuration=config,
    styles=styles,
)

add_community_list(*, data: List[Union[str, praw.models.Subreddit]], description: str = '', short_name: str, styles: Dict[str, str], **other_settings) → praw.models.CommunityList

Add and return a CommunityList widget.

Parameters

data – A list of subreddits. Subreddits can be represented as str or as Subreddit. These types may be mixed within the list.
description – A string containing Markdown (default: "").
short_name – A name for the widget, no longer than 30 characters.
styles – A dictionary with keys "backgroundColor" and "headerColor", and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Returns

The created CommunityList.

Example usage:

widget_moderation = reddit.subreddit("test").widgets.mod
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
subreddits = ["learnpython", reddit.subreddit("redditdev")]
new_widget = widget_moderation.add_community_list(
    short_name="My fav subs", data=subreddits, styles=styles, description="description"
)

add_custom_widget(*, css: str, height: int, image_data: List[Dict[str, Union[str, int]]], short_name: str, styles: Dict[str, str], text: str, **other_settings) → praw.models.CustomWidget

Add and return a CustomWidget.

Parameters

css –
The CSS for the widget, no longer than 100000 characters.

Note

As of this writing, Reddit will not accept empty CSS. If you wish to create a custom widget without CSS, consider using "/**/" (an empty comment) as your CSS.
height – The height of the widget, between 50 and 500.

image_data –

A list of dictionaries as specified in Reddit docs. Each dictionary represents an image and has the key "url" which maps to the URL of an image hosted on Reddit’s servers. Images should be uploaded using upload_image().

For example:

[
    {
        "url": "https://some.link",  # from upload_image()
        "width": 600,
        "height": 450,
        "name": "logo",
    },
    {
        "url": "https://other.link",  # from upload_image()
        "width": 450,
        "height": 600,
        "name": "icon",
    },
]

short_name – A name for the widget, no longer than 30 characters.
styles – A dictionary with keys "backgroundColor" and "headerColor", and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.
text – The Markdown text displayed in the widget.

Returns

The created CustomWidget.

Example usage:

widget_moderation = reddit.subreddit("test").widgets.mod
image_paths = ["/path/to/image1.jpg", "/path/to/image2.png"]
image_urls = [widget_moderation.upload_image(img_path) for img_path in image_paths]
image_data = [
    {"width": 600, "height": 450, "name": "logo", "url": image_urls[0]},
    {"width": 450, "height": 600, "name": "icon", "url": image_urls[1]},
]
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
new_widget = widget_moderation.add_custom_widget(
    image_short_name="My widget",
    text="# Hello world!",
    css="/**/",
    height=200,
    image_data=image_data,
    styles=styles,
)

add_image_widget(*, data: List[Dict[str, Union[str, int]]], short_name: str, styles: Dict[str, str], **other_settings) → praw.models.ImageWidget

Add and return an ImageWidget.

Parameters

data –

A list of dictionaries as specified in Reddit docs. Each dictionary has the key "url" which maps to the URL of an image hosted on Reddit’s servers. Images should be uploaded using upload_image().

For example:

[
    {
        "url": "https://some.link",  # from upload_image()
        "width": 600,
        "height": 450,
        "linkUrl": "https://github.com/praw-dev/praw",
    },
    {
        "url": "https://other.link",  # from upload_image()
        "width": 450,
        "height": 600,
        "linkUrl": "https://praw.readthedocs.io",
    },
]

short_name – A name for the widget, no longer than 30 characters.
styles – A dictionary with keys "backgroundColor" and "headerColor", and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Returns

The created ImageWidget.

Example usage:

widget_moderation = reddit.subreddit("test").widgets.mod
image_paths = ["/path/to/image1.jpg", "/path/to/image2.png"]
image_data = [
    {
        "width": 600,
        "height": 450,
        "linkUrl": "",
        "url": widget_moderation.upload_image(img_path),
    }
    for img_path in image_paths
]
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
new_widget = widget_moderation.add_image_widget(
    short_name="My cool pictures", data=image_data, styles=styles
)

add_menu(*, data: List[Dict[str, Union[List[Dict[str, str]], str]]], **other_settings) → praw.models.Menu

Add and return a Menu widget.

Parameters

data –

A list of dictionaries describing menu contents, as specified in Reddit docs. As of this writing, the format is:

[
    {
        "text": a string no longer than 20 characters,
        "url": a valid URL
    },

    OR

    {
        "children": [
            {
                "text": a string no longer than 20 characters,
                "url": a valid URL,
            },
            ...
        ],
        "text": a string no longer than 20 characters,
    },
    ...
]

Returns

The created Menu.

Example usage:

widget_moderation = reddit.subreddit("test").widgets.mod
menu_contents = [
    {"text": "My homepage", "url": "https://example.com"},
    {
        "text": "Python packages",
        "children": [
            {"text": "PRAW", "url": "https://praw.readthedocs.io/"},
            {"text": "requests", "url": "https://docs.python-requests.org/"},
        ],
    },
    {"text": "Reddit homepage", "url": "https://reddit.com"},
]
new_widget = widget_moderation.add_menu(data=menu_contents)

add_post_flair_widget(*, display: str, order: List[str], short_name: str, styles: Dict[str, str], **other_settings) → praw.models.PostFlairWidget

Add and return a PostFlairWidget.

Parameters

display – Display style. Either "cloud" or "list".
order –
A list of flair template IDs. You can get all flair template IDs in a subreddit with:
```
flairs = [f["id"] for f in subreddit.flair.link_templates]
```
short_name – A name for the widget, no longer than 30 characters.
styles – A dictionary with keys "backgroundColor" and "headerColor", and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Returns

The created PostFlairWidget.

Example usage:

subreddit = reddit.subreddit("test")
widget_moderation = subreddit.widgets.mod
flairs = [f["id"] for f in subreddit.flair.link_templates]
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
new_widget = widget_moderation.add_post_flair_widget(
    short_name="Some flairs", display="list", order=flairs, styles=styles
)

add_text_area(*, short_name: str, styles: Dict[str, str], text: str, **other_settings) → praw.models.TextArea

Add and return a TextArea widget.

Parameters

short_name – A name for the widget, no longer than 30 characters.
styles – A dictionary with keys "backgroundColor" and "headerColor", and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.
text – The Markdown text displayed in the widget.

Returns

The created TextArea.

Example usage:

widget_moderation = reddit.subreddit("test").widgets.mod
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
new_widget = widget_moderation.add_text_area(
    short_name="My cool title", text="*Hello* **world**!", styles=styles
)

reorder(new_order: List[Union[praw.models.ButtonWidget, praw.models.Calendar, praw.models.CommunityList, praw.models.CustomWidget, praw.models.IDCard, praw.models.ImageWidget, praw.models.Menu, praw.models.ModeratorsWidget, praw.models.PostFlairWidget, praw.models.RulesWidget, praw.models.TextArea, praw.models.Widget, str]], *, section: str = 'sidebar')

Reorder the widgets.

Parameters

new_order – A list of widgets. Represented as a list that contains Widget objects, or widget IDs as strings. These types may be mixed.
section – The section to reorder (default: "sidebar").

Example usage:

widgets = reddit.subreddit("test").widgets
order = list(widgets.sidebar)
order.reverse()
widgets.mod.reorder(order)

upload_image(file_path: str) → str

Upload an image to Reddit and get the URL.

Parameters: file_path – The path to the local file.
Returns: The URL of the uploaded image as a str.

This method is used to upload images for widgets. For example, it can be used in conjunction with add_image_widget(), add_custom_widget(), and add_button_widget().

Example usage:

my_sub = reddit.subreddit("test")
image_url = my_sub.widgets.mod.upload_image("/path/to/image.jpg")
image_data = [{"width": 300, "height": 300, "url": image_url, "linkUrl": ""}]
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
my_sub.widgets.mod.add_image_widget(
    short_name="My cool pictures", data=image_data, styles=styles
)