Documentation restructured and made more PEP8-y

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
+User dicts
-.. py:class: Mastodon
+~~~~~~~~~~
+
+.. 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/<acct>'
+     '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 <numerical id>
+     '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=<id>: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: '<p>Hello from Python</p>'
+    '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(<numerical id>)
+    # Returns
+    {
+     'followed_by': Boolean denoting whether they follow you back
+     'following': Boolean denoting whether you follow them
+     'id': Numerical id (same one as <numerical id>)
+     'blocking': Boolean denoting whether you are blocking them
+    }
+
+Context dicts
+~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    mastodon.status_context(<numerical id>)
+    # 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(<numerical id>)
-    # 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(<numerical id>)
-    # 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/<acct>'
-     '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 <numerical id>
-     '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=<id>: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: '<p>Hello from Python</p>'
-    '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(<numerical id>)
-   # 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(<numerical id>)
-    # Returns
-    {
-     'followed_by': Boolean denoting whether they follow you back
-     'following': Boolean denoting whether you follow them
-     'id': Numerical id (same one as <numerical id>)
-     '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/

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')