spla/Mastodonplus.py
1
0
Fork 0
Codi Incidències Sol·licituds Pull Paquets Projectes Llançaments Wiki Activitat

Documentation restructured and made more PEP8-y

Explorar la Font
This commit is contained in:
Lorenz Diener 2016-11-25 20:33:00 +01:00
pare 4a3e2d232d
commit 3585830182
S'han modificat 2 arxius amb 172 adicions i 156 eliminacions
Mostrar estadístiques Descarregar el fitxer de pedaç Descarregar el fitxer de diferències Expand all files Collapse all files

194
docs/index.rst
Veure arxiu

@ -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/<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/

134
mastodon/Mastodon.py
Veure arxiu

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