From 2729ca19319edcc7a0d8df3e211010ccf857b211 Mon Sep 17 00:00:00 2001 From: Lorenz Diener Date: Fri, 25 Nov 2016 15:39:53 +0100 Subject: More "timeline" functions, "notifications" --- CHANGELOG.rst | 13 +++++++++++++ docs/conf.py | 2 +- docs/index.rst | 16 +++++++++++++++- mastodon/Mastodon.py | 44 +++++++++++++++++++++++++++++++++++++++++--- setup.py | 2 +- 5 files changed, 71 insertions(+), 6 deletions(-) create mode 100644 CHANGELOG.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 0000000..e099b66 --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 2914f78..a893c03 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 6439f69..a91cfb7 100644 --- a/docs/index.rst +++ b/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 diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py index e3aac69..7bd6473 100644 --- a/mastodon/Mastodon.py +++ b/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. diff --git a/setup.py b/setup.py index 6a4df40..74292fd 100644 --- a/setup.py +++ b/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'], -- cgit v1.2.3