SubredditWidgetsModeration

class asyncpraw.models.SubredditWidgetsModeration(subreddit, reddit)

Class for moderating a Subreddit’s widgets.

Get an instance of this class from SubredditWidgets.mod.

Example usage:

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

Note

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

__init__(subreddit, reddit)

Initialize a SubredditWidgetsModeration instance.

await add_button_widget(short_name, description, buttons, styles, **other_settings)

Add and return a ButtonWidget.

Parameters
  • short_name – A name for the widget, no longer than 30 characters.

  • description – Markdown text to describe the widget.

  • buttons

    A list of dicts 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.

  • styles – A dict with keys backgroundColor and headerColor, and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Example usage:

subreddit = await reddit.subreddit("test")
widget_moderation = subreddit.widgets.mod
my_image = await widget_moderation.upload_image("/path/to/pic.jpg")
buttons = [
    {
        "kind": "text",
        "text": "View source",
        "url": "https://github.com/asyncpraw-dev/asyncpraw",
        "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://asyncpraw.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 = await widget_moderation.add_button_widget(
    "Things to click", "Click some of these *cool* links!", buttons, styles
)
await add_calendar(short_name, google_calendar_id, requires_sync, configuration, styles, **other_settings)

Add and return a Calendar widget.

Parameters
  • short_name – A name for the widget, no longer than 30 characters.

  • google_calendar_id – An email-style calendar ID. To share a Google Calendar, make it public, then find the “Calendar ID.”

  • requires_sync – A bool.

  • configuration

    A dict as specified in Reddit docs.

    For example:

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

  • styles – A dict with keys backgroundColor and headerColor, and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Example usage:

subreddit = await reddit.subreddit("test")
widget_moderation = subreddit.widgets.mod
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
config = {
    "numEvents": 10,
    "showDate": True,
    "showDescription": False,
    "showLocation": False,
    "showTime": True,
    "showTitle": True,
}
cal_id = "y6nm89jy427drk8l71w75w9wjn@group.calendar.google.com"
new_widget = await widget_moderation.add_calendar(
    "Upcoming Events", cal_id, True, config, styles
)
await add_community_list(short_name, data, styles, description='', **other_settings)

Add and return a CommunityList widget.

Parameters
  • short_name – A name for the widget, no longer than 30 characters.

  • data – A list of subreddits. Subreddits can be represented as str or as Subreddit. These types may be mixed within the list.

  • styles – A dict with keys "backgroundColor" and "headerColor", and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

  • description – A str containing Markdown (default: "").

Example usage:

subreddit = await reddit.subreddit("test")
widget_moderation = subreddit.widgets.mod
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
new_subreddit = await reddit.subreddit("test")
subreddits = ["learnpython", new_subreddit]
new_widget = await widget_moderation.add_community_list(
    "My fav subs", subreddits, styles, "description"
)
await add_custom_widget(short_name, text, css, height, image_data, styles, **other_settings)

Add and return a CustomWidget.

Parameters
  • short_name – A name for the widget, no longer than 30 characters.

  • text – The Markdown text displayed in the widget.

  • 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 dicts as specified in Reddit docs. Each dict 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",
        },
    ]
    

  • styles – A dict with keys backgroundColor and headerColor, and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Example usage:

subreddit = await reddit.subreddit("test")
widget_moderation = subreddit.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_dicts = [
    {"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 = await widget_moderation.add_custom_widget(
    "My widget", "# Hello world!", "/**/", 200, image_dicts, styles
)
await add_image_widget(short_name, data, styles, **other_settings)

Add and return an ImageWidget.

Parameters
  • short_name – A name for the widget, no longer than 30 characters.

  • data

    A list of dicts as specified in Reddit docs. Each dict 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/asyncpraw-dev/asyncpraw",
        },
        {
            "url": "https://other.link",  # from upload_image()
            "width": 450,
            "height": 600,
            "linkUrl": "https://asyncpraw.readthedocs.io",
        },
    ]
    

  • styles – A dict with keys backgroundColor and headerColor, and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Example usage:

subreddit = await reddit.subreddit("test")
widget_moderation = subreddit.widgets.mod
image_paths = ["/path/to/image1.jpg", "/path/to/image2.png"]
image_dicts = [
    {
        "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 = await widget_moderation.add_image_widget(
    "My cool pictures", image_dicts, styles
)
await add_menu(data, **other_settings)

Add and return a Menu widget.

Parameters

data

A list of dicts 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,
    },
    ...
]

Example usage:

subreddit = await reddit.subreddit("test")
widget_moderation = subreddit.widgets.mod
menu_contents = [
    {"text": "My homepage", "url": "https://example.com"},
    {
        "text": "Python packages",
        "children": [
            {"text": "PRAW", "url": "https://asyncpraw.readthedocs.io/"},
            {"text": "requests", "url": "http://python-requests.org"},
        ],
    },
    {"text": "Reddit homepage", "url": "https://reddit.com"},
]
new_widget = await widget_moderation.add_menu(menu_contents)
await add_post_flair_widget(short_name, display, order, styles, **other_settings)

Add and return a PostFlairWidget.

Parameters
  • short_name – A name for the widget, no longer than 30 characters.

  • 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]
    

  • styles – A dict with keys backgroundColor and headerColor, and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Example usage:

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

Add and return a TextArea widget.

Parameters
  • short_name – A name for the widget, no longer than 30 characters.

  • text – The Markdown text displayed in the widget.

  • styles – A dict with keys backgroundColor and headerColor, and values of hex colors. For example, {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}.

Example usage:

subreddit = await reddit.subreddit("test")
widget_moderation = subreddit.widgets.mod
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
new_widget = await widget_moderation.add_text_area(
    "My cool title", "*Hello* **world**!", styles
)
await reorder(new_order, section='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:

subreddit = await reddit.subreddit("test")
widgets = [widget async for widget in subreddit.widgets]
order = list(widgets.sidebar)
order.reverse()
await widgets.mod.reorder(order)
await upload_image(file_path)

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 = await reddit.subreddit("test")
image_url = await my_sub.widgets.mod.upload_image("/path/to/image.jpg")
images = [{"width": 300, "height": 300, "url": image_url, "linkUrl": ""}]
styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}
await my_sub.widgets.mod.add_image_widget("My cool pictures", images, styles)