
    {i&F                       S r SSKJr  SSKJrJr  SSKJr  SSKJ	r	  SSK
Jr  SSKJr  S	S
KJr  SSKJr  SSKJr  SSKJr  \(       a
  SSKJr  SSKr " S S\5      r " S S\5      r " S S\5      r " S S\5      r\\l        g)z"Provide Collections functionality.    )annotations)TYPE_CHECKINGAny   )API_PATH)ClientException)_deprecate_args)cachedproperty   )PRAWBase   )
RedditBase)
Submission)	Subreddit)IteratorNc                  |   ^  \ rS rSrSrSU 4S jjrSS jrSS jrS rSS jr	SS jr
SS	 jrSS
 jrSS jrSrU =r$ )CollectionModeration   zClass to support moderation actions on a :class:`.Collection`.

Obtain an instance via:

.. code-block:: python

    reddit.subreddit("test").collections("some_uuid").mod

c                .   > [         TU ]  USS9  X l        g)zpInitialize a :class:`.CollectionModeration` instance.

:param collection_id: The ID of a :class:`.Collection`.

N_data)super__init__collection_id)selfredditr   	__class__s      X/home/james-whalen/.local/lib/python3.13/site-packages/praw/models/reddit/collections.pyr   CollectionModeration.__init__!   s     	t,*    c                   [        U[        5      (       a  UR                  $ [        U[        5      (       d  S[	        U5       S3n[        U5      eUR                  U R                  R                  R                  S    S35      (       a  U$  U R                  R                  US9R                  $ ! [         a(    U R                  R                  U5      R                  s $ f = f)zGet a post's fullname.

:param post: A fullname, a :class:`.Submission`, a permalink, or an ID.

:returns: The fullname of the post.

z(Cannot get fullname from object of type .
submission_)url)
isinstancer   fullnamestrtype	TypeError
startswith_redditconfigkindsr#   r   )r   postmsgs      r   _post_fullname#CollectionModeration._post_fullname*   s     dJ''== $$$<T$ZLJCC. ??dll1177EFaHIIK	:<<**t*4=== 	:<<**40999	:s   "B1 1/C#"C#c                    U R                  U5      nU R                  R                  [        S   U R                  US.S9  g)ai  Add a post to the collection.

:param submission: The post to add, a :class:`.Submission`, its permalink as a
    ``str``, its fullname as a ``str``, or its ID as a ``str``.

Example usage:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    collection.mod.add_post("bgibu9")

.. seealso::

    :meth:`.remove_post`

collection_add_postr   link_fullnamedataNr1   r,   r/   r   r   r   r#   r6   s      r   add_postCollectionModeration.add_post>   sB    $ ++J7*+#'#5#5V 	 	
r    c                ^    U R                   R                  [        S   SU R                  0S9  g)zDelete this collection.

Example usage:

.. code-block:: python

    reddit.subreddit("test").collections("some_uuid").mod.delete()

.. seealso::

    :meth:`~.SubredditCollectionsModeration.create`

collection_deleter   r7   Nr,   r/   r   r   r   s    r   deleteCollectionModeration.deleteW   s1     	()$BTBT0U 	 	
r    c                    U R                  U5      nU R                  R                  [        S   U R                  US.S9  g)aq  Remove a post from the collection.

:param submission: The post to remove, a :class:`.Submission`, its permalink as
    a ``str``, its fullname as a ``str``, or its ID as a ``str``.

Example usage:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    collection.mod.remove_post("bgibu9")

.. seealso::

    :meth:`.add_post`

collection_remove_postr5   r7   Nr9   r:   s      r   remove_post CollectionModeration.remove_posti   sB    $ ++J7-.#'#5#5V 	 	
r    c                   ^  SR                  U 4S jU 5       5      nT R                  R                  [        S   T R                  US.S9  g)aj  Reorder posts in the collection.

:param links: A list of :class:`.Submission`\ s or a ``str`` that is either a
    fullname or an ID.

Example usage:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    current_order = collection.link_ids
    new_order = reversed(current_order)
    collection.mod.reorder(new_order)

,c              3  F   >#    U  H  nTR                  U5      v   M     g 7fN)r1   ).0r/   r   s     r   	<genexpr>/CollectionModeration.reorder.<locals>.<genexpr>   s     H%$D//55%s   !collection_reorder)r   link_idsr7   N)joinr,   r/   r   r   )r   linksrO   s   `  r   reorderCollectionModeration.reorder   sG      88H%HH)*#'#5#58L 	 	
r    c                `    U R                   R                  [        S   U R                  US.S9  g)a(  Update the collection's description.

:param description: The new description.

Example usage:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    collection.mod.update_description("Please enjoy these links!")

.. seealso::

    :meth:`.update_title`

collection_desc)r   descriptionr7   Nr?   )r   rV   s     r   update_description'CollectionModeration.update_description   s2    " 	&'#'#5#5kR 	 	
r    c                `    U R                   R                  [        S   U R                  US.S9  g)a  Update the collection's display layout.

:param display_layout: Either ``"TIMELINE"`` for events or discussions or
    ``"GALLERY"`` for images or memes. Passing ``None`` will clear the set
    layout and ``collection.display_layout`` will be ``None``, however, the
    collection will appear on Reddit as if ``display_layout`` is set to
    ``"TIMELINE"``.

Example usage:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    collection.mod.update_display_layout("GALLERY")

collection_layout)r   display_layoutr7   Nr?   )r   r[   s     r   update_display_layout*CollectionModeration.update_display_layout   s5    " 	()!%!3!3"0 	 	
r    c                `    U R                   R                  [        S   U R                  US.S9  g)a  Update the collection's title.

:param title: The new title.

Example usage:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    collection.mod.update_title("Titley McTitleface")

.. seealso::

    :meth:`.update_description`

collection_title)r   titler7   Nr?   )r   r`   s     r   update_title!CollectionModeration.update_title   s2    " 	'(#'#5#5F 	 	
r    )r   )r   praw.Redditr   r(   )r/   zstr | praw.models.Submissionreturnr(   )r#   zpraw.models.Submission)rQ   z"list[str | praw.models.Submission])rV   r(   )r[   r(   )r`   r(   )__name__
__module____qualname____firstlineno____doc__r   r1   r;   rA   rE   rR   rW   r\   ra   __static_attributes____classcell__r   s   @r   r   r      s:    +:(
2
$
2
,
,
2
 
r    r   c                  z   ^  \ rS rSrSr S     SU 4S jjjr\" SSS5      SS.       SS	 jj5       rS
rU =r	$ )SubredditCollectionsModeration   zClass to represent moderator actions on a :class:`.Subreddit`'s :class:`.Collection`\ s.

Obtain an instance via:

.. code-block:: python

    reddit.subreddit("test").collections.mod

Nc                0   > [         TU ]  X5        X l        g)z?Initialize a :class:`.SubredditCollectionsModeration` instance.N)r   r   subreddit_fullname)r   r   sub_fullnamer   r   s       r   r   'SubredditCollectionsModeration.__init__   s     	'".r    r`   rV   r[   )r[   c               z    U R                   UUS.nU(       a  X$S'   U R                  R                  [        S   US9$ )a|  Create a new :class:`.Collection`.

The authenticated account must have appropriate moderator permissions in the
subreddit this collection belongs to.

:param description: The description, up to 500 characters.
:param display_layout: Either ``"TIMELINE"`` for events or discussions or
    ``"GALLERY"`` for images or memes. Passing ``""`` or ``None`` will make the
    collection appear on Reddit as if this is set to ``"TIMELINE"`` (default:
    ``None``).
:param title: The title of the collection, up to 300 characters.

:returns: The newly created :class:`.Collection`.

Example usage:

.. code-block:: python

    my_sub = reddit.subreddit("test")
    new_collection = my_sub.collections.mod.create(title="Title", description="desc")
    new_collection.mod.add_post("bgibu9")

To specify the display layout as ``"GALLERY"`` when creating the collection:

.. code-block:: python

    my_sub = reddit.subreddit("test")
    new_collection = my_sub.collections.mod.create(
        title="Title", description="desc", display_layout="GALLERY"
    )
    new_collection.mod.add_post("bgibu9")

.. seealso::

    :meth:`~.CollectionModeration.delete`

)sr_fullnamer`   rV   r[   collection_creater7   )rq   r,   r/   r   )r   rV   r[   r`   r8   s        r   create%SubredditCollectionsModeration.create   sQ    T  22&

 %3!"||  () ! 
 	
r    )rq   rJ   )r   rc   rr   r(   r   dict[str, Any] | None)rV   r(   r[   
str | Noner`   r(   rd   
Collection)
re   rf   rg   rh   ri   r   r	   rw   rj   rk   rl   s   @r   rn   rn      st     (,	// / %	/ / Wm-=>@D2
!2
3=2
MP2
	2
 ?2
r    rn   c                  v   ^  \ rS rSrSr\SS j5       r  S	     S
S jjr S     SU 4S jjjrS r	Sr
U =r$ )SubredditCollectionsi)  zClass to represent a :class:`.Subreddit`'s :class:`.Collection`\ s.

Obtain an instance via:

.. code-block:: python

    reddit.subreddit("test").collections

c                V    [        U R                  U R                  R                  5      $ )a  Get an instance of :class:`.SubredditCollectionsModeration`.

Provides :meth:`~SubredditCollectionsModeration.create`:

.. code-block:: python

    my_sub = reddit.subreddit("test")
    new_collection = my_sub.collections.mod.create(title="Title", description="desc")

)rn   r,   	subredditr'   r@   s    r   modSubredditCollections.mod4  s     .dllDNN<S<STTr    c                X    USL USL :X  a  Sn[        U5      e[        U R                  XS9$ )a  Return the :class:`.Collection` with the specified ID.

:param collection_id: The ID of a :class:`.Collection` (default: ``None``).
:param permalink: The permalink of a collection (default: ``None``).

:returns: The specified :class:`.Collection`.

Exactly one of ``collection_id`` or ``permalink`` is required.

Example usage:

.. code-block:: python

    subreddit = reddit.subreddit("test")

    uuid = "847e4548-a3b5-4ad7-afb4-edbfc2ed0a6b"
    collection = subreddit.collections(uuid)
    print(collection.title)
    print(collection.description)

    permalink = "https://www.reddit.com/r/SUBREDDIT/collection/" + uuid
    collection = subreddit.collections(permalink=permalink)
    print(collection.title)
    print(collection.description)

Nz?Exactly one of 'collection_id' or 'permalink' must be provided.)r   	permalink)r*   r{   r,   )r   r   r   r0   s       r   __call__SubredditCollections.__call__B  s;    > T!yD'89SCC. LL
 	
r    c                0   > [         TU ]  X5        X l        g)z5Initialize a :class:`.SubredditCollections` instance.N)r   r   r   )r   r   r   r   r   s       r   r   SubredditCollections.__init__h  s     	'"r    c              #     #    U R                   R                  [        S   SU R                  R                  0S9nU Sh  vN   g N7f)zIterate over the :class:`.Subreddit`'s :class:`.Collection`\ s.

Example usage:

.. code-block:: python

    for collection in reddit.subreddit("test").collections:
        print(collection.permalink)

collection_subredditru   )paramsN)r,   getr   r   r'   )r   requests     r   __iter__SubredditCollections.__iter__r  sF      ,,""+,!4>>#:#:; # 
 s   =AA A)r   )rd   rn   )NN)r   rz   r   rz   rd   r{   rJ   )r   rc   r   praw.models.Subredditr   ry   )re   rf   rg   rh   ri   r
   r   r   r   r   rj   rk   rl   s   @r   r}   r}   )  s}     U U %) $$
!$
 $
 
	$
T (,	## )# %	# # r    r}   c                     ^  \ rS rSrSrSr\SS j5       r\SS j5       r   S       SU 4S jjjr	SS jr
SS jrSU 4S	 jjrU 4S
 jrS rS rS rSrU =r$ )r{   i  aQ  Class to represent a :class:`.Collection`.

Obtain an instance via:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")

or

.. code-block:: python

    collection = reddit.subreddit("test").collections(
        permalink="https://reddit.com/r/SUBREDDIT/collection/some_uuid"
    )

.. include:: ../../typical_attributes.rst

=================== =============================================================
Attribute           Description
=================== =============================================================
``author``          The :class:`.Redditor` who created the collection.
``collection_id``   The UUID of the collection.
``created_at_utc``  Time the collection was created, represented in `Unix Time`_.
``description``     The collection description.
``display_layout``  The collection display layout.
``last_update_utc`` Time the collection was last updated, represented in `Unix
                    Time`_.
``link_ids``        A list of :class:`.Submission` fullnames.
``permalink``       The collection's permalink (to view on the web).
``sorted_links``    An iterable listing of the posts in this collection.
``title``           The title of the collection.
=================== =============================================================

.. _unix time: https://en.wikipedia.org/wiki/Unix_time

r   c                B    [        U R                  U R                  5      $ )a  Get an instance of :class:`.CollectionModeration`.

Provides access to various methods, including
:meth:`~.CollectionModeration.add_post`, :meth:`~.CollectionModeration.delete`,
:meth:`~.CollectionModeration.reorder`, and
:meth:`~.CollectionModeration.update_title`.

Example usage:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    collection.mod.update_title("My new title!")

)r   r,   r   r@   s    r   r   Collection.mod  s    " $DLL$2D2DEEr    c                \    [        U R                  R                  U R                  /S95      $ )zGet the subreddit that this collection belongs to.

For example:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    subreddit = collection.subreddit

)	fullnames)nextr,   infosubreddit_idr@   s    r   r   Collection.subreddit  s*     DLL%%1B1B0C%DEEr    c                   > X#U4R                  S5      S:w  a  Sn[        U5      eU(       a  U R                  U5      S   nU(       a  X0l        [        TU ]  X5        U R                  SS.U l        g)a  Initialize a :class:`.Collection` instance.

:param reddit: An instance of :class:`.Reddit`.
:param _data: Any data associated with the :class:`.Collection`.
:param collection_id: The ID of the :class:`.Collection`.
:param permalink: The permalink of the :class:`.Collection`.

Nr   zIExactly one of '_data', 'collection_id', or 'permalink' must be provided.   T)r   include_links)countr*   
_url_partsr   r   r   _info_params)r   r   r   r   r   r0   r   s         r   r   Collection.__init__  sp     ),2248A=]CC.  OOI6q9M!.' "//!
r    c              #  8   #    U R                    Sh  vN   g N7f)a  Provide a way to iterate over the posts in this :class:`.Collection`.

Example usage:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    for submission in collection:
        print(submission.title, submission.permalink)

N)sorted_linksr@   s    r   r   Collection.__iter__  s      $$$$s   c                ,    [        U R                  5      $ )zGet the number of posts in this :class:`.Collection`.

Example usage:

.. code-block:: python

    collection = reddit.subreddit("test").collections("some_uuid")
    print(len(collection))

)lenrO   r@   s    r   __len__Collection.__len__  s     4==!!r    c                   > US:X  a!  U R                   R                  U5      U l        O+US:X  a%  U R                   R                  R	                  U5      n[
        TU ]  X5        g)z9Objectify author, subreddit, and sorted_links attributes.author_namer   N)r,   redditorauthor	_objector	objectifyr   __setattr__)r   	attributevaluer   s      r   r   Collection.__setattr__	  sP    %,,//6DK.(LL**44U;EI-r    c                b  > U R                  5       n U R                  R                  R                  U5        [        U 5      " U R                  US9nU R                  R                  UR                  5        [        TU ])  5         g ! [         a    SU R
                  < S3n[	        U5      S ef = f)Nz(Error during fetch. Check collection ID z is correct.r   )_fetch_datar,   r   check_errorr   r   r)   __dict__updater   _fetch)r   r8   r0   otherr   s       r   r   Collection._fetch  s    !	1LL""..t4 T
4<<t4U^^,  	1 =T=O=O<RR^_C!#&D0	1s   %B (B.c                     S0 U R                   4$ )N
collection)r   r@   s    r   _fetch_infoCollection._fetch_info   s    R!2!222r    c                `    U R                   R                  [        S   U R                  SS.S9  g)zFollow this :class:`.Collection`.

Example usage:

.. code-block:: python

    reddit.subreddit("test").collections("some_uuid").follow()

.. seealso::

    :meth:`.unfollow`

collection_followTr   followr7   Nr?   r@   s    r   r   Collection.follow#  s2     	()#'#5#5F 	 	
r    c                `    U R                   R                  [        S   U R                  SS.S9  g)zUnfollow this :class:`.Collection`.

Example usage:

.. code-block:: python

    reddit.subreddit("test").collections("some_uuid").unfollow()

.. seealso::

    :meth:`.follow`

r   Fr   r7   Nr?   r@   s    r   unfollowCollection.unfollow6  s2     	()#'#5#5G 	 	
r    )r   r   r   )rd   r   )rd   r   )NNN)r   rc   r   zdict[str, Any]r   rz   r   rz   )rd   r   )rd   int)r   r(   r   r   )re   rf   rg   rh   ri   	STR_FIELDr
   r   r   r   r   r   r   r   r   r   r   rj   rk   rl   s   @r   r{   r{     s    $L  IF F$ F F  !%$( $

 
 "	

 
 
@%".3
&
 
r    r{   )ri   
__future__r   typingr   r   constr   
exceptionsr   utilr	   
util.cacher
   baser   r   r#   r   r   r   collections.abcr   praw.modelsprawr   rn   r}   r{   _subreddit_collections_class r    r   <module>r      su    ( " %  ) # (   "  (E
8 E
PH
X H
VX8 XvC
 C
L *>	 &r    