Merge pull request #1988 from praw-dev/general-cleanup

General cleanup

.pre-commit-config.yaml

@@ -58,5 +58,4 @@ repos:
  - repo: https://github.com/LilSpazJoekp/docstrfmt
  hooks:
  - id: docstrfmt
- require_serial: true
  rev: v1.5.1

CHANGES.rst

@@ -1,7 +1,7 @@
 Change Log
 ==========
 
-PRAW follows `semantic versioning <http://semver.org/>`_.
+PRAW follows `semantic versioning <https://semver.org/>`_.
 
 Unreleased
 ----------

praw/config.py

@@ -6,6 +6,7 @@
 import sys
 from pathlib import Path
 from threading import Lock
+from typing import Any
 
 from .exceptions import ClientException
 
@@ -32,13 +33,13 @@ class Config:
  }
 
  @staticmethod
- def _config_boolean(item: bool | str) -> bool: # noqa: ANN001
+ def _config_boolean(item: bool | str) -> bool:
  if isinstance(item, bool):
  return item
  return item.lower() in {"1", "yes", "true", "on"}
 
  @classmethod
- def _load_config(cls, *, config_interpolation: str | None = None): # noqa: ANN001
+ def _load_config(cls, *, config_interpolation: str | None = None):
  """Attempt to load settings from various praw.ini files."""
  if config_interpolation is not None:
  interpolator_class = cls.INTERPOLATION_LEVEL[config_interpolation]()
@@ -97,17 +98,19 @@ def __init__(
 
  self._initialize_attributes()
 
- def _fetch(self, key): # noqa: ANN001
+ def _fetch(self, key: str) -> Any:
  value = self.custom[key]
  del self.custom[key]
  return value
 
- def _fetch_default(self, key, *, default=None): # noqa: ANN001
+ def _fetch_default(
+ self, key: str, *, default: bool | float | str | None = None
+ ) -> Any:
  if key not in self.custom:
  return default
  return self._fetch(key)
 
- def _fetch_or_not_set(self, key): # noqa: ANN001
+ def _fetch_or_not_set(self, key: str) -> Any | _NotSet:
  if key in self._settings: # Passed in values have the highest priority
  return self._fetch(key)
 
@@ -117,7 +120,7 @@ def _fetch_or_not_set(self, key): # noqa: ANN001
  # Environment variables have higher priority than praw.ini settings
  return env_value or ini_value or self.CONFIG_NOT_SET
 
- def _initialize_attributes(self): # noqa: ANN001
+ def _initialize_attributes(self):
  self._short_url = self._fetch_default("short_url") or self.CONFIG_NOT_SET
  self.check_for_async = self._config_boolean(
  self._fetch_default("check_for_async", default=True)

praw/endpoints.py

@@ -1,5 +1,4 @@
 """List of API endpoints PRAW knows about."""
-# flake8: noqa
 # fmt: off
 API_PATH = {
  "about_edited": "r/{subreddit}/about/edited/",

praw/exceptions.py

@@ -9,12 +9,13 @@
 """
 from __future__ import annotations
 
+from typing import Any
 from warnings import warn
 
 from .util import _deprecate_args
 
 
-class PRAWException(Exception): # noqa: N818
+class PRAWException(Exception):
  """The base PRAW Exception that all other exception classes extend."""
 
 
@@ -79,7 +80,7 @@ class ClientException(PRAWException):
 class DuplicateReplaceException(ClientException):
  """Indicate exceptions that involve the replacement of :class:`.MoreComments`."""
 
- def __init__(self) -> None:
+ def __init__(self):
  """Initialize a :class:`.DuplicateReplaceException` instance."""
  super().__init__(
  "A duplicate comment has been detected. Are you attempting to call"
@@ -101,7 +102,7 @@ def __init__(self, template_id: str):
 class InvalidImplicitAuth(ClientException):
  """Indicate exceptions where an implicit auth type is used incorrectly."""
 
- def __init__(self) -> None:
+ def __init__(self):
  """Initialize an :class:`.InvalidImplicitAuth` instance."""
  super().__init__("Implicit authorization can only be used with installed apps.")
 
@@ -189,7 +190,7 @@ def __init__(self, message: str, exception: Exception | None):
 class MediaPostFailed(WebSocketException):
  """Indicate exceptions where media uploads failed.."""
 
- def __init__(self) -> None:
+ def __init__(self):
  """Initialize a :class:`.MediaPostFailed` instance."""
  super().__init__(
  "The attempted media upload action has failed. Possible causes include the"
@@ -287,7 +288,7 @@ def __init__(
  self.items = self.parse_exception_list(items)
  super().__init__(*self.items)
 
- def _get_old_attr(self, attrname): # noqa: ANN001
+ def _get_old_attr(self, attrname: str) -> Any:
  warn(
  f"Accessing attribute '{attrname}' through APIException is deprecated."
  " This behavior will be removed in PRAW 8.0. Check out"

praw/models/base.py

@@ -13,7 +13,7 @@ class PRAWBase:
 
  @staticmethod
  def _safely_add_arguments(
- *, arguments, key, **new_arguments # noqa: ANN001,ANN003,ANN205
+ *, arguments: dict[str, Any], key: str, **new_arguments: Any
  ):
  """Replace arguments[key] with a deepcopy and update.
 

praw/models/comment_forest.py

@@ -20,7 +20,11 @@ class CommentForest:
  """
 
  @staticmethod
- def _gather_more_comments(tree, *, parent_tree=None): # noqa: ANN001,ANN205
+ def _gather_more_comments(
+ tree: list[praw.models.MoreComments],
+ *,
+ parent_tree: list[praw.models.MoreComments] | None = None,
+ ) -> list[MoreComments]:
  """Return a list of :class:`.MoreComments` objects obtained from tree."""
  more_comments = []
  queue = [(None, x) for x in tree]
@@ -57,27 +61,11 @@ def __getitem__(self, index: int) -> praw.models.Comment:
  """
  return self._comments[index]
 
- def __init__(
- self,
- submission: praw.models.Submission,
- comments: list[praw.models.Comment] | None = None,
- ):
- """Initialize a :class:`.CommentForest` instance.
-
- :param submission: An instance of :class:`.Submission` that is the parent of the
- comments.
- :param comments: Initialize the forest with a list of comments (default:
- ``None``).
-
- """
- self._comments = comments
- self._submission = submission
-
  def __len__(self) -> int:
  """Return the number of top-level comments in the forest."""
  return len(self._comments)
 
- def _insert_comment(self, comment): # noqa: ANN001
+ def _insert_comment(self, comment: praw.models.Comment):
  if comment.name in self._submission._comments_by_id:
  raise DuplicateReplaceException
  comment.submission = self._submission
@@ -91,7 +79,7 @@ def _insert_comment(self, comment): # noqa: ANN001
  parent = self._submission._comments_by_id[comment.parent_id]
  parent.replies._comments.append(comment)
 
- def _update(self, comments): # noqa: ANN001
+ def _update(self, comments: list[praw.models.Comment]):
  self._comments = comments
  for comment in comments:
  comment.submission = self._submission
@@ -114,6 +102,22 @@ def list( # noqa: A003
  queue.extend(comment.replies)
  return comments
 
+ def __init__(
+ self,
+ submission: praw.models.Submission,
+ comments: list[praw.models.Comment] | None = None,
+ ):
+ """Initialize a :class:`.CommentForest` instance.
+
+ :param submission: An instance of :class:`.Submission` that is the parent of the
+ comments.
+ :param comments: Initialize the forest with a list of comments (default:
+ ``None``).
+
+ """
+ self._comments = comments
+ self._submission = submission
+
  @_deprecate_args("limit", "threshold")
  def replace_more(
  self, *, limit: int | None = 32, threshold: int = 0

praw/models/helpers.py

@@ -30,8 +30,8 @@ def __call__(
  ) -> list[praw.models.Draft] | praw.models.Draft:
  """Return a list of :class:`.Draft` instances.
 
- :param draft_id: When provided, return :class:`.Draft` instance (default:
- ``None``).
+ :param draft_id: When provided, this returns a :class:`.Draft` instance
+ (default: ``None``).
 
  :returns: A :class:`.Draft` instance if ``draft_id`` is provided. Otherwise, a
  list of :class:`.Draft` objects.
@@ -54,7 +54,7 @@ def __call__(
  return Draft(self._reddit, id=draft_id)
  return self._draft_list()
 
- def _draft_list(self) -> list[praw.models.Draft]: # noqa: ANN001
+ def _draft_list(self) -> list[praw.models.Draft]:
  """Get a list of :class:`.Draft` instances.
 
  :returns: A list of :class:`.Draft` instances.
@@ -139,9 +139,7 @@ def create(
 class LiveHelper(PRAWBase):
  r"""Provide a set of functions to interact with :class:`.LiveThread`\ s."""
 
- def __call__(
- self, id: str
- ) -> praw.models.LiveThread: # pylint: disable=invalid-name,redefined-builtin
+ def __call__(self, id: str) -> praw.models.LiveThread:
  """Return a new lazy instance of :class:`.LiveThread`.
 
  This method is intended to be used as:
@@ -193,8 +191,13 @@ def info(self, ids: list[str]) -> Generator[praw.models.LiveThread, None, None]:
 
  :returns: A generator that yields :class:`.LiveThread` instances.
 
- Live threads that cannot be matched will not be generated. Requests will be
- issued in batches for each 100 IDs.
+ :raises: ``prawcore.ServerError`` if invalid live threads are requested.
+
+ Requests will be issued in batches for each 100 IDs.
+
+ .. note::
+
+ This method doesn't support IDs for live updates.
 
  .. warning::
 

praw/models/listing/generator.py

@@ -52,7 +52,7 @@ def __init__(
  self.url = url
  self.yielded = 0
 
- def __iter__(self): # noqa: ANN204
+ def __iter__(self) -> Any:
  """Permit :class:`.ListingGenerator` to operate as an iterator."""
  return self
 
@@ -68,7 +68,7 @@ def __next__(self) -> Any:
  self.yielded += 1
  return self._listing[self._list_index - 1]
 
- def _extract_sublist(self, listing): # noqa: ANN001
+ def _extract_sublist(self, listing: dict[str, Any] | list[Any]):
  if isinstance(listing, list):
  return listing[1] # for submission duplicates
  if isinstance(listing, dict):
@@ -82,7 +82,7 @@ def _extract_sublist(self, listing): # noqa: ANN001
  raise ValueError(msg)
  return listing
 
- def _next_batch(self): # noqa: ANN001
+ def _next_batch(self):
  if self._exhausted:
  raise StopIteration
 

praw/models/listing/mixins/base.py

@@ -15,7 +15,7 @@ class BaseListingMixin(PRAWBase):
  VALID_TIME_FILTERS = {"all", "day", "hour", "month", "week", "year"}
 
  @staticmethod
- def _validate_time_filter(time_filter): # noqa: ANN001
+ def _validate_time_filter(time_filter: str):
  """Validate ``time_filter``.
 
  :raises: :py:class:`ValueError` if ``time_filter`` is not valid.
@@ -28,7 +28,7 @@ def _validate_time_filter(time_filter): # noqa: ANN001
  msg = f"'time_filter' must be one of: {valid_time_filters}"
  raise ValueError(msg)
 
- def _prepare(self, *, arguments, sort): # noqa: ANN001
+ def _prepare(self, *, arguments: dict[str, Any], sort: str) -> str:
  """Fix for :class:`.Redditor` methods that use a query param rather than subpath."""
  if self.__dict__.get("_listing_use_sort"):
  self._safely_add_arguments(arguments=arguments, key="params", sort=sort)

praw/models/listing/mixins/subreddit.py

@@ -19,7 +19,7 @@ class CommentHelper(PRAWBase):
  """Provide a set of functions to interact with a :class:`.Subreddit`'s comments."""
 
  @property
- def _path(self) -> str: # noqa: ANN001
+ def _path(self) -> str:
  return urljoin(self.subreddit._path, "comments/")
 
  def __call__(

praw/models/mod_action.py

@@ -15,8 +15,8 @@ class ModAction(PRAWBase):
  @property
  def mod(self) -> praw.models.Redditor:
  """Return the :class:`.Redditor` who the action was issued by."""
- return self._reddit.redditor(self._mod) # pylint: disable=no-member
+ return self._reddit.redditor(self._mod)
 
  @mod.setter
  def mod(self, value: str | praw.models.Redditor):
- self._mod = value # pylint: disable=attribute-defined-outside-init
+ self._mod = value

praw/models/mod_notes.py

@@ -63,7 +63,7 @@ def _bulk_generator(
  for note_dict in response["mod_notes"]:
  yield self._reddit._objector.objectify(note_dict)
 
- def _ensure_attribute(self, error_message: str, **attributes: Any): # noqa: ANN001
+ def _ensure_attribute(self, error_message: str, **attributes: Any) -> Any:
  attribute, _value = attributes.popitem()
  value = _value or getattr(self, attribute, None)
  if value is None:

praw/models/reddit/base.py

@@ -16,7 +16,7 @@ class RedditBase(PRAWBase):
  """Base class that represents actual Reddit objects."""
 
  @staticmethod
- def _url_parts(url): # noqa: ANN001,ANN205
+ def _url_parts(url: str) -> list[str]:
  parsed = urlparse(url)
  if not parsed.netloc:
  raise InvalidURL(url)
@@ -79,15 +79,15 @@ def __str__(self) -> str:
  """Return a string representation of the instance."""
  return getattr(self, self.STR_FIELD)
 
- def _fetch(self): # pragma: no cover
+ def _fetch(self):
  self._fetched = True
 
- def _fetch_data(self): # noqa: ANN001
+ def _fetch_data(self):
  name, fields, params = self._fetch_info()
  path = API_PATH[name].format(**fields)
  return self._reddit.request(method="GET", params=params, path=path)
 
- def _reset_attributes(self, *attributes): # noqa: ANN001,ANN002
+ def _reset_attributes(self, *attributes: str):
  for attribute in attributes:
  if attribute in self.__dict__:
  del self.__dict__[attribute]

praw/models/reddit/collections.py

@@ -36,7 +36,7 @@ def __init__(self, reddit: praw.Reddit, collection_id: str):
  super().__init__(reddit, _data=None)
  self.collection_id = collection_id
 
- def _post_fullname(self, post): # noqa: ANN001
+ def _post_fullname(self, post: str | praw.models.Submission) -> str:
  """Get a post's fullname.
 
  :param post: A fullname, a :class:`.Submission`, a permalink, or an ID.
@@ -240,7 +240,7 @@ def __init__(
  @_deprecate_args("title", "description", "display_layout")
  def create(
  self, *, description: str, display_layout: str | None = None, title: str
- ) -> praw.models.Collection:
+ ) -> Collection:
  """Create a new :class:`.Collection`.
 
  The authenticated account must have appropriate moderator permissions in the
@@ -523,7 +523,7 @@ def __setattr__(self, attribute: str, value: Any) -> None:
  value = self._reddit._objector.objectify(value)
  super().__setattr__(attribute, value)
 
- def _fetch(self): # noqa: ANN001
+ def _fetch(self):
  data = self._fetch_data()
  try:
  self._reddit._objector.check_error(data)
@@ -536,9 +536,9 @@ def _fetch(self): # noqa: ANN001
 
  other = type(self)(self._reddit, _data=data)
  self.__dict__.update(other.__dict__)
- self._fetched = True
+ super()._fetch()
 
- def _fetch_info(self): # noqa: ANN001
+ def _fetch_info(self):
  return "collection", {}, self._info_params
 
  def follow(self):