More "timeline" functions, "notifications"

CHANGELOG.rst

@@ -0,0 +1,13 @@
+A note on versioning: This librarys major version will grow with the APIs 
+version number. Breaking changes will be avoided as far as at all possible.
+
+v.1.0.1
+-------
+  * Added timeline_*() functions for consistency. timeline() functions as before.
+  * Clarified documentation in various places.
+  * Added previously-undocumented notifications() - API that gets a users notifications.
+  
+v.1.0.0
+-------
+
+ * Initial Release

docs/conf.py

@@ -68,7 +68,7 @@ author = u'Lorenz Diener'
 # The short X.Y version.
 version = u'1.0'
 # The full version, including alpha/beta/rc tags.
-release = u'1.0.0'
+release = u'1.0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -37,8 +37,11 @@ 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.
 
+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.
+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
@@ -68,6 +71,10 @@ This function allows you to access the timelines a logged in
 user could see, as well as hashtag timelines and the public timeline.
 
 .. automethod:: Mastodon.timeline
+.. automethod:: Mastodon.timeline_home
+.. automethod:: Mastodon.timeline_mentions
+.. automethod:: Mastodon.timeline_public
+.. automethod:: Mastodon.timeline_hashtag
 
 Reading data: Statuses
 ----------------------
@@ -78,6 +85,13 @@ These functions allow you to get information about single statuses.
 .. automethod:: Mastodon.status_reblogged_by
 .. automethod:: Mastodon.status_favourited_by
 
+Reading data: Notifications
+---------------------------
+This function allows you to get information about a users notifications.
+
+.. automethod:: Mastodon.notifications
+
+
 Reading data: Accounts
 ----------------------
 These functions allow you to get information about accounts and

mastodon/Mastodon.py

@@ -122,14 +122,40 @@ class Mastodon:
     ###
     # Reading data: Timelines
     ##
-    def timeline(self, timeline = 'home', max_id = None, since_id = None, limit = None):
+    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
-        or tag/:hashtag
+        or tag/hashtag. See the following functions documentation for what those do.
+        
+        The default timeline is the "home" timeline.
         """
         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).
+        """
+        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.
+        """
+        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.
+        """
+        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.
+        """
+        return self.timeline('tag/' + str(hashtag), max_id = max_id, since_id = since_id, limit = limit)
+    
     ###
     # Reading data: Statuses
     ###
@@ -157,6 +183,16 @@ class Mastodon:
         """
         return self.__api_request('GET', '/api/v1/statuses/' + str(id) + '/favourited_by')
     
+    ###
+    # Reading data: Notifications
+    ###
+    def notifications(self):
+        """
+        Returns notifications (mentions, favourites, reblogs, follows) for the authenticated
+        user.
+        """
+        return self.__api_request('GET', '/api/v1/notifications')
+    
     ###
     # Reading data: Accounts
     ###
@@ -312,7 +348,9 @@ class Mastodon:
         type has to be specified manually, otherwise, it is
         determined from the file name.
         
-        Returns the ID of the media that can then be used in status_post().
+        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.

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 setup(name='Mastodon.py',
-      version='1.0.0',
+      version='1.0.1',
       description='Python wrapper for the Mastodon API',
       packages=['mastodon'],
       install_requires=['requests'],