From 0524dd1f2b130fdaddd2d209716bf99236b02a22 Mon Sep 17 00:00:00 2001 From: Lydia Date: Fri, 25 Nov 2016 12:52:55 -0500 Subject: [PATCH 1/8] Add documentation examples --- docs/index.rst | 91 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index a91cfb7..85f1982 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -81,7 +81,20 @@ Reading data: Statuses These functions allow you to get information about single statuses. .. automethod:: Mastodon.status + +Returns a single toot dict for the given status. + .. automethod:: Mastodon.status_context + +.. code-block:: python + mastodon.status_context() + # Returns + { + 'descendants': A list of toot dicts + 'ancestors': A list of toot dicts + } +Note that this can only be called on statuses belonging to the currently logged-in user. + .. automethod:: Mastodon.status_reblogged_by .. automethod:: Mastodon.status_favourited_by @@ -91,6 +104,8 @@ This function allows you to get information about a users notifications. .. automethod:: Mastodon.notifications +Returns a list of toot dicts for toots mentioning the current logged-in user. + Reading data: Accounts ---------------------- @@ -99,13 +114,37 @@ their relationships. .. automethod:: Mastodon.account .. automethod:: Mastodon.account_verify_credentials + +These methods return an account dict: +.. code-block:: python + mastodon.account() + # Returns + { + 'display_name': The user's display name + 'acct': The user's account name (what you @ them with) + 'following_count': How many people they follow + 'url': Their URL; usually 'https://mastodon.social/users/' + 'statuses_count': How many statuses they have + 'followers_count': How many followers they have + 'avatar': URL for their avatar + 'note': Their bio + 'header': URL for their header image + 'id': Same as + 'username': Usually same as acct + } + .. automethod:: Mastodon.account_statuses .. automethod:: Mastodon.account_following .. automethod:: Mastodon.account_followers .. automethod:: Mastodon.account_relationships + +See following below for format of relationship dicts. + .. automethod:: Mastodon.account_suggestions .. automethod:: Mastodon.account_search +Returns a list of user dicts. + Writing data: Statuses ---------------------- These functions allow you to post statuses to Mastodon and to @@ -113,17 +152,56 @@ interact with already posted statuses. .. automethod:: Mastodon.status_post .. automethod:: Mastodon.toot -.. automethod:: Mastodon.status_delete .. automethod:: Mastodon.status_reblog .. automethod:: Mastodon.status_unreblog .. automethod:: Mastodon.status_favourite .. automethod:: Mastodon.status_unfavourite +These methods return a toot dict: +.. code-block:: python + mastodon.toot("Hello from Python") + # Returns the following dictionary: + { + 'sensitive': Denotes whether the toot is marked sensitive + 'created_at': Creation time + 'mentions': A list of account dicts mentioned in the toot + 'uri': Descriptor for the toot + EG 'tag:mastodon.social,2016-11-25:objectId=:objectType=Status' + 'tags': A list of hashtag dicts used in the toot + 'in_reply_to_id': Numerical id of the toot this toot is in response to + 'id': Numerical id of this toot + 'reblogs_count': Number of reblogs + 'favourites_count': Number of favourites + 'reblog': Denotes whether the toot is a reblog + 'url': URL of the toot + 'content': Content of the toot, as HTML: '

Hello from Python

' + 'favourited': Denotes whether the logged in user has favourited this toot + 'account': Account dict for the logged in account + } + +.. automethod:: Mastodon.status_delete +Returns an empty dict: +.. code-block:: python + mastodon.delete_status() + # Returns + {} + Writing data: Accounts ---------------------- These functions allow you to interact with other accounts: To (un)follow and (un)block. +They return a relationship dict: +.. code-block:: python + mastodon.account_follow() + # Returns + { + 'followed_by': Boolean denoting whether they follow you back + 'following': Boolean denoting whether you follow them + 'id': Numerical id (same one as ) + 'blocking': Boolean denoting whether you are blocking them + } + .. automethod:: Mastodon.account_follow .. automethod:: Mastodon.account_unfollow .. automethod:: Mastodon.account_block @@ -137,6 +215,17 @@ to attach media to statuses. .. automethod:: Mastodon.media_post +Returns a media dict: +.. code-block:: python + mastodon.media_post("image.jpg", "image/jpeg") + # Returns + { + 'text_url': The display text for the media (what shows up in toots) + 'preview_url': The URL for the media preview on Amazon S3 + 'type': Media type, EG 'image' + 'url': The URL for the media on Amazon S3 + } + .. _Mastodon: https://github.com/Gargron/mastodon .. _Mastodon flagship instance: http://mastodon.social/ .. _Mastodon api docs: https://github.com/Gargron/mastodon/wiki/API From e94445c86b4dcaa14c79e7c36a7145c42b25ed9d Mon Sep 17 00:00:00 2001 From: Lydia Date: Fri, 25 Nov 2016 13:43:13 -0500 Subject: [PATCH 2/8] Corrections --- docs/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 85f1982..667890f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -121,7 +121,7 @@ These methods return an account dict: # Returns { 'display_name': The user's display name - 'acct': The user's account name (what you @ them with) + 'acct': The user's account name as username@domain (@domain omitted for local users) 'following_count': How many people they follow 'url': Their URL; usually 'https://mastodon.social/users/' 'statuses_count': How many statuses they have @@ -130,7 +130,7 @@ These methods return an account dict: 'note': Their bio 'header': URL for their header image 'id': Same as - 'username': Usually same as acct + 'username': The username (what you @ them with) } .. automethod:: Mastodon.account_statuses @@ -221,9 +221,9 @@ Returns a media dict: # Returns { 'text_url': The display text for the media (what shows up in toots) - 'preview_url': The URL for the media preview on Amazon S3 + 'preview_url': The URL for the media preview 'type': Media type, EG 'image' - 'url': The URL for the media on Amazon S3 + 'url': The URL for the media } .. _Mastodon: https://github.com/Gargron/mastodon From eaa49d87f8caaec39a0fba9fc269ef60e9f832fc Mon Sep 17 00:00:00 2001 From: Lydia Date: Fri, 25 Nov 2016 13:54:40 -0500 Subject: [PATCH 3/8] Corrections --- docs/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 667890f..a9ecf49 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -93,7 +93,6 @@ Returns a single toot dict for the given status. 'descendants': A list of toot dicts 'ancestors': A list of toot dicts } -Note that this can only be called on statuses belonging to the currently logged-in user. .. automethod:: Mastodon.status_reblogged_by .. automethod:: Mastodon.status_favourited_by From 4a3e2d232d7de7e7a82b7e538b757f9b17eb6440 Mon Sep 17 00:00:00 2001 From: Lorenz Diener Date: Fri, 25 Nov 2016 19:59:01 +0100 Subject: [PATCH 4/8] readthedocs does not like .. code-block:: with no empty line after --- docs/index.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index a9ecf49..2d61f14 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -87,6 +87,7 @@ Returns a single toot dict for the given status. .. automethod:: Mastodon.status_context .. code-block:: python + mastodon.status_context() # Returns { @@ -115,7 +116,9 @@ their relationships. .. automethod:: Mastodon.account_verify_credentials These methods return an account dict: + .. code-block:: python + mastodon.account() # Returns { @@ -157,7 +160,9 @@ interact with already posted statuses. .. automethod:: Mastodon.status_unfavourite These methods return a toot dict: + .. code-block:: python + mastodon.toot("Hello from Python") # Returns the following dictionary: { @@ -180,7 +185,9 @@ These methods return a toot dict: .. automethod:: Mastodon.status_delete Returns an empty dict: + .. code-block:: python + mastodon.delete_status() # Returns {} @@ -191,7 +198,9 @@ These functions allow you to interact with other accounts: To (un)follow and (un)block. They return a relationship dict: + .. code-block:: python + mastodon.account_follow() # Returns { @@ -215,7 +224,9 @@ to attach media to statuses. .. automethod:: Mastodon.media_post Returns a media dict: + .. code-block:: python + mastodon.media_post("image.jpg", "image/jpeg") # Returns { From 3585830182215428b689738a7923121655390ae6 Mon Sep 17 00:00:00 2001 From: Lorenz Diener Date: Fri, 25 Nov 2016 20:33:00 +0100 Subject: [PATCH 5/8] Documentation restructured and made more PEP8-y --- docs/index.rst | 194 ++++++++++++++++++++----------------------- mastodon/Mastodon.py | 134 ++++++++++++++++++------------ 2 files changed, 172 insertions(+), 156 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 2d61f14..f388182 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,7 @@ Mastodon.py =========== +.. py:module:: mastodon +.. py:class: Mastodon .. code-block:: python @@ -37,14 +39,96 @@ as a single python module. By default, it talks to the `Mastodon flagship instance`_, but it can be set to talk to any node running Mastodon. +Return values +------------- + Unless otherwise specified, all data is returned as python dictionaries, matching the JSON format used by the API. -For complete documentation on what every function returns, -check the `Mastodon API docs`_, or just play around a bit - the -format of the data is generally very easy to understand. -.. py:module:: mastodon -.. py:class: Mastodon +User dicts +~~~~~~~~~~ + +.. code-block:: python + + { + 'display_name': The user's display name + 'acct': The user's account name as username@domain (@domain omitted for local users) + 'following_count': How many people they follow + 'url': Their URL; usually 'https://mastodon.social/users/' + 'statuses_count': How many statuses they have + 'followers_count': How many followers they have + 'avatar': URL for their avatar + 'note': Their bio + 'header': URL for their header image + 'id': Same as + 'username': The username (what you @ them with) + } + +Toot dicts +~~~~~~~~~~ +.. code-block:: python + + mastodon.toot("Hello from Python") + # Returns the following dictionary: + { + 'sensitive': Denotes whether the toot is marked sensitive + 'created_at': Creation time + 'mentions': A list of account dicts mentioned in the toot + 'uri': Descriptor for the toot + EG 'tag:mastodon.social,2016-11-25:objectId=:objectType=Status' + 'tags': A list of hashtag dicts used in the toot + 'in_reply_to_id': Numerical id of the toot this toot is in response to + 'id': Numerical id of this toot + 'reblogs_count': Number of reblogs + 'favourites_count': Number of favourites + 'reblog': Denotes whether the toot is a reblog + 'url': URL of the toot + 'content': Content of the toot, as HTML: '

Hello from Python

' + 'favourited': Denotes whether the logged in user has favourited this toot + 'account': Account dict for the logged in account + } + +Relationship dicts +~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + mastodon.account_follow() + # Returns + { + 'followed_by': Boolean denoting whether they follow you back + 'following': Boolean denoting whether you follow them + 'id': Numerical id (same one as ) + 'blocking': Boolean denoting whether you are blocking them + } + +Context dicts +~~~~~~~~~~~~~ + +.. code-block:: python + + mastodon.status_context() + # Returns + { + 'descendants': A list of toot dicts + 'ancestors': A list of toot dicts + } + +Media dicts +~~~~~~~~~~~ + +.. code-block:: python + + mastodon.media_post("image.jpg", "image/jpeg") + # Returns + { + 'text_url': The display text for the media (what shows up in toots) + 'preview_url': The URL for the media preview + 'type': Media type, EG 'image' + 'url': The URL for the media + } + + App registration and user authentication ---------------------------------------- @@ -81,20 +165,7 @@ Reading data: Statuses These functions allow you to get information about single statuses. .. automethod:: Mastodon.status - -Returns a single toot dict for the given status. - .. automethod:: Mastodon.status_context - -.. code-block:: python - - mastodon.status_context() - # Returns - { - 'descendants': A list of toot dicts - 'ancestors': A list of toot dicts - } - .. automethod:: Mastodon.status_reblogged_by .. automethod:: Mastodon.status_favourited_by @@ -104,9 +175,6 @@ This function allows you to get information about a users notifications. .. automethod:: Mastodon.notifications -Returns a list of toot dicts for toots mentioning the current logged-in user. - - Reading data: Accounts ---------------------- These functions allow you to get information about accounts and @@ -114,39 +182,12 @@ their relationships. .. automethod:: Mastodon.account .. automethod:: Mastodon.account_verify_credentials - -These methods return an account dict: - -.. code-block:: python - - mastodon.account() - # Returns - { - 'display_name': The user's display name - 'acct': The user's account name as username@domain (@domain omitted for local users) - 'following_count': How many people they follow - 'url': Their URL; usually 'https://mastodon.social/users/' - 'statuses_count': How many statuses they have - 'followers_count': How many followers they have - 'avatar': URL for their avatar - 'note': Their bio - 'header': URL for their header image - 'id': Same as - 'username': The username (what you @ them with) - } - .. automethod:: Mastodon.account_statuses .. automethod:: Mastodon.account_following .. automethod:: Mastodon.account_followers .. automethod:: Mastodon.account_relationships - -See following below for format of relationship dicts. - -.. automethod:: Mastodon.account_suggestions .. automethod:: Mastodon.account_search -Returns a list of user dicts. - Writing data: Statuses ---------------------- These functions allow you to post statuses to Mastodon and to @@ -158,58 +199,13 @@ interact with already posted statuses. .. automethod:: Mastodon.status_unreblog .. automethod:: Mastodon.status_favourite .. automethod:: Mastodon.status_unfavourite - -These methods return a toot dict: - -.. code-block:: python - - mastodon.toot("Hello from Python") - # Returns the following dictionary: - { - 'sensitive': Denotes whether the toot is marked sensitive - 'created_at': Creation time - 'mentions': A list of account dicts mentioned in the toot - 'uri': Descriptor for the toot - EG 'tag:mastodon.social,2016-11-25:objectId=:objectType=Status' - 'tags': A list of hashtag dicts used in the toot - 'in_reply_to_id': Numerical id of the toot this toot is in response to - 'id': Numerical id of this toot - 'reblogs_count': Number of reblogs - 'favourites_count': Number of favourites - 'reblog': Denotes whether the toot is a reblog - 'url': URL of the toot - 'content': Content of the toot, as HTML: '

Hello from Python

' - 'favourited': Denotes whether the logged in user has favourited this toot - 'account': Account dict for the logged in account - } - .. automethod:: Mastodon.status_delete -Returns an empty dict: - -.. code-block:: python - - mastodon.delete_status() - # Returns - {} Writing data: Accounts ---------------------- These functions allow you to interact with other accounts: To (un)follow and (un)block. -They return a relationship dict: - -.. code-block:: python - - mastodon.account_follow() - # Returns - { - 'followed_by': Boolean denoting whether they follow you back - 'following': Boolean denoting whether you follow them - 'id': Numerical id (same one as ) - 'blocking': Boolean denoting whether you are blocking them - } - .. automethod:: Mastodon.account_follow .. automethod:: Mastodon.account_unfollow .. automethod:: Mastodon.account_block @@ -223,18 +219,6 @@ to attach media to statuses. .. automethod:: Mastodon.media_post -Returns a media dict: - -.. code-block:: python - - mastodon.media_post("image.jpg", "image/jpeg") - # Returns - { - 'text_url': The display text for the media (what shows up in toots) - 'preview_url': The URL for the media preview - 'type': Media type, EG 'image' - 'url': The URL for the media - } .. _Mastodon: https://github.com/Gargron/mastodon .. _Mastodon flagship instance: http://mastodon.social/ diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py index 7bd6473..36f20d2 100644 --- a/mastodon/Mastodon.py +++ b/mastodon/Mastodon.py @@ -27,7 +27,7 @@ class Mastodon: @staticmethod def create_app(client_name, scopes = ['read', 'write', 'follow'], redirect_uris = None, to_file = None, api_base_url = __DEFAULT_BASE_URL): """ - Creates a new app with given client_name and scopes (read, write, follow) + Create a new app with given client_name and scopes (read, write, follow) Specify redirect_uris if you want users to be redirected to a certain page after authenticating. Specify to_file to persist your apps info to a file so you can use them in the constructor. @@ -59,7 +59,7 @@ class Mastodon: ### def __init__(self, client_id, client_secret = None, access_token = None, api_base_url = __DEFAULT_BASE_URL, debug_requests = False): """ - Creates a new API wrapper instance based on the given client_secret and client_id. If you + Create a new API wrapper instance based on the given client_secret and client_id. If you give a client_id and it is not a file, you must also give a secret. You can also directly specify an access_token, directly or as a file. @@ -87,7 +87,7 @@ class Mastodon: def log_in(self, username, password, scopes = ['read', 'write', 'follow'], to_file = None): """ - Logs in and sets access_token to what was returned. + Log in and set access_token to what was returned. Can persist access token to file. Will throw an exception if username / password are wrong, scopes are not @@ -124,35 +124,45 @@ class Mastodon: ## def timeline(self, timeline = "home", max_id = None, since_id = None, limit = None): """ - Returns statuses, most recent ones first. Timeline can be home, mentions, public + Fetch statuses, most recent ones first. Timeline can be home, mentions, public or tag/hashtag. See the following functions documentation for what those do. The default timeline is the "home" timeline. + + Returns a list of toot dicts. """ params = self.__generate_params(locals(), ['timeline']) return self.__api_request('GET', '/api/v1/timelines/' + timeline, params) def timeline_home(self, max_id = None, since_id = None, limit = None): """ - Returns the authenticated users home timeline (i.e. followed users and self). + Fetch the authenticated users home timeline (i.e. followed users and self). + + Returns a list of toot dicts. """ return self.timeline('home', max_id = max_id, since_id = since_id, limit = limit) def timeline_mentions(self, max_id = None, since_id = None, limit = None): """ - Returns the authenticated users mentions. + Fetches the authenticated users mentions. + + Returns a list of toot dicts. """ return self.timeline('mentions', max_id = max_id, since_id = since_id, limit = limit) def timeline_public(self, max_id = None, since_id = None, limit = None): """ - Returns the public / visible-network timeline. + Fetches the public / visible-network timeline. + + Returns a list of toot dicts. """ return self.timeline('public', max_id = max_id, since_id = since_id, limit = limit) def timeline_hashtag(self, hashtag, max_id = None, since_id = None, limit = None): """ - Returns all toots with a given hashtag. + Fetch a timeline of toots with a given hashtag. + + Returns a list of toot dicts. """ return self.timeline('tag/' + str(hashtag), max_id = max_id, since_id = since_id, limit = limit) @@ -161,25 +171,33 @@ class Mastodon: ### def status(self, id): """ - Returns a status. + Fetch information about a single toot. + + Returns a toot dict. """ return self.__api_request('GET', '/api/v1/statuses/' + str(id)) def status_context(self, id): """ - Returns ancestors and descendants of the status. + Fetch information about ancestors and descendants of a toot. + + Returns a context dict. """ return self.__api_request('GET', '/api/v1/statuses/' + str(id) + '/context') def status_reblogged_by(self, id): """ - Returns a list of users that have reblogged a status. + Fetch a list of users that have reblogged a status. + + Returns a list of user dicts. """ return self.__api_request('GET', '/api/v1/statuses/' + str(id) + '/reblogged_by') def status_favourited_by(self, id): """ - Returns a list of users that have favourited a status. + Fetch a list of users that have favourited a status. + + Returns a list of user dicts. """ return self.__api_request('GET', '/api/v1/statuses/' + str(id) + '/favourited_by') @@ -188,8 +206,10 @@ class Mastodon: ### def notifications(self): """ - Returns notifications (mentions, favourites, reblogs, follows) for the authenticated + Fetch notifications (mentions, favourites, reblogs, follows) for the authenticated user. + + Returns: TODO """ return self.__api_request('GET', '/api/v1/notifications') @@ -198,53 +218,61 @@ class Mastodon: ### def account(self, id): """ - Returns account. + Fetch account information by user id. + + Returns a user dict. """ return self.__api_request('GET', '/api/v1/accounts/' + str(id)) def account_verify_credentials(self): """ - Returns authenticated user's account. + Fetch authenticated user's account information. + + Returns a user dict. """ return self.__api_request('GET', '/api/v1/accounts/verify_credentials') def account_statuses(self, id, max_id = None, since_id = None, limit = None): """ - Returns statuses by user. Same options as timeline are permitted. + Fetch statuses by user id. Same options as timeline are permitted. + + Returns a list of toot dicts. """ params = self.__generate_params(locals(), ['id']) return self.__api_request('GET', '/api/v1/accounts/' + str(id) + '/statuses', params) def account_following(self, id): """ - Returns users the given user is following. + Fetch users the given user is following. + + Returns a list of user dicts. """ return self.__api_request('GET', '/api/v1/accounts/' + str(id) + '/following') def account_followers(self, id): """ - Returns users the given user is followed by. + Fetch users the given user is followed by. + + Returns a list of user dicts. """ return self.__api_request('GET', '/api/v1/accounts/' + str(id) + '/followers') def account_relationships(self, id): """ - Returns relationships (following, followed_by, blocking) of the logged in user to + Fetch relationships (following, followed_by, blocking) of the logged in user to a given account. id can be a list. + + Returns a list of relationship dicts. """ params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/accounts/relationships', params) - - def account_suggestions(self): - """ - Returns accounts that the system suggests the authenticated user to follow. - """ - return self.__api_request('GET', '/api/v1/accounts/suggestions') def account_search(self, q, limit = None): """ - Returns matching accounts. Will lookup an account remotely if the search term is + Fetch matching accounts. Will lookup an account remotely if the search term is in the username@domain format and not yet in the database. + + Returns a list of user dicts. """ params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/accounts/search', params) @@ -254,10 +282,10 @@ class Mastodon: ### def status_post(self, status, in_reply_to_id = None, media_ids = None): """ - Posts a status. Can optionally be in reply to another status and contain + Post a status. Can optionally be in reply to another status and contain up to four pieces of media (Uploaded via media_post()). - Returns the new status. + Returns a toot dict with the new status. """ params = self.__generate_params(locals()) return self.__api_request('POST', '/api/v1/statuses', params) @@ -265,41 +293,46 @@ class Mastodon: def toot(self, status): """ Synonym for status_post that only takes the status text as input. + + Returns a toot dict with the new status. """ return self.status_post(status) def status_delete(self, id): """ - Deletes a status + Delete a status + + Returns an empty dict for good measure. """ return self.__api_request('DELETE', '/api/v1/statuses/' + str(id)) def status_reblog(self, id): - """Reblogs a status. + """Reblog a status. - Returns a new status that wraps around the reblogged one.""" + Returns a toot with with a new status that wraps around the reblogged one. + """ return self.__api_request('POST', '/api/v1/statuses/' + str(id) + "/reblog") def status_unreblog(self, id): """ - Un-reblogs a status. + Un-reblog a status. - Returns the status that used to be reblogged. + Returns a toot dict with the status that used to be reblogged. """ return self.__api_request('POST', '/api/v1/statuses/' + str(id) + "/unreblog") def status_favourite(self, id): """ - Favourites a status. + Favourite a status. - Returns the favourited status. + Returns a toot dict with the favourited status. """ return self.__api_request('POST', '/api/v1/statuses/' + str(id) + "/favourite") def status_unfavourite(self, id): - """Favourites a status. + """Favourite a status. - Returns the un-favourited status. + Returns a toot dict with the un-favourited status. """ return self.__api_request('POST', '/api/v1/statuses/' + str(id) + "/unfavourite") @@ -308,33 +341,33 @@ class Mastodon: ### def account_follow(self, id): """ - Follows a user. + Follow a user. - Returns the updated relationship to the user. + Returns a relationship dict containing the updated relationship to the user. """ return self.__api_request('POST', '/api/v1/accounts/' + str(id) + "/follow") def account_unfollow(self, id): """ - Unfollows a user. + Unfollow a user. - Returns the updated relationship to the user. + Returns a relationship dict containing the updated relationship to the user. """ return self.__api_request('POST', '/api/v1/accounts/' + str(id) + "/unfollow") def account_block(self, id): """ - Blocks a user. + Block a user. - Returns the updated relationship to the user. + Returns a relationship dict containing the updated relationship to the user. """ return self.__api_request('POST', '/api/v1/accounts/' + str(id) + "/block") def account_unblock(self, id): """ - Unblocks a user. + Unblock a user. - Returns the updated relationship to the user. + Returns a relationship dict containing the updated relationship to the user. """ return self.__api_request('POST', '/api/v1/accounts/' + str(id) + "/unblock") @@ -343,20 +376,19 @@ class Mastodon: ### def media_post(self, media_file, mime_type = None): """ - Posts an image. media_file can either be image data or + Post an image. media_file can either be image data or a file name. If image data is passed directly, the mime type has to be specified manually, otherwise, it is determined from the file name. - Returns the uploaded media metadata object. Importantly, this contains - the ID that can then be used in status_post() to attach the media to - a toot. - Throws a ValueError if the mime type of the passed data or file can not be determined properly. + + Returns a media dict. This contains the id that can be used in + status_post to attach the media file to a toot. """ - if os.path.isfile(media_file): + if os.path.isfile(media_file) and mime_type == None: mime_type = mimetypes.guess_type(media_file)[0] media_file = open(media_file, 'rb') From 10eda366d56ff9ea97e8509af935ddadcc5d176d Mon Sep 17 00:00:00 2001 From: Lorenz Diener Date: Fri, 25 Nov 2016 20:34:45 +0100 Subject: [PATCH 6/8] Note about IDs --- docs/index.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index f388182..eb4bd27 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,15 +39,22 @@ as a single python module. By default, it talks to the `Mastodon flagship instance`_, but it can be set to talk to any node running Mastodon. +A note about IDs +---------------- +Mastodons API uses IDs in several places: User IDs, Toot IDs, ... + +While debugging, it might be tempting to copy-paste in IDs from the +web interface into your code. This will not work, as the IDs on the web +interface and in the URLs are not the same as the IDs used internally +in the API, so don't do that. + Return values ------------- - Unless otherwise specified, all data is returned as python dictionaries, matching the JSON format used by the API. User dicts ~~~~~~~~~~ - .. code-block:: python { @@ -90,7 +97,6 @@ Toot dicts Relationship dicts ~~~~~~~~~~~~~~~~~~ - .. code-block:: python mastodon.account_follow() @@ -104,7 +110,6 @@ Relationship dicts Context dicts ~~~~~~~~~~~~~ - .. code-block:: python mastodon.status_context() @@ -116,7 +121,6 @@ Context dicts Media dicts ~~~~~~~~~~~ - .. code-block:: python mastodon.media_post("image.jpg", "image/jpeg") @@ -128,8 +132,6 @@ Media dicts 'url': The URL for the media } - - App registration and user authentication ---------------------------------------- Before you can use the mastodon API, you have to register your From 6fdf18eebc4458f542009c61907fa2dd22b050ea Mon Sep 17 00:00:00 2001 From: Lorenz Diener Date: Fri, 25 Nov 2016 20:46:20 +0100 Subject: [PATCH 7/8] Documentation for notifications --- docs/index.rst | 22 +++++++++++++++++++--- mastodon/Mastodon.py | 2 +- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index eb4bd27..d7ade82 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -57,6 +57,8 @@ User dicts ~~~~~~~~~~ .. code-block:: python + mastodon.account() + # Returns the following dictionary: { 'display_name': The user's display name 'acct': The user's account name as username@domain (@domain omitted for local users) @@ -100,7 +102,7 @@ Relationship dicts .. code-block:: python mastodon.account_follow() - # Returns + # Returns the following dictionary: { 'followed_by': Boolean denoting whether they follow you back 'following': Boolean denoting whether you follow them @@ -108,12 +110,26 @@ Relationship dicts 'blocking': Boolean denoting whether you are blocking them } +Notification dicts +~~~~~~~~~~~~~~~~~~ +.. code-block:: python + + mastodon.notifications() + # Returns the following dictionary: + { + 'id': id of the notification. + 'type': "mention", "reblog", "favourite" or "follow". + 'status': In case of "mention", the mentioning status. + In case of reblog / favourite, the reblogged / favourited status. + 'account': User dict of the user from whom the notification originates. + } + Context dicts ~~~~~~~~~~~~~ .. code-block:: python mastodon.status_context() - # Returns + # Returns the following dictionary: { 'descendants': A list of toot dicts 'ancestors': A list of toot dicts @@ -124,7 +140,7 @@ Media dicts .. code-block:: python mastodon.media_post("image.jpg", "image/jpeg") - # Returns + # Returns the following dictionary: { 'text_url': The display text for the media (what shows up in toots) 'preview_url': The URL for the media preview diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py index 36f20d2..eb13859 100644 --- a/mastodon/Mastodon.py +++ b/mastodon/Mastodon.py @@ -209,7 +209,7 @@ class Mastodon: Fetch notifications (mentions, favourites, reblogs, follows) for the authenticated user. - Returns: TODO + Returns a list of notification dicts. """ return self.__api_request('GET', '/api/v1/notifications') From b958ce54ba32968ef159bda91c8f480c74374f68 Mon Sep 17 00:00:00 2001 From: Lorenz Diener Date: Fri, 25 Nov 2016 20:47:48 +0100 Subject: [PATCH 8/8] Minor typo fix --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index d7ade82..e7c9366 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -114,7 +114,7 @@ Notification dicts ~~~~~~~~~~~~~~~~~~ .. code-block:: python - mastodon.notifications() + mastodon.notifications()[0] # Returns the following dictionary: { 'id': id of the notification.