Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# RedditModNotes

class praw.models.RedditModNotes(reddit: praw.Reddit)

  Provides methods to interact with moderator notes at a global level.

  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:

      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}")

  __call__(*, all_notes: bool = False, pairs: Optional[List[Tuple[Union[praw.models.Subreddit, str], Union[Redditor, str]]]] = None, redditors: Optional[List[Union[Redditor, str]]] = None, subreddits: Optional[List[Union[str, praw.models.Subreddit]]] = None, things: Optional[List[Union[Comment, Submission]]] = None, **generator_kwargs: Any) → Generator[praw.models.ModNote, None, None]

    Get note(s) for each subreddit/user pair, or `None` if they don’t have any.

    Parameters:

      - all_notes –

        Whether to return all notes or only the latest note for each subreddit/redditor pair (default: `False`).

        Note

        Setting this to `True` will result in a request for each unique subreddit/redditor pair. If `subreddits` and `redditors` are provided, this will make a request equivalent to number of redditors multiplied by the number of subreddits.

      - pairs –

        A list of subreddit/redditor tuples.

        Note

        Required if `subreddits`, `redditors`, nor `things` are provided.

      - redditors –

        A list of redditors to return notes for. This parameter is used in tandem with `subreddits` to get notes from multiple subreddits for each of the provided redditors.

        Note

        Required if `items` or `things` is not provided or if `subreddits` is provided.

      - subreddits –

        A list of subreddits to return notes for. This parameter is used in tandem with `redditors` to get notes for multiple redditors from each of the provided subreddits.

        Note

        Required if `items` or `things` is not provided or if `redditors` is provided.

      - things – A list of comments and/or submissions to return notes for.

      - generator_kwargs – Additional keyword arguments passed to the generator. This parameter is ignored when `all_notes` is `False`.

    Returns:

      A generator that yields the most recent `ModNote` (or `None` if the user doesn’t have any notes) per entry in their relative order. If `all_notes` is `True`, this will yield all notes for each entry.

    Note

    This method will merge the subreddits and redditors provided from `pairs`, `redditors`, `subreddits`, and `things`.

    Note

    This method accepts `Redditor` instances or redditor names and `Subreddit` instances or subreddit names where applicable.

    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:

        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}")

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

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

        for note in reddit.notes(
            redditors=["spez", redditor],
            subreddits=["announcements", subreddit, "test"],
            all_notes=True,
        ):
            print(f"{note.label}: {note.note}")

    For example, the latest note for the authors of the last 5 comments and submissions from r/test can be iterated through like so:

        submissions = list(reddit.subreddit("test").new(limit=5))
        comments = list(reddit.subreddit("test").comments(limit=5))

        for note in reddit.notes(things=submissions + comments):
            print(f"{note.label}: {note.note}")

    Note

    Setting `all_notes` to `True` will make a request for each redditor and subreddit combination. The previous example will make 6 requests.

  __init__(reddit: praw.Reddit)

    Initialize a `BaseModNotes` instance.

    Parameters:

      reddit – An instance of `Reddit`.

  create(*, label: Optional[str] = None, note: str, redditor: Optional[Union[Redditor, str]] = None, subreddit: Optional[Union[praw.models.Subreddit, str]] = None, thing: Optional[Union[Comment, Submission, str]] = None, **other_settings: Any) → praw.models.ModNote

    Create a `ModNote` for a redditor in the specified subreddit.

    Parameters:

      - label – The label for the note. As of this writing, this can be one of the following: `"ABUSE_WARNING"`, `"BAN"`, `"BOT_BAN"`, `"HELPFUL_USER"`, `"PERMA_BAN"`, `"SOLID_CONTRIBUTOR"`, `"SPAM_WARNING"`, `"SPAM_WATCH"`, or `None` (default: `None`).

      - note – The content of the note. As of this writing, this is limited to 250 characters.

      - redditor –

        The redditor to create the note for (default: `None`).

        Note

        This parameter is required if `thing` is not provided or this is not called from a `Redditor` instance (e.g., `reddit.redditor.notes`).

      - subreddit –

        The subreddit associated with the note (default: `None`).

        Note

        This parameter is required if `thing` is not provided or this is not called from a `Subreddit` instance (e.g., `reddit.subreddit.mod`).

      - thing – Either the fullname of a comment/submission, a `Comment`, or a `Submission` to associate with the note.

      - other_settings – Additional keyword arguments can be provided to handle new parameters as Reddit introduces them.

    Returns:

      The new `ModNote` object.

    For example, to create a note for u/spez in r/test:

        reddit.subreddit("test").mod.notes.create(
            label="HELPFUL_USER", note="Test note", redditor="spez"
        )
        # or
        reddit.redditor("spez").mod.notes.create(
            label="HELPFUL_USER", note="Test note", subreddit="test"
        )
        # or
        reddit.notes.create(
            label="HELPFUL_USER", note="Test note", redditor="spez", subreddit="test"
        )

  delete(*, delete_all: bool = False, note_id: Optional[str] = None, redditor: Optional[Union[Redditor, str]] = None, subreddit: Optional[Union[praw.models.Subreddit, str]] = None)

    Delete note(s) for a redditor.

    Parameters:

      - delete_all –

        When `True`, delete all notes for the specified redditor in the specified subreddit (default: `False`).

        Note

        This will make a request for each note.

      - note_id – The ID of the note to delete. This parameter is ignored if `delete_all` is `True`.

      - redditor –

        The redditor to delete the note(s) for (default: `None`). Can be a `Redditor` instance or a redditor name.

        Note

        This parameter is required if this method is not called from a `Redditor` instance (e.g., `redditor.notes`).

      - subreddit –

        The subreddit to delete the note(s) from (default: `None`). Can be a `Subreddit` instance or a subreddit name.

        Note

        This parameter is required if this method is not called from a `Subreddit` instance (e.g., `reddit.subreddit.mod`).

    For example, to delete a note with the ID `"ModNote_d324b280-5ecc-435d-8159-3e259e84e339"`, try:

        reddit.subreddit("test").mod.notes.delete(
            note_id="ModNote_d324b280-5ecc-435d-8159-3e259e84e339", redditor="spez"
        )
        # or
        reddit.redditor("spez").notes.delete(
            note_id="ModNote_d324b280-5ecc-435d-8159-3e259e84e339", subreddit="test"
        )
        # or
        reddit.notes.delete(
            note_id="ModNote_d324b280-5ecc-435d-8159-3e259e84e339",
            subreddit="test",
            redditor="spez",
        )

    To delete all notes for u/spez, try:

        reddit.subreddit("test").mod.notes.delete(delete_all=True, redditor="spez")
        # or
        reddit.redditor("spez").notes.delete(delete_all=True, subreddit="test")
        # or
        reddit.notes.delete(delete_all=True, subreddit="test", redditor="spez")

  things(*things: Union[Comment, Submission], all_notes: Optional[bool] = None, **generator_kwargs: Any) → Generator[praw.models.ModNote, None, None]

    Return notes associated with the author of a `Comment` or `Submission`.

    Parameters:

      - things – One or more things to return notes on. Must be a `Comment` or `Submission`.

      - all_notes –

        Whether to return all notes, or only the latest (default: `True` if only one thing is provided otherwise `False`).

        Note

        Setting this to `True` will result in a request for each thing.

    Returns:

      A generator that yields the most recent `ModNote` (or `None` if the user doesn’t have any notes) per entry in their relative order. If `all_notes` is `True`, this will yield all notes for each entry.

    For example, to get the latest note for the authors of the top 25 submissions in r/test:

        submissions = reddit.subreddit("test").top(limit=25)
        for note in reddit.notes.things(*submissions):
            print(f"{note.label}: {note.note}")

    For example, to get the latest note for the authors of the last 25 comments in r/test:

        comments = reddit.subreddit("test").comments(limit=25)
        for note in reddit.notes.things(*comments):
            print(f"{note.label}: {note.note}")