o 2g+h@sdZddlmZddlmZmZmZmZddlm Z ddl m Z ddl m Z dd lmZdd lmZdd l mZd d lmZd dlmZd dlmZerPddlZGdddZGdddeZGdddZGdddZGdddZGdddeeZ dS)zProvide the LiveThread class.) annotations) TYPE_CHECKINGAnyIterableIterator)API_PATH)_deprecate_args)cachedproperty) RedditorList)ListingGenerator)stream_generator) RedditBase) FullnameMixin)RedditorNc@seZdZdZed"ddZd#d d Zd$d dZddZe ddddd%ddZ ddZ d&ddZ d&ddZ e ddddd%ddZe ddddd%d d!ZdS)'LiveContributorRelationshipzszBLiveContributorRelationship._handle_permissions..)setjoinrrrr_handle_permissionssz/LiveContributorRelationship._handle_permissionslist[praw.models.Redditor]cCs8tdj|jjd}|jj|}t|tr|S|dS)aReturn a :class:`.RedditorList` for live threads' contributors. Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") for contributor in thread.contributor(): print(contributor) live_contributorsidr)rformatthreadr'_redditget isinstancer )selfurltemprrr__call__s z$LiveContributorRelationship.__call__r)praw.models.LiveThreadcC ||_dS)a Initialize a :class:`.LiveContributorRelationship` instance. :param thread: An instance of :class:`.LiveThread`. .. note:: This class should not be initialized directly. Instead, obtain an instance via: :meth:`.LiveThread.contributor`. Nr)r-r)rrr__init__-s z$LiveContributorRelationship.__init__cC&tdj|jjd}|jj|dS)zAccept an invite to contribute the live thread. Usage: .. code-block:: python thread = reddit.live("ydwwxneu7vsa") thread.contributor.accept_invite() live_accept_inviter&Nrr(r)r'r*postr-r.rrr accept_invite: z)LiveContributorRelationship.accept_inviteredditorNr"str | praw.models.Redditorlist[str] | NonecC@tdj|jjd}t|d||d}|jjj||ddS)aInvite a redditor to be a contributor of the live thread. :param redditor: A redditor name or :class:`.Redditor` instance. :param permissions: When provided (not ``None``), permissions should be a list of strings specifying which subset of permissions to grant. An empty list ``[]`` indicates no permissions, and when not provided (``None``), indicates full permissions. :raises: :class:`.RedditAPIException` if the invitation already exists. Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") redditor = reddit.redditor("spez") # "manage" and "settings" permissions thread.contributor.invite(redditor, permissions=["manage", "settings"]) .. seealso:: :meth:`.LiveContributorRelationship.remove_invite` to remove the invite for redditor. live_inviter&liveupdate_contributor_invitenametyperdataNrr(r)r'rr#r*r9r-r=rr.rGrrrinviteHs !z"LiveContributorRelationship.invitecCr6)zAbdicate the live thread contributor position (use with care). Usage: .. code-block:: python thread = reddit.live("ydwwxneu7vsa") thread.contributor.leave() live_leaver&Nr8r:rrrleaveqr<z!LiveContributorRelationship.leavecCFt|tr|jn|}d|i}tdj|jjd}|jjj||ddS)aRemove the redditor from the live thread contributors. :param redditor: A redditor fullname (e.g., ``"t2_1w72"``) or :class:`.Redditor` instance. Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") redditor = reddit.redditor("spez") thread.contributor.remove(redditor) thread.contributor.remove("t2_1w72") # with fullname r'live_remove_contribr&rFN r,rfullnamerr(r)r'r*r9r-r=rPrGr.rrrremovesz"LiveContributorRelationship.removecCrM)aBRemove the invite for redditor. :param redditor: A redditor fullname (e.g., ``"t2_1w72"``) or :class:`.Redditor` instance. Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") redditor = reddit.redditor("spez") thread.contributor.remove_invite(redditor) thread.contributor.remove_invite("t2_1w72") # with fullname .. seealso:: :meth:`.LiveContributorRelationship.invite` to invite a redditor to be a contributor of the live thread. r'live_remove_inviter&rFNrOrQrrr remove_invitesz)LiveContributorRelationship.remove_invitecCr@)a Update the contributor permissions for ``redditor``. :param redditor: A redditor name or :class:`.Redditor` instance. :param permissions: When provided (not ``None``), permissions should be a list of strings specifying which subset of permissions to grant (other permissions are removed). An empty list ``[]`` indicates no permissions, and when not provided (``None``), indicates full permissions. For example, to grant all permissions to the contributor, try: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") thread.contributor.update("spez") To grant ``"access"`` and ``"edit"`` permissions (and to remove other permissions), try: .. code-block:: python thread.contributor.update("spez", permissions=["access", "edit"]) To remove all permissions from the contributor, try: .. code-block:: python subreddit.moderator.update("spez", permissions=[]) live_update_permsr&liveupdate_contributorrCrFNrHrIrrrupdate $z"LiveContributorRelationship.updatecCr@)a2Update the contributor invite permissions for ``redditor``. :param redditor: A redditor name or :class:`.Redditor` instance. :param permissions: When provided (not ``None``), permissions should be a list of strings specifying which subset of permissions to grant (other permissions are removed). An empty list ``[]`` indicates no permissions, and when not provided (``None``), indicates full permissions. For example, to set all permissions to the invitation, try: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") thread.contributor.update_invite("spez") To set ``"access"`` and ``"edit"`` permissions (and to remove other permissions) to the invitation, try: .. code-block:: python thread.contributor.update_invite("spez", permissions=["access", "edit"]) To remove all permissions from the invitation, try: .. code-block:: python thread.contributor.update_invite("spez", permissions=[]) rUr&rBrCrFNrHrIrrr update_inviterXz)LiveContributorRelationship.update_invite)rrrr)rr$r)r1)r=r>rr?)r=r>)__name__ __module__ __qualname____doc__ staticmethodr#r0r5r;r rJrLrRrTrWrYrrrrrs&    (  +rcseZdZdZdZed1ddZed2dd Zed3d d Zd4ddZ d5ddZ d6ddZ  d7d8fd d! Z fd"d#Z d$d%Zd9d)d*Zd:d,d-Zd;d/d0ZZS)< LiveThreadaBAn individual :class:`.LiveThread` object. .. include:: ../../typical_attributes.rst ==================== ========================================================= Attribute Description ==================== ========================================================= ``created_utc`` The creation time of the live thread, in `Unix Time`_. ``description`` Description of the live thread, as Markdown. ``description_html`` Description of the live thread, as HTML. ``id`` The ID of the live thread. ``nsfw`` A ``bool`` representing whether or not the live thread is marked as NSFW. ==================== ========================================================= .. _unix time: https://en.wikipedia.org/wiki/Unix_time r'r.praw.models.reddit.live.LiveThreadContributioncCt|S)zProvide an instance of :class:`.LiveThreadContribution`. Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") thread.contrib.add("### update") )LiveThreadContributionr-rrrcontribs zLiveThread.contrib3praw.models.reddit.live.LiveContributorRelationshipcCrb)aOProvide an instance of :class:`.LiveContributorRelationship`. You can call the instance to get a list of contributors which is represented as :class:`.RedditorList` instance consists of :class:`.Redditor` instances. Those :class:`.Redditor` instances have ``permissions`` attributes as contributors: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") for contributor in thread.contributor(): # prints `Redditor(name="Acidtwist") ["all"]` print(contributor, contributor.permissions) )rrdrrr contributor+szLiveThread.contributor(praw.models.reddit.live.LiveThreadStreamcCrb)aProvide an instance of :class:`.LiveThreadStream`. Streams are used to indefinitely retrieve new updates made to a live thread, like: .. code-block:: python for live_update in reddit.live("ta535s1hq2je").stream.updates(): print(live_update.body) Updates are yielded oldest first as :class:`.LiveUpdate`. Up to 100 historical updates will initially be returned. To only retrieve new updates starting from when the stream is created, pass ``skip_existing=True``: .. code-block:: python live_thread = reddit.live("ta535s1hq2je") for live_update in live_thread.stream.updates(skip_existing=True): print(live_update.author) )LiveThreadStreamrdrrrstream=szLiveThread.streamotherstr | praw.models.LiveThreadboolcCs2t|tr |t|kSt||jot|t|kS)zReturn whether the other instance equals the current. .. note:: This comparison is case sensitive. )r,r __class__)r-rkrrr__eq__Vs  zLiveThread.__eq__ update_idrpraw.models.LiveUpdatecCst|j|j|S)aReturn a lazy :class:`.LiveUpdate` instance. :param update_id: A live update ID, e.g., ``"7827987a-c998-11e4-a0b9-22000b6a88d2"``. Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") update = thread["7827987a-c998-11e4-a0b9-22000b6a88d2"] update.thread # LiveThread(id="ukaeu1ik4sw5") update.id # "7827987a-c998-11e4-a0b9-22000b6a88d2" update.author # "umbrae" ) LiveUpdater*r')r-rprrr __getitem__bszLiveThread.__getitem__intcCst|jjtt|AS)z(Return the hash of the current instance.)hashrnr[rrdrrr__hash__uszLiveThread.__hash__Nreddit praw.Reddit str | None_datadict[str, Any] | Nonecs<||fddkrd}t||r||_tj||ddS)zInitialize a :class:`.LiveThread` instance. :param reddit: An instance of :class:`.Reddit`. :param id: A live thread ID, e.g., ``"ukaeu1ik4sw5"`` Nrz(Either 'id' or '_data' must be provided.rz)count TypeErrorr'superr5)r-rwr'rzmsgrnrrr5ys  zLiveThread.__init__cs>|}|d}t||j|d}|j|jtdS)NrGr|) _fetch_datarEr*__dict__rWr_fetch)r-rGrkrrrrs zLiveThread._fetchcCsdd|jidfS)N liveaboutr'r&rdrrr _fetch_infoszLiveThread._fetch_infogenerator_kwargsstr | int | dict[str, str] Iterator[praw.models.Submission]cKs&tdj|jd}t|j|fi|S)aFGet submissions linking to the thread. :param generator_kwargs: keyword arguments passed to :class:`.ListingGenerator` constructor. :returns: A :class:`.ListingGenerator` object which yields :class:`.Submission` objects. Additional keyword arguments are passed in the initialization of :class:`.ListingGenerator`. Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") for submission in thread.discussions(limit=None): print(submission.title) live_discussionsr&)rr(r'r r*)r-rr.rrr discussionsszLiveThread.discussionsrEcCs*tdj|jd}|jj|d|iddS)acReport the thread violating the Reddit rules. :param type: One of ``"spam"``, ``"vote-manipulation"``, ``"personal-information"``, ``"sexualizing-minors"``, or ``"site-breaking"``. Usage: .. code-block:: python thread = reddit.live("xyu8kmjvfrww") thread.report("spam") live_reportr&rErFN)rr(r'r*r9)r-rEr.rrrreportszLiveThread.report Iterator[praw.models.LiveUpdate]cks>tdj|jd}t|j|fi|D]}||_|VqdS)aReturn a :class:`.ListingGenerator` yields :class:`.LiveUpdate` s. :param generator_kwargs: keyword arguments passed to :class:`.ListingGenerator` constructor. :returns: A :class:`.ListingGenerator` object which yields :class:`.LiveUpdate` objects. Additional keyword arguments are passed in the initialization of :class:`.ListingGenerator`. Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") after = "LiveUpdate_fefb3dae-7534-11e6-b259-0ef8c7233633" for submission in thread.updates(limit=5, params={"after": after}): print(submission.body) live_updatesr&N)rr(r'r r*_thread)r-rr.rWrrrupdatess zLiveThread.updates)rra)rrf)rrh)rkrlrrm)rprrrq)rrt)NN)rwrxr'ryrzr{)rrrr)rEr)rrrr)r[r\r]r^ STR_FIELDr rergrjrorsrvr5rrrrr __classcell__rrrrr`s(        r`c@sPeZdZdZdddZddd Zd d Zed d ddddddddddZdS)rczCProvides a set of contribution functions to a :class:`.LiveThread`.r)r1cCr2)aInitialize a :class:`.LiveThreadContribution` instance. :param thread: An instance of :class:`.LiveThread`. This instance can be retrieved through ``thread.contrib`` where thread is a :class:`.LiveThread` instance. E.g., .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") thread.contrib.add("### update") Nr3r4rrrr5s zLiveThreadContribution.__init__bodyrcCs.tdj|jjd}|jjj|d|iddS)aAdd an update to the live thread. :param body: The Markdown formatted content for the update. Usage: .. code-block:: python thread = reddit.live("ydwwxneu7vsa") thread.contrib.add("test `LiveThreadContribution.add()`") live_add_updater&rrFNr8)r-rr.rrradds zLiveThreadContribution.addcCr6)zClose the live thread permanently (cannot be undone). Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") thread.contrib.close() live_closer&Nr8r:rrrcloser<zLiveThreadContribution.closetitle descriptionnsfw resourcesN)rrrrry bool | Noneother_settingsc  s||||d}||tdd|DrdSt|jj|jjfdd|D}tdj |jjd}|jjj || d |jj | dS) aUpdate settings of the live thread. :param description: The live thread's description (default: ``None``). :param nsfw: Indicate whether this thread is not safe for work (default: ``None``). :param resources: Markdown formatted information that is useful for the live thread (default: ``None``). :param title: The title of the live thread (default: ``None``). Does nothing if no arguments are provided. Each setting will maintain its current value if ``None`` is specified. Additional keyword arguments can be provided to handle new settings as Reddit introduces them. Usage: .. code-block:: python thread = reddit.live("xyu8kmjvfrww") # update 'title' and 'nsfw' updated_thread = thread.contrib.update(title=new_title, nsfw=True) If Reddit introduces new settings, you must specify ``None`` for the setting you want to maintain: .. code-block:: python # update 'nsfw' and maintain new setting 'foo' thread.contrib.update(nsfw=True, foo=None) )rrrrcss|]}|duVqdSNr)rvaluerrrrDsz0LiveThreadContribution.update..Ncs(i|]\}}||durt|n|qSr)getattr)rkeyrr3rr Hsz1LiveThreadContribution.update..live_update_threadr&rF)rWrvaluesr`r)r*r'itemsrr(r9copy_reset_attributeskeys) r-rrrrrsettingsrGr.rr3rrWs-  zLiveThreadContribution.updaterZ)rr) rryrrrryrryrry) r[r\r]r^r5rrr rWrrrrrcs   rcc@s$eZdZdZd ddZdd d Zd S)rizProvides a :class:`.LiveThread` stream. Usually used via: .. code-block:: python for live_update in reddit.live("ta535s1hq2je").stream.updates(): print(live_update.body) live_threadr1cCr2)zInitialize a :class:`.LiveThreadStream` instance. :param live_thread: The live thread associated with the stream. N)r)r-rrrrr5_s zLiveThreadStream.__init__stream_optionsdict[str, Any]rrcKst|jjfi|S)a!Yield new updates to the live thread as they become available. :param skip_existing: Set to ``True`` to only fetch items created after the stream (default: ``False``). As with :meth:`.LiveThread.updates()`, updates are yielded as :class:`.LiveUpdate`. Updates are yielded oldest first. Up to 100 historical updates will initially be returned. Keyword arguments are passed to :func:`.stream_generator`. For example, to retrieve all new updates made to the ``"ta535s1hq2je"`` live thread, try: .. code-block:: python for live_update in reddit.live("ta535s1hq2je").stream.updates(): print(live_update.body) To only retrieve new updates starting from when the stream is created, pass ``skip_existing=True``: .. code-block:: python live_thread = reddit.live("ta535s1hq2je") for live_update in live_thread.stream.updates(skip_existing=True): print(live_update.author) )rrr)r-rrrrrgs"zLiveThreadStream.updatesN)rr1)rrrr)r[r\r]r^r5rrrrrriSs ric@s*eZdZdZd ddZddZdd Zd S) LiveUpdateContributionzAProvides a set of contribution functions to :class:`.LiveUpdate`.rWrqcCr2)aInitialize a :class:`.LiveUpdateContribution` instance. :param update: An instance of :class:`.LiveUpdate`. This instance can be retrieved through ``update.contrib`` where update is a :class:`.LiveUpdate` instance. E.g., .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") update = thread["7827987a-c998-11e4-a0b9-22000b6a88d2"] update.contrib # LiveUpdateContribution instance update.contrib.remove() N)rW)r-rWrrrr5s zLiveUpdateContribution.__init__cC:tdj|jjjd}d|jji}|jjjj||ddS)zRemove a live update. Usage: .. code-block:: python thread = reddit.live("ydwwxneu7vsa") update = thread["6854605a-efec-11e6-b0c7-0eafac4ff094"] update.contrib.remove() live_remove_updater&r'rFNrr(rWr)r'rPr*r9r-r.rGrrrrRs zLiveUpdateContribution.removecCr)aStrike a content of a live update. .. code-block:: python thread = reddit.live("xyu8kmjvfrww") update = thread["cb5fe532-dbee-11e6-9a91-0e6d74fabcc4"] update.contrib.strike() To check whether the update is stricken or not, use ``update.stricken`` attribute. .. note:: Accessing lazy attributes on updates (includes ``update.stricken``) may raise :py:class:`AttributeError`. See :class:`.LiveUpdate` for details. live_striker&r'rFNrrrrrstrikes zLiveUpdateContribution.strikeN)rWrq)r[r\r]r^r5rRrrrrrrs   rcsheZdZdZdZdZedddZeddd Z ddfdd Z d fdd Z fddZ Z S)!rra.An individual :class:`.LiveUpdate` object. .. include:: ../../typical_attributes.rst =============== =================================================================== Attribute Description =============== =================================================================== ``author`` The :class:`.Redditor` who made the update. ``body`` Body of the update, as Markdown. ``body_html`` Body of the update, as HTML. ``created_utc`` The time the update was created, as `Unix Time`_. ``stricken`` A ``bool`` representing whether or not the update was stricken (see :meth:`.strike`). =============== =================================================================== .. _unix time: https://en.wikipedia.org/wiki/Unix_time r'r.praw.models.reddit.live.LiveUpdateContributioncCrb)a&Provide an instance of :class:`.LiveUpdateContribution`. Usage: .. code-block:: python thread = reddit.live("ukaeu1ik4sw5") update = thread["7827987a-c998-11e4-a0b9-22000b6a88d2"] update.contrib # LiveUpdateContribution instance )rrdrrrres zLiveUpdate.contribr`cCs|jS)z@Return :class:`.LiveThread` object the update object belongs to.)rrdrrrr)szLiveUpdate.threadNrwrx thread_idryrprzr{csZ|durtj||dddS|r'|r'||_tj|ddt|j||_dSd}t|)aInitialize a :class:`.LiveUpdate` instance. Either ``thread_id`` and ``update_id``, or ``_data`` must be provided. :param reddit: An instance of :class:`.Reddit`. :param thread_id: A live thread ID, e.g., ``"ukaeu1ik4sw5"``. :param update_id: A live update ID, e.g., ``"7827987a-c998-11e4-a0b9-22000b6a88d2"``. Usage: .. code-block:: python update = LiveUpdate(reddit, "ukaeu1ik4sw5", "7827987a-c998-11e4-a0b9-22000b6a88d2") update.thread # LiveThread(id="ukaeu1ik4sw5") update.id # "7827987a-c998-11e4-a0b9-22000b6a88d2" update.author # "umbrae" NT)rz_fetchedr|z@Either 'thread_id' and 'update_id', or '_data' must be provided.)rr5r'r`r*rr~)r-rwrrprzrrrrr5szLiveUpdate.__init__ attributerrrcs(|dkr t|j|d}t||dS)zObjectify author.author)rDN)rr*r __setattr__)r-rrrrrrszLiveUpdate.__setattr__csDtdj|jj|jd}|j|d}|j|jt dS)N live_focus)rrpr) rr(r)r'r*r+rrWrr)r-r.rkrrrr szLiveUpdate._fetch)rr)rr`)NNN)rwrxrryrpryrzr{)rrrr)r[r\r]r^r_kindr repropertyr)r5rrrrrrrrrs  'rr)!r^ __future__rtypingrrrrconstrutilr util.cacher list.redditorr listing.generatorr rbasermixinsrr=r praw.modelsprawrr`rcrirrrrrrrs,          sZs9<