Fix 413 response from Discourse due to empty dict passed as json

Due to some changes in the Discourse API, certain methods now work better if redirects are allowed.

Get /c/{id}.json will redirect to /c/{category_slug}.json which will cause the client.category_topics(id) method to fail as the redirect is not followed by default.

Now the keyword arguments to requests.request can be overridden by individual methods. This is implemented for .category_topics

.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+
+    name: Test on Python ${{ matrix.py_version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        py_version: [2.7, 3.5, 3.6, 3.7]
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Python ${{ matrix.py_version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.py_version }}
+    - name: Install mock for Python 2.7
+      run: pip install mock
+    - name: Run tests
+      run: python setup.py test

.travis.yml

@@ -4,6 +4,7 @@ python:
     - "2.7"
     - "3.4"
     - "3.5"
+    - "3.6"
     - "pypy"
     - "pypy3"
 

AUTHORS

@@ -9,4 +9,4 @@ Scott Nixon
 Jason Dorweiler
 Pierre-Alain Dupont
 Karl Goetz
-
+Alex Kerney

CONTRIBUTING.rst

@@ -69,5 +69,8 @@ Once running you can access the Discourse install at http://localhost:4000.
 TODO
 ====
 
-Refer to, https://github.com/discourse/discourse_api/blob/master/routes.txt for
-a list of all operations available in Discourse.
+For a list of all operations:
+
+    you can just run rake routes inside of the discourse repo to get an up to date list
+
+Or check the old [`routes.txt`](https://github.com/discourse/discourse_api/blob/aa75df6cd851f0666f9e8071c4ef9dfdd39fc8f8/routes.txt) file, though this is certainly outdated.

HISTORY.rst

@@ -3,6 +3,22 @@
 Release history
 ===============
 
+1.1.0
+-----
+
+- Added ability to follow redirects in requests
+
+1.0.0
+-----
+
+- Authenticate with headers
+
+0.9.0
+-----
+
+- Added rate limiting support
+- Added some support for user activation
+
 0.8.0
 -----
 

README.rst

@@ -2,9 +2,14 @@
 pydiscourse
 ===========
 
-.. image:: https://secure.travis-ci.org/bennylope/pydiscourse.svg?branch=master
+.. image:: https://github.com/bennylope/pydiscourse/workflows/Tests/badge.svg
     :alt: Build Status
-    :target: http://travis-ci.org/bennylope/pydiscourse
+    :target: https://github.com/bennylope/pydiscourse/actions
+
+.. image:: https://img.shields.io/badge/Check%20out%20the-Docs-blue.svg
+    :alt: Check out the Docs
+    :target: https://discourse.readthedocs.io/en/latest/
+
 
 A Python library for working with Discourse.
 

docs/conf.py

@@ -51,9 +51,9 @@ copyright = u'2014, Marc Sibson'
 # built documents.
 #
 # The short X.Y version.
-version = '0.8'
+version = '1.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.8.0'
+release = '1.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

pydiscourse/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
 
-__version__ = "0.8.0"
+__version__ = "1.1.0"
 
 from pydiscourse.client import DiscourseClient

pydiscourse/client.py

@@ -3,11 +3,17 @@ Core API client module
 """
 
 import logging
+import time
 
 import requests
 
+from datetime import timedelta, datetime
+
 from pydiscourse.exceptions import (
-    DiscourseError, DiscourseServerError, DiscourseClientError
+    DiscourseError,
+    DiscourseServerError,
+    DiscourseClientError,
+    DiscourseRateLimitedError,
 )
 from pydiscourse.sso import sso_payload
 
@@ -58,6 +64,15 @@ class DiscourseClient(object):
         """
         return self._get("/users/{0}.json".format(username))["user"]
 
+    def approve(self, user_id):
+        return self._get("/admin/users/{0}/approve.json".format(user_id))
+
+    def activate(self, user_id):
+        return self._put("/admin/users/{0}/activate.json".format(user_id))
+
+    def deactivate(self, user_id):
+        return self._put("/admin/users/{0}/deactivate.json".format(user_id))
+
     def user_all(self, user_id):
         """
         Get all user information for a specific user, needs to be admin
@@ -69,6 +84,50 @@ class DiscourseClient(object):
         """
         return self._get("/admin/users/{0}.json".format(user_id))
 
+    def invite(self, email, group_names, custom_message, **kwargs):
+        """
+        Invite a user by email to join your forum
+
+        Args:
+            email: their email, will be used for activation and summary emails
+            group_names: the group names
+            custom_message: message to include
+            **kwargs: ???? what else can be sent through?
+
+        Returns:
+            API response body (dict)
+
+        """
+        return self._post(
+            "/invites",
+            email=email,
+            group_names=group_names,
+            custom_message=custom_message,
+            **kwargs
+        )
+
+    def invite_link(self, email, group_names, custom_message, **kwargs):
+        """
+        Generate an invite link for a user to join your forum
+
+        Args:
+            email: their email, will be used for activation and summary emails
+            group_names: the group names
+            custom_message: message to include
+            **kwargs: ???? what else can be sent through?
+
+        Returns:
+            Invite link
+
+        """
+        return self._post(
+            "/invites/link",
+            email=email,
+            group_names=group_names,
+            custom_message=custom_message,
+            **kwargs
+        )
+
     def create_user(self, name, username, email, password, **kwargs):
         """
         Create a Discourse user
@@ -153,8 +212,11 @@ class DiscourseClient(object):
             ????
 
         """
+        suspend_until = (datetime.now() + timedelta(days=duration)).isoformat()
         return self._put(
-            "/admin/users/{0}/suspend".format(userid), duration=duration, reason=reason
+            "/admin/users/{0}/suspend".format(userid),
+            suspend_until=suspend_until,
+            reason=reason,
         )
 
     def unsuspend(self, userid):
@@ -416,6 +478,23 @@ class DiscourseClient(object):
             "/topics/private-messages-unread/{0}.json".format(username), **kwargs
         )
 
+    def category_topics(self, category_id, **kwargs):
+        """
+        Returns a list of all topics in a category.
+
+        Args:
+            **kwargs:
+
+        Returns:
+            JSON API response
+
+        """
+        return self._get(
+            "/c/{0}.json".format(category_id),
+            override_request_kwargs={"allow_redirects": True},
+            **kwargs
+        )
+
     def hot_topics(self, **kwargs):
         """
 
@@ -462,6 +541,20 @@ class DiscourseClient(object):
         """
         return self._get("/t/{0}/{1}.json".format(slug, topic_id), **kwargs)
 
+    def delete_topic(self, topic_id, **kwargs):
+        """
+        Remove a topic
+
+        Args:
+            category_id:
+            **kwargs:
+
+        Returns:
+            JSON API response
+
+        """
+        return self._delete(u"/t/{0}".format(topic_id), **kwargs)
+
     def post(self, topic_id, post_id, **kwargs):
         """
 
@@ -527,7 +620,7 @@ class DiscourseClient(object):
 
     def update_topic(self, topic_url, title, **kwargs):
         """
-        Update a topic 
+        Update a topic
 
         Args:
             topic_url:
@@ -702,7 +795,7 @@ class DiscourseClient(object):
             text_color: hex color without number symbol
             permissions: dict of 'everyone', 'admins', 'moderators', 'staff' with values of ???
             parent: name of the category
-            parent_category_id: 
+            parent_category_id:
             **kwargs:
 
         Returns:
@@ -850,13 +943,13 @@ class DiscourseClient(object):
                 ]
 
         """
-        return self._get("/admin/groups.json", **kwargs)
+        return self._get("/groups/search.json", **kwargs)
 
     def group(self, group_name):
         """
         Get all infos of a group by group name
         """
-        return self._get("/groups/{0}/members.json".format(group_name))
+        return self._get("/groups/{0}.json".format(group_name))
 
     def create_group(
         self,
@@ -1192,7 +1285,7 @@ class DiscourseClient(object):
         kwargs["parent_tag_name"] = parent_tag_name
         return self._post("/tag_groups", json=True, **kwargs)["tag_group"]
 
-    def _get(self, path, **kwargs):
+    def _get(self, path, override_request_kwargs=None, **kwargs):
         """
 
         Args:
@@ -1202,9 +1295,9 @@ class DiscourseClient(object):
         Returns:
 
         """
-        return self._request(GET, path, params=kwargs)
+        return self._request(GET, path, params=kwargs, override_request_kwargs=override_request_kwargs)
 
-    def _put(self, path, json=False, **kwargs):
+    def _put(self, path, json=False, override_request_kwargs=None, **kwargs):
         """
 
         Args:
@@ -1215,12 +1308,12 @@ class DiscourseClient(object):
 
         """
         if not json:
-            return self._request(PUT, path, data=kwargs)
+            return self._request(PUT, path, data=kwargs, override_request_kwargs=override_request_kwargs)
 
         else:
-            return self._request(PUT, path, json=kwargs)
+            return self._request(PUT, path, json=kwargs, override_request_kwargs=override_request_kwargs)
 
-    def _post(self, path, files={}, json=False, **kwargs):
+    def _post(self, path, files=None, json=False, override_request_kwargs=None, **kwargs):
         """
 
         Args:
@@ -1231,12 +1324,12 @@ class DiscourseClient(object):
 
         """
         if not json:
-            return self._request(POST, path, files=files, data=kwargs)
+            return self._request(POST, path, files=files, data=kwargs, override_request_kwargs=override_request_kwargs)
 
         else:
-            return self._request(POST, path, files=files, json=kwargs)
+            return self._request(POST, path, files=files, json=kwargs, override_request_kwargs=override_request_kwargs)
 
-    def _delete(self, path, **kwargs):
+    def _delete(self, path, override_request_kwargs=None, **kwargs):
         """
 
         Args:
@@ -1246,9 +1339,11 @@ class DiscourseClient(object):
         Returns:
 
         """
-        return self._request(DELETE, path, params=kwargs)
+        return self._request(DELETE, path, params=kwargs, override_request_kwargs=override_request_kwargs)
 
-    def _request(self, verb, path, params={}, files={}, data={}, json={}):
+    def _request(
+        self, verb, path, params=None, files=None, data=None, json=None, override_request_kwargs=None
+    ):
         """
         Executes HTTP request to API and handles response
 
@@ -1256,42 +1351,83 @@ class DiscourseClient(object):
             verb: HTTP verb as string: GET, DELETE, PUT, POST
             path: the path on the Discourse API
             params: dictionary of parameters to include to the API
+            override_request_kwargs: dictionary of requests.request keyword arguments to override defaults
 
         Returns:
+            dictionary of response body data or None
 
         """
-        params["api_key"] = self.api_key
-        if "api_username" not in params:
-            params["api_username"] = self.api_username
+        override_request_kwargs = override_request_kwargs or {}
+
         url = self.host + path
 
-        headers = {"Accept": "application/json; charset=utf-8"}
-        response = requests.request(
-            verb,
-            url,
-            allow_redirects=False,
-            params=params,
-            files=files,
-            data=data,
-            json=json,
-            headers=headers,
-            timeout=self.timeout,
-        )
+        headers = {
+            "Accept": "application/json; charset=utf-8",
+            "Api-Key": self.api_key,
+            "Api-Username": self.api_username,
+        }
 
-        log.debug("response %s: %s", response.status_code, repr(response.text))
-        if not response.ok:
-            try:
-                msg = u",".join(response.json()["errors"])
-            except (ValueError, TypeError, KeyError):
-                if response.reason:
-                    msg = response.reason
-                else:
-                    msg = u"{0}: {1}".format(response.status_code, response.text)
+        # How many times should we retry if rate limited
+        retry_count = 4
+        # Extra time (on top of that required by API) to wait on a retry.
+        retry_backoff = 1
 
-            if 400 <= response.status_code < 500:
-                raise DiscourseClientError(msg, response=response)
+        while retry_count > 0:
+            request_kwargs = dict(
+                allow_redirects=False,
+                params=params,
+                files=files,
+                data=data,
+                json=json,
+                headers=headers,
+                timeout=self.timeout,
+            )
 
-            raise DiscourseServerError(msg, response=response)
+            request_kwargs.update(override_request_kwargs)
+
+            response = requests.request(verb, url, **request_kwargs)
+
+            log.debug("response %s: %s", response.status_code, repr(response.text))
+            if response.ok:
+                break
+            if not response.ok:
+                try:
+                    msg = u",".join(response.json()["errors"])
+                except (ValueError, TypeError, KeyError):
+                    if response.reason:
+                        msg = response.reason
+                    else:
+                        msg = u"{0}: {1}".format(response.status_code, response.text)
+
+                if 400 <= response.status_code < 500:
+                    if 429 == response.status_code:
+                        # This codepath relies on wait_seconds from Discourse v2.0.0.beta3 / v1.9.3 or higher.
+                        rj = response.json()
+                        wait_delay = (
+                            retry_backoff + rj["extras"]["wait_seconds"]
+                        )  # how long to back off for.
+
+                        if retry_count > 1:
+                            time.sleep(wait_delay)
+                        retry_count -= 1
+                        log.info(
+                            "We have been rate limited and waited {0} seconds ({1} retries left)".format(
+                                wait_delay, retry_count
+                            )
+                        )
+                        log.debug("API returned {0}".format(rj))
+                        continue
+                    else:
+                        raise DiscourseClientError(msg, response=response)
+
+                # Any other response.ok resulting in False
+                raise DiscourseServerError(msg, response=response)
+
+        if retry_count == 0:
+            raise DiscourseRateLimitedError(
+                "Number of rate limit retries exceeded. Increase retry_backoff or retry_count",
+                response=response,
+            )
 
         if response.status_code == 302:
             raise DiscourseError(

pydiscourse/exceptions.py

@@ -11,3 +11,7 @@ class DiscourseServerError(DiscourseError):
 
 class DiscourseClientError(DiscourseError):
     """ An invalid request has been made """
+
+
+class DiscourseRateLimitedError(DiscourseError):
+    """ Request required more than the permissible number of retries """

setup.py

@@ -34,15 +34,16 @@ setup(
         ]
     },
     classifiers=[
-        "Development Status :: 3 - Alpha",
+        "Development Status :: 5 - Production/Stable",
         "Environment :: Web Environment",
         "Intended Audience :: Developers",
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
         "Programming Language :: Python",
         "Programming Language :: Python :: 2.7",
-        "Programming Language :: Python :: 3.4",
         "Programming Language :: Python :: 3.5",
+        "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.7",
         'Programming Language :: Python :: Implementation :: PyPy',
     ],
     zip_safe=False,

tests/test_client.py

@@ -1,10 +1,13 @@
 import sys
 import unittest
-import mock
+
+try:
+    from unittest import mock
+except ImportError:
+    import mock
 
 from pydiscourse import client
 
-import sys
 
 if sys.version_info < (3,):
 
@@ -46,12 +49,12 @@ class ClientBaseTestCase(unittest.TestCase):
         self.assertEqual(args[0], verb)
         self.assertEqual(args[1], self.host + url)
 
-        kwargs = kwargs["params"]
-        self.assertEqual(kwargs.pop("api_username"), self.api_username)
-        self.assertEqual(kwargs.pop("api_key"), self.api_key)
+        headers = kwargs["headers"]
+        self.assertEqual(headers.pop("Api-Username"), self.api_username)
+        self.assertEqual(headers.pop("Api-Key"), self.api_key)
 
         if verb == "GET":
-            self.assertEqual(kwargs, params)
+            self.assertEqual(kwargs["params"], params)
 
 
 class TestClientRequests(ClientBaseTestCase):
@@ -179,7 +182,7 @@ class TestTopics(ClientBaseTestCase):
         )
 
 
-@mock.patch("requests.request")
+@mock.patch("pydiscourse.client.requests.request")
 class MiscellaneousTests(ClientBaseTestCase):
 
     def test_search(self, request):

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py27, py34, py35, pypy, pypy3
+envlist = py27, py34, py35, py36, py37, pypy, pypy3
 
 [testenv]
 setenv =