diff --git a/docs/index.rst b/docs/index.rst index 6cb782e..3921356 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -362,6 +362,25 @@ Relationship dicts # logged-in users Timeline } +Filter dicts +~~~~~~~~~~~~ +.. _filter dict: + +.. code-block:: python + + mastodon.account_follow() + # Returns the following dictionary: + { + 'id': # Numerical id of the filter + 'phrase': # Filtered keyword or phrase + 'context': # List of places where the filters are applied ('home', 'notifications', 'public', 'thread') + 'expires_at': # Expiry date for the filter + 'irreversible': # Boolean denoting if this filter is executed server-side + # or if it should be ran client-side (Note that Mastodon.py does + # not run client-side filters for you). + 'whole_word': # Boolean denoting whether this filter can match partial words + } + Notification dicts ~~~~~~~~~~~~~~~~~~ .. _notification dict: @@ -677,6 +696,13 @@ their relationships. .. automethod:: Mastodon.account_relationships .. automethod:: Mastodon.account_search +Writing data: Keyword filters +----------------------------- +These functions allow you to get information about keyword filters. + +.. automethod:: Mastodon.filters +.. automethod:: Mastodon.filter + Reading data: Follow suggestions -------------------------------- @@ -779,6 +805,14 @@ These functions allow you to interact with other accounts: To (un)follow and .. automethod:: Mastodon.account_unmute .. automethod:: Mastodon.account_update_credentials +Writing data: Keyword filters +----------------------------- +These functions allow you to manipulate keyword filters. + +.. automethod:: Mastodon.filter_create +.. automethod:: Mastodon.filter_update +.. automethod:: Mastodon.filter_delete + Writing data: Follow suggestions -------------------------------- diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py index 5e73622..0020710 100644 --- a/mastodon/Mastodon.py +++ b/mastodon/Mastodon.py @@ -173,6 +173,7 @@ class Mastodon: __DICT_VERSION_REPORT = "1.1.0" __DICT_VERSION_PUSH = "2.4.0" __DICT_VERSION_PUSH_NOTIF = "2.4.0" + __DICT_VERSION_FILTER = "2.4.3" ### # Registering apps @@ -832,6 +833,29 @@ class Mastodon: url = '/api/v1/accounts/{0}/lists'.format(str(id)) return self.__api_request('GET', url, params) + ### + # Reading data: Keyword filters + ### + @api_version("2.4.3", "2.4.3", __DICT_VERSION_FILTER) + def filters(): + """ + Fetch all of the logged-in users filters. + + Returns a list of `filter dicts`_. Not paginated. + """ + return self.__api_request('GET', '/api/v1/filters') + + @api_version("2.4.3", "2.4.3", __DICT_VERSION_FILTER) + def filter(id): + """ + Fetches information about the filter with the specified `id`. + + Returns a `filter dict`_. + """ + id = self.__unpack_id(id) + url = '/api/v1/filters/{0}'.format(str(id)) + return self.__api_request('GET', url) + ### # Reading data: Follow suggestions ### @@ -1469,13 +1493,65 @@ class Mastodon: return self.__api_request('PATCH', '/api/v1/accounts/update_credentials', params, files=files) + ### + # Writing data: Keyword filters + ### + @api_version("2.4.3", "2.4.3", __DICT_VERSION_FILTER) + def filter_create(phrase, context, irreversible = True, whole_word = True, expires_in = None): + """ + Creates a new keyword filter. `phrase` is the phrase that should be + filtered out, `context` specifies from where to filter the keywords. + Valid contexts are 'home', 'notifications', 'public' and 'thread'. + + Set `irreversible` to False if you want the filter to merely be applied + at client side. Note that Mastodon.py doesn't do any client-side + filtering for you. + + Set `whole_word` to False if you want to allow filter matches to + start or end within a word, not only at word boundaries. + + Set `expires_in` to specify for how many seconds the filter should be + kept around. + + Returns the `filter dict`_ of the newly created filter. + """ + params = self.__generate_params(locals()) + + for context_val in context: + if not context_val in ['home', 'notifications', 'public', 'thread']: + raise MastodonIllegalArgumentError('Invalid filter context.') + + return self.__api_request('POST', '/api/v1/filters', params) + + @api_version("2.4.3", "2.4.3", __DICT_VERSION_FILTER) + def filter_update(id, phrase = None, context = None, irreversible = None, whole_word = None, expires_in = None): + """ + Updates the filter with the given `id`. Parameters are the same + as in `filter_create()`. + + Returns the `filter dict`_ of the updated filter. + """ + id = self.__unpack_id(id) + params = self.__generate_params(locals(), ['id']) + url = '/api/v1/filters/{0}'.format(str(id)) + return self.__api_request('PUT', url, params) + + @api_version("2.4.3", "2.4.3", "2.4.3") + def filter_delete(id): + """ + Deletes the filter with the given `id`. + """ + id = self.__unpack_id(id) + url = '/api/v1/filters/{0}'.format(str(id)) + self.__api_request('DELETE', url) + ### # Writing data: Follow suggestions ### @api_version("2.4.3", "2.4.3", __DICT_VERSION_ACCOUNT) def suggestion_delete(self, account_id): """ - Remove a single user from the follow suggestions. + Remove the user with the given `account_id` from the follow suggestions. """ account_id = self.__unpack_id(account_id) url = '/api/v1/suggestions/{0}'.format(str(account_id)) @@ -1947,7 +2023,7 @@ class Mastodon: """ Parse dates in certain known json fields, if possible. """ - known_date_fields = ["created_at", "week", "day"] + known_date_fields = ["created_at", "week", "day", "expires_at"] for k, v in json_object.items(): if k in known_date_fields: try: