Update return documentation

Closes gh-173

.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Tests
+
+on: [push]
+
+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"
 

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,12 @@
 Release history
 ===============
 
+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 = '0.9'
 # The full version, including alpha/beta/rc tags.
-release = '0.8.0'
+release = '0.9.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__ = "0.9.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,19 @@ 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), **kwargs)
+
     def hot_topics(self, **kwargs):
         """
 
@@ -462,6 +537,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 +616,7 @@ class DiscourseClient(object):
 
     def update_topic(self, topic_url, title, **kwargs):
         """
-        Update a topic 
+        Update a topic
 
         Args:
             topic_url:
@@ -702,7 +791,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,7 +939,7 @@ class DiscourseClient(object):
                 ]
 
         """
-        return self._get("/admin/groups.json", **kwargs)
+        return self._get("/groups/search.json", **kwargs)
 
     def group(self, group_name):
         """
@@ -1258,6 +1347,7 @@ class DiscourseClient(object):
             params: dictionary of parameters to include to the API
 
         Returns:
+            dictionary of response body data or None
 
         """
         params["api_key"] = self.api_key
@@ -1266,32 +1356,66 @@ class DiscourseClient(object):
         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,
-        )
 
-        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:
+            response = requests.request(
+                verb,
+                url,
+                allow_redirects=False,
+                params=params,
+                files=files,
+                data=data,
+                json=json,
+                headers=headers,
+                timeout=self.timeout,
+            )
 
-            raise DiscourseServerError(msg, response=response)
+            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,):
 
@@ -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 =