Merge pull request #316 from praw-dev/selftext

Add support for selftext in link, image, gallery, and video posts

Author: LilSpazJoekp

AUTHORS.rst

@@ -94,4 +94,5 @@ Source Contributors
 - zacc `@zacc <https://github.com/zacc>`_
 - Arkadiy Illarionov `@qarkai <https://github.com/qarkai>`_
 - c0d3rman `@c0d3rman <https://github.com/c0d3rman>`
+- Aaron Becker `@aaronjbecker <https://github.com/aaronjbecker>`_
 - Add "Name <email (optional)> and github profile link" above this line.

CHANGES.rst

@@ -9,6 +9,8 @@ Unreleased
 **Added**
 
 - Add support for Python 3.13.
+- Add support for optional Markdown-formatted ``selftext`` when submitting link, image,
+  gallery and video posts.
 - Support delayed session creation in asyncprawcore 2.5.0+.
 - Add parameter ``fetch`` to :meth:`.get_rule` to control whether to fetch the rule data
   when initializing the rule object.
@@ -26,6 +28,14 @@ Unreleased
   must now be passed by keyword.
 - The ``flair_type`` argument to :class:`.SubredditFlairTemplates` must be passed by
   keyword.
+- The ``selftext`` and ``url`` arguments to :meth:`.Subreddit.submit` are no longer
+  mutually exclusive. When ``url`` is provided ``selftext`` will be used as optional
+  body text to accompany the link submission. An exception is raised when trying to use
+  ``inline_media`` with ``selftext`` for a ``url`` submission because Reddit does not
+  support inline media in body text for link submissions.
+- :meth:`.Subreddit.submit_video`, :meth:`.Subreddit.submit_gallery`, and
+  :meth:`.Subreddit.submit_image` now accept an optional Markdown-formatted ``selftext``
+  parameter.
 - :meth:`.CommentForest.list` no longer needs to be awaited.
 - The keyword argument ``lazy`` has been replace by ``fetch`` to consolidate the keyword
   argument used to explicitly perform a fetch when initializing an object.
@@ -49,6 +59,10 @@ Unreleased
   - :meth:`.SubredditCollections.__call__`
   - :meth:`.SubredditHelper.__call__`
 
+**Fixed**
+
+- An issue where submitting a gallery post with websockets enabled would fail.
+
 **Removed**
 
 - Remove ``Reddit.random_subreddit``, ``Subreddit.random``, and

asyncpraw/models/reddit/subreddit.py

@@ -3073,22 +3073,27 @@ async def _upload_media(
         self,
         *,
         expected_mime_prefix: str | None = None,
-        media_path: str,
+        media_path: str | None,
         upload_type: str = "link",
     ) -> str:
         """Upload media and return its URL and a websocket (Undocumented endpoint).
 
         :param expected_mime_prefix: If provided, enforce that the media has a mime type
             that starts with the provided prefix.
+        :param media_path: The path to the media file to upload. Default is the PRAW
+            logo.
         :param upload_type: One of ``"link"``, ``"gallery"'', or ``"selfpost"``
             (default: ``"link"``).
 
         :returns: The link to the uploaded media.
 
         """
         if media_path is None:
-            file = Path(__file__).absolute()
-            media_path = file.parent.parent.parent / "images" / "PRAW logo.png"
+            # if we're uploading without a media path, assume we're uploading a PRAW logo
+            # this default is commonly used when ``video_poster_url`` is not provided in ``submit_video``
+            module_path = Path(__file__).absolute()
+            logo_path = module_path.parent.parent.parent / "images" / "PRAW logo.png"
+            file = Path(logo_path)
         else:
             file = Path(media_path)
 
@@ -3262,12 +3267,14 @@ async def submit(
             this value will set a custom text (default: ``None``). ``flair_id`` is
             required when ``flair_text`` is provided.
         :param inline_media: A dict of :class:`.InlineMedia` objects where the key is
-            the placeholder name in ``selftext``.
+            the placeholder name in ``selftext``. Link post selftext does not support
+            inline media.
         :param nsfw: Whether the submission should be marked NSFW (default: ``False``).
         :param resubmit: When ``False``, an error will occur if the URL has already been
             submitted (default: ``True``).
-        :param selftext: The Markdown formatted content for a ``text`` submission. Use
-            an empty string, ``""``, to make a title-only submission.
+        :param selftext: The Markdown formatted content for a ``text`` submission or an
+            optional post body for ``link`` submissions. Use an empty string, ``""``, to
+            make a title-only submission.
         :param send_replies: When ``True``, messages will be sent to the submission
             author when comments are made to the submission (default: ``True``).
         :param spoiler: Whether the submission should be marked as a spoiler (default:
@@ -3276,7 +3283,10 @@ async def submit(
 
         :returns: A :class:`.Submission` object for the newly created submission.
 
-        Either ``selftext`` or ``url`` can be provided, but not both.
+        Provide ``selftext`` alone for a ``text`` submission. ``selftext`` can accompany
+        a ``url`` for a ``link`` submission. ``selftext`` that accompanies a ``link``
+        submission is optional. ``selftext`` for ``link`` submissions does not support
+        ``inline_media``.
 
         For example, to submit a URL to r/test do:
 
@@ -3334,6 +3344,16 @@ async def submit(
                 template_id = next(x for x in choices if x["flair_text"] == "news")["flair_template_id"]
                 await subreddit.submit("title", flair_id=template_id, url="https://www.news.com/")
 
+        .. note::
+
+            If you need to access any attributes of the submission after submitting it,
+            you must re-fetch the submission, like so:
+
+            .. code-block:: python
+
+                submission = await subreddit.submit(title, url=url)
+                await submission.load()
+
         .. seealso::
 
             - :meth:`~.Subreddit.submit_gallery` to submit more than one image in the
@@ -3343,8 +3363,10 @@ async def submit(
             - :meth:`~.Subreddit.submit_video` to submit videos and videogifs
 
         """
-        if (bool(selftext) or selftext == "") == bool(url):  # noqa: PLC1901
-            msg = "Either 'selftext' or 'url' must be provided."
+        # link posts can now include selftext (no longer exclusive)
+        # test for empty string in selftext for title-only submissions
+        if not url and not (bool(selftext) or selftext == ""):  # noqa: PLC1901
+            msg = "Either 'selftext' and/or 'url' must be provided."
             raise TypeError(msg)
 
         data = {
@@ -3365,7 +3387,15 @@ async def submit(
         ):
             if value is not None:
                 data[key] = value
-        if selftext is not None:
+        if url is not None:
+            data.update(kind="link", url=url)
+            if inline_media:
+                msg = "As of 2025-10-08, `inline_media` is not supported for link post selftext. Only Markdown text can be added to non-self posts."
+                raise TypeError(msg)
+            # we can ignore an empty string for selftext here b/c body text is optional for link posts
+            if selftext:
+                data.update(text=selftext)
+        elif selftext is not None:
             data.update(kind="self")
             if inline_media:
                 body = selftext.format(**{
@@ -3375,8 +3405,6 @@ async def submit(
                 data.update(richtext_json=dumps(converted))
             else:
                 data.update(text=selftext)
-        else:
-            data.update(kind="link", url=url)
 
         return await self._reddit.post(API_PATH["submit"], data=data)
 
@@ -3390,6 +3418,7 @@ async def submit_gallery(
         flair_id: str | None = None,
         flair_text: str | None = None,
         nsfw: bool = False,
+        selftext: str | None = None,
         send_replies: bool = True,
         spoiler: bool = False,
     ) -> asyncpraw.models.Submission:
@@ -3408,6 +3437,8 @@ async def submit_gallery(
             this value will set a custom text (default: ``None``). ``flair_id`` is
             required when ``flair_text`` is provided.
         :param nsfw: Whether the submission should be marked NSFW (default: ``False``).
+        :param selftext: Optional Markdown-formatted post body content (default:
+            ``None``).
         :param send_replies: When ``True``, messages will be sent to the submission
             author when comments are made to the submission (default: ``True``).
         :param spoiler: Whether the submission should be marked asa spoiler (default:
@@ -3466,6 +3497,7 @@ async def submit_gallery(
             ("flair_text", flair_text),
             ("collection_id", collection_id),
             ("discussion_type", discussion_type),
+            ("text", selftext),
         ):
             if value is not None:
                 data[key] = value
@@ -3479,7 +3511,7 @@ async def submit_gallery(
                         media_path=image["image_path"],
                         upload_type="gallery",
                     )
-                )[0],
+                ),
             })
         response = await self._reddit.request(json=data, method="POST", path=API_PATH["submit_gallery_post"])
         response = response["json"]
@@ -3498,6 +3530,7 @@ async def submit_image(
         flair_text: str | None = None,
         nsfw: bool = False,
         resubmit: bool = True,
+        selftext: str | None = None,
         send_replies: bool = True,
         spoiler: bool = False,
         timeout: int = 10,
@@ -3517,6 +3550,8 @@ async def submit_image(
         :param nsfw: Whether the submission should be marked NSFW (default: ``False``).
         :param resubmit: When ``False``, an error will occur if the URL has already been
             submitted (default: ``True``).
+        :param selftext: Optional Markdown-formatted post body content (default:
+            ``None``).
         :param send_replies: When ``True``, messages will be sent to the submission
             author when comments are made to the submission (default: ``True``).
         :param spoiler: Whether the submission should be marked as a spoiler (default:
@@ -3579,6 +3614,7 @@ async def submit_image(
             ("flair_text", flair_text),
             ("collection_id", collection_id),
             ("discussion_type", discussion_type),
+            ("text", selftext),
         ):
             if value is not None:
                 data[key] = value
@@ -3680,6 +3716,7 @@ async def submit_video(
         flair_text: str | None = None,
         nsfw: bool = False,
         resubmit: bool = True,
+        selftext: str | None = None,
         send_replies: bool = True,
         spoiler: bool = False,
         thumbnail_path: str | None = None,
@@ -3702,6 +3739,8 @@ async def submit_video(
         :param nsfw: Whether the submission should be marked NSFW (default: ``False``).
         :param resubmit: When ``False``, an error will occur if the URL has already been
             submitted (default: ``True``).
+        :param selftext: Optional Markdown-formatted post body content (default:
+            ``None``).
         :param send_replies: When ``True``, messages will be sent to the submission
             author when comments are made to the submission (default: ``True``).
         :param spoiler: Whether the submission should be marked as a spoiler (default:
@@ -3768,6 +3807,7 @@ async def submit_video(
             ("flair_text", flair_text),
             ("collection_id", collection_id),
             ("discussion_type", discussion_type),
+            ("text", selftext),
         ):
             if value is not None:
                 data[key] = value