From 7cfb17d6981c0814c3b5c38f3bc9712a73d1da03 Mon Sep 17 00:00:00 2001 From: Lorenz Diener Date: Wed, 26 Apr 2017 12:19:41 +0200 Subject: [PATCH] Documentation and consistence changes --- docs/index.rst | 91 ++++++++++++++++++++++++++------------------ mastodon/Mastodon.py | 9 ++++- 2 files changed, 62 insertions(+), 38 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index cba55f3..bad52d2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -109,24 +109,24 @@ Toot dicts mastodon.toot("Hello from Python") # Returns the following dictionary: { - 'sensitive': Denotes whether media attachments to the toot are 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 - 'media_attachments': list of media dicts of attached files. Only present - when there are attached files. - '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

' - 'spoiler_text': Warning text that should be displayed before the toot content - 'favourited': Denotes whether the logged in user has favourited this toot - 'account': Account dict for the logged in account + 'sensitive': # Denotes whether media attachments to the toot are 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 + 'media_attachments': # list of media dicts of attached files. Only present + # when there are attached files. + '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

' + 'spoiler_text': # Warning text that should be displayed before the toot content + 'favourited': # Denotes whether the logged in user has favourited this toot + 'account': # Account dict for the logged in account } Relationship dicts @@ -136,12 +136,12 @@ Relationship dicts mastodon.account_follow() # Returns the following dictionary: { - '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 - 'muting': Boolean denoting whether you are muting them - 'requested': Boolean denoting whether you have sent them a follow request + '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 + 'muting': # Boolean denoting whether you are muting them + 'requested': # Boolean denoting whether you have sent them a follow request } Notification dicts @@ -151,11 +151,11 @@ Notification dicts mastodon.notifications()[0] # 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. + '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 @@ -165,8 +165,8 @@ Context dicts mastodon.status_context() # Returns the following dictionary: { - 'descendants': A list of toot dicts - 'ancestors': A list of toot dicts + 'descendants': # A list of toot dicts + 'ancestors': # A list of toot dicts } Media dicts @@ -176,10 +176,10 @@ Media dicts mastodon.media_post("image.jpg", "image/jpeg") # 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 - 'type': Media type, EG 'image' - 'url': The URL for the media + '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 @@ -200,6 +200,7 @@ methods for this are provided. .. automethod:: Mastodon.create_app .. automethod:: Mastodon.__init__ .. automethod:: Mastodon.log_in +.. automethod:: Mastodon.auth_request_url Reading data: Timelines ----------------------- @@ -237,9 +238,17 @@ their relationships. .. automethod:: Mastodon.account_statuses .. automethod:: Mastodon.account_following .. automethod:: Mastodon.account_followers +.. automethod:: Mastodon.follows .. automethod:: Mastodon.account_relationships .. automethod:: Mastodon.account_search +Reading data: Searching +----------------------- +This function allows you to search for content. + +.. automethod:: Mastodon.search + + Reading data: Mutes and blocks ------------------------------ These functions allow you to get information about accounts that are @@ -253,7 +262,7 @@ Reading data: Favourites This function allows you to get information about statuses favourited by the authenticated user. -.. authomethod:: Mastodon.favourites +.. automethod:: Mastodon.favourites Reading data: Follow requests ----------------------------- @@ -302,7 +311,15 @@ to attach media to statuses. .. automethod:: Mastodon.media_post +Streaming +--------- +These functions allow access to the streaming API. + +.. automethod:: Mastodon.user_stream +.. automethod:: Mastodon.public_stream +.. automethod:: Mastodon.hashtag_stream + .. _Mastodon: https://github.com/Gargron/mastodon .. _Mastodon flagship instance: http://mastodon.social/ -.. _Mastodon api docs: https://github.com/Gargron/mastodon/wiki/API +.. _Mastodon api docs: https://github.com/Gargron/mastodon/wiki/API \ No newline at end of file diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py index e670a7f..88daac8 100644 --- a/mastodon/Mastodon.py +++ b/mastodon/Mastodon.py @@ -133,19 +133,23 @@ class Mastodon: def __get_token_expired(self): + """Internal helper for oauth code""" if self._token_expired < datetime.datetime.now(): return True else: return False def __set_token_expired(self, value): + """Internal helper for oauth code""" self._token_expired = datetime.datetime.now() + datetime.timedelta(seconds=value) return def __get_refresh_token(self): + """Internal helper for oauth code""" return self._refresh_token def __set_refresh_token(self, value): + """Internal helper for oauth code""" self._refresh_token = value return @@ -414,7 +418,7 @@ class Mastodon: ### # Reading data: Searching ### - def content_search(self, q, resolve = False): + def search(self, q, resolve = False): """ Fetch matching hashtags, accounts and statuses. Will search federated instances if resolve is True. @@ -676,6 +680,9 @@ class Mastodon: media_file_description = (file_name, media_file, mime_type) return self.__api_request('POST', '/api/v1/media', files = {'file': media_file_description}) + ### + # Streaming + ### def user_stream(self, listener): """ Streams events that are relevant to the authorized user, i.e. home