From 43c7d7ceb8da17954aedee96bd6fb5444a4a728c Mon Sep 17 00:00:00 2001 From: halcy Date: Tue, 29 Nov 2022 00:50:02 +0200 Subject: Restructure the docs, a lot --- docs/01_general.rst | 1 + docs/04_auth.rst | 19 +++-- docs/05_statuses.rst | 84 ++++++++++++++++++ docs/06_accounts.rst | 114 +++++++++++++++++++++++++ docs/07_timelines.rst | 20 +++++ docs/08_instances.rst | 58 +++++++++++++ docs/09_notifications.rst | 61 +++++++++++++ docs/10_streaming.rst | 75 ++++++++++++++++ docs/11_misc.rst | 36 ++++++++ docs/12_utilities.rst | 22 +++++ docs/13_admin.rst | 60 +++++++++++++ docs/14_contributing.rst | 33 ++++++++ docs/15_everything.rst | 188 +++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 23 ++++- docs/update_everything_page.sh | 8 ++ tests/README.markdown | 9 +- 16 files changed, 797 insertions(+), 14 deletions(-) create mode 100644 docs/05_statuses.rst create mode 100644 docs/06_accounts.rst create mode 100644 docs/07_timelines.rst create mode 100644 docs/08_instances.rst create mode 100644 docs/09_notifications.rst create mode 100644 docs/10_streaming.rst create mode 100644 docs/11_misc.rst create mode 100644 docs/12_utilities.rst create mode 100644 docs/13_admin.rst create mode 100644 docs/14_contributing.rst create mode 100644 docs/15_everything.rst create mode 100755 docs/update_everything_page.sh diff --git a/docs/01_general.rst b/docs/01_general.rst index e0c3719..556cd63 100644 --- a/docs/01_general.rst +++ b/docs/01_general.rst @@ -95,6 +95,7 @@ manually (or persist objects, not just dicts). There are convenience functions available for fetching the previous and next page of a paginated request as well as for fetching all pages starting from a first page. +For details, see `fetch_next()`_, `fetch_previous()`_. and `fetch_remaining()`_. IDs and unpacking ----------------- diff --git a/docs/04_auth.rst b/docs/04_auth.rst index 1a05603..845ffde 100644 --- a/docs/04_auth.rst +++ b/docs/04_auth.rst @@ -1,5 +1,5 @@ -App registration and user authentication -======================================== +App registration, authentication and preferences +================================================ .. py:module:: mastodon .. py:class: Mastodon @@ -20,12 +20,13 @@ once, and then persist your client id and secret. A convenient method for this is provided by the functions dealing with registering the app, logging in and the Mastodon classes constructor. -To talk to an instance different from the flagship instance, specify -the api_base_url (usually, just the URL of the instance, i.e. -https://mastodon.social/ for the flagship instance). If no protocol -is specified, Mastodon.py defaults to https. - +App registration and information +-------------------------------- .. automethod:: Mastodon.create_app +.. automethod:: Mastodon.app_verify_credentials + +Authentication +-------------- .. automethod:: Mastodon.__init__ .. _log_in(): .. automethod:: Mastodon.log_in @@ -36,3 +37,7 @@ is specified, Mastodon.py defaults to https. .. automethod:: Mastodon.revoke_access_token .. automethod:: Mastodon.create_account .. automethod:: Mastodon.email_resend_confirmation + +User preferences +---------------- +.. automethod:: Mastodon.preferences \ No newline at end of file diff --git a/docs/05_statuses.rst b/docs/05_statuses.rst new file mode 100644 index 0000000..5615a9f --- /dev/null +++ b/docs/05_statuses.rst @@ -0,0 +1,84 @@ +Statuses, media and polls +========================= +.. py:module:: mastodon +.. py:class: Mastodon + +Statuses +-------- +These functions allow you to get information about single statuses and to post and update them, as well as to favourite, bookmark, mute reblog ("boost") and to undo all of those. +For status pinning, check out TODO and TODO on the accounts page. + +Reading +~~~~~~~ +.. automethod:: Mastodon.status +.. automethod:: Mastodon.status_context +.. automethod:: Mastodon.status_reblogged_by +.. automethod:: Mastodon.status_favourited_by +.. automethod:: Mastodon.status_card +.. automethod:: Mastodon.status_history +.. automethod:: Mastodon.status_source + +.. automethod:: Mastodon.favourites + +.. automethod:: Mastodon.bookmarks + +Writing +~~~~~~~ +.. _status_post(): +.. automethod:: Mastodon.status_post +.. automethod:: Mastodon.status_reply +.. automethod:: Mastodon.toot +.. _make_poll(): +.. automethod:: Mastodon.make_poll + +.. automethod:: Mastodon.status_reblog +.. automethod:: Mastodon.status_unreblog + +.. automethod:: Mastodon.status_favourite +.. automethod:: Mastodon.status_unfavourite + +.. automethod:: Mastodon.status_mute +.. automethod:: Mastodon.status_unmute + +.. automethod:: Mastodon.status_bookmark +.. automethod:: Mastodon.status_unbookmark + +.. automethod:: Mastodon.status_delete +.. _status_update(): +.. automethod:: Mastodon.status_update + +Scheduled statuses +------------------ +These functions allow you to get information about scheduled statuses and to update scheduled statuses that already exist. +To create new scheduled statuses, use `status_post()`_ with the `scheduled_at` parameter. + +Reading +~~~~~~~ +.. automethod:: Mastodon.scheduled_statuses +.. automethod:: Mastodon.scheduled_status + +Writing +~~~~~~~ +.. automethod:: Mastodon.scheduled_status_update +.. automethod:: Mastodon.scheduled_status_delete + +Media +----- +This function allows you to upload media to Mastodon and update media uploads. +The returned media IDs (Up to 4 at the same time on a default configuration Mastodon instance) can then be used with post_status to attach media to statuses. + +.. _media_post(): +.. automethod:: Mastodon.media_post +.. automethod:: Mastodon.media_update + +Polls +----- +This function allows you to get and refresh information about polls as well as to vote in polls + +Reading +~~~~~~~ +.. automethod:: Mastodon.poll + +Writing +~~~~~~~ +.. automethod:: Mastodon.poll_vote \ No newline at end of file diff --git a/docs/06_accounts.rst b/docs/06_accounts.rst new file mode 100644 index 0000000..7fe37e5 --- /dev/null +++ b/docs/06_accounts.rst @@ -0,0 +1,114 @@ +Accounts, relationships and lists +================================= +.. py:module:: mastodon +.. py:class: Mastodon + +Accounts +-------- +These functions allow you to get information about accounts and associated data as well as update that data - profile data (incuding pinned statuses and endorsements) for the logged in users account, and notes for everyone else + +Reading +~~~~~~~~ +.. automethod:: Mastodon.account_verify_credentials +.. automethod:: Mastodon.me + +.. automethod:: Mastodon.account +.. automethod:: Mastodon.account_search +.. automethod:: Mastodon.account_lookup + +.. automethod:: Mastodon.featured_tags +.. automethod:: Mastodon.featured_tag_suggestions +.. automethod:: Mastodon.account_featured_tags + +.. automethod:: Mastodon.endorsements + +.. automethod:: Mastodon.account_statuses +.. automethod:: Mastodon.account_following +.. automethod:: Mastodon.account_familiar_followers + +.. automethod:: Mastodon.account_lists + +Writing +~~~~~~~ +.. automethod:: Mastodon.account_update_credentials + +.. automethod:: Mastodon.account_pin +.. automethod:: Mastodon.account_unpin + +.. automethod:: Mastodon.account_note_set + +.. automethod:: Mastodon.featured_tag_create +.. automethod:: Mastodon.featured_tag_delete + +.. _status_pin(): +.. automethod:: Mastodon.status_pin +.. _status_unpin(): +.. automethod:: Mastodon.status_unpin + +Following and followers +----------------------- +These functions allow you to get information about the logged in users followers and users that the logged in users follows as well as follow requests and follow suggestions, and to +manage that data - most importantly, follow and unfollow users. + +Reading +~~~~~~~ +.. automethod:: Mastodon.account_followers +.. automethod:: Mastodon.account_relationships +.. automethod:: Mastodon.follows + +.. automethod:: Mastodon.follow_requests + +.. automethod:: Mastodon.suggestions + +Writing +~~~~~~~ +.. _account_follow(): +.. automethod:: Mastodon.account_follow +.. automethod:: Mastodon.account_unfollow + +.. automethod:: Mastodon.follow_request_authorize +.. automethod:: Mastodon.follow_request_reject + +.. automethod:: Mastodon.suggestion_delete + +Mutes and blocks +---------------- +These functions allow you to get information about accounts and domains that are muted or blocked by the logged in user, and to block and mute users and domains + +Reading +~~~~~~~ +.. automethod:: Mastodon.mutes +.. automethod:: Mastodon.blocks +.. automethod:: Mastodon.domain_blocks + +Writing +~~~~~~~ +.. automethod:: Mastodon.account_mute +.. automethod:: Mastodon.account_unmute + +.. automethod:: Mastodon.account_block +.. automethod:: Mastodon.account_unblock + +.. automethod:: Mastodon.account_remove_from_followers + +.. automethod:: Mastodon.domain_block +.. automethod:: Mastodon.domain_unblock + +Lists +----- +These functions allow you to view information about lists as well as to create and update them. +By default, the maximum number of lists for a user is 50. + +Reading +~~~~~~~ +.. automethod:: Mastodon.lists +.. automethod:: Mastodon.list +.. automethod:: Mastodon.list_accounts + +Writing +~~~~~~~ +.. automethod:: Mastodon.list_create +.. automethod:: Mastodon.list_update +.. automethod:: Mastodon.list_delete +.. automethod:: Mastodon.list_accounts_add +.. automethod:: Mastodon.list_accounts_delete diff --git a/docs/07_timelines.rst b/docs/07_timelines.rst new file mode 100644 index 0000000..8a82d3b --- /dev/null +++ b/docs/07_timelines.rst @@ -0,0 +1,20 @@ +Reading data: Timelines +======================= +.. py:module:: mastodon +.. py:class: Mastodon + +These functions allow you to access the timelines a logged in +user could see, as well as hashtag timelines and the public (federated) +and local timelines. For the public, local and hashtag timelines, +access is allowed even when not authenticated if the instance admin has enabled this functionality. + +.. _timeline(): +.. automethod:: Mastodon.timeline +.. automethod:: Mastodon.timeline_home +.. automethod:: Mastodon.timeline_local +.. _timeline_public(): +.. automethod:: Mastodon.timeline_public +.. _timeline_hashtag(): +.. automethod:: Mastodon.timeline_hashtag +.. automethod:: Mastodon.timeline_list +.. automethod:: Mastodon.conversations \ No newline at end of file diff --git a/docs/08_instances.rst b/docs/08_instances.rst new file mode 100644 index 0000000..35b3c5d --- /dev/null +++ b/docs/08_instances.rst @@ -0,0 +1,58 @@ +Instance-wide data and search +============================= +.. py:module:: mastodon +.. py:class: Mastodon + +Instance information +-------------------- +These functions allow you to fetch information associated with the +current instance as well as data from the instance-wide profile directory. + +.. _instance(): +.. automethod:: Mastodon.instance +.. automethod:: Mastodon.instance_activity +.. automethod:: Mastodon.instance_peers +.. automethod:: Mastodon.instance_health +.. automethod:: Mastodon.instance_nodeinfo +.. automethod:: Mastodon.instance_rules + +Profile directory +~~~~~~~~~~~~~~~~~ +.. automethod:: Mastodon.directory + +Emoji +~~~~~ +.. automethod:: Mastodon.custom_emojis + +Announcements +------------- +These functions allow you to fetch announcements, mark annoucements read and modify reactions. + +Reading +~~~~~~~ +.. automethod:: Mastodon.announcements + +Writing +~~~~~~~ +.. automethod:: Mastodon.announcement_dismiss +.. automethod:: Mastodon.announcement_reaction_create +.. automethod:: Mastodon.announcement_reaction_delete + +Trends +------ +These functions, when enabled, allow you to fetch trending tags, statuses and links. + +.. _trending_tags(): +.. automethod:: Mastodon.trending_tags +.. _trending_statuses(): +.. automethod:: Mastodon.trending_statuses +.. _trending_links(): +.. automethod:: Mastodon.trending_links +.. automethod:: Mastodon.trends + +Search +------ +These functions allow you to search for users, tags and, when enabled, full text, by default within your own posts and those you have interacted with. + +.. automethod:: Mastodon.search +.. automethod:: Mastodon.search_v2 diff --git a/docs/09_notifications.rst b/docs/09_notifications.rst new file mode 100644 index 0000000..cc45fdb --- /dev/null +++ b/docs/09_notifications.rst @@ -0,0 +1,61 @@ +Notifications and filtering +=========================== +.. py:module:: mastodon +.. py:class: Mastodon + +Notifications +------------- +This function allows you to get information about a user's notifications as well as to clear all or some notifications and to mark conversations as read. + +Reading +~~~~~~~ +.. automethod:: Mastodon.notifications + +Writing +~~~~~~~ +.. automethod:: Mastodon.notifications_clear +.. automethod:: Mastodon.notifications_dismiss +.. automethod:: Mastodon.conversations_read + + +Keyword filters +--------------- +These functions allow you to get information about keyword filters as well as to create and update filters. + +**Very Important Note: The filtering system was revised in 4.0.0. This means that these functions will now not work anymore if an instance is on Mastodon 4.0.0 or above. +When updating Mastodon.py for 4.0.0, we'll make an effort to emulate old behaviour, but this will not always be possible. Consider these methods deprecated, for now.** + +Reading +~~~~~~~ +.. automethod:: Mastodon.filters +.. automethod:: Mastodon.filter +.. automethod:: Mastodon.filters_apply + +Writing +~~~~~~~ +.. automethod:: Mastodon.filter_create +.. automethod:: Mastodon.filter_update +.. automethod:: Mastodon.filter_delete + +Push notifications +------------------ +Mastodon supports the delivery of notifications via webpush. + +These functions allow you to manage webpush subscriptions and to decrypt received +pushes. Note that the intended setup is not Mastodon pushing directly to a user's client - +the push endpoint should usually be a relay server that then takes care of delivering the +(encrypted) push to the end user via some mechanism, where it can then be decrypted and +displayed. + +Mastodon allows an application to have one webpush subscription per user at a time. + +All crypto utilities require Mastodon.py's optional "webpush" feature dependencies +(specifically, the "cryptography" and "http_ece" packages). + +.. automethod:: Mastodon.push_subscription +.. automethod:: Mastodon.push_subscription_set +.. automethod:: Mastodon.push_subscription_update + +.. _push_subscription_generate_keys(): +.. automethod:: Mastodon.push_subscription_generate_keys +.. automethod:: Mastodon.push_subscription_decrypt_push diff --git a/docs/10_streaming.rst b/docs/10_streaming.rst new file mode 100644 index 0000000..7a7723b --- /dev/null +++ b/docs/10_streaming.rst @@ -0,0 +1,75 @@ +Streaming +========= +.. py:module:: mastodon +.. py:class: Mastodon + +These functions allow access to the streaming API. For the public, local and hashtag streams, +access is generally possible without authenticating. + +If `run_async` is False, these methods block forever (or until an error is encountered). + +If `run_async` is True, the listener will listen on another thread and these methods +will return a handle corresponding to the open connection. If, in addition, `reconnect_async` is True, +the thread will attempt to reconnect to the streaming API if any errors are encountered, waiting +`reconnect_async_wait_sec` seconds between reconnection attempts. Note that no effort is made +to "catch up" - events created while the connection is broken will not be received. If you need to make +sure to get absolutely all notifications / deletes / toots, you will have to do that manually, e.g. +using the `on_abort` handler to fill in events since the last received one and then reconnecting. +Both `run_async` and `reconnect_async` default to false, and you'll have to set each to true +separately to get the behaviour described above. + +The connection may be closed at any time by calling the handles close() method. The +current status of the handler thread can be checked with the handles is_alive() function, +and the streaming status can be checked by calling is_receiving(). + +The streaming functions take instances of `StreamListener` as the `listener` parameter. +A `CallbackStreamListener` class that allows you to specify function callbacks +directly is included for convenience. + +For new well-known events implement the streaming function in `StreamListener` or `CallbackStreamListener`. +The function name is `on_` + the event name. If the event name contains dots, they are replaced with +underscored, e.g. for an event called 'status.update' the listener function should be named `on_status_update`. + +It may be that future Mastodon versions will come with completely new (unknown) event names. +If you want to do something when such an event is received, override the listener function `on_unknown_event`. +This has an additional parameter `name` which informs about the name of the event. `unknown_event` contains the +content of the event. Alternatively, a callback function can be passed in the `unknown_event_handler` parameter +in the `CallbackStreamListener` constructor. + +Note that the `unknown_event` handler is *not* guaranteed to receive events once they have been implemented. +Events will only go to this handler temporarily, while Mastodon.py has not been updated. Changes to what events +do and do not go into the handler will not be considered a breaking change. If you want to handle a new event whose +name you _do_ know, define an appropriate handler in your StreamListener, which will work even if it is not listed here. + +When in not-async mode or async mode without async_reconnect, the stream functions may raise +various exceptions: `MastodonMalformedEventError` if a received event cannot be parsed and +`MastodonNetworkError` if any connection problems occur. + +Mastodon.py currently does not support websocket based, multiplexed streams, but might in the future. + +Stream endpoints +---------------- +.. automethod:: Mastodon.stream_user +.. automethod:: Mastodon.stream_public +.. automethod:: Mastodon.stream_local +.. automethod:: Mastodon.stream_hashtag +.. automethod:: Mastodon.stream_list +.. automethod:: Mastodon.stream_healthy + +StreamListener +-------------- + +.. autoclass:: StreamListener +.. automethod:: StreamListener.on_update +.. automethod:: StreamListener.on_notification +.. automethod:: StreamListener.on_delete +.. automethod:: StreamListener.on_conversation +.. automethod:: StreamListener.on_status_update +.. automethod:: StreamListener.on_unknown_event +.. automethod:: StreamListener.on_abort +.. automethod:: StreamListener.handle_heartbeat + +CallbackStreamListener +~~~~~~~~~~~~~~~~~~~~~~ + +.. autoclass:: CallbackStreamListener \ No newline at end of file diff --git a/docs/11_misc.rst b/docs/11_misc.rst new file mode 100644 index 0000000..a85d518 --- /dev/null +++ b/docs/11_misc.rst @@ -0,0 +1,36 @@ +Misc: Markers, reports +====================== +.. py:module:: mastodon +.. py:class: Mastodon + +Markers +------- +These functions allow you to interact with the timeline "last read" markers, +to allow for persisting where the user was reading a timeline between sessions +and clients / devices. + + +Reading +~~~~~~~ +.. automethod:: Mastodon.markers_get + +Writing +~~~~~~~ +.. automethod:: Mastodon.markers_set + +Reports +------- + +Reading +~~~~~~~ +In Mastodon versions before 2.5.0 this function allowed for the retrieval +of reports filed by the logged in user. It has since been removed. + +.. automethod:: Mastodon.reports + +Writing +~~~~~~~ +This function allows you to report a user to the instance moderators as well as to +the users home instance. + +.. automethod:: Mastodon.report \ No newline at end of file diff --git a/docs/12_utilities.rst b/docs/12_utilities.rst new file mode 100644 index 0000000..9666578 --- /dev/null +++ b/docs/12_utilities.rst @@ -0,0 +1,22 @@ +Utility: Pagination and Blurhash +================================ +.. py:module:: mastodon +.. py:class: Mastodon + +Pagination +---------- +These functions allow for convenient retrieval of paginated data. + +.. _fetch_next(): +.. automethod:: Mastodon.fetch_next +.. _fetch_previous(): +.. automethod:: Mastodon.fetch_previous +.. _fetch_remaining(): +.. automethod:: Mastodon.fetch_remaining + +Blurhash decoding +----------------- +This function allows for easy basic decoding of blurhash strings to images. +This requires Mastodon.pys optional "blurhash" feature dependencies. + +.. automethod:: Mastodon.decode_blurhash diff --git a/docs/13_admin.rst b/docs/13_admin.rst new file mode 100644 index 0000000..1c97d2c --- /dev/null +++ b/docs/13_admin.rst @@ -0,0 +1,60 @@ +Administration and moderation +============================= +.. py:module:: mastodon +.. py:class: Mastodon + +These functions allow you to perform moderation actions on users and generally +process reports using the API. To do this, you need access to the "admin:read" and/or +"admin:write" scopes or their more granular variants (both for the application and the +access token), as well as at least moderator access. Mastodon.py will not request these +by default, as that would be very dangerous. + +BIG WARNING: TREAT ANY ACCESS TOKENS THAT HAVE ADMIN CREDENTIALS AS EXTREMELY, MASSIVELY +SENSITIVE DATA AND MAKE EXTRA SURE TO REVOKE THEM AFTER TESTING, NOT LET THEM SIT IN FILES +SOMEWHERE, TRACK WHICH ARE ACTIVE, ET CETERA. ANY EXPOSURE OF SUCH ACCESS TOKENS MEANS YOU +EXPOSE THE PERSONAL DATA OF ALL YOUR USERS TO WHOEVER HAS THESE TOKENS. TREAT THEM WITH +EXTREME CARE. + +This is not to say that you should not treat access tokens from admin accounts that do not +have admin: scopes attached with a lot of care, but be extra careful with those that do. + +Accounts +-------- +.. automethod:: Mastodon.admin_accounts_v2 +.. automethod:: Mastodon.admin_accounts +.. automethod:: Mastodon.admin_accounts_v1 +.. automethod:: Mastodon.admin_account +.. automethod:: Mastodon.admin_account_enable +.. automethod:: Mastodon.admin_account_approve +.. automethod:: Mastodon.admin_account_reject +.. automethod:: Mastodon.admin_account_unsilence +.. automethod:: Mastodon.admin_account_unsuspend +.. automethod:: Mastodon.admin_account_moderate + +Reports +------- +.. automethod:: Mastodon.admin_reports +.. automethod:: Mastodon.admin_report +.. automethod:: Mastodon.admin_report_assign +.. automethod:: Mastodon.admin_report_unassign +.. automethod:: Mastodon.admin_report_reopen +.. automethod:: Mastodon.admin_report_resolve + +Trends +------ +.. automethod:: Mastodon.admin_trending_tags +.. automethod:: Mastodon.admin_trending_statuses +.. automethod:: Mastodon.admin_trending_links +.. automethod:: Mastodon.admin_domain_blocks + +Federation +---------- +.. automethod:: Mastodon.admin_create_domain_block +.. automethod:: Mastodon.admin_update_domain_block +.. automethod:: Mastodon.admin_delete_domain_block + +Moderation actions +------------------ +.. automethod:: Mastodon.admin_measures +.. automethod:: Mastodon.admin_dimensions +.. automethod:: Mastodon.admin_retention \ No newline at end of file diff --git a/docs/14_contributing.rst b/docs/14_contributing.rst new file mode 100644 index 0000000..7f743b0 --- /dev/null +++ b/docs/14_contributing.rst @@ -0,0 +1,33 @@ +Contributing +============ + +How to contribute +----------------- + +Mastodon.py is incomplete a lot of the time because Mastodon has a very rich API with many functions, not all of which are implemented here. +Even when it is complete for a given Mastodon API version, there are forks and other Mastodon-API-compatible software that implement their own methods which Mastodon.py could in principle support. +And even when all of that work is done, it will inevitably have bugs, or places where the library could be made easier to use (which, really, are also bugs), missing tests that could catch bugs quicker, tooling to make updating everything faster, et cetera. + +You can help get more of this done, and you should! This can take many forms: If you notice somtehing is missing, broken or confusing: + +* You could file an issue on github, either with or without suggestions for how to fix the issue: https://github.com/halcy/Mastodon.py/issues +* You could, after filing an issue, do a PR that fixes that issue +* You could even just vaguely complain in my (https://icosahedron.website/@halcy) general direction on Mastodon + +All of these help immensely, even if it's just "hey, I don't really get why X isn't working". We can't make the library better if we don't know what the actual issues people +have are, so while I'm not going to implement every suggestion and do have some ideas of what does and does not make a good library, your feedback is, in fact, extremely valuable +and welcome. + +If you're looking for some "starter issues" to address: Currently, we don't have support for much of any of the new 4.0.0 API endpoints implemented. Pick one and have a go, +especially from the admin API. Tests are somewhat annoying to set up, as they need to run against a live mastodon instance - great if you can write them, but feel free to +skip out on them, too, or just write them "in the dry" without actually running them and leaving that for someone else. + +Tests +----- +Mastodon.py has an extensive suite of tests. The purpose of these is twofold: + +* Make sure nothing is broken and that there aren't any regressions +* Where the official docs are unclear, verify assumptions we make about the Mastodon API and document the results + +The tests use pytest and pytest-vcr so that they can be ran even without a mastodon server, but new tests require +setting up a mastodon dev server. Further documentation can be found in the "tests" directory in the repository. \ No newline at end of file diff --git a/docs/15_everything.rst b/docs/15_everything.rst new file mode 100644 index 0000000..84ddbbe --- /dev/null +++ b/docs/15_everything.rst @@ -0,0 +1,188 @@ +Every function on a huge CTRL-F-able page +========================================= +.. py:module:: mastodon +.. py:class: Mastodon + +.. automethod:: Mastodon.retrieve_mastodon_version +.. automethod:: Mastodon.verify_minimum_version +.. automethod:: Mastodon.create_app +.. automethod:: Mastodon.app_verify_credentials +.. automethod:: Mastodon.__init__ +.. automethod:: Mastodon.log_in +.. automethod:: Mastodon.auth_request_url +.. automethod:: Mastodon.set_language +.. automethod:: Mastodon.revoke_access_token +.. automethod:: Mastodon.create_account +.. automethod:: Mastodon.email_resend_confirmation +.. automethod:: Mastodon.preferencesStatuses, media and polls +.. automethod:: Mastodon.status +.. automethod:: Mastodon.status_context +.. automethod:: Mastodon.status_reblogged_by +.. automethod:: Mastodon.status_favourited_by +.. automethod:: Mastodon.status_card +.. automethod:: Mastodon.status_history +.. automethod:: Mastodon.status_source +.. automethod:: Mastodon.favourites +.. automethod:: Mastodon.bookmarks +.. automethod:: Mastodon.status_post +.. automethod:: Mastodon.status_reply +.. automethod:: Mastodon.toot +.. automethod:: Mastodon.make_poll +.. automethod:: Mastodon.status_reblog +.. automethod:: Mastodon.status_unreblog +.. automethod:: Mastodon.status_favourite +.. automethod:: Mastodon.status_unfavourite +.. automethod:: Mastodon.status_mute +.. automethod:: Mastodon.status_unmute +.. automethod:: Mastodon.status_bookmark +.. automethod:: Mastodon.status_unbookmark +.. automethod:: Mastodon.status_delete +.. automethod:: Mastodon.status_update +.. automethod:: Mastodon.scheduled_statuses +.. automethod:: Mastodon.scheduled_status +.. automethod:: Mastodon.scheduled_status_update +.. automethod:: Mastodon.scheduled_status_delete +.. automethod:: Mastodon.media_post +.. automethod:: Mastodon.media_update +.. automethod:: Mastodon.poll +.. automethod:: Mastodon.poll_voteAccounts, relationships and lists +.. automethod:: Mastodon.account_verify_credentials +.. automethod:: Mastodon.me +.. automethod:: Mastodon.account +.. automethod:: Mastodon.account_search +.. automethod:: Mastodon.account_lookup +.. automethod:: Mastodon.featured_tags +.. automethod:: Mastodon.featured_tag_suggestions +.. automethod:: Mastodon.account_featured_tags +.. automethod:: Mastodon.endorsements +.. automethod:: Mastodon.account_statuses +.. automethod:: Mastodon.account_following +.. automethod:: Mastodon.account_familiar_followers +.. automethod:: Mastodon.account_lists +.. automethod:: Mastodon.account_update_credentials +.. automethod:: Mastodon.account_pin +.. automethod:: Mastodon.account_unpin +.. automethod:: Mastodon.account_note_set +.. automethod:: Mastodon.featured_tag_create +.. automethod:: Mastodon.featured_tag_delete +.. automethod:: Mastodon.status_pin +.. automethod:: Mastodon.status_unpin +.. automethod:: Mastodon.account_followers +.. automethod:: Mastodon.account_relationships +.. automethod:: Mastodon.follows +.. automethod:: Mastodon.follow_requests +.. automethod:: Mastodon.suggestions +.. automethod:: Mastodon.account_follow +.. automethod:: Mastodon.account_unfollow +.. automethod:: Mastodon.follow_request_authorize +.. automethod:: Mastodon.follow_request_reject +.. automethod:: Mastodon.suggestion_delete +.. automethod:: Mastodon.mutes +.. automethod:: Mastodon.blocks +.. automethod:: Mastodon.domain_blocks +.. automethod:: Mastodon.account_mute +.. automethod:: Mastodon.account_unmute +.. automethod:: Mastodon.account_block +.. automethod:: Mastodon.account_unblock +.. automethod:: Mastodon.account_remove_from_followers +.. automethod:: Mastodon.domain_block +.. automethod:: Mastodon.domain_unblock +.. automethod:: Mastodon.lists +.. automethod:: Mastodon.list +.. automethod:: Mastodon.list_accounts +.. automethod:: Mastodon.list_create +.. automethod:: Mastodon.list_update +.. automethod:: Mastodon.list_delete +.. automethod:: Mastodon.list_accounts_add +.. automethod:: Mastodon.list_accounts_delete +.. automethod:: Mastodon.timeline +.. automethod:: Mastodon.timeline_home +.. automethod:: Mastodon.timeline_local +.. automethod:: Mastodon.timeline_public +.. automethod:: Mastodon.timeline_hashtag +.. automethod:: Mastodon.timeline_list +.. automethod:: Mastodon.conversationsInstance-wide data and search +.. automethod:: Mastodon.instance +.. automethod:: Mastodon.instance_activity +.. automethod:: Mastodon.instance_peers +.. automethod:: Mastodon.instance_health +.. automethod:: Mastodon.instance_nodeinfo +.. automethod:: Mastodon.instance_rules +.. automethod:: Mastodon.directory +.. automethod:: Mastodon.custom_emojis +.. automethod:: Mastodon.announcements +.. automethod:: Mastodon.announcement_dismiss +.. automethod:: Mastodon.announcement_reaction_create +.. automethod:: Mastodon.announcement_reaction_delete +.. automethod:: Mastodon.trending_tags +.. automethod:: Mastodon.trending_statuses +.. automethod:: Mastodon.trending_links +.. automethod:: Mastodon.trends +.. automethod:: Mastodon.search +.. automethod:: Mastodon.search_v2 +.. automethod:: Mastodon.notifications +.. automethod:: Mastodon.notifications_clear +.. automethod:: Mastodon.notifications_dismiss +.. automethod:: Mastodon.conversations_read +.. automethod:: Mastodon.filters +.. automethod:: Mastodon.filter +.. automethod:: Mastodon.filters_apply +.. automethod:: Mastodon.filter_create +.. automethod:: Mastodon.filter_update +.. automethod:: Mastodon.filter_delete +.. automethod:: Mastodon.push_subscription +.. automethod:: Mastodon.push_subscription_set +.. automethod:: Mastodon.push_subscription_update +.. automethod:: Mastodon.push_subscription_generate_keys +.. automethod:: Mastodon.push_subscription_decrypt_push +.. automethod:: Mastodon.stream_user +.. automethod:: Mastodon.stream_public +.. automethod:: Mastodon.stream_local +.. automethod:: Mastodon.stream_hashtag +.. automethod:: Mastodon.stream_list +.. automethod:: Mastodon.stream_healthy +.. autoclass:: StreamListener +.. automethod:: StreamListener.on_update +.. automethod:: StreamListener.on_notification +.. automethod:: StreamListener.on_delete +.. automethod:: StreamListener.on_conversation +.. automethod:: StreamListener.on_status_update +.. automethod:: StreamListener.on_unknown_event +.. automethod:: StreamListener.on_abort +.. automethod:: StreamListener.handle_heartbeat +.. autoclass:: CallbackStreamListenerMisc: Markers, reports +.. automethod:: Mastodon.markers_get +.. automethod:: Mastodon.markers_set +.. automethod:: Mastodon.reports +.. automethod:: Mastodon.reportUtility: Pagination and Blurhash +.. automethod:: Mastodon.fetch_next +.. automethod:: Mastodon.fetch_previous +.. automethod:: Mastodon.fetch_remaining +.. automethod:: Mastodon.decode_blurhash +.. automethod:: Mastodon.admin_accounts_v2 +.. automethod:: Mastodon.admin_accounts +.. automethod:: Mastodon.admin_accounts_v1 +.. automethod:: Mastodon.admin_account +.. automethod:: Mastodon.admin_account_enable +.. automethod:: Mastodon.admin_account_approve +.. automethod:: Mastodon.admin_account_reject +.. automethod:: Mastodon.admin_account_unsilence +.. automethod:: Mastodon.admin_account_unsuspend +.. automethod:: Mastodon.admin_account_moderate +.. automethod:: Mastodon.admin_reports +.. automethod:: Mastodon.admin_report +.. automethod:: Mastodon.admin_report_assign +.. automethod:: Mastodon.admin_report_unassign +.. automethod:: Mastodon.admin_report_reopen +.. automethod:: Mastodon.admin_report_resolve +.. automethod:: Mastodon.admin_trending_tags +.. automethod:: Mastodon.admin_trending_statuses +.. automethod:: Mastodon.admin_trending_links +.. automethod:: Mastodon.admin_domain_blocks +.. automethod:: Mastodon.admin_create_domain_block +.. automethod:: Mastodon.admin_update_domain_block +.. automethod:: Mastodon.admin_delete_domain_block +.. automethod:: Mastodon.admin_measures +.. automethod:: Mastodon.admin_dimensions +.. automethod:: Mastodon.admin_retention + diff --git a/docs/index.rst b/docs/index.rst index ed8a578..d5a7e88 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -53,9 +53,10 @@ Mastodon.py contains work by a large number of contributors, many of which have put significant work into making it a better library. You can find some information about who helped with which particular feature or fix in the changelog. +.. _Mastodon.py on GitHub: https://github.com/halcy/Mastodon.py .. _Mastodon: https://github.com/mastodon/mastodon -.. _Mastodon flagship instance: https://mastodon.social/ -.. _Official Mastodon API docs: https://docs.joinmastodon.org/client/intro/ +.. _The mastodon project as such: https://joinmastodon.org/ +.. _Official Mastodon API docs: https://docs.joinmastodon.org/api/guidelines/ .. toctree:: :caption: Introduction @@ -68,4 +69,20 @@ about who helped with which particular feature or fix in the changelog. .. toctree:: :caption: API methods - 04_auth \ No newline at end of file + 04_auth + 05_statuses + 06_accounts + 07_timelines + 08_instances + 09_notifications + 10_streaming + 11_misc + 12_utilities + 13_admin + +.. toctree:: + :caption: Appendix + + 14_contributing + 15_everything + \ No newline at end of file diff --git a/docs/update_everything_page.sh b/docs/update_everything_page.sh new file mode 100755 index 0000000..89da4cc --- /dev/null +++ b/docs/update_everything_page.sh @@ -0,0 +1,8 @@ +#!/bin/bash +echo "Every function on a huge CTRL-F-able page" > 15_everything.rst +echo "=========================================" >> 15_everything.rst +echo ".. py:module:: mastodon" >> 15_everything.rst +echo ".. py:class: Mastodon" >> 15_everything.rst +echo "" >> 15_everything.rst +cat 01_general.rst 02_return_values.rst 03_errors.rst 04_auth.rst 05_statuses.rst 06_accounts.rst 07_timelines.rst 08_instances.rst 09_notifications.rst 10_streaming.rst 11_misc.rst 12_utilities.rst 13_admin.rst | grep -E "automethod|autoclass" >> 15_everything.rst +echo "" >> 15_everything.rst diff --git a/tests/README.markdown b/tests/README.markdown index ae3e42a..49bf894 100644 --- a/tests/README.markdown +++ b/tests/README.markdown @@ -23,10 +23,10 @@ Note that some tests are slightly unstable, as they require sidekiq to do things This test suite uses [VCR.py][] to record requests to Mastodon and replay them in successive runs. -If you want to add or change tests, you will need a Mastodon development server running on `http://localhost:3000`, with the default `admin` user and default password. -To set this up, follow the development guide and set up the database using "rails db:setup". +If you want to add or change tests, you will need a Mastodon development server running on `http://localhost:3000`. +To set this up, follow the development guide at https://docs.joinmastodon.org/dev/setup/ . -It also needs various things to be set up for it. The following command should do the trick: +It also needs various things to be set up for it. The following command will do the trick: sudo redis-cli flushall && sleep 3 && \ sudo /etc/init.d/redis-server restart && \ @@ -39,7 +39,8 @@ It also needs various things to be set up for it. The following command should d You _may_ additionally have to set up a database password and pass it as DB_PASS for the streaming tests to function. -Tests that send requests to Mastodon should be marked as needing VCR with the `pytest.mark.vcr` decorator. +Tests that send requests to Mastodon should be marked as needing VCR with the `pytest.mark.vcr` decorator. Streaming tests use a +heavily monkeypatched version of VCR.py to work and may behave in weird ways sometimes. ```python import pytest -- cgit v1.2.3