From 0524dd1f2b130fdaddd2d209716bf99236b02a22 Mon Sep 17 00:00:00 2001 From: Lydia Date: Fri, 25 Nov 2016 12:52:55 -0500 Subject: [PATCH 1/3] Add documentation examples --- docs/index.rst | 91 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index a91cfb7..85f1982 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -81,7 +81,20 @@ 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() + # Returns + { + 'descendants': A list of toot dicts + 'ancestors': A list of toot dicts + } +Note that this can only be called on statuses belonging to the currently logged-in user. + .. automethod:: Mastodon.status_reblogged_by .. automethod:: Mastodon.status_favourited_by @@ -91,6 +104,8 @@ 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 ---------------------- @@ -99,13 +114,37 @@ their relationships. .. automethod:: Mastodon.account .. automethod:: Mastodon.account_verify_credentials + +These methods return an account dict: +.. code-block:: python + mastodon.account() + # Returns + { + 'display_name': The user's display name + 'acct': The user's account name (what you @ them with) + 'following_count': How many people they follow + 'url': Their URL; usually 'https://mastodon.social/users/' + '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 + 'username': Usually same as acct + } + .. 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 @@ -113,17 +152,56 @@ interact with already posted statuses. .. automethod:: Mastodon.status_post .. automethod:: Mastodon.toot -.. automethod:: Mastodon.status_delete .. automethod:: Mastodon.status_reblog .. 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=: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: '

Hello from Python

' + '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() + # 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() + # Returns + { + '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 + } + .. automethod:: Mastodon.account_follow .. automethod:: Mastodon.account_unfollow .. automethod:: Mastodon.account_block @@ -137,6 +215,17 @@ 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 on Amazon S3 + 'type': Media type, EG 'image' + 'url': The URL for the media on Amazon S3 + } + .. _Mastodon: https://github.com/Gargron/mastodon .. _Mastodon flagship instance: http://mastodon.social/ .. _Mastodon api docs: https://github.com/Gargron/mastodon/wiki/API From e94445c86b4dcaa14c79e7c36a7145c42b25ed9d Mon Sep 17 00:00:00 2001 From: Lydia Date: Fri, 25 Nov 2016 13:43:13 -0500 Subject: [PATCH 2/3] Corrections --- docs/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 85f1982..667890f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -121,7 +121,7 @@ These methods return an account dict: # Returns { 'display_name': The user's display name - 'acct': The user's account name (what you @ them with) + '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/' 'statuses_count': How many statuses they have @@ -130,7 +130,7 @@ These methods return an account dict: 'note': Their bio 'header': URL for their header image 'id': Same as - 'username': Usually same as acct + 'username': The username (what you @ them with) } .. automethod:: Mastodon.account_statuses @@ -221,9 +221,9 @@ Returns a media dict: # Returns { 'text_url': The display text for the media (what shows up in toots) - 'preview_url': The URL for the media preview on Amazon S3 + 'preview_url': The URL for the media preview 'type': Media type, EG 'image' - 'url': The URL for the media on Amazon S3 + 'url': The URL for the media } .. _Mastodon: https://github.com/Gargron/mastodon From eaa49d87f8caaec39a0fba9fc269ef60e9f832fc Mon Sep 17 00:00:00 2001 From: Lydia Date: Fri, 25 Nov 2016 13:54:40 -0500 Subject: [PATCH 3/3] Corrections --- docs/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 667890f..a9ecf49 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -93,7 +93,6 @@ Returns a single toot dict for the given status. 'descendants': A list of toot dicts 'ancestors': A list of toot dicts } -Note that this can only be called on statuses belonging to the currently logged-in user. .. automethod:: Mastodon.status_reblogged_by .. automethod:: Mastodon.status_favourited_by