Merge pull request #146 from praw-dev/deprecate_lazy

Deprecate lazy keyword argument

CHANGES.rst

@@ -21,6 +21,11 @@ Unreleased
 - An import error when using Async PRAW in environments where ``libsqlite3-dev`` is
   needed to utilize ``aiosqlite`` package which depends on the ``sqlite3`` builtin.
 
+**Deprecated**
+
+- The keyword argument ``lazy`` has been replace by ``fetch`` to consolidate the keyword
+  argument used to explicitly perform a fetch when initializing an object.
+
 7.4.0 (2021/07/30)
 ------------------
 

README.rst

@@ -81,7 +81,7 @@ With the ``reddit`` instance you can then interact with Reddit:
 
     # Comment on a known submission
     submission = await reddit.submission(
-        url="https://www.reddit.com/comments/5e1az9", lazy=True
+        url="https://www.reddit.com/comments/5e1az9", fetch=False
     )
     await submission.reply("Super rad!")
 

asyncpraw/models/comment_forest.py

@@ -153,7 +153,7 @@ async def replace_more(
 
         .. code-block:: python
 
-            submission = await reddit.submission("3hahrw", lazy=True)
+            submission = await reddit.submission("3hahrw", fetch=False)
             comments = await submission.comments()
             await comments.replace_more()
 

asyncpraw/models/helpers.py

@@ -34,7 +34,7 @@ async def __call__(
             await livethread.close()
 
         :param id: A live thread ID, e.g., ``ukaeu1ik4sw5``.
-        :param fetch: Determines if the object is lazily loaded (default: False).
+        :param fetch: Determines if Async PRAW will fetch the object (default: False).
 
         """
         live_thread = LiveThread(self._reddit, id=id)
@@ -154,7 +154,7 @@ async def __call__(
         :param redditor: A redditor name (e.g., ``"spez"``) or :class:`~.Redditor`
             instance who owns the multireddit.
         :param name: The name of the multireddit.
-        :param fetch: Determines if the object is lazily loaded (default: False).
+        :param fetch: Determines if Async PRAW will fetch the object (default: False).
 
         """
         path = f"/user/{redditor}/m/{name}"
@@ -227,7 +227,7 @@ async def __call__(
                 print(comment.author)
 
         :param display_name: The name of the subreddit.
-        :param fetch: Determines if the object is lazily loaded (default: False).
+        :param fetch: Determines if Async PRAW will fetch the object (default: False).
 
         """
         lower_name = display_name.lower()

asyncpraw/models/listing/mixins/submission.py

@@ -24,7 +24,7 @@ def duplicates(
 
         .. code-block:: python
 
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
 
             async for duplicate in submission.duplicates():
                 # process each duplicate

asyncpraw/models/reddit/collections.py

@@ -5,6 +5,7 @@
 from ...exceptions import ClientException
 from ...util.cache import cachedproperty
 from ..base import AsyncPRAWBase
+from ..util import deprecate_lazy
 from .base import RedditBase
 from .redditor import Redditor
 from .submission import Submission
@@ -505,17 +506,19 @@ def mod(self) -> SubredditCollectionsModeration:
         """
         return SubredditCollectionsModeration(self._reddit, self.subreddit)
 
+    @deprecate_lazy
     async def __call__(
         self,
         collection_id: Optional[str] = None,
         permalink: Optional[str] = None,
-        lazy: bool = False,
+        fetch: bool = True,
+        **kwargs,
     ):
         """Return the :class:`.Collection` with the specified ID.
 
         :param collection_id: The ID of a Collection (default: None).
         :param permalink: The permalink of a Collection (default: None).
-        :param lazy: If True, object is loaded lazily (default: False)
+        :param fetch: Determines if Async PRAW will fetch the object (default: True).
 
         :returns: The specified Collection.
 
@@ -543,7 +546,7 @@ async def __call__(
         .. code-block:: python
 
             subreddit = await reddit.subreddit("SUBREDDIT", fetch=True)
-            collection = await subreddit.collections(uuid, lazy=True)
+            collection = await subreddit.collections(uuid, fetch=False)
             await collection.mod.add("submission_id")
 
         """
@@ -554,7 +557,7 @@ async def __call__(
         collection = Collection(
             self._reddit, collection_id=collection_id, permalink=permalink
         )
-        if not lazy:
+        if fetch:
             await collection._fetch()
         return collection
 

asyncpraw/models/reddit/comment.py

@@ -101,7 +101,7 @@ def mod(self) -> "asyncpraw.models.reddit.comment.CommentModeration":
 
         .. code-block:: python
 
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.approve()
 
         """
@@ -242,7 +242,7 @@ async def parent(
 
         .. code-block:: python
 
-            comment = await reddit.comment("cklhv0f", lazy=True)
+            comment = await reddit.comment("cklhv0f", fetch=False)
             parent = await comment.parent()
             # `replies` is empty until the comment is refreshed
             print(parent.replies)  # Output: []
@@ -302,7 +302,7 @@ async def refresh(self):
 
         .. code-block:: python
 
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.refresh()
 
         """
@@ -352,7 +352,7 @@ class CommentModeration(ThingModerationMixin):
 
     .. code-block:: python
 
-        comment = await reddit.comment("dkk4qjd", lazy=True)
+        comment = await reddit.comment("dkk4qjd", fetch=False)
         await comment.mod.approve()
 
     """
@@ -375,7 +375,7 @@ async def show(self):
         .. code-block:: python
 
             # Uncollapse a comment:
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.show()
 
         """

asyncpraw/models/reddit/emoji.py

@@ -4,6 +4,7 @@
 
 from ...const import API_PATH
 from ...exceptions import ClientException
+from ..util import deprecate_lazy
 from .base import RedditBase
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -139,11 +140,12 @@ async def update(
 class SubredditEmoji:
     """Provides a set of functions to a Subreddit for emoji."""
 
-    async def get_emoji(self, name: str, lazy: bool = False) -> Emoji:
+    @deprecate_lazy
+    async def get_emoji(self, name: str, fetch: bool = True, **kwargs) -> Emoji:
         """Return the Emoji for the subreddit named ``name``.
 
-        :param name: The name of the emoji
-        :param lazy: If True, object is loaded lazily (default: False)
+        :param name: The name of the emoji.
+        :param fetch: Determines if Async PRAW will fetch the object (default: True).
 
         This method is to be used to fetch a specific emoji url, like so:
 
@@ -159,12 +161,12 @@ async def get_emoji(self, name: str, lazy: bool = False) -> Emoji:
         .. code-block:: python
 
             subreddit = await reddit.subreddit("praw_test")
-            emoji = await subreddit.emoji.get_emoji("test", lazy=True)
+            emoji = await subreddit.emoji.get_emoji("test", fetch=False)
             await emoji.delete()
 
         """
         emoji = Emoji(self._reddit, self.subreddit, name)
-        if not lazy:
+        if fetch:
             await emoji._fetch()
         return emoji
 

asyncpraw/models/reddit/live.py

@@ -5,7 +5,7 @@
 from ...util.cache import cachedproperty
 from ..list.redditor import RedditorList
 from ..listing.generator import ListingGenerator
-from ..util import stream_generator
+from ..util import deprecate_lazy, stream_generator
 from .base import RedditBase
 from .mixins import FullnameMixin
 from .redditor import Redditor
@@ -96,7 +96,7 @@ async def invite(
         .. code-block:: python
 
             thread = await reddit.live("ukaeu1ik4sw5")
-            redditor = await reddit.redditor("spez", lazy=True)
+            redditor = await reddit.redditor("spez", fetch=False)
 
             # "manage" and "settings" permissions
             await thread.contributor.invite(redditor, ["manage", "settings"])
@@ -140,7 +140,7 @@ async def remove(self, redditor: Union[str, "asyncpraw.models.Redditor"]):
         .. code-block:: python
 
             thread = await reddit.live("ukaeu1ik4sw5")
-            redditor = await reddit.redditor("spez", lazy=True)
+            redditor = await reddit.redditor("spez", fetch=False)
             await thread.contributor.remove(redditor)
             await thread.contributor.remove("t2_1w72")  # with fullname
 
@@ -164,7 +164,7 @@ async def remove_invite(self, redditor: Union[str, "asyncpraw.models.Redditor"])
         .. code-block:: python
 
             thread = await reddit.live("ukaeu1ik4sw5")
-            redditor = await reddit.redditor("spez", lazy=True)
+            redditor = await reddit.redditor("spez", fetch=False)
             await thread.contributor.remove_invite(redditor)
             await thread.contributor.remove_invite("t2_1w72")  # with fullname
 
@@ -365,14 +365,15 @@ def __eq__(self, other: Union[str, "asyncpraw.models.LiveThread"]) -> bool:
             return other == str(self)
         return isinstance(other, self.__class__) and str(self) == str(other)
 
+    @deprecate_lazy
     async def get_update(
-        self, update_id: str, lazy: bool = False
+        self, update_id: str, fetch: bool = True, **kwargs
     ) -> "asyncpraw.models.LiveUpdate":
         """Return a :class:`.LiveUpdate` instance.
 
         :param update_id: A live update ID, e.g.,
             ``"7827987a-c998-11e4-a0b9-22000b6a88d2"``.
-        :param lazy: If True, object is loaded lazily (default: False).
+        :param fetch: Determines if Async PRAW will fetch the object (default: True).
 
         Usage:
 
@@ -390,12 +391,12 @@ async def get_update(
         .. code-block:: python
 
             thread = await reddit.live("ukaeu1ik4sw5")
-            update = await thread.get_update("7827987a-c998-11e4-a0b9-22000b6a88d2", lazy=True)
+            update = await thread.get_update("7827987a-c998-11e4-a0b9-22000b6a88d2", fetch=False)
             update.contrib  # LiveUpdateContribution instance
 
         """
         update = LiveUpdate(self._reddit, self.id, update_id)
-        if not lazy:
+        if fetch:
             await update._fetch()
         return update
 
@@ -717,7 +718,7 @@ def contrib(self) -> "asyncpraw.models.reddit.live.LiveUpdateContribution":
         .. code-block:: python
 
             thread = await reddit.live("ukaeu1ik4sw5")
-            update = await thread.get_update("7827987a-c998-11e4-a0b9-22000b6a88d2", lazy=True)
+            update = await thread.get_update("7827987a-c998-11e4-a0b9-22000b6a88d2", fetch=False)
             update.contrib  # LiveUpdateContribution instance
 
         """

asyncpraw/models/reddit/mixins/__init__.py

@@ -55,10 +55,10 @@ async def approve(self):
         .. code-block:: python
 
             # approve a comment:
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.approve()
             # approve a submission:
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
             await submission.mod.approve()
 
         """
@@ -81,10 +81,10 @@ async def distinguish(self, how="yes", sticky=False):
         .. code-block:: python
 
             # distinguish and sticky a comment:
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.distinguish(how="yes", sticky=True)
             # undistinguish a submission:
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
             await submission.mod.distinguish(how="no")
 
         .. seealso::
@@ -110,10 +110,10 @@ async def ignore_reports(self):
         .. code-block:: python
 
             # ignore future reports on a comment:
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.ignore_reports()
             # ignore future reports on a submission:
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
             await submission.mod.ignore_reports()
 
         .. seealso::
@@ -133,10 +133,10 @@ async def lock(self):
         .. code-block:: python
 
             # lock a comment:
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.lock()
             # lock a submission:
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
             await submission.mod.lock()
 
         .. seealso::
@@ -164,15 +164,15 @@ async def remove(self, spam=False, mod_note="", reason_id=None):
         .. code-block:: python
 
             # remove a comment and mark as spam:
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.remove(spam=True)
             # remove a submission
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
             await submission.mod.remove()
             # remove a submission with a removal reason
             sub = await reddit.subreddit("subreddit")
             reason = await sub.mod.removal_reasons.get_reason("110ni21zo23ql")
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
             await submission.mod.remove(reason_id=reason.id)
 
         """
@@ -234,10 +234,10 @@ async def undistinguish(self):
         .. code-block:: python
 
             # undistinguish a comment:
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.undistinguish()
             # undistinguish a submission:
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
             await submission.mod.undistinguish()
 
         .. seealso::
@@ -258,10 +258,10 @@ async def unignore_reports(self):
         .. code-block:: python
 
             # accept future reports on a comment:
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.unignore_reports()
             # accept future reports on a submission:
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
             await submission.mod.unignore_reports()
 
         .. seealso::
@@ -281,10 +281,10 @@ async def unlock(self):
         .. code-block:: python
 
             # unlock a comment:
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.mod.unlock()
             # unlock a submission:
-            submission = await reddit.submission(id="5or86n", lazy=True)
+            submission = await reddit.submission(id="5or86n", fetch=False)
             await submission.mod.unlock()
 
         .. seealso::

asyncpraw/models/reddit/mixins/editable.py

@@ -12,10 +12,10 @@ async def delete(self):
 
         .. code-block:: python
 
-            comment = await reddit.comment("dkk4qjd", lazy=True)
+            comment = await reddit.comment("dkk4qjd", fetch=False)
             await comment.delete()
 
-            submission = await reddit.submission("8dmv8z", lazy=True)
+            submission = await reddit.submission("8dmv8z", fetch=False)
             await submission.delete()
 
         """