Merge ceca90e into 5d3fbba

AUTHORS.rst

@@ -83,4 +83,5 @@ Source Contributors
 - Gerard Rodes <GerardRodesVidal@gmail.com> `@GerardRodes
   <https://github.com/GerardRodes>`_
 - cmays90 `@cmays90 <https://github.com/cmays90>`_
+- Dio Brando `@isFakeAccount <https://github.com/isFakeAccount>`_
 - Add "Name <email (optional)> and github profile link" above this line.

CHANGES.rst

@@ -6,6 +6,10 @@ Async PRAW follows `semantic versioning <http://semver.org/>`_.
 Unreleased
 ----------
 
+**Added**
+
+- :meth:`.pin` to manage pinned submissions on the authenticated user's profile.
+
 7.5.0 (2021/11/13)
 ------------------
 

asyncpraw/models/user.py

@@ -2,6 +2,8 @@
 from typing import TYPE_CHECKING, AsyncIterator, Dict, List, Optional, Union
 from warnings import warn
 
+from asyncprawcore import Conflict
+
 from ..const import API_PATH
 from ..exceptions import ReadOnlyException
 from ..models import Preferences
@@ -192,6 +194,70 @@ async def multireddits(self) -> List["asyncpraw.models.Multireddit"]:
         """Return a list of multireddits belonging to the user."""
         return await self._reddit.get(API_PATH["my_multireddits"])
 
+    async def pin(
+        self,
+        submission: "asyncpraw.models.Submission",
+        *,
+        num: int = None,
+        state: bool = True,
+    ):
+        """Set the pin state of a submission on the authenticated user's profile.
+
+        :param submission: An instance of :class:`.Submission` that will be
+            pinned/unpinned.
+        :param num: If specified, the slot in which the submission will be pinned into.
+            If there is a submission already in the specified slot, it will be replaced.
+            If ``None`` or there is not a submission in the specified slot, the first
+            available slot will be used (default: ``None``). If all slots are used the
+            following will occur:
+
+            - Old Reddit:
+
+              1. The submission in the last slot will be unpinned.
+              2. The remaining pinned submissions will be shifted down a slot.
+              3. The new submission will be pinned in the first slot.
+
+            - New Reddit:
+
+              1. The submission in the first slot will be unpinned.
+              2. The remaining pinned submissions will be shifted up a slot.
+              3. The new submission will be pinned in the last slot.
+
+            .. note::
+
+                At the time of writing (10/22/2021), there are 4 pin slots available and
+                pins are in reverse order on old Reddit. If ``num`` is an invalid value,
+                Reddit will ignore it and the same behavior will occur as if ``num`` is
+                ``None``.
+
+        :param state: ``True`` pins the submission, ``False`` unpins (default:
+            ``True``).
+
+        :raises: ``asyncprawcore.BadRequest`` when pinning a removed or deleted
+            submission.
+
+        :raises: ``asyncprawcore.Forbidden`` when pinning a submission the authenticated
+            user is not the author of.
+
+        .. code-block:: python
+
+            me = await reddit.user.me()
+            async for submission in me.submissions.new():
+                reddit.user.pin(submission)
+                break
+
+        """
+        data = {
+            "id": submission.fullname,
+            "num": num,
+            "state": state,
+            "to_profile": True,
+        }
+        try:
+            return await self._reddit.post(API_PATH["sticky_submission"], data=data)
+        except Conflict:
+            pass
+
     def subreddits(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
     ) -> AsyncIterator["asyncpraw.models.Subreddit"]: