Add keyword filters

docs/index.rst

@@ -362,6 +362,25 @@ Relationship dicts
                            # logged-in users Timeline
     }
 
+Filter dicts
+~~~~~~~~~~~~
+.. _filter dict:
+ 
+.. code-block:: python
+
+    mastodon.account_follow(<numerical id>)
+    # 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
 --------------------------------
 

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: