o
    2g                     @  s,  U d Z ddlmZ ddlmZmZ ddlmZ ddlm	Z	m
Z
mZ ddlmZ ddlmZ dd	lmZ d
dlmZ d
dlmZ e	rEddlZedddZded< G dd deZG dd deZG dd deZG dd deZG dd deZG dd deZG dd deZ G d d! d!eZ!G d"d# d#eZ"G d$d deZ#G d%d& d&eZ$G d'd( d(e#eZ%G d)d* d*e#Z&G d+d, d,e#eZ'G d-d. d.e#Z(G d/d0 d0e#Z)G d1d2 d2e#eZ*G d3d4 d4e#eZ+G d5d6 d6e#eZ,G d7d8 d8e#eZ-G d9d: d:e#eZ.G d;d< d<e#Z/G d=d> d>Z0G d?d@ d@Z1dS )Az#Provide classes related to widgets.    )annotations)JSONEncoderdumps)Path)TYPE_CHECKINGAnyTypeVar   )API_PATH)_deprecate_args)cachedproperty   )PRAWBase)BaseListN
WidgetTypeWidget)boundr   c                   @     e Zd ZdZdS )Buttona  Class 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__ r   r   R/home/garg/my-data/venv/lib/python3.10/site-packages/praw/models/reddit/widgets.pyr          r   c                   @  r   )CalendarConfigurationa  Class 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.
    =================== ================================================

    Nr   r   r   r   r   r   0   r   r   c                   @  r   )Hovera  Class 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.
    ============= =====================================================================

    Nr   r   r   r   r   r   C   r   r   c                   @  r   )Imagea  Class 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.
    =========== =================================================

    Nr   r   r   r   r   r   ]   r   r   c                   @  r   )	ImageDataa  Class 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.
    ========== =========================================

    Nr   r   r   r   r   r    n   r   r    c                   @  r   )MenuLinka  Class 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.
    ========= ====================================

    Nr   r   r   r   r   r!      r   r!   c                   @  r   )Stylesap  Class 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######``).
    =================== ========================================================

    Nr   r   r   r   r   r"      r   r"   c                   @     e Zd ZdZdZdS )Submenua  Class 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.
    ============ ======================================================================

    childrenNr   r   r   r   CHILD_ATTRIBUTEr   r   r   r   r$      s    r$   c                      s   e Zd ZdZed$ddZed%ddZed&d
dZed'ddZed(ddZ	ed)ddZ
d*ddZd+ fddZd,ddZ fd d!Zd"d# Z  ZS )-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`

    returnpraw.models.IDCardc                 C     | j | jd  S )z7Get this :class:`.Subreddit`'s :class:`.IDCard` widget.idCardWidgetitemslayoutselfr   r   r   id_card     zSubredditWidgets.id_carddict[str, praw.models.Widget]c                 C  s8   i }| j  D ]\}}| j|d< | jj|||< q|S )zCGet this :class:`.Subreddit`'s widgets as a dict from ID to widget.	subreddit)
_raw_itemsr.   r5   _reddit	_objector	objectify)r1   r.   	item_namedatar   r   r   r.     s
   
zSubredditWidgets.items&praw.models.SubredditWidgetsModerationc                 C  s   t | j| jS )a0  Get 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`.

        )SubredditWidgetsModerationr5   r7   r0   r   r   r   mod  s   zSubredditWidgets.modpraw.models.ModeratorsWidgetc                 C  r+   )z:Get this :class:`.Subreddit`'s :class:`.ModeratorsWidget`.moderatorWidgetr-   r0   r   r   r   moderators_widget  r3   z"SubredditWidgets.moderators_widgetlist[praw.models.Widget]c                       fdd j d d D S )z;Get a list of :class:`.Widget`\ s that make up the sidebar.c                      g | ]} j | qS r   r.   .0widget_namer0   r   r   
<listcomp>&      
z,SubredditWidgets.sidebar.<locals>.<listcomp>sidebarorderr/   r0   r   r0   r   rK   #     
zSubredditWidgets.sidebarlist[praw.models.Menu]c                   rC   )z;Get a list of :class:`.Widget`\ s that make up the top bar.c                   rD   r   rE   rF   r0   r   r   rI   -  rJ   z+SubredditWidgets.topbar.<locals>.<listcomp>topbarrL   rM   r0   r   r0   r   rP   *  rN   zSubredditWidgets.topbarattrstrr   c                 C  s<   | ds| js|   t| |S | jjd|}t|)zReturn the value of ``attr``._z object has no attribute )
startswith_fetched_fetchgetattr	__class__r   AttributeError)r1   rQ   msgr   r   r   __getattr__1  s
   
zSubredditWidgets.__getattr__r5   praw.models.Subredditc                   s,   d| _ d| _|| _d| _t |ji  dS )zInitialize a :class:`.SubredditWidgets` instance.

        :param subreddit: The :class:`.Subreddit` the widgets belong to.

        NF)r6   rU   r5   progressive_imagessuper__init__r7   )r1   r5   rX   r   r   r_   9  s
   zSubredditWidgets.__init__c                 C  s   d| j dS )z?Return an object initialization representation of the instance.zSubredditWidgets(subreddit=)r5   r0   r   r   r   __repr__F  s   zSubredditWidgets.__repr__c                   sp   | j jtd j| jdd| jid}|d| _t 	| jj | g d}| j
j}|D ]}||d  q+d| _d S )Nwidgetsrb   r]   )paramsr.   )r2   rA   rK   rP   r.   T)r7   getr
   formatr5   r]   popr6   r^   r_   __dict__rU   )r1   r;   cached_property_namesinst_dict_popnamer`   r   r   rV   J  s   
zSubredditWidgets._fetchc                 C  s   |    dS )a  Refresh 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)rV   r0   r   r   r   refresh`  s   zSubredditWidgets.refresh)r)   r*   )r)   r4   )r)   r<   )r)   r?   )r)   rB   )r)   rO   )rQ   rR   r)   r   )r5   r\   )r)   rR   )r   r   r   r   r   r2   r.   r>   rA   rK   rP   r[   r_   rc   rV   rm   __classcell__r   r   r`   r   r(      s&    P

r(   c                      s:   e Zd ZdZedddZdd	d
Zd fddZ  ZS )r   z+Base class to represent a :class:`.Widget`.r)   praw.models.WidgetModerationc                 C  s   t | | j| jS )aR  Get 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`.

        )WidgetModerationr5   r7   r0   r   r   r   r>   t  s   z
Widget.modotherobjectboolc                 C  s4   t |tr| j |j kS t| | j kS )z&Check equality against another object.)
isinstancer   idlowerrR   )r1   rq   r   r   r   __eq__  s   
zWidget.__eq__redditpraw.Reddit_datadict[str, Any]c                   s&   d| _ d| _t j||d d| _dS )z'Initialize a :class:`.Widget` instance. rz   N)r5   ru   r^   r_   _modr1   rx   rz   r`   r   r   r_     s   
zWidget.__init__)r)   ro   )rq   rr   r)   rs   rx   ry   rz   r{   )	r   r   r   r   r   r>   rw   r_   rn   r   r   r`   r   r   q  s    
c                   @  s   e Zd ZdZdddZdS )	WidgetEncoderz'Class to encode widget-related objects.or   r)   c                 C  s@   t || jr
t|S t |trdd t| D S t| |S )zSerialize ``PRAWBase`` objects.c                 S      i | ]\}}| d s||qS rS   rT   )rG   keyvalr   r   r   
<dictcomp>  s     z)WidgetEncoder.default.<locals>.<dictcomp>)rt   _subreddit_classrR   r   varsr.   r   default)r1   r   r   r   r   r     s
   
zWidgetEncoder.defaultN)r   r   r)   r   )r   r   r   r   r   r   r   r   r   r     s    r   c                   @  r#   )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.
    ==================== ==============================================================

    buttonsNr&   r   r   r   r   r     s    Vr   c                   @  r   )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.
    ================= =====================================================

    Nr   r   r   r   r   r     r   r   c                   @  r#   )CommunityLista  Class 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.
    ============= =====================================================================

    r;   Nr&   r   r   r   r   r   ?  s    =r   c                      s"   e Zd ZdZd fddZ  ZS )	CustomWidgeta  Class 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.
    ================= ============================================================

    rx   ry   rz   r{   c                   s0    fdd| dD |d< t j |d dS )z-Initialize a :class:`.CustomWidget` instance.c                   s   g | ]}t  |qS r   )r    )rG   r;   rx   r   r   rI     rJ   z)CustomWidget.__init__.<locals>.<listcomp>	imageDatar}   N)rh   r^   r_   r   r`   r   r   r_     s   

zCustomWidget.__init__r   )r   r   r   r   r_   rn   r   r   r`   r   r     s    Cr   c                   @  r   )IDCarda  Class 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".
    ========================= =======================================================

    Nr   r   r   r   r   r     r   r   c                   @  r#   )ImageWidgeta  Class 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.
    ============= =====================================================================

    r;   Nr&   r   r   r   r   r     s    Dr   c                   @  r#   )Menua  Class 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.
    ============= ====================================================================

    r;   Nr&   r   r   r   r   r   :  s    Cr   c                      &   e Zd ZdZdZd	 fddZ  ZS )
ModeratorsWidgeta  Class 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.
    ============= =====================================================================

    modsrx   ry   rz   r{   c                   (   | j |vr
g || j < t j||d dS )z1Initialize a :class:`.ModeratorsWidget` instance.r}   Nr'   r^   r_   r   r`   r   r   r_        

zModeratorsWidget.__init__r   r   r   r   r   r'   r_   rn   r   r   r`   r   r     s    r   c                   @  r#   )PostFlairWidgeta  Class 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.
    ============= =====================================================================

    rL   Nr&   r   r   r   r   r     s    ?r   c                      r   )
RulesWidgeta  Class 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.
    ============= =====================================================================

    r;   rx   ry   rz   r{   c                   r   )z,Initialize a :class:`.RulesWidget` instance.r}   Nr   r   r`   r   r   r_     r   zRulesWidget.__init__r   r   r   r   r`   r   r     s    &r   c                   @  r   )TextAreaa  Class 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.
    ============= =====================================================================

    Nr   r   r   r   r   r     r   r   c                   @  s,   e Zd ZdZddd	Zd
d ZdddZdS )rp   zClass 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()

    widgetr   r5   praw.models.Subreddit | strrx   ry   c                 C  s   || _ || _|| _dS )z1Initialize a :class:`.WidgetModeration` instance.N)r   r7   
_subreddit)r1   r   r5   rx   r   r   r   r_   e  s   
zWidgetModeration.__init__c                 C  s(   t d j| jj| jd}| j| dS )zuDelete the widget.

        Example usage:

        .. code-block:: python

            widget.mod.delete()

        widget_modify	widget_idr5   N)r
   rg   r   ru   r   r7   delete)r1   pathr   r   r   r   p  s   

zWidgetModeration.deletekwargsr   r)   c                 K  sv   t d j| jj| jd}dd t| j D }|d= d|v r"|d= || | jj	|dt
|tdid	}| j|_|S )
a  Update the widget. Returns the updated widget.

        Parameters differ based on the type of widget. See `Reddit documentation
        <https://www.reddit.com/dev/api#PUT_api_widget_{widget_id}>`_ 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.

        r   r   c                 S  r   r   r   )rG   r   valuer   r   r   r     s    z+WidgetModeration.update.<locals>.<dictcomp>r5   r>   jsonclsr;   )r
   rg   r   ru   r   r   r.   updater7   putr   r   r5   )r1   r   r   payloadr   r   r   r   r     s   

zWidgetModeration.updateN)r   r   r5   r   rx   ry   )r   r   r)   r   )r   r   r   r   r_   r   r   r   r   r   r   rp   X  s
    
rp   c                   @  s
  e Zd ZdZdMddZdNddZedddddOddZeddddddPd d!Zedd"ddd#d$dQd'd(Z	edd)d*d+d,ddRd0d1Z
edd"ddSd3d4Zed"dTd7d8Zedd9d:ddUd=d>Zedd)ddVd@dAZedBdCdDdEdWdGdHZdXdJdKZdLS )Yr=   a  Class 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.

    r5   r\   rx   ry   c                 C  s   || _ || _dS )z;Initialize a :class:`.SubredditWidgetsModeration` instance.N)r   r7   )r1   r5   rx   r   r   r   r_     s   
z#SubredditWidgetsModeration.__init__r   r{   r)   r   c                 C  s:   t d j| jd}| jj|dt|tdid}| j|_|S )Nwidget_createrb   r   r   r   )r
   rg   r   r7   postr   r   r5   )r1   r   r   r   r   r   r   _create_widget  s   z)SubredditWidgetsModeration._create_widget
short_namedescriptionr   styles1list[dict[str, dict[str, str | int] | str | int]]rR   dict[str, str]other_settingsr   praw.models.ButtonWidgetc                K  s$   ||d||d}| | | |S )a  Add 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)r   r   kind	shortNamer   r   r   )r1   r   r   r   r   r   button_widgetr   r   r   add_button_widget  s    

z,SubredditWidgetsModeration.add_button_widgetgoogle_calendar_idrequires_syncconfigurationdict[str, bool | int]rs   praw.models.Calendarc                K  s&   |||||dd}| | | |S )at  Add 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)r   googleCalendarIdrequiresSyncr   r   r   r   )r1   r   r   r   r   r   r   r   r   r   r   add_calendarU  s   A

z'SubredditWidgetsModeration.add_calendarr;   r|   )r   !list[str | praw.models.Subreddit]praw.models.CommunityListc                K  s$   |d|||d}| | | |S )aQ  Add 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"
            )

        zcommunity-list)r;   r   r   r   r   r   )r1   r;   r   r   r   r   community_listr   r   r   add_community_list  s   #

z-SubredditWidgetsModeration.add_community_listtextcssheight
image_dataintlist[dict[str, str | int]]praw.models.CustomWidgetc          	      K  s(   |||d|||d}| | | |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)r   r   r   r   r   r   r   r   )	r1   r   r   r   r   r   r   r   custom_widgetr   r   r   add_custom_widget  s   P
	
z,SubredditWidgetsModeration.add_custom_widgetpraw.models.ImageWidgetc                K  s"   |d||d}| | | |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)r;   r   r   r   r   )r1   r;   r   r   r   image_widgetr   r   r   add_image_widget'  s   A

z+SubredditWidgetsModeration.add_image_widget+list[dict[str, list[dict[str, str]] | str]]praw.models.Menu | Widgetc                K  s   |dd}| | | |S )a  Add 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)r;   r   r   )r1   r;   r   r   r   r   r   add_menup  s   
;

z#SubredditWidgetsModeration.add_menudisplayrL   	list[str]$praw.models.PostFlairWidget | Widgetc                K  s$   d||||d}| | | |S )a  Add 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)r   r   r   rL   r   r   )r1   r   rL   r   r   r   
post_flairr   r   r   add_post_flair_widget  s   )

z0SubredditWidgetsModeration.add_post_flair_widgetpraw.models.TextAreac                K  s"   |||dd}| | | |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)r   r   r   r   r   )r1   r   r   r   r   	text_arear   r   r   add_text_area  s   

z(SubredditWidgetsModeration.add_text_area	new_ordersectionrK   )r   list[Widget | str]c                C  s@   dd |D }t d j| j|d}| jj|t||dd dS )a  Reorder 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)

        c                 S  s$   g | ]}t |tr|jnt|qS r   )rt   r   ru   rR   )rG   thingr   r   r   rI     s    z6SubredditWidgetsModeration.reorder.<locals>.<listcomp>widget_order)r5   r   )r   r   r   N)r
   rg   r   r7   patchr   )r1   r   r   rL   r   r   r   r   reorder  s   z"SubredditWidgetsModeration.reorder	file_pathc           
      C  s   t |}|jdd}| drd|d< td j| jd}| jj||dd	 }d
d |d D }d|d  }|	d}| jj
jjj||d|id}	W d   n1 sVw   Y  |	  | d|d  S )af  Upload an image to Reddit and get the URL.

        :param 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 :meth:`.add_image_widget`, :meth:`.add_custom_widget`, and
        :meth:`.add_button_widget`.

        Example usage:

        .. code-block:: python

            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
            )

        z
image/jpeg)filepathmimetypez.pngz	image/pngr   widget_leaserb   r   s3UploadLeasec                 S  s   i | ]	}|d  |d qS )rl   r   r   )rG   itemr   r   r   r   F  s    z;SubredditWidgetsModeration.upload_image.<locals>.<dictcomp>fieldszhttps:actionrbfile)r;   filesN/r   )r   rl   rv   endswithr
   rg   r   r7   r   open_core
_requestor_httpraise_for_status)
r1   r   r   img_dataurlupload_leaseupload_data
upload_urlr   responser   r   r   upload_image#  s"   
z'SubredditWidgetsModeration.upload_imageN)r5   r\   rx   ry   )r   r{   r)   r   )r   r   r   rR   r   rR   r   r   r   r   r)   r   )r   r   r   rR   r   rs   r   rR   r   r   r   r   r)   r   )r;   r   r   rR   r   rR   r   r   r   r   r)   r   )r   rR   r   r   r   r   r   rR   r   r   r   rR   r   r   r)   r   )
r;   r   r   rR   r   r   r   r   r)   r   )r;   r   r   r   r)   r   )r   rR   rL   r   r   rR   r   r   r   r   r)   r   )
r   rR   r   r   r   rR   r   r   r)   r   )r   r   r   rR   )r   rR   r)   rR   )r   r   r   r   r_   r   r   r   r   r   r   r   r   r   r   r   r  r   r   r   r   r=     s6    

 
H+
ZH>
1&r=   )2r   
__future__r   r   r   r   pathlibr   typingr   r   r   constr
   utilr   
util.cacher   baser   	list.baser   praw.modelsprawr   __annotations__r   r   r   r   r    r!   r"   r$   r(   r   r   r   r   r   r   r   r   r   r   r   r   r   rp   r=   r   r   r   r   <module>   sL     @ZJAL&HG*C19O