diff --git a/docs/13_admin.rst b/docs/13_admin.rst index 5191711..dc1131a 100644 --- a/docs/13_admin.rst +++ b/docs/13_admin.rst @@ -73,4 +73,14 @@ Email domain blocks .. automethod:: Mastodon.admin_create_email_domain_block .. automethod:: Mastodon.admin_delete_email_domain_block - +Trend management +---------------- +.. automethod:: Mastodon.admin_trending_tags +.. automethod:: Mastodon.admin_trending_statuses +.. automethod:: Mastodon.admin_trending_links +.. automethod:: Mastodon.admin_approve_trending_link +.. automethod:: Mastodon.admin_reject_trending_link +.. automethod:: Mastodon.admin_approve_trending_status +.. automethod:: Mastodon.admin_reject_trending_status +.. automethod:: Mastodon.admin_approve_trending_tag +.. automethod:: Mastodon.admin_reject_trending_tag diff --git a/mastodon/admin.py b/mastodon/admin.py index cead76a..8af7e8c 100644 --- a/mastodon/admin.py +++ b/mastodon/admin.py @@ -699,3 +699,74 @@ class Mastodon(Internals): """ id = self.__unpack_id(id) self.__api_request('DELETE', f'/api/v1/admin/email_domain_blocks/{id}') + + @api_version("3.5.0", "3.5.0") + def admin_trending_links(self) -> NonPaginatableList[PreviewCard]: + """ + Fetch trending links, including unapproved and unreviewed ones. Requires scope `admin:read`. + """ + return self.__api_request('GET', '/api/v1/admin/trends/links') + + @api_version("3.5.0", "3.5.0") + def admin_trending_statuses(self) -> NonPaginatableList[Status]: + """ + Fetch trending statuses, including unapproved and unreviewed ones. Requires scope `admin:read`. + """ + return self.__api_request('GET', '/api/v1/admin/trends/statuses') + + @api_version("3.5.0", "4.1.0") + def admin_trending_tags(self) -> NonPaginatableList[Tag]: + """ + Fetch trending tags, including unapproved and unreviewed ones. Requires scope `admin:read`. + + Returns a regular Tag without admin attributes between Mastodon.py v4.0.0 and v4.1.0 due to a bug. + """ + return self.__api_request('GET', '/api/v1/admin/trends/tags') + + @api_version("4.2.0", "4.2.0") + def admin_approve_trending_link(self, id: Union[PreviewCard, IdType]) -> PreviewCard: + """ + Approve a trending link. Requires scope `admin:write`. + """ + id = self.__unpack_id(id) + return self.__api_request('POST', f'/api/v1/admin/trends/links/{id}/approve') + + @api_version("4.2.0", "4.2.0") + def admin_reject_trending_link(self, id: Union[PreviewCard, IdType]) -> PreviewCard: + """ + Reject a trending link. Requires scope `admin:write`. + """ + id = self.__unpack_id(id) + return self.__api_request('POST', f'/api/v1/admin/trends/links/{id}/reject') + + @api_version("4.2.0", "4.2.0") + def admin_approve_trending_status(self, id: Union[Status, IdType]) -> Status: + """ + Approve a trending status. Requires scope `admin:write`. + """ + id = self.__unpack_id(id) + return self.__api_request('POST', f'/api/v1/admin/trends/statuses/{id}/approve') + + @api_version("4.2.0", "4.2.0") + def admin_reject_trending_status(self, id: Union[Status, IdType]) -> Status: + """ + Reject a trending status. Requires scope `admin:write`. + """ + id = self.__unpack_id(id) + return self.__api_request('POST', f'/api/v1/admin/trends/statuses/{id}/reject') + + @api_version("4.2.0", "4.2.0") + def admin_approve_trending_tag(self, id: Union[Tag, IdType]) -> Tag: + """ + Approve a trending tag. Requires scope `admin:write`. + """ + id = self.__unpack_id(id) + return self.__api_request('POST', f'/api/v1/admin/trends/tags/{id}/approve') + + @api_version("4.2.0", "4.2.0") + def admin_reject_trending_tag(self, id: Union[Tag, IdType]) -> Tag: + """ + Reject a trending tag. Requires scope `admin:write`. + """ + id = self.__unpack_id(id) + return self.__api_request('POST', f'/api/v1/admin/trends/tags/{id}/reject') diff --git a/mastodon/return_types.py b/mastodon/return_types.py index ca85ea8..9b3d242 100644 --- a/mastodon/return_types.py +++ b/mastodon/return_types.py @@ -2448,8 +2448,56 @@ class PreviewCard(AttribAccessDict): * 4.2.0: added """ + history: "Optional[NonPaginatableList[TrendingLinkHistory]]" + """ + Only present for trending links. A list of TrendingLinkHistory objects. (optional) + + Version history: + * 3.5.0: added + """ + _version = "4.3.0" +class TrendingLinkHistory(AttribAccessDict): + """ + A history entry for a trending link. + + Example: + + .. code-block:: python + + # Returns a TrendingLinkHistory object + mastodon.trending_links()[0].history[0] + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/PreviewCard/#trends-link + """ + + day: "datetime" + """ + The day this history entry is for, as a `datetime` object. + + Version history: + * 3.5.0: added + """ + + uses: "int" + """ + The number of times this link was used on this day. + + Version history: + * 3.5.0: added + """ + + accounts: "int" + """ + The number of accounts that used this link on this day. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + class PreviewCardAuthor(AttribAccessDict): """ A preview card attached to a status, e.g. for an embedded video or link. @@ -4832,7 +4880,7 @@ class AdminAccount(AttribAccessDict): Version history: * 2.9.1: added - * 3.5.0: return type changed from String to [AdminIp]({{< relref "entities/Admin_Ip" >}}) due to a bug + * 3.5.0: return type changed from String to AdminIP * 4.0.0: bug fixed, return type is now a String again """ @@ -5604,7 +5652,7 @@ class ExtendedDescription(AttribAccessDict): .. code-block:: python # Returns a ExtendedDescription object - TODO_TO_BE_IMPLEMENTED + mastodon.instance_extended_description() See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/ExtendedDescription """ @@ -5767,7 +5815,7 @@ class StatusSource(AttribAccessDict): .. code-block:: python # Returns a StatusSource object - TODO_TO_BE_IMPLEMENTED + mastodon.status_source() See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/StatusSource """ @@ -5851,7 +5899,7 @@ class Translation(AttribAccessDict): .. code-block:: python # Returns a Translation object - TODO_TO_BE_IMPLEMENTED + mastodon.status_translate(, 'de') See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Translation """ @@ -6421,7 +6469,7 @@ class AccountWarning(AttribAccessDict): .. code-block:: python # Returns a AccountWarning object - # There isn't really a good way to get this manually - you get it if a moderation takes action. + # There isn't really a good way to get this manually - you get it if a moderator takes action. See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/AccountWarning """ @@ -6517,7 +6565,7 @@ class Appeal(AttribAccessDict): .. code-block:: python # Returns a Appeal object - TODO_TO_BE_IMPLEMENTED + # There isn't really a good way to get this manually - you get it if a moderator takes action. See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Appeal/ """ @@ -6573,6 +6621,7 @@ ENTITY_NAME_MAP = { "MediaAttachmentFocusPoint": MediaAttachmentFocusPoint, "MediaAttachmentColors": MediaAttachmentColors, "PreviewCard": PreviewCard, + "TrendingLinkHistory": TrendingLinkHistory, "PreviewCardAuthor": PreviewCardAuthor, "Search": Search, "SearchV2": SearchV2, @@ -6683,6 +6732,7 @@ __all__ = [ "MediaAttachmentFocusPoint", "MediaAttachmentColors", "PreviewCard", + "TrendingLinkHistory", "PreviewCardAuthor", "Search", "SearchV2", diff --git a/mastodon/types_base.py b/mastodon/types_base.py index d1b1094..014dd89 100644 --- a/mastodon/types_base.py +++ b/mastodon/types_base.py @@ -163,7 +163,7 @@ if sys.version_info < (3, 9): DomainBlock, ExtendedDescription, FilterKeyword, FilterStatus, IdentityProof, StatusSource, \ Suggestion, Translation, AccountCreationError, AccountCreationErrorDetails, AccountCreationErrorDetailsField, NotificationPolicy, \ NotificationPolicySummary, RelationshipSeveranceEvent, GroupedNotificationsResults, PartialAccountWithAvatar, NotificationGroup, AccountWarning, \ - UnreadNotificationsCount, Appeal + UnreadNotificationsCount, Appeal, TrendingLinkHistory if isinstance(t, ForwardRef): try: t = t._evaluate(globals(), locals(), frozenset()) diff --git a/srcgen/return_types.json b/srcgen/return_types.json index 53d7f58..f24985a 100644 --- a/srcgen/return_types.json +++ b/srcgen/return_types.json @@ -2043,6 +2043,62 @@ "added" ] ] + }, + "id": { + "description": "The ID of the Tag in the database. Only present for data returned from admin endpoints.", + "field_type": "str", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "trendable": { + "description": "Whether the hashtag has been approved to trend. Only present for data returned from admin endpoints.", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "usable": { + "description": "Whether the hashtag has not been disabled from auto-linking. Only present for data returned from admin endpoints.", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "requires_review": { + "description": "Whether the hashtag has not been reviewed yet to approve or deny its trending. Only present for data returned from admin endpoints.", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null } } }, @@ -3830,6 +3886,74 @@ ] ], "enum": null + }, + "history": { + "description": "Only present for trending links. A list of TrendingLinkHistory objects.", + "field_type": "NonPaginatableList", + "field_subtype": "TrendingLinkHistory", + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + } + } + }, + { + "name": "Trending link history", + "python_name": "TrendingLinkHistory", + "func_call": "mastodon.trending_links()[0].history[0]", + "func_call_real": "mastodon.trending_links()[0].history[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/PreviewCard/#trends-link", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A history entry for a trending link.", + "fields": { + "day": { + "description": "The day this history entry is for, as a `datetime` object.", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "uses": { + "description": "The number of times this link was used on this day.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "accounts": { + "description": "The number of accounts that used this link on this day.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null } } }, @@ -7269,7 +7393,7 @@ ], [ "3.5.0", - "return type changed from String to [AdminIp]({{< relref \"entities/Admin_Ip\" >}}) due to a bug" + "return type changed from String to AdminIP" ], [ "4.0.0", diff --git a/tests/test_admin.py b/tests/test_admin.py index 5fcf6dc..ce10a81 100644 --- a/tests/test_admin.py +++ b/tests/test_admin.py @@ -295,3 +295,9 @@ def test_admin_email_domain_blocks(api2): all_blocks_after_delete = api2.admin_email_domain_blocks() assert not any(block.id == created_block.id for block in all_blocks_after_delete) + +@pytest.mark.vcr() +def test_admin_trends(api2): + assert isinstance(api2.admin_trending_tags(), list) + assert isinstance(api2.admin_trending_statuses(), list) + assert isinstance(api2.admin_trending_links(), list)