redditwarp.siteprocs.submission.ASYNC

class redditwarp.siteprocs.submission.ASYNC.SubmissionProcedures(client: Client)

Bases: object

fetch: Fetch

Fetch a submission.

Parameters:

idy (Union[int, str]) – Submission ID.

Return type:

Submission

Raises:

redditwarp.exceptions.NoResultException – The target was not found.

get: Get

Get a submission.

Parameters:

idy (Union[int, str]) – Submission ID.

Return type:

Optional[Submission]

create: Create

Create a submission.

bulk_fetch(ids: Iterable[_YIntOrStr]) → CallChunkChainingAsyncIterator[Submission]

Bulk fetch submissions.

Any ID not found will be ignored.

Parameters:

ids (Iterable[_YIntOrStr]) – Submission IDs.

Return type:

CallChunkChainingAsyncIterator[Submission]

async reply(idy: int | str, body: str | Mapping[str, JSON_ro]) → Comment

Comment on a submission.

Parameters:

• idy (Union[int, str]) –

• body (Union[str, Mapping[str, JSON_ro]]) – Either markdown or richtext.

Return type:

Comment

(raises):

Same as comment reply() but for submissions.

class MediaUploading(outer: SubmissionProcedures)

Bases: object

async obtain_upload_lease(*, filepath: str, mimetype: str | None = None) → SubmissionMediaUploadLease

async deposit_file(file: IO[bytes], upload_lease: SubmissionMediaUploadLease, *, timeout: float = 1000) → None

async upload(file: IO[bytes], *, filepath: str | None = None, timeout: float = 1000) → SubmissionMediaUploadLease

property media_uploading: None

async edit_text_post_body(idy: int | str, body: str | Mapping[str, JSON_ro]) → TextPost

Edit the body text of a text post.

Parameters:

• idy (Union[int, str]) –

• body (Union[str, Mapping[str, JSON_ro]]) – Either markdown or richtext.

Return type:

TextPost

Raises:

Same as comment edit_body() but for submissions.

async delete(idy: int | str) → None

Delete a submission.

If the target doesn’t exist or isn’t valid, nothing happens.

When a submission is deleted it’s text content (if a text post) will be set to “[deleted]” and the submission will be unlisted from its subreddit. Users can still otherwise view and reply to deleted to submissions if they have a direct link to it.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

redditwarp.exceptions.RedditError –

• USER_REQUIRED:

  There is no user context.

async lock(idy: int | str) → None

Lock a submission.

Nothing happens if the target is already locked.

Hint

Locking prevents a submission/comment from receiving new comments. A locked submission is unable to receive any new comments. Locking a comment only stops direct comments, but existing child comments can still receive replies.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    The target doesn’t exist or you don’t have permission to lock it.

async unlock(idy: int | str) → None

Unlock a submission.

Behaves similarly to lock().

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

Similar to lock().

async vote(idy: int | str, direction: int) → None

Cast a vote on a submission.

Parameters:

• idy (Union[int, str]) –

• direction (int) – Either: 1 (upvote), 0 unvote, -1 downvote.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 404:

    The target could not be found.

async save(idy: int | str, category: str | None = None) → None

Save a submission.

Parameters:

• idy (Union[int, str]) –

• category (Optional[str]) –

  A category/label.

  Requires Reddit Premium. Ignored if no Reddit Premium.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 404:

    The category name specified was invalid.

async unsave(idy: int | str) → None

Save a submission.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

redditwarp.exceptions.RedditError –

• USER_REQUIRED:

  There is no user context.

async hide(idy: int | str) → None

Hide a submission.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 400:

    The target was not found.

async unhide(idy: int | str) → None

Unhide a submission.

See hide().

bulk_hide(ids: Iterable[_YIntOrStr]) → CallChunkCallingAsyncIterator[None]

Bulk hide submissions.

If any of the list of submission IDs don’t exist then the endpoint will return a HTTP 400 status error and none of the submissions will be hidden. This can be annoying since if the list is long it can be hard to tell which ID is the culprit.

Parameters:

ids (Iterable[_YIntOrStr]) –

Return type:

CallChunkCallingAsyncIterator[None]

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 400:

    If any of the IDs were not found.

bulk_unhide(ids: Iterable[_YIntOrStr]) → CallChunkCallingAsyncIterator[None]

Bulk hide submissions.

See bulk_hide().

async mark_nsfw(idy: int | str) → None

Mark a submission as NSFW.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    You do not have permission to mark the target.

async unmark_nsfw(idy: int | str) → None

Unmark a submission as NSFW.

See mark_nsfw().

async mark_spoiler(idy: int | str) → None

Mark a submission as spoiler.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    You do not have permission to mark the target.

async unmark_spoiler(idy: int | str) → None

Unmark a submission as spoiler.

See mark_spoiler().

async distinguish(idy: int | str) → Submission

Distinguish a submission.

Hint

Distinguishing decoratates the author’s name by giving it a different color and putting a sigil beside it.

Parameters:

idy (Union[int, str]) –

Returns:

The target submission.

Return type:

Submission

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    You do not have permission to distinguish the target.

  • 404:

    The target could not be found.

async undistinguish(idy: int | str) → Submission

Undistinguish a submission.

Parameters:

idy (Union[int, str]) –

Returns:

The target submission.

Return type:

Submission

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    You do not have permission.

  • 404:

    The target could not be found.

async sticky(idy: int | str, slot: int | None = None) → None

Set a submission as sticky in its subreddit.

Hint

Stickied posts are shown at the top of the subreddit in the default ‘Hot’ listing.

In a subreddit, there can be at most 2 sticked posts at a time.

When stickying the slot parameter indicates which of the two positions the new post should occupy. If there is a sticked post in the slot specified by slot, it will be replaced. Otherwise the post will be placed in the bottom-most slot. If the number specified by slot is outside the valid range it will be clamped within range.

Stickying a post that is already stickied causes a 409 (Conflict) HTTP error. Unstickying a post that isn’t stickied does nothing.

Note

You cannot reorder sticky posts directly. You must unsticky and re-sticky them.

Parameters:

• idy (Union[int, str]) –

• slot (Optional[int]) –

  Which sticky slot to use.

  If not specified, the bottom-most slot will be used if available. If the sticky list is at maximum length, the bottom-most slot will be replaced with the new post.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    You do not have permission to sticky that post.

  • 409:

    The post is already stickied.

async unsticky(idy: int | str) → None

Unsticky a submission.

See sticky().

Unstickying a post that isn’t stickied does nothing.

async pin_to_profile(idy: int | str, slot: int | None = None) → None

Pin a post you created to your user profile.

Hint

Pinned posts show up at the start of the ‘Overview’, or ‘Submitted’ (old UI) / ‘POSTS’ (redesign UI) user profile listings.

A user can have at most 4 pinned posts at a time.

The rules for the num parameter are the same as in subreddit stickying. See sticky(). However, there are differences when the slot number is unspecified. See the slot parameter description.

Note

This feature uses the same endpoint as sticky() but there are stark differences in insertion behaviour when slot is not specified.

To summarise:

• When subreddit stickying: the post will be placed at the bottom of the list. If the list is full then the bottom-most post will be replaced.

• When user profile pinning: the post will be placed at the top of the list. If the list is full then the bottom-most post will be evicted.

Pinning a post that is already pinned causes a 409 (Conflict) HTTP error. Unpinning a post that isn’t pinned does nothing.

Note

You cannot reorder pinned posts directly. You must unpin and re-pin them.

Parameters:

• idy (Union[int, str]) –

• slot (Optional[int]) –

  Which pin slot to use.

  If slot is not specified, the new post is inserted at the top of the list. If the list is at maximum length, the least recently pinned post will be evicted. It acts like a queue.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    You do not have permission to pin that post.

  • 409:

    The post is already pinned.

async unpin_from_profile(idy: int | str) → None

Unpin a submission from your user profile.

See pin_to_profile().

Unpinning a post that isn’t pinned does nothing.

async set_contest_mode(idy: int | str, state: bool) → None

Set or unset ‘contest mode’ for a submission’s comments.

Hint

In contest mode, vote counts are hidden and comments are displayed in a random order.

Parameters:

• idy (Union[int, str]) –

• state (bool) –

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    • The specified ID was not found.

    • You do not have permission to modify the target.

async set_suggested_sort(idy: int | str, sort: str) → None

Set or unset the suggested sort for a submission’s comments.

Hint

When set, users will see comments in the suggested sort order by default. They can still manually change back to their preferred sort if they choose.

Parameters:

• idy (Union[int, str]) –

• sort (str) –

  Either: confidence, top, new, controversial, old, random, qa, live, blank.

  If not specified or an unknown value, the suggested sort will be unset.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    • The specified ID was not found.

    • You do not have permission to modify the target.

async enable_reply_notifications(idy: int | str) → None

Enable inbox reply notifications for a submission.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

redditwarp.exceptions.RedditError –

• USER_REQUIRED:

  There is no user context.

async disable_reply_notifications(idy: int | str) → None

Disable inbox reply notifications for a submission.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

redditwarp.exceptions.RedditError –

• USER_REQUIRED:

  There is no user context.

async set_event_time(idy: int | str, event_start: str | None = None, event_end: str | None = None, event_tz: str | None = None) → None

Add or modify event times on a submission.

Specify only event_start to change only the starting date. The same cannot be done for event_end, a 500 HTTP error will occur.

If both event_start and event_end are specified then the event_start must be before event_end in time, otherwise a MIN_EVENT_TIME API error is returned. It is possible however to make a second request specifying only event_start to modify the start date so that event_start is after event_end. If this happens then the time difference can be longer than 7 days.

Parameters:

• idy (Union[int, str]) –

• event_start (Optional[str]) – A datetime ISO 8601 string. E.g. 2018-09-11T12:00:00.

• event_end (Optional[str]) – A datetime ISO 8601 string.

• event_tz (Optional[str]) –

  A timezone. E.g., America/Los_Angeles.

  If not specified, effectively defaults to UTC.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

  • BAD_TIME:

    • The value specified for event_start or event_end is in a bad format.

    • The date string specified for event_start or event_end is in the past.

    Note that this error will always indicate event_start is wrong even if it’s event_end that needs fixing.

  • MIN_EVENT_TIME:

    The value specified for event_tz is invalid.

  • MAX_EVENT_TIME:

    The event can’t be longer than 7 days.

  • INVALID_TIMEZONE:

    The value specified for event_tz is invalid.

• redditwarp.http.exceptions.StatusCodeException –

  • 500:

    The event_start parameter was not specified.

async follow_event(idy: int | str) → None

Follow a post event.

Hint

Followers receive a push notification when the event starts.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    The target submission is not an event.

  • 404:

    The target submission does not exist.

async unfollow_event(idy: int | str) → None

Unfollow a post event.

See follow_event().

async approve(idy: int | str) → None

Approve a submission.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    You do not have permission.

    • The target specified does not exist.

    • The target belongs to a subreddit you do not have permission over.

async remove(idy: int | str) → None

Remove a submission.

This is a moderator action.

Parameters:

idy (Union[int, str]) –

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    You do not have permission.

    • The target specified does not exist.

    • The target belongs to a subreddit you do not have permission over.

async remove_spam(idy: int | str) → None

Remove as spam.

See remove().

async ignore_reports(idy: int | str) → None

Ignore reports on a submission.

Hint

If you ignore reports, you won’t receive notifications and the ignored thing will be absent from moderation listings.

Nothing happens if the target is already ignored.

Parameters:

idy (Union[int, str]) – Submission ID.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    • The target specified does not exist.

    • The target belongs to a subreddit you do not have permission over.

async unignore_reports(idy: int | str) → None

Unignore reports on a submission.

Nothing happens if the target is already unignored.

Parameters:

idy (Union[int, str]) – Submission ID.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    • The target specified does not exist.

    • The target belongs to a subreddit you do not have permission over.

async snooze_reports(idy: int | str, reason: str) → None

Ignore a custom report reason in a subreddit for 7 days.

Parameters:

• idy (Union[int, str]) – Submission ID.

• reason (str) – The custom report reason to snooze.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    • The target specified does not exist.

    • The target belongs to a subreddit you do not have permission over.

async unsnooze_reports(idy: int | str, reason: str) → None

Unsnooze a custom report.

See snooze_reports().

async apply_removal_reason(idy: int | str, reason_id: str | None = None, note: str | None = None) → None

Set a removal reason on a removed submission.

If the target is not a removed submission, nothing happens.

Parameters:

• idy (Union[int, str]) – Submission ID.

• reason_id (Optional[int]) – A removal reason ID.

• note (Optional[str]) – A note.

Return type:

None

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

  • JSON_MISSING_KEY:

    Empty strings or null values were specified for both reason_id and note at the same time.

  • NO_THING_ID:

    The given target ID is not valid.

  • INVALID_ID:

    The reason ID is invalid.

  • MUST_BE_PRESENT:

    The subreddit specified does not exist.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    • The target specified does not belong to a subreddit you moderate.

async send_removal_comment(idy: int | str, title: str, message: str, *, exposed: bool = False, locked: bool = False) → Comment

Send a removal comment.

Sends a removal reason comment to a user for a removed submission of theirs.

This action can be performed multiple times. (The UI does not normally let you do this.)

Unlike apply_removal_reason(), the target you specify must be a removed item otherwise an INVALID_ID API error is produced.

Parameters:

• idy (Union[int, str]) – ID of a removed submission.

• title (str) –

  A title.

  This is ultimately unused for removal comments, but a non-empty string must be specified or you’ll get a NO_TEXT API error.

  The UI sends the title of the selected removal reason.

• message (str) –

  A message for the comment body.

  Can be an empty string. This is interesting because you can’t normally create comments with empty bodies.

• exposed (bool) –

  If false (default), the comment will be created by a special moderator named u/{subreddit}_ModTeam.

  If true, the comment is created by the current user.

• locked (bool) – Lock the newly created comment.

Returns:

The newly created comment.

Return type:

Comment

Raises:

• redditwarp.exceptions.RedditError –

  • USER_REQUIRED:

    There is no user context.

  • NO_TEXT:

    The value for the title parameter was empty.

  • INVALID_ID:

    • The target specified doesn’t exist or is invalid.

    • The target specified is not a removed item.

  • MUST_BE_PRESENT:

    The subreddit specified does not exist.

• redditwarp.http.exceptions.StatusCodeException –

  • 403:

    • The target specified does not belong to a subreddit you moderate.

async send_removal_message(idy: int | str, title: str, message: str, *, exposed: bool = False) → None

Send a removal message.

Behaves similarly to send_removal_comment().

Parameters:

• idy (Union[int, str]) – ID of a removed comment.

• title (str) –

  A title.

  A non-empty string must be specified or you’ll get a NO_TEXT API error.

  The UI sends the title of the selected removal reason.

• message (str) –

  A message for the comment body.

  Can be an empty string.

• exposed (bool) –

  If false (default), the comment will be send on behalf of the subreddit.

  If true, the comment is sent by the current user.

Returns:

None

(raises):

See send_removal_comment().

search(sr: str, query: str, amount: int | None = None, *, sort: str = 'relevance', time: str = 'all') → ImpartedPaginatorChainingAsyncIterator[SubmissionSearchAsyncPaginator, Submission]

Search for submissions.

Parameters:

• sr (str) –

  A subreddit name.

  Use an empty string to search all of Reddit.

• query (str) – A search query.

• amount (Optional[int]) – The number of items to retrieve.

• sort (str) –

  Either: relevance, hot, top, new, or comments.

  Default: relevance.

• time (str) –

  Either: all, hour, day, week, month, year.

  Default: all.

Return type:

ImpartedPaginatorChainingAsyncIterator[SubmissionSearchAsyncPaginator, Submission]

duplicates(target: int | str, amount: int | None = None, *, sort: str = 'num_comments') → ImpartedPaginatorChainingAsyncIterator[SubmissionDuplicatesAsyncPaginator, Submission]

Get crossposts for a submission.

Parameters:

• target (Union[int, str]) – Submission ID.

• amount (Optional[int]) – The number of items to retrieve.

• sort (str) –

  Either num_comments or new.

  Default: num_comments.

Return type:

ImpartedPaginatorChainingAsyncIterator[SubmissionDuplicatesAsyncPaginator, Submission]

Raises:

redditwarp.http.exceptions.StatusCodeException –

• 403:

  Fetching some submissions resulted in a 403.

• 404:

  The target submission could not be found.