FjPdZddlmZddlmZmZddlmZmZddl m Z ddl m Z m Z ddlmZddlmZer dd lZdd lmZGd d e e ZGd de e ZGdde e ZGdde e ZGdde e ZGdde e ZGdde e ZGdde eZGdde ZGddZGdd e e ZGd!d"eeZGd#d$eZ Gd%d&eeZ!Gd'd(eZ"Gd)d*eZ#Gd+d,eeZ$Gd-d.eeZ%Gd/d0eeZ&Gd1d2eeZ'Gd3d4eeZ(Gd5d6eZ)Gd7d8eZ*Gd9d:Z+y );z#Provide classes related to widgets.) annotations) JSONEncoderdumps) TYPE_CHECKINGAny)API_PATH)DynamicAttributesPRAWBase)BaseList)cachedpropertyN)modelsceZdZdZy)ButtonaClass to represent a single button inside a :class:`.ButtonWidget`. .. include:: ../../typical_attributes.rst ============== ===================================================================== Attribute Description ============== ===================================================================== ``color`` The hex color used to outline the button. ``fillColor`` The hex color for the background of the button. ``height`` Image height. Only present on image buttons. ``hoverState`` A ``dict`` describing the state of the button when hovered over. Optional. ``kind`` Either ``"text"`` or ``"image"``. ``linkUrl`` A link that can be visited by clicking the button. Only present on image buttons. ``text`` The text displayed on the button. ``textColor`` The hex color for the text of the button. ``url`` - If the button is a text button, a link that can be visited by clicking the button. - If the button is an image button, the URL of a Reddit-hosted image. ``width`` Image width. Only present on image buttons. ============== ===================================================================== N__name__ __module__ __qualname____doc__X/root/workspace/ytshorts/venv/lib/python3.12/site-packages/praw/models/reddit/widgets.pyrrsrrceZdZdZy)CalendarConfigurationaClass to represent the configuration of a :class:`.Calendar`. .. include:: ../../typical_attributes.rst =================== ================================================ Attribute Description =================== ================================================ ``numEvents`` The number of events to display on the calendar. ``showDate`` Whether to show the dates of events. ``showDescription`` Whether to show the descriptions of events. ``showLocation`` Whether to show the locations of events. ``showTime`` Whether to show the times of events. ``showTitle`` Whether to show the titles of events. =================== ================================================ Nrrrrrr-srrceZdZdZy)HoveraClass to represent the hover data for a :class:`.ButtonWidget`. These values will take effect when the button is hovered over (the user moves their cursor so it's on top of the button). .. include:: ../../typical_attributes.rst ============= ===================================================================== Attribute Description ============= ===================================================================== ``color`` The hex color used to outline the button. ``fillColor`` The hex color for the background of the button. ``textColor`` The hex color for the text of the button. ``height`` Image height. Only present on image buttons. ``kind`` Either ``text`` or ``image``. ``text`` The text displayed on the button. ``url`` - If the button is a text button, a link that can be visited by clicking the button. - If the button is an image button, the URL of a Reddit-hosted image. ``width`` Image width. Only present on image buttons. ============= ===================================================================== Nrrrrrr@srrceZdZdZy)ImageaClass to represent an image that's part of a :class:`.ImageWidget`. .. include:: ../../typical_attributes.rst =========== ================================================= Attribute Description =========== ================================================= ``height`` Image height. ``linkUrl`` A link that can be visited by clicking the image. ``url`` The URL of the (Reddit-hosted) image. ``width`` Image width. =========== ================================================= NrrrrrrZ rrceZdZdZy) ImageDataaClass for image data that's part of a :class:`.CustomWidget`. .. include:: ../../typical_attributes.rst ========== ========================================= Attribute Description ========== ========================================= ``height`` The image height. ``name`` The image name. ``url`` The URL of the image on Reddit's servers. ``width`` The image width. ========== ========================================= Nrrrrr r krrr ceZdZdZy)MenuLinkaClass to represent a single link inside a :class:`.Menu` or :class:`.Submenu`. .. include:: ../../typical_attributes.rst ========= ==================================== Attribute Description ========= ==================================== ``text`` The text of the menu link. ``url`` The URL that the menu item links to. ========= ==================================== Nrrrrr"r"|s rr"ceZdZdZy)StylesapClass to represent the style information of a widget. .. include:: ../../typical_attributes.rst =================== ======================================================== Attribute Description =================== ======================================================== ``backgroundColor`` The background color of a widget, given as a hexadecimal (``0x######``). ``headerColor`` The header color of a widget, given as a hexadecimal (``0x######``). =================== ======================================================== Nrrrrr$r$rrr$ceZdZdZdZy)SubmenuaClass to represent a submenu of links inside a :class:`.Menu`. .. include:: ../../typical_attributes.rst ============ ====================================================================== Attribute Description ============ ====================================================================== ``children`` A list of the :class:`.MenuLink`\ s in this submenu. Can be iterated over by iterating over the :class:`.Submenu` (e.g., ``for menu_link in submenu``). ``text`` The name of the submenu. ============ ====================================================================== childrenNrrrrCHILD_ATTRIBUTErrrr&r&s !Orr&ceZdZdZed dZeddZeddZeddZeddZ eddZ ddZ dfd Z dd Z dfd Zdd ZxZS)SubredditWidgetsa Class to represent a :class:`.Subreddit`'s widgets. Create an instance like so: .. code-block:: python widgets = reddit.subreddit("test").widgets Data will be lazy-loaded. By default, PRAW will not request progressively loading images from Reddit. To enable this, instantiate a :class:`.SubredditWidgets` object via :meth:`~.Subreddit.widgets`, then set the attribute ``progressive_images`` to ``True`` before performing any action that would result in a network request. .. code-block:: python widgets = reddit.subreddit("test").widgets widgets.progressive_images = True for widget in widgets.sidebar: # do something ... Access a :class:`.Subreddit`'s widgets with the following attributes: .. code-block:: python print(widgets.id_card) print(widgets.moderators_widget) print(widgets.sidebar) print(widgets.topbar) The attribute :attr:`.id_card` contains the :class:`.Subreddit`'s ID card, which displays information like the number of subscribers. The attribute :attr:`.moderators_widget` contains the :class:`.Subreddit`'s moderators widget, which lists the moderators of the subreddit. The attribute :attr:`.sidebar` contains a list of widgets which make up the sidebar of the subreddit. The attribute :attr:`.topbar` contains a list of widgets which make up the top bar of the subreddit. To edit a :class:`.Subreddit`'s widgets, use :attr:`~.SubredditWidgets.mod`. For example: .. code-block:: python widgets.mod.add_text_area( short_name="My title", text="**bold text**", styles={"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}, ) For more information, see :class:`.SubredditWidgetsModeration`. To edit a particular widget, use ``.mod`` on the widget. For example: .. code-block:: python for widget in widgets.sidebar: widget.mod.update(shortName="Exciting new name") For more information, see :class:`.WidgetModeration`. **Currently available widgets**: - :class:`.ButtonWidget` - :class:`.Calendar` - :class:`.CommunityList` - :class:`.CustomWidget` - :class:`.IDCard` - :class:`.ImageWidget` - :class:`.Menu` - :class:`.ModeratorsWidget` - :class:`.PostFlairWidget` - :class:`.RulesWidget` - :class:`.TextArea` c:|j|jdS)z7Get this :class:`.Subreddit`'s :class:`.IDCard` widget. idCardWidgetitemslayoutselfs rid_cardzSubredditWidgets.id_cardszz$++n566rci}|jjD]=\}}|j|d<|jjj |||<?|S)zCGet this :class:`.Subreddit`'s widgets as a dict from ID to widget. subredditdata) _raw_itemsr/r5_reddit _objector objectify)r2r/ item_namer7s rr/zSubredditWidgets.itemssi __ " " $ K   $D #||55??T?JE)   K  rcBt|j|jS)a0Get an instance of :class:`.SubredditWidgetsModeration`. .. note:: Using any of the methods of :class:`.SubredditWidgetsModeration` will likely result in the data of this :class:`.SubredditWidgets` being outdated. To re-sync, call :meth:`.refresh`. )SubredditWidgetsModerationr5r9r1s rmodzSubredditWidgets.mods*$..$,,GGrc:|j|jdS)z:Get this :class:`.Subreddit`'s :class:`.ModeratorsWidget`.moderatorWidgetr.r1s rmoderators_widgetz"SubredditWidgets.moderators_widget szz$++&7899rcf|jddDcgc]}|j|c}Scc}w)z;Get a list of :class:`.Widget`\ s that make up the sidebar.sidebarorderr0r/r2 widget_names rrDzSubredditWidgets.sidebar%s1<@;;y;QRY;Z[K ;'[[[.cf|jddDcgc]}|j|c}Scc}w)z;Get a list of :class:`.Widget`\ s that make up the top bar.topbarrErFrGs rrKzSubredditWidgets.topbar*s1<@;;x;PQX;YZK ;'ZZZrIc|jds(|js|jt||S|jj d|}t |)zReturn the value of ``attr``._z object has no attribute ) startswith_fetched_fetchgetattr __class__rAttributeError)r2attrmsgs r __getattr__zSubredditWidgets.__getattr__/sQs#DMM KKM4& &((++DTHMS!!rcrd|_d|_||_d|_t||j iy)zInitialize a :class:`.SubredditWidgets` instance. :param subreddit: The :class:`.Subreddit` the widgets belong to. NF)r8rOr5progressive_imagessuper__init__r9)r2r5rRs rrZzSubredditWidgets.__init__7s7 26 ""' **B/rc"d|jdS)z?Return an object initialization representation of the instance.zSubredditWidgets(subreddit=)r5r1s r__repr__zSubredditWidgets.__repr__Ds,T^^,>a@@rcp|jjtdj|jd|j i}|j d|_t|%|jj|gd}|jj }|D] }||d d|_ y)Nwidgetsr]rX)paramsr/)r3rBrDrKr/T) r9getrformatr5rXpopr8rYrZ__dict__rO)r2r7cached_property_names inst_dict_popnamerRs rrPzSubredditWidgets._fetchHs|| Y  & & & @($*A*AB   ((7+ //6!  )) ) &D $ % & rc$|jy)aRefresh the :class:`.Subreddit`'s widgets. By default, PRAW will not request progressively loading images from Reddit. To enable this, set the attribute ``progressive_images`` to ``True`` prior to calling ``refresh()``. .. code-block:: python widgets = reddit.subreddit("test").widgets widgets.progressive_images = True widgets.refresh() N)rPr1s rrefreshzSubredditWidgets.refresh^s  r)returnz models.IDCard)rkzdict[str, models.Widget])rkz!models.SubredditWidgetsModeration)rkzmodels.ModeratorsWidget)rkzlist[models.Widget])rkzlist[models.Menu])rTstrrkr)r5models.SubredditrkNone)rkrlrkrn)rrrrr r3r/r?rBrDrKrVrZr^rPrj __classcell__rRs@rr+r+sN`77   H H::\\[[" 0A,rr+c2eZdZdZddZddZ ddZ ddZdd ddZ dd Z dd Z dd Z dd Z dd Z ddddZddZy)r>aClass for moderating a :class:`.Subreddit`'s widgets. Get an instance of this class from :attr:`.SubredditWidgets.mod`. Example usage: .. code-block:: python 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. c ||_||_y)z;Initialize a :class:`.SubredditWidgetsModeration` instance.N) _subredditr9)r2r5reddits rrZz#SubredditWidgetsModeration.__init__s# rctdj|j}|jj |dt |t i}|j|_|S)N widget_creater]jsonclsr6)rrcrtr9postr WidgetEncoderr5)r2payloadpathwidgets r_create_widgetz)SubredditWidgetsModeration._create_widgetsT(//$///J""4vuW-7X.Y"Z?? rc V||d||d}|j||j|S)aAdd and return a :class:`.ButtonWidget`. :param 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: .. code-block:: text { "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: .. code-block:: text { "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: .. code-block:: text { "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: .. code-block:: text { "kind": "image", "url": a valid URL of a Reddit-hosted image, "height": an integer, "width": an integer } .. note:: The method :meth:`.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. :param description: Markdown text to describe the widget. :param short_name: A name for the widget, no longer than 30 characters. :param styles: A dictionary with keys ``"backgroundColor"`` and ``"headerColor"``, and values of hex colors. For example, ``{"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}``. :returns: The created :class:`.ButtonWidget`. .. _reddit docs: https://www.reddit.com/dev/api#POST_api_widget Example usage: .. code-block:: python 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, ) button)buttons descriptionkind shortNamestylesupdater)r2rr short_namerother_settings button_widgets radd_button_widgetz,SubredditWidgetsModeration.add_button_widgets<D&#   ^,""=11rc X||d|||d}|j||j|S)atAdd and return a :class:`.Calendar` widget. :param configuration: A dictionary as specified in `Reddit docs`_. For example: .. code-block:: python { "numEvents": 10, "showDate": True, "showDescription": False, "showLocation": False, "showTime": True, "showTitle": True, } :param google_calendar_id: An email-style calendar ID. To share a Google Calendar, make it public, then find the "Calendar ID". :param requires_sync: Whether the calendar needs synchronization. :param short_name: A name for the widget, no longer than 30 characters. :param styles: A dictionary with keys ``"backgroundColor"`` and ``"headerColor"``, and values of hex colors. For example, ``{"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}``. :returns: The created :class:`.Calendar`. .. _reddit docs: https://www.reddit.com/dev/api#POST_api_widget Example usage: .. code-block:: python 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, ) calendar) configurationgoogleCalendarIdr requiresSyncrrr)r2rgoogle_calendar_id requires_syncrrrrs r add_calendarz'SubredditWidgetsModeration.add_calendars=|+ 2)#   '""8,,r)rc V||d||d}|j||j|S)aQAdd and return a :class:`.CommunityList` widget. :param data: A list of subreddits. Subreddits can be represented as ``str`` or as :class:`.Subreddit`. These types may be mixed within the list. :param description: A string containing Markdown (default: ``""``). :param short_name: A name for the widget, no longer than 30 characters. :param styles: A dictionary with keys ``"backgroundColor"`` and ``"headerColor"``, and values of hex colors. For example, ``{"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}``. :returns: The created :class:`.CommunityList`. Example usage: .. code-block:: python 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" ) zcommunity-list)r7rrrrr)r2r7rrrrcommunity_lists radd_community_listz-SubredditWidgetsModeration.add_community_listds<D&$#   n-"">22rc Z|||d|||d}|j||j|S)ai Add and return a :class:`.CustomWidget`. :param 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. :param height: The height of the widget, between 50 and 500. :param 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 :meth:`.upload_image`. For example: .. code-block:: python [ { "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", }, ] :param short_name: A name for the widget, no longer than 30 characters. :param styles: A dictionary with keys ``"backgroundColor"`` and ``"headerColor"``, and values of hex colors. For example, ``{"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}``. :param text: The Markdown text displayed in the widget. :returns: The created :class:`.CustomWidget`. .. _reddit docs: https://www.reddit.com/dev/api#POST_api_widget Example usage: .. code-block:: python 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, ) custom)cssheight imageDatarrrtextr) r2rr image_datarrrr custom_widgets radd_custom_widgetz,SubredditWidgetsModeration.add_custom_widgetsB^##  ^,""=11rc T|d||d}|j||j|S)a%Add and return an :class:`.ImageWidget`. :param 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 :meth:`.upload_image`. For example: .. code-block:: python [ { "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", }, ] :param short_name: A name for the widget, no longer than 30 characters. :param styles: A dictionary with keys ``"backgroundColor"`` and ``"headerColor"``, and values of hex colors. For example, ``{"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}``. :returns: The created :class:`.ImageWidget`. .. _reddit docs: https://www.reddit.com/dev/api#POST_api_widget Example usage: .. code-block:: python 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 ) image)r7rrrr)r2r7rrr image_widgets radd_image_widgetz+SubredditWidgetsModeration.add_image_widgets9@#  N+""<00rc P|dd}|j||j|S)aAdd and return a :class:`.Menu` widget. :param data: A list of dictionaries describing menu contents, as specified in `Reddit docs`_. As of this writing, the format is: .. code-block:: text [ { "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 :class:`.Menu`. .. _reddit docs: https://www.reddit.com/dev/api#POST_api_widget Example usage: .. code-block:: python 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) menu)r7rr)r2r7rrs radd_menuz#SubredditWidgetsModeration.add_menu1s,tf- N#""4((rc V|d|||d}|j||j|S)aAdd and return a :class:`.PostFlairWidget`. :param display: Display style. Either ``"cloud"`` or ``"list"``. :param order: A list of flair template IDs. You can get all flair template IDs in a subreddit with: .. code-block:: python flairs = [f["id"] for f in subreddit.flair.link_templates] :param short_name: A name for the widget, no longer than 30 characters. :param styles: A dictionary with keys ``"backgroundColor"`` and ``"headerColor"``, and values of hex colors. For example, ``{"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}``. :returns: The created :class:`.PostFlairWidget`. Example usage: .. code-block:: python 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 ) z post-flair)displayrrErrr)r2rrErrr post_flairs radd_post_flair_widgetz0SubredditWidgetsModeration.add_post_flair_widgetos<P #   .)"":..rc Td|||d}|j||j|S)a:Add and return a :class:`.TextArea` widget. :param short_name: A name for the widget, no longer than 30 characters. :param styles: A dictionary with keys ``"backgroundColor"`` and ``"headerColor"``, and values of hex colors. For example, ``{"backgroundColor": "#FFFF66", "headerColor": "#3333EE"}``. :param text: The Markdown text displayed in the widget. :returns: The created :class:`.TextArea`. Example usage: .. code-block:: python 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 ) textarea)rrrrr)r2rrrr text_areas r add_text_areaz(SubredditWidgetsModeration.add_text_areas8<#  (""9--rrD)sectionc|Dcgc])}t|tr |jn t|+}}tdj ||j }|jj|t||dycc}w)aReorder the widgets. :param new_order: A list of widgets. Represented as a list that contains :class:`.Widget` objects, or widget IDs as strings. These types may be mixed. :param section: The section to reorder (default: ``"sidebar"``). Example usage: .. code-block:: python widgets = reddit.subreddit("test").widgets order = list(widgets.sidebar) order.reverse() widgets.mod.reorder(order) widget_order)rr5)rxrr6N) isinstanceWidgetidrlrrcrtr9patchr)r2 new_orderrthingrEr~s rreorderz"SubredditWidgetsModeration.reorderss$U^^5Zv6CJF^^'..w$//.Z 4uU|&PQ_s.Bc8|j|jS)aUpload an image to Reddit and get the URL. :param media: The :class:`.WidgetMedia` to upload. :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 :meth:`.add_image_widget`, :meth:`.add_custom_widget`, and :meth:`.add_button_widget`. Example usage: .. code-block:: python from praw.models import WidgetMedia my_sub = reddit.subreddit("test") image_url = my_sub.widgets.mod.upload_image(WidgetMedia("/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 ) )_uploadrt)r2medias r upload_imagez'SubredditWidgetsModeration.upload_images4}}T__--rN)r5rmru praw.Redditrkrn)r}dict[str, Any]rkr) rz1list[dict[str, dict[str, str | int] | str | int]]rrlrrlrdict[str, str]rrrkzmodels.ButtonWidget)rzdict[str, bool | int]rrlrboolrrlrrrrrkzmodels.Calendar) r7zlist[str | models.Subreddit]rrlrrlrrrrrkzmodels.CommunityList)rrlrintrlist[dict[str, str | int]]rrlrrrrlrrrkzmodels.CustomWidget) r7rrrlrrrrrkzmodels.ImageWidget)r7z+list[dict[str, list[dict[str, str]] | str]]rrrkzmodels.Menu | Widget) rrlrEz list[str]rrlrrrrrkzmodels.PostFlairWidget | Widget) rrlrrrrlrrrkzmodels.TextArea)rzlist[Widget | str]rrlrkrn)rzmodels.WidgetMediarkrl)rrrrrZrrrrrrrrrrrrrrr>r>osC( I2CI2 I2  I2  I2I2 I2VF--F- F-  F-  F-F-F- F-X )3+)3 )3  )3  )3)3 )3VX2X2 X2 / X2  X2X2X2X2 X2tF1)F1 F1  F1  F1 F1P<):<) <)  <)|//// //  //  //// )//b$.$. $.  $.  $. $.LHQR,.rr>cFeZdZdZeddZddZddZd fd ZxZ S) rz+Base class to represent a :class:`.Widget`.cDt||j|jS)aRGet an instance of :class:`.WidgetModeration` for this widget. .. note:: Using any of the methods of :class:`.WidgetModeration` will likely make the data in the :class:`.SubredditWidgets` that this widget belongs to outdated. To remedy this, call :meth:`~.SubredditWidgets.refresh`. )WidgetModerationr5r9r1s rr?z Widget.mods dnndllCCrct|tr5|jj|jjk(St |j|jjk(S)z&Check equality against another object.)rrrlowerrl)r2others r__eq__z Widget.__eq__ sN eV $77==?ehhnn&66 65z!TWW]]_44rct|jjt|jj z S)z(Return the hash of the current instance.)hashrRrrrr1s r__hash__zWidget.__hash__s+DNN++,tDGGMMO/DDDrcRd|_d|_t| ||d|_y)z'Initialize a :class:`.Widget` instance.r_dataN)r5rrYrZ_mod)r2rurrRs rrZzWidget.__init__s* u- r)rkzmodels.WidgetModeration)robjectrkr)rkrrurrrrkrn) rrrrr r?rrrZrprqs@rrrs/5 D D5 ErrceZdZdZdZy) ButtonWidgeta Class to represent a widget containing one or more buttons. Find an existing one: .. code-block:: python button_widget = None widgets = reddit.subreddit("test").widgets for widget in widgets.sidebar: if isinstance(widget, praw.models.ButtonWidget): button_widget = widget break for button in button_widget: print(button.text, button.url) Create one: .. code-block:: python widgets = reddit.subreddit("test").widgets 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": "#000000", "textColor": "#FFFFFF", "fillColor": "#0000FF", }, }, { "kind": "text", "text": "View documentation", "url": "https://praw.readthedocs.io", "color": "#FFFFFF", "textColor": "#FFFF00", "fillColor": "#0000FF", }, ] styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"} button_widget = widgets.mod.add_button_widget( "Things to click", "Click some of these *cool* links!", buttons, styles ) For more information on creation, see :meth:`.add_button_widget`. Update one: .. code-block:: python new_styles = {"backgroundColor": "#FFFFFF", "headerColor": "#FF9900"} button_widget = button_widget.mod.update(shortName="My fav buttons", styles=new_styles) Delete one: .. code-block:: python button_widget.mod.delete() .. include:: ../../typical_attributes.rst ==================== ============================================================== Attribute Description ==================== ============================================================== ``buttons`` A list of :class:`.Button`\ s. These can also be accessed just by iterating over the :class:`.ButtonWidget` (e.g., ``for button in button_widget``). ``description`` The description, in Markdown. ``description_html`` The description, in HTML. ``id`` The widget ID. ``kind`` The widget kind (always ``"button"``). ``shortName`` The short name of the widget. ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ==================== ============================================================== rNr(rrrrrsTl OrrceZdZdZy)Calendara Class to represent a calendar widget. Find an existing one: .. code-block:: python calendar = None widgets = reddit.subreddit("test").widgets for widget in widgets.sidebar: if isinstance(widget, praw.models.Calendar): calendar = widget break print(calendar.googleCalendarId) Create one: .. code-block:: python widgets = reddit.subreddit("test").widgets 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" calendar = widgets.mod.add_calendar( short_name="Upcoming Events", google_calendar_id=cal_id, requires_sync=True, configuration=config, styles=styles, ) For more information on creation, see :meth:`.add_calendar`. Update one: .. code-block:: python new_styles = {"backgroundColor": "#FFFFFF", "headerColor": "#FF9900"} calendar = calendar.mod.update(shortName="My fav events", styles=new_styles) Delete one: .. code-block:: python calendar.mod.delete() .. include:: ../../typical_attributes.rst ================= ===================================================== Attribute Description ================= ===================================================== ``configuration`` A ``dict`` describing the calendar configuration. ``data`` A list of dictionaries that represent events. ``id`` The widget ID. ``kind`` The widget kind (always ``"calendar"``). ``requiresSync`` A ``bool`` representing whether the calendar requires synchronization. ``shortName`` The short name of the widget. ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ================= ===================================================== NrrrrrrusFrrceZdZdZdZy) CommunityListaClass to represent a Related Communities widget. Find an existing one: .. code-block:: python community_list = None widgets = reddit.subreddit("test").widgets for widget in widgets.sidebar: if isinstance(widget, praw.models.CommunityList): community_list = widget break print(community_list) Create one: .. code-block:: python widgets = reddit.subreddit("test").widgets styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"} subreddits = ["learnpython", reddit.subreddit("test")] community_list = widgets.mod.add_community_list( short_name="Related subreddits", data=subreddits, styles=styles, description="description", ) For more information on creation, see :meth:`.add_community_list`. Update one: .. code-block:: python new_styles = {"backgroundColor": "#FFFFFF", "headerColor": "#FF9900"} community_list = community_list.mod.update(shortName="My fav subs", styles=new_styles) Delete one: .. code-block:: python community_list.mod.delete() .. include:: ../../typical_attributes.rst ============= ===================================================================== Attribute Description ============= ===================================================================== ``data`` A list of :class:`.Subreddit`\ s. These can also be iterated over by iterating over the :class:`.CommunityList` (e.g., ``for sub in community_list``). ``id`` The widget ID. ``kind`` The widget kind (always ``"community-list"``). ``shortName`` The short name of the widget. ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ============= ===================================================================== r7Nr(rrrrrs;zOrrc$eZdZdZdfd ZxZS) CustomWidgetaClass to represent a custom widget. Find an existing one: .. code-block:: python custom = None widgets = reddit.subreddit("test").widgets for widget in widgets.sidebar: if isinstance(widget, praw.models.CustomWidget): custom = widget break print(custom.text) print(custom.css) Create one: .. code-block:: python widgets = reddit.subreddit("test").widgets styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"} custom = widgets.mod.add_custom_widget( short_name="My custom widget", text="# Hello world!", css="/**/", height=200, image_data=[], styles=styles, ) For more information on creation, see :meth:`.add_custom_widget`. Update one: .. code-block:: python new_styles = {"backgroundColor": "#FFFFFF", "headerColor": "#FF9900"} custom = custom.mod.update(shortName="My fav customization", styles=new_styles) Delete one: .. code-block:: python custom.mod.delete() .. include:: ../../typical_attributes.rst ================= ============================================================ Attribute Description ================= ============================================================ ``css`` The CSS of the widget, as a ``str``. ``height`` The height of the widget, as an ``int``. ``id`` The widget ID. ``imageData`` A ``list`` of :class:`.ImageData` that belong to the widget. ``kind`` The widget kind (always ``"custom"``). ``shortName`` The short name of the widget. ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``stylesheetUrl`` A link to the widget's stylesheet. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ``text`` The text contents, as Markdown. ``textHtml`` The text contents, as HTML. ================= ============================================================ c|jdDcgc]}t||c}|d<t| ||ycc}w)z-Initialize a :class:`.CustomWidget` instance.rrN)rdr rYrZ)r2rurr7rRs rrZzCustomWidget.__init__Ds@BG))KBXY$i5Yk u-ZsAr)rrrrrZrprqs@rrrsAF..rrceZdZdZy)IDCardaClass to represent an ID card widget. .. code-block:: python widgets = reddit.subreddit("test").widgets id_card = widgets.id_card print(id_card.subscribersText) Update one: .. code-block:: python widgets.id_card.mod.update(currentlyViewingText="Bots") .. include:: ../../typical_attributes.rst ========================= ======================================================= Attribute Description ========================= ======================================================= ``currentlyViewingCount`` The number of redditors viewing the subreddit. ``currentlyViewingText`` The text displayed next to the view count. For example, ``"users online"``. ``description`` The subreddit description. ``id`` The widget ID. ``kind`` The widget kind (always ``"id-card"``). ``shortName`` The short name of the widget. ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ``subscribersCount`` The number of subscribers to the subreddit. ``subscribersText`` The text displayed next to the subscriber count. For example, "users subscribed". ========================= ======================================================= NrrrrrrJs"rrceZdZdZdZy) ImageWidgetaClass to represent an image widget. Find an existing one: .. code-block:: python image_widget = None widgets = reddit.subreddit("test").widgets for widget in widgets.sidebar: if isinstance(widget, praw.models.ImageWidget): image_widget = widget break for image in image_widget: print(image.url) Create one: .. code-block:: python widgets = reddit.subreddit("test").widgets image_paths = ["/path/to/image1.jpg", "/path/to/image2.png"] image_data = [ { "width": 600, "height": 450, "linkUrl": "", "url": widgets.mod.upload_image(img_path), } for img_path in image_paths ] styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"} image_widget = widgets.mod.add_image_widget( short_name="My cool pictures", data=image_data, styles=styles ) For more information on creation, see :meth:`.add_image_widget`. Update one: .. code-block:: python new_styles = {"backgroundColor": "#FFFFFF", "headerColor": "#FF9900"} image_widget = image_widget.mod.update(shortName="My fav images", styles=new_styles) Delete one: .. code-block:: python image_widget.mod.delete() .. include:: ../../typical_attributes.rst ============= ===================================================================== Attribute Description ============= ===================================================================== ``data`` A list of the :class:`.Image`\ s in this widget. Can be iterated over by iterating over the :class:`.ImageWidget` (e.g., ``for img in image_widget``). ``id`` The widget ID. ``kind`` The widget kind (always ``"image"``). ``shortName`` The short name of the widget. ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ============= ===================================================================== r7Nr(rrrrrpsBHOrrceZdZdZdZy)MenuaClass to represent the top menu widget of a :class:`.Subreddit`. Menus can generally be found as the first item in a :class:`.Subreddit`'s top bar. .. code-block:: python topbar = reddit.subreddit("test").widgets.topbar if len(topbar) > 0: probably_menu = topbar[0] assert isinstance(probably_menu, praw.models.Menu) for item in probably_menu: if isinstance(item, praw.models.Submenu): print(item.text) for child in item: print("\t", child.text, child.url) else: # MenuLink print(item.text, item.url) Create one: .. code-block:: python widgets = reddit.subreddit("test").widgets menu_contents = [ {"text": "My homepage", "url": "https://example.com"}, { "text": "Python packages", "children": [ {"text": "PRAW", "url": "https://praw.readthedocs.io/"}, {"text": "requests", "url": "http://python-requests.org"}, ], }, {"text": "Reddit homepage", "url": "https://reddit.com"}, ] menu = widgets.mod.add_menu(data=menu_contents) For more information on creation, see :meth:`.add_menu`. Update one: .. code-block:: python menu_items = list(menu) menu_items.reverse() menu = menu.mod.update(data=menu_items) Delete one: .. code-block:: python menu.mod.delete() .. include:: ../../typical_attributes.rst ============= ==================================================================== Attribute Description ============= ==================================================================== ``data`` A list of the :class:`.MenuLink`\ s and :class:`.Submenu`\ s in this widget. Can be iterated over by iterating over the :class:`.Menu` (e.g., ``for item in menu``). ``id`` The widget ID. ``kind`` The widget kind (always ``"menu"``). ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ============= ==================================================================== r7Nr(rrrrrsAFOrrc(eZdZdZdZdfd ZxZS)ModeratorsWidgetaClass to represent a moderators widget. .. code-block:: python widgets = reddit.subreddit("test").widgets print(widgets.moderators_widget) Update one: .. code-block:: python new_styles = {"backgroundColor": "#FFFFFF", "headerColor": "#FF9900"} widgets.moderators_widget.mod.update(styles=new_styles) .. include:: ../../typical_attributes.rst ============= ===================================================================== Attribute Description ============= ===================================================================== ``id`` The widget ID. ``kind`` The widget kind (always ``"moderators"``). ``mods`` A list of the :class:`.Redditor`\ s that moderate the subreddit. Can be iterated over by iterating over the :class:`.ModeratorsWidget` (e.g., ``for mod in widgets.moderators_widget``). ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ``totalMods`` The total number of moderators in the subreddit. ============= ===================================================================== modscZ|j}|J||vrg||<t| ||y)z1Initialize a :class:`.ModeratorsWidget` instance.Nrr)rYrZr2rurchild_attributerRs rrZzModeratorsWidget.__init__!>..*** % '%'E/ " u-rrrrrrr)rZrprqs@rrrs>O..rrceZdZdZdZy)PostFlairWidgetaClass to represent a post flair widget. Find an existing one: .. code-block:: python post_flair_widget = None widgets = reddit.subreddit("test").widgets for widget in widgets.sidebar: if isinstance(widget, praw.models.PostFlairWidget): post_flair_widget = widget break for flair in post_flair_widget: print(flair) print(post_flair_widget.templates[flair]) Create one: .. code-block:: python subreddit = reddit.subreddit("test") widgets = subreddit.widgets flairs = [f["id"] for f in subreddit.flair.link_templates] styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"} post_flair = widgets.mod.add_post_flair_widget( short_name="Some flairs", display="list", order=flairs, styles=styles ) For more information on creation, see :meth:`.add_post_flair_widget`. Update one: .. code-block:: python new_styles = {"backgroundColor": "#FFFFFF", "headerColor": "#FF9900"} post_flair = post_flair.mod.update(shortName="My fav flairs", styles=new_styles) Delete one: .. code-block:: python post_flair.mod.delete() .. include:: ../../typical_attributes.rst ============= ===================================================================== Attribute Description ============= ===================================================================== ``display`` The display style of the widget, either ``"cloud"`` or ``"list"``. ``id`` The widget ID. ``kind`` The widget kind (always ``"post-flair"``). ``order`` A list of the flair IDs in this widget. Can be iterated over by iterating over the :class:`.PostFlairWidget` (e.g., ``for flair_id in post_flair``). ``shortName`` The short name of the widget. ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ``templates`` A ``dict`` that maps flair IDs to dictionaries that describe flairs. ============= ===================================================================== rENr(rrrrr+s=~Orrc(eZdZdZdZdfd ZxZS) RulesWidgetaClass to represent a rules widget. .. code-block:: python widgets = reddit.subreddit("test").widgets rules_widget = None for widget in widgets.sidebar: if isinstance(widget, praw.models.RulesWidget): rules_widget = widget break from pprint import pprint pprint(rules_widget.data) Update one: .. code-block:: python new_styles = {"backgroundColor": "#FFFFFF", "headerColor": "#FF9900"} rules_widget.mod.update(display="compact", shortName="The LAWS", styles=new_styles) .. include:: ../../typical_attributes.rst ============= ===================================================================== Attribute Description ============= ===================================================================== ``data`` A list of the subreddit rules. Can be iterated over by iterating over the :class:`.RulesWidget` (e.g., ``for rule in rules_widget``). ``display`` The display style of the widget, either ``"full"`` or ``"compact"``. ``id`` The widget ID. ``kind`` The widget kind (always ``"subreddit-rules"``). ``shortName`` The short name of the widget. ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ============= ===================================================================== r7cZ|j}|J||vrg||<t| ||y)z,Initialize a :class:`.RulesWidget` instance.Nrrrs rrZzRulesWidget.__init__rrrrrqs@rrrns$LO..rrceZdZdZy)TextAreaaClass to represent a text area widget. Find a text area in a subreddit: .. code-block:: python widgets = reddit.subreddit("test").widgets text_area = None for widget in widgets.sidebar: if isinstance(widget, praw.models.TextArea): text_area = widget break print(text_area.text) Create one: .. code-block:: python widgets = reddit.subreddit("test").widgets styles = {"backgroundColor": "#FFFF66", "headerColor": "#3333EE"} text_area = widgets.mod.add_text_area( short_name="My cool title", text="*Hello* **world**!", styles=styles ) For more information on creation, see :meth:`.add_text_area`. Update one: .. code-block:: python new_styles = {"backgroundColor": "#FFFFFF", "headerColor": "#FF9900"} text_area = text_area.mod.update(shortName="My fav text", styles=new_styles) Delete one: .. code-block:: python text_area.mod.delete() .. include:: ../../typical_attributes.rst ============= ===================================================================== Attribute Description ============= ===================================================================== ``id`` The widget ID. ``kind`` The widget kind (always ``"textarea"``). ``shortName`` The short name of the widget. ``styles`` A ``dict`` with the keys ``"backgroundColor"`` and ``"headerColor"``. ``subreddit`` The :class:`.Subreddit` the button widget belongs to. ``text`` The widget's text, as Markdown. ``textHtml`` The widget's text, as HTML. ============= ===================================================================== Nrrrrrrs5rrc$eZdZUdZded<ddZy)r|z'Class to encode widget-related objects.ztype[models.Subreddit]_subreddit_classct||jr t|St|tr?t |j Dcic]\}}|j dr||c}}Stj||Scc}}w)zSerialize ``PRAWBase`` objects.rM) rrrlr varsr/rNrdefault)r2okeyvals rrzWidgetEncoder.defaultsm a.. /q6M a "-1!W]]_XcCNNSVDWCHX X""4++Ys B(BN)rrrkr)rrrr__annotations__rrrrr|r|s1,,,rr|c8eZdZdZ ddZddZddZy) rzClass for moderating a particular widget. Example usage: .. code-block:: python widget = reddit.subreddit("test").widgets.sidebar[0] widget.mod.update(shortName="My new title") widget.mod.delete() c.||_||_||_y)z1Initialize a :class:`.WidgetModeration` instance.N)rr9rt)r2rr5rus rrZzWidgetModeration.__init__s  #rctdj|j|jj}|j j |y)zuDelete the widget. Example usage: .. code-block:: python widget.mod.delete() widget_modifyr5 widget_idN)rrcrtrrr9delete)r2r~s rrzWidgetModeration.deletesA(//$//UYU`U`UcUc/d D!rc tdj|j|jj}t |jj Dcic]\}}|jdr||}}}|d=|jdd|j||jj|dt|ti }|j|_|Scc}}w) aUpdate the widget. Returns the updated widget. Parameters differ based on the type of widget. See `Reddit documentation `_ or the document of the particular type of widget. :returns: The updated :class:`.Widget`. For example, update a text widget like so: .. code-block:: python text_widget.mod.update(shortName="New text area", text="Hello!") .. note:: Most parameters follow the ``lowerCamelCase`` convention. When in doubt, check the Reddit documentation linked above. rrrMr5r?Nrxryr6)rrcrtrrrr/rNrdrr9putrr|r5)r2kwargsr~rvaluer}rs rrzWidgetModeration.update s*(//$//UYU`U`UcUc/d04T[[0A0G0G0Ie*#uQTQ_Q_`cQd3:ee K  E4 v!!$feG6W-X!Y?? fs C(9C(N)rrr5zmodels.Subreddit | strrurrkrnro)rrrkr)rrrrrZrrrrrrrs<  $ $* $ $  $ "rr),r __future__rrxrrtypingrr praw.constrpraw.models.baser r praw.models.list.baser praw.util.cacher prawr rrrrr r"r$r&r+r>rrrrrrrrrrrrr|rrrrrs)"#%8** 6-x& x4 x"!8"  (  "!!&}x}@G .G .T DW 68W tGvGT>FH>BG.6G.T#V#LE&(EPD68DN).vx).X@fh@F0.&(0.f6v6r ,K ,AAr