Class "Site"

Implements the StackExchange APIs client for a specific site.

Source code

Note #1: the **kwargs argument in methods is necessary for request parameters, like pagesize, order, etc.

Note #2: The Item class in the methods return type hint is a standard dict class with the ability to get values not only using the d['key'] construction, but also d.key.

Methods:

__init__

Signature:

__init__(self, name: str, access_token: str | None = None,
         app_key: str | None = None) -> None

Arguments:

• name - site's name (see Module "sites" page);

• access_token - access token;

• app_key - application key.

---

get

Signature:

get(self, query: str, **kwargs: Any) -> dict

Returns raw result of calling query to API.

---

post

Auth required

Signature:

post(self, query: str, **kwargs: Any) -> RawResponseDict

Returns raw result of POST-calling query to API.

---

add_answer

Auth required

Signature:

add_answer(self, q_id: int, body: str, **kwargs: Any) -> Item

Create a new answer on the given question.

---

add_answers_suggested_edit

Auth required

Signature:

add_answers_suggested_edit(self, a_id: int, body: str,
                           comment: str, **kwargs: Any) -> Item

Create a suggested edit on an existing answer.

---

add_comment

Auth required

Signature:

add_comment(self, post_id: int, body: str, **kwargs: Any) -> Item

Create a new comment.

---

add_question

Auth required

Signature:

add_question(self, title: str, body: str, tags: list[str], **kwargs: Any) -> Item

Create a new question.

---

add_questions_suggested_edit

Auth required

Signature:

add_answers_suggested_edit(self, a_id: int, body: str,
                           comment: str, **kwargs: Any) -> Item

Create a suggested edit on an existing question.

---

delete_answer

Auth required

Signature:

delete_answer(self, a_id: int, **kwargs: Any) -> None

Deletes an answer.

---

delete_comment

Auth required

Signature:

delete_comment(self, c_id: int, **kwargs: Any) -> None

Deletes a comment.

---

delete_question

Auth required

Signature:

delete_question(self, q_id: int, **kwargs: Any) -> None

Deletes a question.

---

edit_answer

Auth required

Signature:

edit_answer(self, a_id: int, body: str, **kwargs: Any) -> Item

Edits an existing answer.

---

edit_comment

Auth required

Signature:

edit_answer(self, a_id: int, body: str, **kwargs: Any) -> Item

Edits an existing comment.

---

edit_question

Auth required

Signature:

edit_question(self, q_id: int, title: str, body: str, tags: list[str],
              **kwargs: Any) -> Item

Edits an existing question.

---

get_answers

Signature:

get_answers(self, ids: Iterable[int] | None = None, *kwargs: Any) -> list[Item]

Returns, if ids is set, all the undeleted answers in the system, else the set of answers identified by ids.

---

get_answer

Signature:

get_answer(self, a_id: int, **kwargs: Any) -> Item | None

Returns answer identified by a_id. Returns None if requested object don't found.

---

get_answers_on_collectives

Signature:

get_answers_on_collectives(self, slugs: Iterable[str], **kwargs: Any) -> list[Item]

Returns answers belonging to collectives in slugs found on the site.

---

get_answers_on_questions

Signature:

get_answers_on_questions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the answers to a set of questions identified by ids.

---

get_articles

Signature:

get_articles(self, ids: Iterable[int] | None = None, **kwargs: Any) -> list[Item]

Returns, if ids is set, all articles on the site, else the articles identified by ids.

---

get_article

Signature:

get_article(self, a_id: int, **kwargs: Any) -> Item | None

Returns article identified by a_id. Returns None if requested object don't found.

---

get_badges

Signature:

get_badges(self, **kwargs: Any) -> list[Item]

Returns all badges in the system.

---

get_badges_recipients

Signature:

get_badges_recipients(self, ids: Iterable[int] | None = None,
                      **kwargs: Any) -> list[Item]

Returns, if ids is set, recently awarded badges in the system, constrained to a certain set of badges, else recently awarded badges in the system.

---

get_tag_based_badges

Signature:

get_tag_based_badges(self, **kwargs: Any) -> list[Item]

Returns the badges that are awarded for participation in specific tags.

---

get_non_tag_based_badges

Signature:

get_non_tag_based_badges(self, **kwargs: Any) -> list[Item]

Returns all non-tagged-based badges in alphabetical order.

---

get_collectives

Signature:

get_collectives(self, slugs: Iterable[str] | None = None,
                **kwargs: Any) -> list[Item]

Returns, if slugs is set, collectives in slugs found on the site, else, all collectives in the system.

---

get_collective

Signature:

get_collective(self, slug: str, **kwargs: Any) -> Item | None

Returns collective with specific slug. Returns None if requested object don't found.

---

get_comments

Signature:

get_comments(self, ids: Iterable[int] | None = None, **kwargs: Any) -> list[Item]

Returns, if ids is set, the comments identified by ids, else, all comments on the site.

---

get_comment

Signature:

get_comment(self, c_id: int, **kwargs: Any) -> Item | None

Returns the comment identified in c_id. Returns None if requested object don't found.

---

get_comments_on_answers

Signature:

get_comments_on_answers(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the comments on a set of answers.

---

get_comments_on_articles

Signature:

get_comments_on_articles(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the comments on a set of articles.

---

get_comments_on_posts

Signature:

get_comments_on_posts(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the comments on a set of posts.

---

get_comments_on_questions

Signature:

get_comments_on_questions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the comments on a set of questions.

---

get_info

Signature:

get_info(self) -> Item

Returns a collection of statistics about the site.

---

get_linked_in_articles

Signature:

get_linked_in_articles(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the questions that are linked to the articles identified by ids.

---

get_linked_in_questions

Signature:

get_linked_in_questions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns questions which link to those questions identified by ids.

---

get_posts

Signature:

get_posts(self, ids: Iterable[int] | None = None, **kwargs: Any) -> list[Item]

Returns, if ids is set, the posts identified by ids, else, all posts on the site.

---

get_post

Signature:

get_post(self, p_id: int, **kwargs: Any) -> Item | None

Returns the post identified in p_id. Returns None if requested object don't found.

---

get_privileges

Signature:

get_privileges(self, **kwargs: Any) -> list[Item]

Returns the earnable privileges on a site.

---

get_questions

Signature:

get_questions(self, ids: Iterable[int] | None = None, **kwargs: Any) -> list[Item]

Returns, if ids is set, all the undeleted questions in the system, else the set of questions identified by ids.

---

get_question

Signature:

get_question(self, q_id: int, **kwargs: Any) -> Item | None

Returns the question identified in q_id. Returns None if requested object don't found.

---

get_questions_on_answers

Signature:

get_questions_on_answers(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the questions on a set of answers.

---

get_bountied_questions

Signature:

get_bountied_questions(self, **kwargs: Any) -> list[Item]

Returns all the questions with active bounties in the system.

---

get_questions_on_collectives

Signature:

get_questions_on_collectives(self, slugs: Iterable[str], **kwargs: Any) -> list[Item]

Returns the questions on a set of collectives.

---

get_questions_with_no_answers

Signature:

get_questions_with_no_answers(self, **kwargs: Any) -> list[Item]

Returns questions which have received no answers.

---

get_related_to_questions

Signature:

get_related_to_questions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns questions that the site considers related to those identified by ids.

---

get_unanswered_questions

Signature:

get_unanswered_questions(self, **kwargs: Any) -> list[Item]

Returns questions the site considers to be unanswered.

---

get_unanswered_questions_on_my_tags

Auth required

Signature:

get_unanswered_questions_on_my_tags(self, **kwargs: Any) -> list[Item]

Returns questions the site considers to be unanswered, which are within a user's favorite tags.

If a user has no favorites, their frequented tags are used instead.

---

get_revisions

Signature:

get_revisions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns edit revisions identified by ids.

---

get_revisions_on_posts

Signature:

get_revisions_on_posts(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns revisions on the set of posts, identified by ids.

---

search

Signature:

search(self, **kwargs: Any) -> list[Item]

Searches a site for any questions which fit the given criteria.

Warning: one of tagged or intitle keyword arguments must be set.

---

advanced_search

Signature:

advanced_search(self, **kwargs: Any) -> list[Item]

Searches a site for any questions which fit the given criteria.

---

get_similar

Signature:

get_similar(self, title: str, **kwargs: Any) -> list[Item]

Returns questions which are similar to a hypothetical one based on a title and tag combination.

---

get_suggested_edits

Signature:

get_suggested_edits(self, ids: Iterable[int] | None = None,
                    **kwargs: Any) -> list[Item]

Returns, if ids is set, the suggested edits identified by ids, else all suggested edits on the site.

---

get_suggested_edits_on_posts

Signature:

get_suggested_edits_on_posts(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns suggested edits on the set of posts, identified by ids.

---

get_tags

Signature:

get_tags(self, **kwargs: Any) -> list[Item]

Returns all tags in the system.

---

get_top_answerers_on_tag

Signature:

get_top_answerers_on_tag(self, tag: str, period: str,
                         **kwargs: Any) -> list[Item] | NoReturn

Returns the top 20 answerers active in a given tag, of either all-time or the last 30 days.

---

get_top_askers_on_tag

Signature:

get_top_askers_on_tag(self, tag: str, period: str,
                      **kwargs: Any) -> list[Item] | NoReturn

Returns the top 20 askers active in a given tag, of either all-time or the last 30 days.

---

get_tags_wikis

Signature:

get_tags_wikis(self, tags: Iterable[str], **kwargs: Any) -> list[Item]

Returns the wikis that go with the given set of tags in tags.

---

get_tags_on_collectives

Signature:

get_tags_on_collectives(self, slugs: Iterable[str], **kwargs: Any) -> list[Item]

Returns tags belonging to collectives in slugs found on the site.

---

get_tags_info

Signature:

get_tags_info(self, tags: Iterable[str], **kwargs: Any) -> list[Item]

Returns tags' info from the tags found on the site.

---

get_tags_faq

Signature:

get_tags_faq(self, tags: Iterable[str], **kwargs: Any) -> list[Item]

Returns the frequently asked questions for the given set of tags in tags.

---

get_me

Auth required

Signature:

get_me(self, **kwargs: Any) -> Item

Returns the user associated with the passed access_token.

---

get_moderator_only_tags

Signature:

get_moderator_only_tags(self, **kwargs: Any) -> list[Item]

Returns the tags found on a site that only moderators can use.

---

get_my_full_reputation_history

Auth required

Signature:

get_my_full_reputation_history(self, **kwargs: Any) -> list[Item]

Returns user's full reputation history, including private events.

---

get_my_inbox

Auth required

Signature:

get_my_inbox(self, **kwargs: Any) -> list[Item]

Returns the user identified by access_token's inbox.

---

get_my_unread_inbox

Auth required

Signature:

get_my_unread_inbox(self, **kwargs: Any) -> list[Item]

Returns the unread items in the user identified by access_token's inbox.

---

get_related_tags

Signature:

get_related_tags(self, tags: Iterable[str], **kwargs: Any) -> list[Item]

Returns the tags that are most related to those in tags.

---

get_required_tags

Signature:

get_required_tags(self, **kwargs: Any) -> list[Item]

Returns the tags found on a site that fulfill required tag constraints on questions.

---

get_tags_synonyms

Signature:

get_tags_synonyms(self, tags: Iterable[str] | None = None,
                  **kwargs: Any) -> list[Item]

Returns, if tags is set, all the synonyms that point to the tags identified in tags, else all tag synonyms found on the site.

---

get_questions_timeline

Signature:

get_questions_timeline(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns a subset of the events that have happened to the questions identified by ids.

---

get_users

Signature:

get_users(self, ids: Iterable[int] | None = None, **kwargs: Any) -> list[Item]

Returns, if ids is set, the users identified by ids, else all users on a site.

---

get_user

Signature:

get_user(self, uid: int, **kwargs: Any) -> Item | None

Returns the user identified in uid. Returns None if requested object don't found.

---

get_users_answers

Signature:

get_users_answers(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the answers the users in ids have posted.

---

get_users_badges

Signature:

get_users_badges(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the badges the users in ids have earned.

---

get_users_on_collectives

Signature:

get_users_on_collectives(self, slugs: Iterable[str], **kwargs: Any) -> list[Item]

Returns users belonging to collectives in slugs found on the site.

---

get_users_comments

Signature:

get_users_comments(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the comments posted by users in ids.

---

get_users_comments_to

Signature:

get_users_comments_to(self, ids: Iterable[int], toid: int, **kwargs: Any) -> list[Item]

Returns the comments that the users in ids have posted in reply to the single user identified in toid.

---

get_users_favorites

Signature:

get_users_favorites(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the questions that users in ids have bookmarked.

---

get_users_mentions

Signature:

get_users_mentions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns all the comments that the users in ids were mentioned in.

---

get_users_posts

Signature:

get_users_posts(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the posts the users in ids have posted.

---

get_user_privileges

Signature:

get_user_privileges(self, uid: int, **kwargs: Any) -> list[Item]

Returns the privileges a user with ID uid has.

---

get_users_questions

Signature:

get_users_questions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the questions asked by the users in ids.

---

get_users_unaccepted_questions

Signature:

get_users_unaccepted_questions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the questions asked by the users in ids which have at least one answer, but no accepted answer.

---

get_users_unanswered_questions

Signature:

get_users_unanswered_questions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the questions asked by the users in ids which the site considers unanswered, while still having at least one answer posted.

---

get_users_bountied_questions

Signature:

get_users_bountied_questions(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the questions on which the users in {ids} have active bounties.

---

get_users_questions_with_no_answers

Signature:

get_users_questions_with_no_answers(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the questions asked by the users in ids which have no answers.

---

get_users_reputation

Signature:

get_users_reputation(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns a subset of the reputation changes for users in {ids}.

---

get_users_reputation_history

Signature:

get_users_reputation_history(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns users' public reputation history.

---

get_users_suggested_edits

Signature:

get_users_suggested_edits(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the suggested edits that the users in ids have submitted.

---

get_users_tags

Signature:

get_users_tags(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns the tags the users identified in ids have been active in.

---

get_user_top_answers_on_tags

Signature:

get_user_top_answers_on_tags(self, uid: int, tags: Iterable[str], **kwargs: Any) -> list[Item]

Returns the top 30 answers a user has posted in response to questions with the given tags.

---

get_user_top_questions_on_tags

Signature:

get_user_top_questions_on_tags(self, uid: int, tags: Iterable[str], **kwargs: Any) -> list[Item]

Returns the top 30 questions a user has asked with the given tags.

---

get_users_timeline

Signature:

get_users_timeline(self, ids: Iterable[int], **kwargs: Any) -> list[Item]

Returns a subset of the actions the users in ids have taken on the site.

---

get_user_top_answers_tags

Signature:

get_user_top_answers_tags(self, uid: int, **kwargs: Any) -> list[Item]

Returns a single user's top tags by answer score.

---

get_user_top_questions_tags

Signature:

get_user_top_questions_tags(self, uid: int, **kwargs: Any) -> list[Item]

Returns a single user's top tags by question score.

---

get_user_top_tags

Signature:

get_user_top_tags(self, uid: int, **kwargs: Any) -> list[Item]

Returns a single user's top tags by combined question and answer score.

---

get_moderators

Signature:

get_moderators(self, **kwargs: Any) -> list[Item]

Returns those users on a site who can exercise moderation powers.

---

get_elected_moderators

Signature:

get_elected_moderators(self, **kwargs: Any) -> list[Item]

Returns those users on a site who both have moderator powers, and were actually elected.

---