Skip to content
Back to top
View this page

# 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, Dict[str, str] | str | int | Dict[str, 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, 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[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, 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, 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, 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[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
        )