"""Provide the Reddit class."""

from __future__ import annotations

import asyncio
import builtins
import configparser
import os
import re
import time
from itertools import islice
from logging import getLogger
from typing import IO, TYPE_CHECKING, Any, cast
from urllib.parse import urlparse

from prawcore import (
    Authorizer,
    DeviceIDAuthorizer,
    ReadOnlyAuthorizer,
    Redirect,
    Requestor,
    ScriptAuthorizer,
    TrustedAuthenticator,
    UntrustedAuthenticator,
    session,
)
from prawcore.exceptions import BadRequest

from praw import models
from praw.config import Config
from praw.const import API_PATH, USER_AGENT_FORMAT, __version__
from praw.exceptions import (
    ClientException,
    MissingRequiredAttributeException,
    RedditAPIException,
)
from praw.objector import Objector

try:
    from update_checker import update_check

    UPDATE_CHECKER_MISSING = False
except ImportError:  # pragma: no cover
    update_check = None
    UPDATE_CHECKER_MISSING = True

if TYPE_CHECKING:
    import sys

    if sys.version_info >= (3, 11):
        from typing import Self
    else:
        from typing_extensions import Self

    from collections.abc import Generator, Iterable, Iterator

    import prawcore.auth
    import prawcore.requestor

    from praw.exceptions import RedditErrorItem


Comment = models.Comment
Redditor = models.Redditor
Submission = models.Submission
Subreddit = models.Subreddit

logger = getLogger("praw")


class Reddit:
    """The Reddit class provides convenient access to Reddit's API.

    Instances of this class are the gateway to interacting with Reddit's API through
    PRAW. The canonical way to obtain an instance of this class is via:

    .. code-block:: python

        import praw

        reddit = praw.Reddit(
            client_id="CLIENT_ID",
            client_secret="CLIENT_SECRET",
            password="PASSWORD",
            user_agent="USERAGENT",
            username="USERNAME",
        )

    """

    _ratelimit_regex = re.compile(r"([0-9]{1,3}) (milliseconds?|seconds?|minutes?)")
    update_checked = False

    @property
    def _next_unique(self) -> int:
        value = self._unique_counter
        self._unique_counter += 1
        return value

    @property
    def read_only(self) -> bool:
        """``True`` when using the ``ReadOnlyAuthorizer``."""
        return self._core == self._read_only_core

    @read_only.setter
    def read_only(self, value: bool) -> None:
        """Set or unset the use of the ReadOnlyAuthorizer.

        :raises: :class:`.ClientException` when attempting to unset ``read_only`` and
            only the ``ReadOnlyAuthorizer`` is available.

        """
        if value:
            self._core = self._read_only_core
        elif self._authorized_core is None:
            msg = "read_only cannot be unset as only the ReadOnlyAuthorizer is available."
            raise ClientException(msg)
        else:
            self._core = self._authorized_core

    def __enter__(self) -> Self:
        """Handle the context manager open."""
        return self

    def __exit__(self, *_: object) -> None:
        """Handle the context manager close."""

    def __init__(
        self,
        site_name: str | None = None,
        *,
        config_interpolation: str | None = None,
        requestor_class: type[prawcore.requestor.Requestor] | None = None,
        requestor_kwargs: dict[str, Any] | None = None,
        **config_settings: str | bool | int | None,
    ) -> None:
        """Initialize a :class:`.Reddit` instance.

        :param site_name: The name of a section in your ``praw.ini`` file from which to
            load settings from. This parameter, in tandem with an appropriately
            configured ``praw.ini``, file is useful if you wish to easily save
            credentials for different applications, or communicate with other servers
            running Reddit. If ``site_name`` is ``None``, then the site name will be
            looked for in the environment variable ``praw_site``. If it is not found
            there, the ``DEFAULT`` site will be used (default: ``None``).
        :param config_interpolation: Config parser interpolation type that will be
            passed to :class:`.Config` (default: ``None``).
        :param requestor_class: A class that will be used to create a requestor. If not
            set, use ``prawcore.Requestor`` (default: ``None``).
        :param requestor_kwargs: Dictionary with additional keyword arguments used to
            initialize the requestor (default: ``None``).

        Additional keyword arguments will be used to initialize the :class:`.Config`
        object. This can be used to specify configuration settings during instantiation
        of the :class:`.Reddit` instance. For more details, please see
        :ref:`configuration`.

        Required settings are:

        - ``client_id``
        - ``client_secret`` (for installed applications set this value to ``None``)
        - ``user_agent``

        The ``requestor_class`` and ``requestor_kwargs`` allow for customization of the
        requestor :class:`.Reddit` will use. This allows, e.g., easily adding behavior
        to the requestor or wrapping its |Session|_ in a caching layer. Example usage:

        .. |Session| replace:: ``Session``

        .. _session: https://requests.readthedocs.io/en/stable/api/#request-sessions

        .. code-block:: python

            import json

            import requests
            from prawcore import Requestor

            from praw import Reddit


            class JSONDebugRequestor(Requestor):
                def request(self, *args, **kwargs):
                    response = super().request(*args, **kwargs)
                    print(json.dumps(response.json(), indent=4))
                    return response


            my_session = requests.Session()
            reddit = Reddit(
                ..., requestor_class=JSONDebugRequestor, requestor_kwargs={"session": my_session}
            )

        """
        self._core = self._authorized_core = self._read_only_core = None
        self._objector: Objector
        self._unique_counter = 0

        try:
            config_section = (
                site_name or os.getenv("praw_site") or "DEFAULT"  # ruff:ignore[uncapitalized-environment-variables]
            )
            self.config = Config(config_section, config_interpolation, **config_settings)
        except configparser.NoSectionError as exc:
            help_message = (
                "You provided the name of a praw.ini configuration which does not"
                " exist.\n\nFor help with creating a Reddit instance,"
                " visit\nhttps://praw.readthedocs.io/en/latest/code_overview/reddit_instance.html\n\nFor"
                " help on configuring PRAW,"
                " visit\nhttps://praw.readthedocs.io/en/latest/getting_started/configuration.html"
            )
            if site_name is not None:
                exc.message += f"\n{help_message}"
            raise

        required_message = (
            "Required configuration setting {!r} missing. \nThis setting can be"
            " provided in a praw.ini file, as a keyword argument to the Reddit class"
            " constructor, or as an environment variable."
        )
        for attribute in ("client_id", "user_agent"):
            if getattr(self.config, attribute) in {self.config.CONFIG_NOT_SET, None}:
                raise MissingRequiredAttributeException(required_message.format(attribute))
        if self.config.client_secret is self.config.CONFIG_NOT_SET:
            msg = f"{required_message.format('client_secret')}\nFor installed applications this value must be set to None via a keyword argument to the Reddit class constructor."
            raise MissingRequiredAttributeException(msg)

        self._check_for_update()
        self._prepare_objector()
        self._prepare_prawcore(requestor_class=requestor_class, requestor_kwargs=requestor_kwargs)

        self.auth = models.Auth(self, None)
        """An instance of :class:`.Auth`.

        Provides the interface for interacting with installed and web applications.

        .. seealso::

            :ref:`auth_url`

        """

        self.announcements = models.AnnouncementHelper(self, None)
        r"""An instance of :class:`.AnnouncementHelper`.

        Provides the interface for working with :class:`.Announcement`\ s for the
        currently authenticated user.

        For example, to iterate through announcements:

        .. code-block:: python

            for announcement in reddit.announcements():
                print(announcement.subject)

        To mark all announcements as read:

        .. code-block:: python

            reddit.announcements.mark_all_read()

        """

        self.drafts = models.DraftHelper(self, None)
        """An instance of :class:`.DraftHelper`.

        Provides the interface for working with :class:`.Draft` instances.

        For example, to list the currently authenticated user's drafts:

        .. code-block:: python

            drafts = reddit.drafts()

        To create a draft on r/test run:

        .. code-block:: python

            reddit.drafts.create(title="title", selftext="selftext", subreddit="test")

        """

        self.front = models.Front(self)
        """An instance of :class:`.Front`.

        Provides the interface for interacting with front page listings. For example:

        .. code-block:: python

            for submission in reddit.front.hot():
                print(submission)

        """

        self.inbox = models.Inbox(self, None)
        """An instance of :class:`.Inbox`.

        Provides the interface to a user's inbox which produces :class:`.Message`,
        :class:`.Comment`, and :class:`.Submission` instances. For example, to iterate
        through comments which mention the authorized user run:

        .. code-block:: python

            for comment in reddit.inbox.mentions():
                print(comment)

        """

        self.live = models.LiveHelper(self, None)
        """An instance of :class:`.LiveHelper`.

        Provides the interface for working with :class:`.LiveThread` instances. At
        present only new live threads can be created.

        .. code-block:: python

            reddit.live.create(title="title", description="description")

        """

        self.multireddit = models.MultiredditHelper(self, None)
        """An instance of :class:`.MultiredditHelper`.

        Provides the interface to working with :class:`.Multireddit` instances. For
        example, you can obtain a :class:`.Multireddit` instance via:

        .. code-block:: python

            reddit.multireddit(redditor="samuraisam", name="programming")

        """

        self.notes = models.RedditModNotes(self)
        r"""An instance of :class:`.RedditModNotes`.

        Provides the interface for working with :class:`.ModNote`\ s for multiple
        redditors across multiple subreddits.

        .. note::

            The authenticated user must be a moderator of the provided subreddit(s).

        For example, the latest note for u/spez in r/redditdev and r/test, and for
        u/bboe in r/redditdev can be iterated through like so:

        .. code-block:: python

            redditor = reddit.redditor("bboe")
            subreddit = reddit.subreddit("redditdev")

            pairs = [(subreddit, "spez"), ("test", "spez"), (subreddit, redditor)]

            for note in reddit.notes(pairs=pairs):
                print(f"{note.label}: {note.note}")

        """

        self.redditors = models.Redditors(self, None)
        """An instance of :class:`.Redditors`.

        Provides the interface for :class:`.Redditor` discovery. For example, to iterate
        over the newest Redditors, run:

        .. code-block:: python

            for redditor in reddit.redditors.new(limit=None):
                print(redditor)

        """

        self.subreddit = models.SubredditHelper(self, None)
        """An instance of :class:`.SubredditHelper`.

        Provides the interface to working with :class:`.Subreddit` instances. For
        example, to create a :class:`.Subreddit` run:

        .. code-block:: python

            reddit.subreddit.create(name="coolnewsubname")

        To obtain a lazy :class:`.Subreddit` instance run:

        .. code-block:: python

            reddit.subreddit("test")

        Multiple subreddits can be combined and filtered views of r/all can also be used
        just like a subreddit:

        .. code-block:: python

            reddit.subreddit("redditdev+learnpython+botwatch")
            reddit.subreddit("all-redditdev-learnpython")

        """

        self.subreddits = models.Subreddits(self, None)
        """An instance of :class:`.Subreddits`.

        Provides the interface for :class:`.Subreddit` discovery. For example, to
        iterate over the set of default subreddits run:

        .. code-block:: python

            for subreddit in reddit.subreddits.default(limit=None):
                print(subreddit)

        """

        self.user = models.User(self)
        """An instance of :class:`.User`.

        Provides the interface to the currently authorized :class:`.Redditor`. For
        example, to get the name of the current user run:

        .. code-block:: python

            print(reddit.user.me())

        """

    def _check_for_async(self) -> None:
        if self.config.check_for_async:  # pragma: no cover
            # IPython injects get_ipython into builtins; it is absent outside IPython.
            get_ipython = getattr(builtins, "get_ipython", None)
            if get_ipython is not None and get_ipython().__class__.__name__ == "ZMQInteractiveShell":
                return
            in_async = False
            try:
                asyncio.get_running_loop()
                in_async = True
            except Exception:  # ruff:ignore[blind-except, try-except-pass]
                pass  # Quietly fail if any exception occurs during the check
            if in_async:
                logger.warning(
                    "It appears that you are using PRAW in an asynchronous"
                    " environment.\nIt is strongly recommended to use Async PRAW:"
                    " https://asyncpraw.readthedocs.io.\nSee"
                    " https://praw.readthedocs.io/en/latest/getting_started/multiple_instances.html#discord-bots-and-"
                    "asynchronous-environments"
                    " for more info.\n",
                )

    def _check_for_update(self) -> None:
        if UPDATE_CHECKER_MISSING or update_check is None:
            return
        if not Reddit.update_checked and self.config.check_for_updates:
            update_check(package_name=__package__ or "praw", package_version=__version__)
            Reddit.update_checked = True

    def _handle_rate_limit(self, exception: RedditAPIException) -> int | float | None:
        for item in exception.items:
            if item.error_type == "RATELIMIT" and item.message is not None:
                amount_search = self._ratelimit_regex.search(item.message)
                if not amount_search:
                    break
                seconds = int(amount_search.group(1))
                if amount_search.group(2).startswith("minute"):
                    seconds *= 60
                elif amount_search.group(2).startswith("millisecond"):
                    seconds = 0
                if seconds <= int(self.config.ratelimit_seconds):
                    return seconds + 1
        return None

    def _objectify_request(
        self,
        *,
        data: dict[str, Any] | bytes | IO | str | None = None,
        files: dict[str, IO] | None = None,
        json: dict[Any, Any] | list[Any] | None = None,
        method: str = "",
        params: dict[str, str | int] | None = None,
        path: str = "",
    ) -> Any:
        """Run a request through the ``Objector``.

        :param data: Dictionary, bytes, or file-like object to send in the body of the
            request (default: ``None``).
        :param files: Dictionary, filename to file (like) object mapping (default:
            ``None``).
        :param json: JSON-serializable object to send in the body of the request with a
            Content-Type header of application/json (default: ``None``). If ``json`` is
            provided, ``data`` should not be.
        :param method: The HTTP method (e.g., ``"GET"``, ``"POST"``, ``"PUT"``,
            ``"DELETE"``).
        :param params: The query parameters to add to the request (default: ``None``).
        :param path: The path to fetch.

        """
        return self._objector.objectify(
            data=self.request(
                data=data,
                files=files,
                json=json,
                method=method,
                params=params,
                path=path,
            )
        )

    def _prepare_common_authorizer(self, authenticator: prawcore.auth.BaseAuthenticator) -> None:
        if self.config.refresh_token:
            authorizer = Authorizer(authenticator=authenticator, refresh_token=self.config.refresh_token)
        else:
            self._core = self._read_only_core
            return
        self._core = self._authorized_core = session(authorizer=authorizer, window_size=self.config.window_size)

    def _prepare_objector(self) -> None:
        mappings = {
            self.config.kinds["comment"]: models.Comment,
            self.config.kinds["message"]: models.Message,
            self.config.kinds["redditor"]: models.Redditor,
            self.config.kinds["submission"]: models.Submission,
            self.config.kinds["subreddit"]: models.Subreddit,
            self.config.kinds["trophy"]: models.Trophy,
            "Announcement": models.Announcement,
            "AnnouncementListing": models.AnnouncementListing,
            "Button": models.Button,
            "Collection": models.Collection,
            "Draft": models.Draft,
            "DraftList": models.DraftList,
            "Image": models.Image,
            "LabeledMulti": models.Multireddit,
            "Listing": models.Listing,
            "LiveUpdate": models.LiveUpdate,
            "LiveUpdateEvent": models.LiveThread,
            "MenuLink": models.MenuLink,
            "ModeratedList": models.ModeratedList,
            "ModmailAction": models.ModmailAction,
            "ModmailConversation": models.ModmailConversation,
            "ModmailConversations-list": models.ModmailConversationsListing,
            "ModmailMessage": models.ModmailMessage,
            "Submenu": models.Submenu,
            "TrophyList": models.TrophyList,
            "UserList": models.RedditorList,
            "UserSubreddit": models.UserSubreddit,
            "ann": models.Announcement,
            "button": models.ButtonWidget,
            "calendar": models.Calendar,
            "community-list": models.CommunityList,
            "custom": models.CustomWidget,
            "id-card": models.IDCard,
            "image": models.ImageWidget,
            "menu": models.Menu,
            "mod_note": models.ModNote,
            "modaction": models.ModAction,
            "moderator-list": models.ModeratorListing,
            "moderators": models.ModeratorsWidget,
            "more": models.MoreComments,
            "post-flair": models.PostFlairWidget,
            "rule": models.Rule,
            "stylesheet": models.Stylesheet,
            "subreddit-rules": models.RulesWidget,
            "textarea": models.TextArea,
            "widget": models.Widget,
        }
        self._objector = Objector(self, mappings)

    def _prepare_prawcore(
        self,
        *,
        requestor_class: type[prawcore.requestor.Requestor] | None = None,
        requestor_kwargs: dict[str, Any] | None = None,
    ) -> None:
        requestor_class = requestor_class or Requestor
        requestor_kwargs = requestor_kwargs or {}

        requestor = requestor_class(
            oauth_url=self.config.oauth_url,
            reddit_url=self.config.reddit_url,
            user_agent=USER_AGENT_FORMAT.format(self.config.user_agent),
            **requestor_kwargs,
        )

        if self.config.client_secret:
            self._prepare_trusted_prawcore(requestor)
        else:
            self._prepare_untrusted_prawcore(requestor)

    def _prepare_trusted_prawcore(self, requestor: prawcore.requestor.Requestor) -> None:
        # Only reached when client_secret is set (see _prepare_prawcore).
        assert self.config.client_secret is not None
        authenticator = TrustedAuthenticator(
            client_id=self.config.client_id,
            client_secret=self.config.client_secret,
            redirect_uri=self.config.redirect_uri,
            requestor=requestor,
        )
        read_only_authorizer = ReadOnlyAuthorizer(authenticator=authenticator)
        self._read_only_core = session(authorizer=read_only_authorizer, window_size=self.config.window_size)

        if self.config.username and self.config.password:
            script_authorizer = ScriptAuthorizer(
                authenticator=authenticator, password=self.config.password, username=self.config.username
            )
            self._core = self._authorized_core = session(
                authorizer=script_authorizer, window_size=self.config.window_size
            )
        else:
            self._prepare_common_authorizer(authenticator)

    def _prepare_untrusted_prawcore(self, requestor: prawcore.requestor.Requestor) -> None:
        authenticator = UntrustedAuthenticator(
            client_id=self.config.client_id, redirect_uri=self.config.redirect_uri, requestor=requestor
        )
        read_only_authorizer = DeviceIDAuthorizer(authenticator=authenticator)
        self._read_only_core = session(authorizer=read_only_authorizer, window_size=self.config.window_size)
        self._prepare_common_authorizer(authenticator)

    def _resolve_share_url(self, url: str) -> str:
        """Return the canonical URL for a given share URL."""
        parts = urlparse(url).path.rstrip("/").split("/")
        if "s" in parts:  # handling new share urls from mobile apps
            try:
                self.get(url)
            except Redirect as e:
                next_request = e.response.next
                assert next_request is not None
                assert next_request.url is not None
                return next_request.url
        return url

    def comment(self, id: str | None = None, *, url: str | None = None) -> models.Comment:
        """Return a lazy instance of :class:`.Comment`.

        :param id: The ID of the comment.
        :param url: A permalink pointing to the comment.

        .. note::

            If you want to obtain the comment's replies, you will need to call
            :meth:`~.Comment.refresh` on the returned :class:`.Comment`.

        """
        if url:
            url = self._resolve_share_url(url)
        return models.Comment(self, id=id, url=url)

    def delete(
        self,
        path: str,
        *,
        data: dict[str, Any] | bytes | IO | str | None = None,
        json: dict[Any, Any] | list[Any] | None = None,
        params: dict[str, str | int] | None = None,
    ) -> Any:
        """Return parsed objects returned from a DELETE request to ``path``.

        :param path: The path to fetch.
        :param data: Dictionary, bytes, or file-like object to send in the body of the
            request (default: ``None``).
        :param json: JSON-serializable object to send in the body of the request with a
            Content-Type header of application/json (default: ``None``). If ``json`` is
            provided, ``data`` should not be.
        :param params: The query parameters to add to the request (default: ``None``).

        """
        return self._objectify_request(data=data, json=json, method="DELETE", params=params, path=path)

    def domain(self, domain: str) -> models.DomainListing:
        """Return an instance of :class:`.DomainListing`.

        :param domain: The domain to obtain submission listings for.

        """
        return models.DomainListing(self, domain)

    def get(
        self,
        path: str,
        *,
        params: dict[str, str | int] | None = None,
    ) -> Any:
        """Return parsed objects returned from a GET request to ``path``.

        :param path: The path to fetch.
        :param params: The query parameters to add to the request (default: ``None``).

        """
        return self._objectify_request(method="GET", params=params, path=path)

    def info(
        self,
        *,
        fullnames: Iterable[str] | None = None,
        subreddits: Iterable[models.Subreddit | str] | None = None,
        url: str | None = None,
    ) -> Generator[
        models.Subreddit | models.Comment | models.Submission,
        None,
        None,
    ]:
        """Fetch information about each item in ``fullnames``, ``url``, or ``subreddits``.

        :param fullnames: A list of fullnames for comments, submissions, and/or
            subreddits.
        :param subreddits: A list of subreddit names or :class:`.Subreddit` objects to
            retrieve subreddits from.
        :param url: A url (as a string) to retrieve lists of link submissions from.

        :returns: A generator that yields found items in their relative order.

        Items that cannot be matched will not be generated. Requests will be issued in
        batches for each 100 fullnames.

        .. note::

            For comments that are retrieved via this method, if you want to obtain its
            replies, you will need to call :meth:`~.Comment.refresh` on the yielded
            :class:`.Comment`.

        .. note::

            When using the URL option, it is important to be aware that URLs are treated
            literally by Reddit's API. As such, the URLs ``"youtube.com"`` and
            ``"https://www.youtube.com"`` will provide a different set of submissions.

        """
        set_count = sum(1 for value in (fullnames, url, subreddits) if value is not None)
        if set_count != 1:
            msg = "Either 'fullnames', 'url', or 'subreddits' must be provided."
            raise TypeError(msg)

        is_using_fullnames = fullnames is not None
        ids_or_names = fullnames if is_using_fullnames else subreddits

        if ids_or_names is not None:
            if isinstance(ids_or_names, str):
                msg = "'fullnames' and 'subreddits' must be a non-str iterable."
                raise TypeError(msg)

            api_parameter_name = "id" if is_using_fullnames else "sr_name"

            def name_generator(
                names: Iterable[str | models.Subreddit],
            ) -> Generator[
                models.Subreddit | models.Comment | models.Submission,
                None,
                None,
            ]:
                iterable: Iterator[str] = (
                    iter(str(item) for item in names) if is_using_fullnames else iter([str(item) for item in names])
                )
                while True:
                    chunk = list(islice(iterable, 100))
                    if not chunk:
                        break
                    params: dict[str, str | int] = {api_parameter_name: ",".join(chunk)}
                    yield from self.get(API_PATH["info"], params=params)

            return name_generator(ids_or_names)

        def url_generator(
            _url: str,
        ) -> Generator[
            models.Subreddit | models.Comment | models.Submission,
            None,
            None,
        ]:
            params: dict[str, str | int] = {"url": _url}
            yield from self.get(API_PATH["info"], params=params)

        assert url is not None
        return url_generator(url)

    def patch(
        self,
        path: str,
        *,
        data: dict[str, Any] | bytes | IO | str | None = None,
        json: dict[Any, Any] | list[Any] | None = None,
        params: dict[str, str | int] | None = None,
    ) -> Any:
        """Return parsed objects returned from a PATCH request to ``path``.

        :param path: The path to fetch.
        :param data: Dictionary, bytes, or file-like object to send in the body of the
            request (default: ``None``).
        :param json: JSON-serializable object to send in the body of the request with a
            Content-Type header of application/json (default: ``None``). If ``json`` is
            provided, ``data`` should not be.
        :param params: The query parameters to add to the request (default: ``None``).

        """
        return self._objectify_request(data=data, json=json, method="PATCH", params=params, path=path)

    def post(
        self,
        path: str,
        *,
        data: dict[str, Any] | bytes | IO | str | None = None,
        files: dict[str, IO] | None = None,
        json: dict[Any, Any] | list[Any] | None = None,
        params: dict[str, str | int] | None = None,
    ) -> Any:
        """Return parsed objects returned from a POST request to ``path``.

        :param path: The path to fetch.
        :param data: Dictionary, bytes, or file-like object to send in the body of the
            request (default: ``None``).
        :param files: Dictionary, filename to file (like) object mapping (default:
            ``None``).
        :param json: JSON-serializable object to send in the body of the request with a
            Content-Type header of application/json (default: ``None``). If ``json`` is
            provided, ``data`` should not be.
        :param params: The query parameters to add to the request (default: ``None``).

        """
        if json is None:
            data = data or {}

        attempts = 3
        last_exception: RedditAPIException | None = None
        while attempts > 0:
            attempts -= 1
            try:
                return self._objectify_request(
                    data=data,
                    files=files,
                    json=json,
                    method="POST",
                    params=params,
                    path=path,
                )
            except RedditAPIException as exception:
                last_exception = exception
                seconds = self._handle_rate_limit(exception=exception)
                if seconds is None:
                    break
                second_string = "second" if seconds == 1 else "seconds"
                logger.debug("Rate limit hit, sleeping for %d %s", seconds, second_string)
                time.sleep(seconds)
        assert last_exception is not None
        raise last_exception

    def put(
        self,
        path: str,
        *,
        data: dict[str, Any] | bytes | IO | str | None = None,
        json: dict[Any, Any] | list[Any] | None = None,
    ) -> Any:
        """Return parsed objects returned from a PUT request to ``path``.

        :param path: The path to fetch.
        :param data: Dictionary, bytes, or file-like object to send in the body of the
            request (default: ``None``).
        :param json: JSON-serializable object to send in the body of the request with a
            Content-Type header of application/json (default: ``None``). If ``json`` is
            provided, ``data`` should not be.

        """
        return self._objectify_request(data=data, json=json, method="PUT", path=path)

    def redditor(self, name: str | None = None, *, fullname: str | None = None) -> models.Redditor:
        """Return a lazy instance of :class:`.Redditor`.

        :param name: The name of the redditor.
        :param fullname: The fullname of the redditor, starting with ``t2_``.

        Either ``name`` or ``fullname`` can be provided, but not both.

        """
        return models.Redditor(self, fullname=fullname, name=name)

    def request(
        self,
        *,
        data: dict[str, Any] | bytes | IO | str | None = None,
        files: dict[str, IO] | None = None,
        json: dict[Any, Any] | list[Any] | None = None,
        method: str,
        params: dict[str, str | int] | None = None,
        path: str,
    ) -> Any:
        """Return the parsed JSON data returned from a request to URL.

        :param data: Dictionary, bytes, or file-like object to send in the body of the
            request (default: ``None``).
        :param files: Dictionary, filename to file (like) object mapping (default:
            ``None``).
        :param json: JSON-serializable object to send in the body of the request with a
            Content-Type header of application/json (default: ``None``). If ``json`` is
            provided, ``data`` should not be.
        :param method: The HTTP method (e.g., ``"GET"``, ``"POST"``, ``"PUT"``,
            ``"DELETE"``).
        :param params: The query parameters to add to the request (default: ``None``).
        :param path: The path to fetch.

        """
        if self.config.check_for_async:
            self._check_for_async()
        if data and json:
            msg = "At most one of 'data' or 'json' is supported."
            raise ClientException(msg)
        assert self._core is not None
        try:
            return self._core.request(
                data=data,
                files=files,
                json=json,
                method=method,
                params=params,
                path=path,
            )
        except BadRequest as exception:
            error_data: dict[str, Any]
            try:
                error_data = exception.response.json()
            except ValueError:
                if exception.response.text:
                    error_data = {"reason": exception.response.text}
                else:
                    raise exception from None
            if set(error_data) == {"error", "message"}:
                raise
            explanation = error_data.get("explanation")
            if "fields" in error_data:
                assert len(error_data["fields"]) == 1
                field = error_data["fields"][0]
            else:
                field = None
            raise RedditAPIException(
                cast(
                    "list[RedditErrorItem | list[str] | str]",
                    [error_data["reason"], explanation, field],
                )
            ) from exception

    def submission(self, id: str | None = None, *, url: str | None = None) -> models.Submission:
        """Return a lazy instance of :class:`.Submission`.

        :param id: A Reddit base36 submission ID, e.g., ``"2gmzqe"``.
        :param url: A URL supported by :meth:`.Submission.id_from_url`.

        Either ``id`` or ``url`` can be provided, but not both.

        """
        if url:
            url = self._resolve_share_url(url)
        return models.Submission(self, id=id, url=url)

    def username_available(self, name: str) -> bool:
        """Check to see if the username is available.

        For example, to check if the username ``bboe`` is available, try:

        .. code-block:: python

            reddit.username_available("bboe")

        """
        return self._objectify_request(method="GET", params={"user": name}, path=API_PATH["username_available"])
