Remove Python 3.7 support

Respect pagination when returning all group members

.git-blame-ignore-revs

@@ -0,0 +1,3 @@
+c0db7215c95dbd31770ade1fc6ea65aa426d4590
+0177c46356b9d0fc4b93f09aab7a224643a3685e
+f6b4c02fc0f144dffc88cdd48b8261a69228d2f0

.github/workflows/pypi.yml

@@ -0,0 +1,33 @@
+name: Publish package to PyPI
+
+on: 
+  push:
+    branches: [master]
+  release:
+    types: [created]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools wheel twine
+
+    - name: Build and publish distribution
+      if: (github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')) || github.event_name == 'release'
+      env: 
+        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+      run: |
+        python setup.py sdist bdist_wheel
+        twine upload dist/*

.github/workflows/test.yml

@@ -1,23 +1,25 @@
 name: Tests
 
-on: [push]
+on: [ push, pull_request ]
 
 jobs:
   test:
 
-    name: Test on Python ${{ matrix.py_version }}
+    name: Test on Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        py_version: [2.7, 3.5, 3.6, 3.7]
+        python-version: [ "3.8", "3.9", "3.10", "3.11" ]
 
     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
+      - uses: actions/checkout@v1
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox tox-gh-actions
+      - name: Test with tox
+        run: tox

.gitignore

@@ -36,3 +36,9 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+
+# Pyenv
+.python-version
+
+# PyCharm
+.idea

.travis.yml

@@ -1,11 +0,0 @@
-sudo: false
-language: python
-python:
-    - "2.7"
-    - "3.4"
-    - "3.5"
-    - "3.6"
-    - "pypy"
-    - "pypy3"
-
-script: python setup.py test

AUTHORS

@@ -9,4 +9,7 @@ Scott Nixon
 Jason Dorweiler
 Pierre-Alain Dupont
 Karl Goetz
-
+Alex Kerney
+Gustav <https://github.com/dkgv>
+Sebastian2023 <https://github.com/Sebastian2023>
+Dominik George <https://github.com/Natureshadow>

CONTRIBUTING.rst

@@ -43,7 +43,7 @@ Or it's slightly faster cousin `detox
 
 Alternatively, you can run the self test with the following commands::
 
-    pip install -r requirements.dev.txt
+    pip install -r requirements.txt
     pip install -e .
     python setup.py test
 

HISTORY.rst

@@ -3,6 +3,56 @@
 Release history
 ===============
 
+1.5.0
+-----
+
+- Owner creation endpoint update from @akhmerov
+- Python 3.11 support from @Dettorer
+- Group membership fixes from @inducer
+- Rate limiting fixes from @inducer
+- Latest posts endpoint from @max-lancaster
+
+
+1.4.0
+-----
+
+- Documented here as skipped release
+
+1.3.0
+-----
+
+- Add fix for handling global Discourse timeouts
+- Add group owners
+- Update API for add_group_owner
+
+1.2.0
+-----
+
+- BREAKING? Dropped support for Python 2.7, 3.4, 3.5
+- Added numerous new endpoint queries
+- Updated category querying
+
+1.1.2
+-----
+
+- Fix for Discourse users API change
+
+1.1.1
+-----
+
+- Fix for empty dictionary and 413 API response
+- Fix for getting member groups
+
+1.1.0
+-----
+
+- Added ability to follow redirects in requests
+
+1.0.0
+-----
+
+- Authenticate with headers
+
 0.9.0
 -----
 

docs/conf.py

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

pydiscourse/__init__.py

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

pydiscourse/exceptions.py

@@ -1,17 +0,0 @@
-from requests.exceptions import HTTPError
-
-
-class DiscourseError(HTTPError):
-    """ A generic error while attempting to communicate with Discourse """
-
-
-class DiscourseServerError(DiscourseError):
-    """ The Discourse Server encountered an error while processing the request """
-
-
-class DiscourseClientError(DiscourseError):
-    """ An invalid request has been made """
-
-
-class DiscourseRateLimitedError(DiscourseError):
-    """ Request required more than the permissible number of retries """

requirements.txt

@@ -0,0 +1,2 @@
+pytest==6.2.5
+pytest-cov==3.0.0

setup.cfg

@@ -1,2 +1,47 @@
-[wheel]
+[metadata]
+name = pydiscourse
+version = attr: pydiscourse.__version__
+author = "Marc Sibson and contributors"
+author_email = "ben@benlopatin.com"
+license = "MIT"
+url = https://github.com/bennylope/pydiscourse
+description = "A Python library for the Discourse API"
+long_description = file: README.rst, HISTORY.rst
+platforms =
+    OS Independent
+
+[options]
+zip_safe = False
+include_package_data = True
+packages = find:
+package_dir =
+    =src
+install_requires =
+    requests>=2.4.2
+    typing; python_version<"3.6"
+classifiers =
+    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 :: 3.8
+    Programming Language :: Python :: 3.9
+    Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
+
+[options.packages.find]
+where=src
+
+[options.entry_points]
+console_scripts =
+    pydiscoursecli = pydiscourse.main:main
+
+[bdist_wheel]
 universal = 1
+
+[build-system]
+requires =
+    setuptools >= "40.9.0"
+    wheel

setup.py

@@ -1,50 +1,7 @@
-from setuptools import setup, find_packages
+# -*- coding: utf-8 -*-
+"""
+See setup.cfg for packaging settings
+"""
 
-
-README = open('README.rst').read()
-HISTORY = open('HISTORY.rst').read().replace('.. :changelog:', '')
-
-with open("pydiscourse/__init__.py", "r") as module_file:
-    for line in module_file:
-        if line.startswith("__version__"):
-            version_string = line.split("=")[1]
-            VERSION = version_string.strip().replace("\"", "")
-
-
-setup(
-    name="pydiscourse",
-    version=VERSION,
-    description="A Python library for the Discourse API",
-    long_description=README + '\n\n' + HISTORY,
-    author="Marc Sibson and contributors",
-    author_email="ben+pydiscourse@benlopatin.com",
-    license="BSD",
-    url="https://github.com/bennylope/pydiscourse",
-    packages=find_packages(exclude=["tests.*", "tests"]),
-    install_requires=[
-        'requests>=2.4.2',
-    ],
-    tests_require=[
-        'mock',
-    ],
-    test_suite='tests',
-    entry_points={
-        'console_scripts': [
-            'pydiscoursecli = pydiscourse.main:main'
-        ]
-    },
-    classifiers=[
-        "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.5",
-        "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: 3.7",
-        'Programming Language :: Python :: Implementation :: PyPy',
-    ],
-    zip_safe=False,
-)
+from setuptools import setup
+setup()

src/pydiscourse/__init__.py

@@ -0,0 +1,8 @@
+"""Python client for the Discourse API."""
+
+__version__ = "1.5.0"
+
+from pydiscourse.client import DiscourseClient
+
+
+__all__ = ["DiscourseClient"]

src/pydiscourse/client.py

@@ -128,6 +128,30 @@ class DiscourseClient(object):
             **kwargs
         )
 
+    def user_by_id(self, pk):
+        """
+        Get user from ID
+
+        Args:
+            pk: user id
+
+        Returns:
+            user
+        """
+        return self._get("/admin/users/{0}.json".format(pk))
+
+    def user_by_email(self, email):
+        """
+        Get user from email
+
+        Args:
+            email: user email
+
+        Returns:
+            user
+        """
+        return self._get("/admin/users/list/all.json?email={0}".format(email))
+
     def create_user(self, name, username, email, password, **kwargs):
         """
         Create a Discourse user
@@ -147,7 +171,7 @@ class DiscourseClient(object):
             ????
 
         """
-        r = self._get("/users/hp.json")
+        r = self._get("/session/hp.json")
         challenge = r["challenge"][::-1]  # reverse challenge, discourse security check
         confirmations = r["value"]
         return self._post(
@@ -371,7 +395,7 @@ class DiscourseClient(object):
         """
         return self._put(
             "/users/{0}/preferences/username".format(username),
-            username=new_username,
+            new_username=new_username,
             **kwargs
         )
 
@@ -489,8 +513,14 @@ class DiscourseClient(object):
             JSON API response
 
         """
-        return self._get("/c/{0}.json".format(category_id), **kwargs)
+        return self._get(
+            "/c/{0}.json".format(category_id),
+            override_request_kwargs={"allow_redirects": True},
+            **kwargs
+        )
 
+    # Doesn't work on recent Discourse versions (2014+)
+    # https://github.com/discourse/discourse_api/pull/204
     def hot_topics(self, **kwargs):
         """
 
@@ -502,6 +532,15 @@ class DiscourseClient(object):
         """
         return self._get("/hot.json", **kwargs)
 
+    def top_topics(self, **kwargs):
+        """
+        Get top topics
+
+        Returns:
+            List of top topics
+        """
+        return self._get("/top.json", **kwargs)
+
     def latest_topics(self, **kwargs):
         """
 
@@ -564,6 +603,36 @@ class DiscourseClient(object):
         """
         return self._get("/t/{0}/{1}.json".format(topic_id, post_id), **kwargs)
 
+    def post_action_users(self, post_id, post_action_type_id=None, **kwargs):
+        """
+
+        Args:
+            post_id: int
+            post_action_type_id: Optional[int]
+            **kwargs:
+
+        Returns:
+
+        """
+        # https://meta.discourse.org/t/getting-who-liked-a-post-from-the-api/103618
+
+        kwargs["id"] = post_id
+        if post_action_type_id is not None:
+            kwargs["post_action_type_id"] = post_action_type_id
+        return self._get("/post_action_users", **kwargs)
+
+    def post_by_id(self, post_id, **kwargs):
+        """
+        Get a post from its id
+        Args:
+            post_id: id of the post
+            **kwargs:
+
+        Returns:
+            post
+        """
+        return self._get("/posts/{0}.json".format(post_id), **kwargs)
+
     def posts(self, topic_id, post_ids=None, **kwargs):
         """
         Get a set of posts from a topic
@@ -580,6 +649,21 @@ class DiscourseClient(object):
             kwargs["post_ids[]"] = post_ids
         return self._get("/t/{0}/posts.json".format(topic_id), **kwargs)
 
+    def latest_posts(self, before=None, **kwargs):
+        """
+        List latest posts across topics
+
+        Args:
+            before: Load posts with an id lower than this value. Useful for pagination.
+            **kwargs:
+
+        Returns:
+
+        """
+        if before:
+            kwargs["before"] = before
+        return self._get("/posts.json", **kwargs)
+
     def topic_timings(self, topic_id, time, timings={}, **kwargs):
         """
         Set time spent reading a post
@@ -692,6 +776,14 @@ class DiscourseClient(object):
         kwargs["post[edit_reason]"] = edit_reason
         return self._put("/posts/{0}".format(post_id), **kwargs)
 
+    def reset_bump_date(self, topic_id, **kwargs):
+        """
+        Reset bump date
+
+        See https://meta.discourse.org/t/what-is-a-bump/105562
+        """
+        return self._put("/t/{0}/reset-bump-date".format(topic_id), **kwargs)
+
     def topics_by(self, username, **kwargs):
         """
 
@@ -832,21 +924,30 @@ class DiscourseClient(object):
         """
         return self._get("/categories.json", **kwargs)["category_list"]["categories"]
 
-    def category(self, name, parent=None, **kwargs):
+    def category(self, category_id, parent=None, **kwargs):
         """
 
         Args:
-            name:
-            parent:
+            category_id:
             **kwargs:
 
         Returns:
 
         """
-        if parent:
-            name = u"{0}/{1}".format(parent, name)
 
-        return self._get(u"/category/{0}.json".format(name), **kwargs)
+        return self._get(u"/c/{0}/show.json".format(category_id), **kwargs)
+
+    def update_category(self, category_id, **kwargs):
+        """
+
+        Args:
+            category_id:
+            **kwargs:
+
+        Returns:
+
+        """
+        return self._put("/categories/{0}".format(category_id), json=True, **kwargs)
 
     def delete_category(self, category_id, **kwargs):
         """
@@ -861,12 +962,32 @@ class DiscourseClient(object):
         """
         return self._delete(u"/categories/{0}".format(category_id), **kwargs)
 
+    def get_site_info(self):
+        """
+        Get site info to fetch all categories and subcategories
+        """
+        return self._get("/site.json")
+
+    def get_site_settings(self):
+        """
+        Get site settings
+        """
+        return self._get("/admin/site_settings.json")
+
+    def category_latest_topics(self, name, parent=None, **kwargs):
+        """
+        Get latest topics from a category
+        """
+        if parent:
+            name = u"{0}/{1}".format(parent, name)
+        return self._get(u"/c/{0}/l/latest.json".format(name), **kwargs)
+
     def site_settings(self, **kwargs):
         """
+        Update site settings
 
         Args:
-            settings:
-            **kwargs:
+            **kwargs: key-value of properties to update
 
         Returns:
 
@@ -945,7 +1066,7 @@ class DiscourseClient(object):
         """
         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,
@@ -1024,8 +1145,23 @@ class DiscourseClient(object):
             JSON API response
 
         """
+        return self.add_group_owners(groupid, [username])
+
+    def add_group_owners(self, groupid, usernames):
+        """
+        Add a list of owners to a group by usernames
+
+        Args:
+            groupid: the ID of the group
+            username: the list of new owner usernames
+
+        Returns:
+            JSON API response
+
+        """
+        usernames = ",".join(usernames)
         return self._put(
-            "/admin/groups/{0}/owners.json".format(groupid), usernames=username
+            "/groups/{0}/owners.json".format(groupid), **{"usernames": usernames}
         )
 
     def delete_group_owner(self, groupid, userid):
@@ -1053,13 +1189,28 @@ class DiscourseClient(object):
         group = self._get("/groups/{0}/members.json".format(group_name))
         return group["owners"]
 
+    def _get_paginated_list(self, url, name, offset, **kwargs):
+        result = []
+        initial_offset = offset
+        while True:
+            kwargs["offset"] = offset
+            response = self._get(url, **kwargs)
+            nreturned = len(response[name])
+            result.extend(response[name])
+            offset += nreturned
+
+            if response["meta"]["total"] == len(result) - initial_offset:
+                return result
+            if nreturned == 0:
+                raise RuntimeError("more items expected, but none returned")
+
     def group_members(self, group_name, offset=0, **kwargs):
         """
         Get all members of a group by group name
         """
-        kwargs["offset"] = offset
-        group = self._get("/groups/{0}/members.json".format(group_name), **kwargs)
-        return group["members"]
+        return self._get_paginated_list(
+                "/groups/{0}/members.json".format(group_name),
+                "members", offset, **kwargs)
 
     def add_group_member(self, groupid, username):
         """
@@ -1077,7 +1228,7 @@ class DiscourseClient(object):
 
         """
         return self._put(
-            "/admin/groups/{0}/members.json".format(groupid), usernames=username
+            "/groups/{0}/members.json".format(groupid), usernames=username
         )
 
     def add_group_members(self, groupid, usernames):
@@ -1097,7 +1248,8 @@ class DiscourseClient(object):
         """
         usernames = ",".join(usernames)
         return self._put(
-            "/admin/groups/{0}/members.json".format(groupid), usernames=usernames
+            "/groups/{0}/members.json".format(groupid), usernames=usernames,
+            json=True,
         )
 
     def add_user_to_group(self, groupid, userid):
@@ -1117,7 +1269,7 @@ class DiscourseClient(object):
         """
         return self._post("/admin/users/{0}/groups".format(userid), group_id=groupid)
 
-    def delete_group_member(self, groupid, userid):
+    def delete_group_member(self, groupid, username):
         """
         Deletes a member from a group by user ID
 
@@ -1125,15 +1277,16 @@ class DiscourseClient(object):
 
         Args:
             groupid: the ID of the group
-            userid: the ID of the user
+            username: the user name of the user
 
         Returns:
             JSON API response
 
         """
-        return self._delete(
-            "/admin/groups/{0}/members.json".format(groupid), user_id=userid
-        )
+        return self._request(
+            DELETE, "/groups/{0}/members.json".format(groupid),
+            json={"usernames": username})
+
 
     def color_schemes(self, **kwargs):
         """
@@ -1281,7 +1434,29 @@ 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 data_explorer_query(self, query_id, **kwargs):
+        """
+        Run a query with database explorer plugin.
+        Requires discourse-data-explorer installed
+        https://github.com/discourse/discourse-data-explorer
+        """
+        return self._post(
+            "/admin/plugins/explorer/queries/{}/run".format(query_id), **kwargs
+        )
+
+    def notifications(self, category_id, **kwargs):
+        """
+        Get notifications
+
+        Args:
+            category_id
+            **kwargs:
+                notification_level=(int)
+
+        """
+        return self._post("/category/{}/notifications".format(category_id), **kwargs)
+
+    def _get(self, path, override_request_kwargs=None, **kwargs):
         """
 
         Args:
@@ -1291,9 +1466,11 @@ 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:
@@ -1304,12 +1481,18 @@ 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:
@@ -1320,12 +1503,24 @@ 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:
@@ -1335,9 +1530,20 @@ 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
 
@@ -1345,17 +1551,22 @@ 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"}
+        headers = {
+            "Accept": "application/json; charset=utf-8",
+            "Api-Key": self.api_key,
+            "Api-Username": self.api_username,
+        }
 
         # How many times should we retry if rate limited
         retry_count = 4
@@ -1363,9 +1574,7 @@ class DiscourseClient(object):
         retry_backoff = 1
 
         while retry_count > 0:
-            response = requests.request(
-                verb,
-                url,
+            request_kwargs = dict(
                 allow_redirects=False,
                 params=params,
                 files=files,
@@ -1375,6 +1584,10 @@ class DiscourseClient(object):
                 timeout=self.timeout,
             )
 
+            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
@@ -1390,20 +1603,29 @@ class DiscourseClient(object):
                 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.
+                        content_type = response.headers.get("Content-Type")
+                        if content_type is not None and "application/json" in content_type:
+                            ret = response.json()
+                            wait_delay = (
+                                retry_backoff + ret["extras"]["wait_seconds"]
+                            )  # how long to back off for.
+                        else:
+                            # We got an early 429 error without a proper JSON body
+                            ret = response.content
+                            wait_delay = retry_backoff + 10
 
+                        limit_name = response.headers.get(
+                                "Discourse-Rate-Limit-Error-Code", "<unknown>")
+
+                        log.info(
+                                "We have been rate limited (limit: {2}) and will wait {0} seconds ({1} retries left)".format(
+                                wait_delay, retry_count, limit_name
+                            )
+                        )
                         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))
+                        log.debug("API returned {0}".format(ret))
                         continue
                     else:
                         raise DiscourseClientError(msg, response=response)
@@ -1441,7 +1663,10 @@ class DiscourseClient(object):
         except ValueError:
             raise DiscourseError("failed to decode response", response=response)
 
-        if "errors" in decoded:
+        # Checking "errors" length because
+        # data-explorer (e.g. POST /admin/plugins/explorer/queries/{}/run)
+        # sends an empty errors array
+        if "errors" in decoded and len(decoded["errors"]) > 0:
             message = decoded.get("message")
             if not message:
                 message = u",".join(decoded["errors"])

src/pydiscourse/exceptions.py

@@ -0,0 +1,19 @@
+"""API exceptions."""
+
+from requests.exceptions import HTTPError
+
+
+class DiscourseError(HTTPError):
+    """A generic error while attempting to communicate with Discourse"""
+
+
+class DiscourseServerError(DiscourseError):
+    """The Discourse Server encountered an error while processing the request"""
+
+
+class DiscourseClientError(DiscourseError):
+    """An invalid request has been made"""
+
+
+class DiscourseRateLimitedError(DiscourseError):
+    """Request required more than the permissible number of retries"""

src/pydiscourse/main.py

@@ -1,5 +1,7 @@
 #!/usr/bin/env python
 
+"""Simple command line interface for making Discourse API queries."""
+
 import cmd
 import json
 import logging
@@ -12,15 +14,19 @@ from pydiscourse.client import DiscourseClient, DiscourseError
 
 
 class DiscourseCmd(cmd.Cmd):
+    """Handles CLI commands"""
+
     prompt = "discourse>"
     output = sys.stdout
 
     def __init__(self, client):
+        """Initialize command"""
         cmd.Cmd.__init__(self)
         self.client = client
         self.prompt = "%s>" % self.client.host
 
     def __getattr__(self, attr):
+        """Gets attributes with dynamic name handling"""
         if attr.startswith("do_"):
             method = getattr(self.client, attr[3:])
 
@@ -48,6 +54,7 @@ class DiscourseCmd(cmd.Cmd):
         raise AttributeError
 
     def postcmd(self, result, line):
+        """Writes output of the command to console"""
         try:
             json.dump(
                 result, self.output, sort_keys=True, indent=4, separators=(",", ": ")
@@ -57,6 +64,7 @@ class DiscourseCmd(cmd.Cmd):
 
 
 def main():
+    """Runs the CLI application"""
     op = optparse.OptionParser()
     op.add_option("--host", default="http://localhost:4000")
     op.add_option("--api-user", default="system")

src/pydiscourse/sso.py

@@ -1,6 +1,4 @@
-"""
-Utilities to implement Single Sign On for Discourse with a Python managed
-authentication DB
+"""Implement Single Sign On for Discourse with a Python managed auth DB.
 
 https://meta.discourse.org/t/official-single-sign-on-for-discourse/13045
 
@@ -26,23 +24,20 @@ from base64 import b64encode, b64decode
 import hmac
 import hashlib
 
-try:  # py3
-    from urllib.parse import unquote, urlencode, parse_qs
-except ImportError:
-    from urllib import unquote, urlencode
-    from urlparse import parse_qs
-
+from urllib.parse import unquote, urlencode, parse_qs
 
 from pydiscourse.exceptions import DiscourseError
 
 
 def sso_validate(payload, signature, secret):
-    """
+    """Validates SSO payload.
+
+    Args:
         payload: provided by Discourse HTTP call to your SSO endpoint as sso GET param
         signature: provided by Discourse HTTP call to your SSO endpoint as sig GET param
         secret: the secret key you entered into Discourse sso secret
 
-        return value: The nonce used by discourse to validate the redirect URL
+    return value: The nonce used by discourse to validate the redirect URL
     """
     if None in [payload, signature]:
         raise DiscourseError("No SSO payload or signature.")
@@ -72,6 +67,7 @@ def sso_validate(payload, signature, secret):
 
 
 def sso_payload(secret, **kwargs):
+    """Returns an encoded SSO payload"""
     return_payload = b64encode(urlencode(kwargs).encode("utf-8"))
     h = hmac.new(secret.encode("utf-8"), return_payload, digestmod=hashlib.sha256)
     query_string = urlencode({"sso": return_payload, "sig": h.hexdigest()})
@@ -79,14 +75,16 @@ def sso_payload(secret, **kwargs):
 
 
 def sso_redirect_url(nonce, secret, email, external_id, username, **kwargs):
-    """
+    """Returns the Discourse redirection URL.
+
+    Args:
         nonce: returned by sso_validate()
         secret: the secret key you entered into Discourse sso secret
         user_email: email address of the user who logged in
         user_id: the internal id of the logged in user
         user_username: username of the logged in user
 
-        return value: URL to redirect users back to discourse, now logged in as user_username
+    return value: URL to redirect users back to discourse, now logged in as user_username
     """
     kwargs.update(
         {

tests/test_client.py

@@ -1,10 +1,7 @@
 import sys
 import unittest
 
-try:
-    from unittest import mock
-except ImportError:
-    import mock
+from unittest import mock
 
 from pydiscourse import client
 
@@ -49,12 +46,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):
@@ -185,6 +182,11 @@ class TestTopics(ClientBaseTestCase):
 @mock.patch("pydiscourse.client.requests.request")
 class MiscellaneousTests(ClientBaseTestCase):
 
+    def test_latest_posts(self, request):
+        prepare_response(request)
+        r = self.client.latest_posts(before=54321)
+        self.assertRequestCalled(request, "GET", "/posts.json", before=54321)
+
     def test_search(self, request):
         prepare_response(request)
         self.client.search("needle")
@@ -196,6 +198,11 @@ class MiscellaneousTests(ClientBaseTestCase):
         self.assertRequestCalled(request, "GET", "/categories.json")
         self.assertEqual(r, request().json()["category_list"]["categories"])
 
+    def test_update_category(self, request):
+        prepare_response(request)
+        self.client.update_category(123, a="a", b="b")
+        self.assertRequestCalled(request, "PUT", "/categories/123", a="a", b="b")
+
     def test_users(self, request):
         prepare_response(request)
         self.client.users()

tests/test_sso.py

@@ -1,18 +1,9 @@
 from base64 import b64decode
 
-try:  # py26
-    import unittest2 as unittest
-except ImportError:
-    import unittest
-
-
-try:  # py3
-    from urllib.parse import unquote
-    from urllib.parse import urlparse, parse_qs
-except ImportError:
-    from urlparse import urlparse, parse_qs
-    from urllib import unquote
+import unittest
 
+from urllib.parse import unquote
+from urllib.parse import urlparse, parse_qs
 
 from pydiscourse import sso
 from pydiscourse.exceptions import DiscourseError

tox.ini

@@ -1,10 +1,19 @@
 [tox]
-envlist = py27, py34, py35, py36, py37, pypy, pypy3
+envlist = py37, py38, py39, py310, py311
+
+[gh-actions]
+python =
+    3.8: py38
+    3.9: py39
+    3.10: py310
+    3.11: py311
 
 [testenv]
 setenv =
     PYTHONPATH = {toxinidir}:{toxinidir}/pydiscourse
-commands = python setup.py test
+commands = pytest {posargs} --cov=pydiscourse
+deps =
+    -r{toxinidir}/requirements.txt
 
 [testenv:flake8]
 basepython=python
@@ -12,10 +21,10 @@ deps=
     flake8
     flake8_docstrings
 commands=
-    flake8 pydiscourse
+    flake8 src/pydiscourse --docstring-convention google --ignore D415
 
 [flake8]
 ignore = E126,E128
-max-line-length = 99
+max-line-length = 119
 exclude = .ropeproject
 max-complexity = 10