Merge pull request #93 from pydiscourse/v1.7

Bump version

.coveragerc

@@ -1,3 +0,0 @@
-[run]
-
-include: pydiscourse/*

.git-blame-ignore-revs

@@ -0,0 +1,11 @@
+c0db7215c95dbd31770ade1fc6ea65aa426d4590
+0177c46356b9d0fc4b93f09aab7a224643a3685e
+f6b4c02fc0f144dffc88cdd48b8261a69228d2f0
+2a3036f0395a810b0941522bfb1ca80b159525ce
+c49d29620dfb867f73ebb6be84b5e1ba922fadc9
+dc498679cc6769acafe19cf0083f40154ffdcff8
+7ab58533b759d1ff879476a5703051b201afd835
+fe4f67c04160a76948d810848ae082713ea6b5ed
+2aac9a20beb19a6a052286f73f5d0f5bf76ed758
+2be1a46c1da497e136818b5ef77708b8c5b69e57
+31db8017bc90978b879c5caa7f1cd4777d19a27e

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,8 @@
+### Summary of changes
+
+
+## Checklist
+
+- [ ] Changes represent a *discrete update*
+- [ ] Commit messages are meaningful and descriptive
+- [ ] Changeset does not include any extraneous changes unrelated to the discrete change

.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

@@ -0,0 +1,47 @@
+name: Tests
+
+on: [ push, pull_request ]
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Lint with Ruff
+        run: ruff .
+
+  test:
+
+    needs: lint
+
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12" ]
+
+    steps:
+      - 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

.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+exclude: "docs|.git|.tox"
+default_stages: [ commit ]
+fail_fast: true
+
+repos:
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: "v0.0.286"
+    hooks:
+      - id: ruff
+
+  - repo: https://github.com/psf/black
+    rev: 23.7.0
+    hooks:
+      - id: black
+        args:
+          - --config=pyproject.toml
+          - src/pydiscourse
+          - tests

.travis.yml

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

AUTHORS

@@ -4,3 +4,12 @@ Marc Sibson
 James Potter
 Ben Lopatin
 Daniel Zohar
+Matheus Fernandes
+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

@@ -12,13 +12,45 @@ Please use `Google docstring format
 
 This *will* be enforced.
 
+Pull requests
+=============
+
+Reviewing and merging pull requests is work, so whatever you can do to make this
+easier for the package maintainer not only speed up the process of getting your
+changes merged but also ensure they are. These few guidelines help significantly.
+If they are confusing or you need help understanding how to accomplish them,
+please ask for help in an issue.
+
+- Please do make sure your changeset represents a *discrete update*. If you would like to fix formatting, by all means, but don't mix that up with a bug fix. Those are separate PRs.
+- Please do make sure that both your pull request description and your commits are meaningful and descriptive. Rebase first, if need be.
+- Please do make sure your changeset does not include more commits than necessary. Rebase first, if need be.
+- Please do make sure the changeset is not very big. If you have a large change propose it in an issue first.
+- Please do make sure your changeset is based on a branch from the current HEAD of the fork you wish to merge against. This is a general best practice. Rebase first, if need be.
+
 Testing
 =======
 
-The best way to run the tests is with `tox <http://tox.readthedocs.org/en/latest/>`_::
+Running tests
+-------------
+
+The simplest way to quickly and repeatedly run tests while developing a feature or fix
+is to use `pytest` in your current Python environment.
+
+After installing the test dependencies::
+
+    pip install -r requirements.txt
+    pip install -e .
+
+Your can run the tests with `pytest`::
+
+    pytest --cov=src/pydiscourse
+
+This will ensure you get coverage reporting.
+
+The most comprehensive way to run the tests is with `tox <http://tox.readthedocs.org/en/latest/>`_::
 
     pip install tox
-    detox
+    tox
 
 Or it's slightly faster cousin `detox
 <https://pypi.python.org/pypi/detox>`_ which will parallelize test runs::
@@ -26,16 +58,29 @@ Or it's slightly faster cousin `detox
     pip install detox
     detox
 
-Alternatively, you can run the self test with the following commands::
+Writing tests
+-------------
 
-    pip install -r requirements.dev.txt
-    pip install -e .
-    python setup.py test
+The primary modules of the library have coverage requirements, so you should
+write a test or tests when you add a new feature.
+
+**At a bare minimum a test should show which Discourse API endpoint is called,
+using which HTTP method, and returning any necessary data for the new function/method.**
+
+In most cases this can be accomplished quite simply by using the `discourse_request`
+fixture, which allows for mocking the HTTP request in the `requests` library. In some cases
+this may be insufficient, and you may want to directly use the `requests_mock` mocking
+fixture.
+
+If in the course of writing your test you see a `requests_mock.NoMockAddress` exception
+raised then either the *method* or the *path* (including querystring) - or both! - in
+either your mock OR your new API client method is incorrect.
 
 Live Testing
 ============
 
 You can test against a Discourse instance by following the [Official Discourse developement instructions][discoursedev].
+
 For the impatient here is the quick and dirty version::
 
     git clone git@github.com:discourse/discourse.git
@@ -54,5 +99,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,137 @@
 Release history
 ===============
 
+
+1.7.0
+-----
+
+- Possible breaking change: Change `search()` term paramater from `term` to `q`,
+  fixes search. Thanks @weber-s
+- Add support for Python 3.12
+
+1.6.1
+-----
+
+- Adds `posts_by_number` endpoint from @Dettorer
+
+1.6.0
+-----
+
+- Breaking: `toggle_gravatar`, `pick_avatar`, `create_group` now *require*
+  keyword arguments where keyword arguments were used. This *may* break existing
+  code if you have not referenced these by keyword!
+- Introduced `ruff` and `black` into pre-commit hook
+- Added `lint` job to GitHub Actions, tests will run if and only if lint job
+  passes.
+- Sundry code cleanup
+
+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
+-----
+
+- Added rate limiting support
+- Added some support for user activation
+
+0.8.0
+-----
+
+- Add some PR guidance
+- Add support for files in the core request methods
+- Adds numerous new API controls, including:
+   - tag_group
+   - user_actions
+   - upload_image
+   - block
+   - trust_level_lock
+   - create_site_customization (theme)
+   - create_color_scheme
+   - color_schemes
+   - add_group_members
+   - group_members
+   - group_owners
+   - delete_group
+   - create_group
+   - group
+   - customize_site_texts
+   - delete_category
+   - user_emails
+   - update_topic_status
+   - create_post
+   - update_topic
+   - update_avatar
+   - user_all
+
+
+0.7.0
+-----
+
+* Place request parameters in the request body for POST and PUT requests.
+  Allows larger request sizes and solves for `URI Too Large` error.
+
+0.6.0
+-----
+
+* Adds method to add user to group by user ID
+
+0.5.0
+-----
+
+* Adds badges functionality
+
+0.4.0
+-----
+
+* Adds initial groups functionality
+
 0.3.2
 -----
 

Makefile

@@ -37,13 +37,15 @@ test-all:  ## Run all tox test environments, parallelized
 
 check: clean-build clean-pyc clean-test lint test-coverage
 
-release: clean  ## Uploads new source and wheel distributions (cleans first)
-	python setup.py sdist upload
-	python setup.py bdist_wheel upload
+build: clean  ## Create distribution files for release
+	python setup.py sdist bdist_wheel
 
-dist: clean  ## Creates new source and wheel distributions (cleans first)
+release: build  ## Create distribution files and publish to PyPI
+	python setup.py check -r -s
+	twine upload dist/*
+
+sdist: clean  ##sdist Create source distribution only
 	python setup.py sdist
-	python setup.py bdist_wheel
 	ls -l dist
 
 api-docs:  ## Build autodocs from docstrings

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.3'
+version = '1.7'
 # The full version, including alpha/beta/rc tags.
-release = '0.3.2'
+release = '1.7.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.3.2'
-
-from pydiscourse.client import DiscourseClient

pydiscourse/client.py

@@ -1,726 +0,0 @@
-"""
-Core API client module
-"""
-
-import logging
-
-import requests
-
-from pydiscourse.exceptions import (
-    DiscourseError, DiscourseServerError, DiscourseClientError)
-from pydiscourse.sso import sso_payload
-
-
-log = logging.getLogger('pydiscourse.client')
-
-
-class DiscourseClient(object):
-    """Discourse API client"""
-
-    def __init__(self, host, api_username, api_key, timeout=None):
-        """
-        Initialize the client
-
-        Args:
-            host: full domain name including scheme for the Discourse API
-            api_username: username to connect with
-            api_key: API key to connect with
-            timeout: optional timeout for the request (in seconds)
-
-        Returns:
-
-        """
-        self.host = host
-        self.api_username = api_username
-        self.api_key = api_key
-        self.timeout = timeout
-
-    def user(self, username):
-        """
-        Get user information for a specific user
-
-        TODO: include sample data returned
-        TODO: what happens when no user is found?
-
-        Args:
-            username: username to return
-
-        Returns:
-            dict of user information
-
-        """
-        return self._get('/users/{0}.json'.format(username))['user']
-
-    def create_user(self, name, username, email, password, **kwargs):
-        """
-        Create a Discourse user
-
-        Set keyword argument active='true' to avoid sending activation emails
-
-        TODO: allow optional password and generate a random one
-
-        Args:
-            name: the full name of the new user
-            username: their username (this is a key... that they can change)
-            email: their email, will be used for activation and summary emails
-            password: their initial password
-            **kwargs: ???? what else can be sent through?
-
-        Returns:
-            ????
-
-        """
-        r = self._get('/users/hp.json')
-        challenge = r['challenge'][::-1]  # reverse challenge, discourse security check
-        confirmations = r['value']
-        return self._post('/users', name=name, username=username, email=email,
-                          password=password, password_confirmation=confirmations,
-                          challenge=challenge, **kwargs)
-
-    def user_by_external_id(self, external_id):
-        """
-
-        Args:
-            external_id:
-
-        Returns:
-
-        """
-        response = self._get("/users/by-external/{0}".format(external_id))
-        return response['user']
-    by_external_id = user_by_external_id
-
-    def log_out(self, userid):
-        """
-
-        Args:
-            userid:
-
-        Returns:
-
-        """
-        return self._post('/admin/users/{0}/log_out'.format(userid))
-
-    def trust_level(self, userid, level):
-        """
-
-        Args:
-            userid:
-            level:
-
-        Returns:
-
-        """
-        return self._put('/admin/users/{0}/trust_level'.format(userid), level=level)
-
-    def suspend(self, userid, duration, reason):
-        """
-        Suspend a user's account
-
-        Args:
-            userid: the Discourse user ID
-            duration: the length of time in days for which a user's account
-                    should be suspended
-            reason: the reason for suspending the account
-
-        Returns:
-            ????
-
-        """
-        return self._put('/admin/users/{0}/suspend'.format(userid),
-                         duration=duration, reason=reason)
-
-    def unsuspend(self, userid):
-        """
-        Unsuspends a user's account
-
-        Args:
-            userid: the Discourse user ID
-
-        Returns:
-            None???
-        """
-        return self._put('/admin/users/{0}/unsuspend'.format(userid))
-
-    def list_users(self, type, **kwargs):
-        """
-
-        optional user search: filter='test@example.com' or filter='scott'
-
-        Args:
-            type:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._get('/admin/users/list/{0}.json'.format(type), **kwargs)
-
-    def update_avatar_from_url(self, username, url, **kwargs):
-        """
-
-        Args:
-            username:
-            url:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._post('/users/{0}/preferences/avatar'.format(username), file=url, **kwargs)
-
-    def update_avatar_image(self, username, img, **kwargs):
-        """
-
-        Args:
-            username:
-            img:
-            **kwargs:
-
-        Returns:
-
-        """
-        files = {'file': img}
-        return self._post('/users/{0}/preferences/avatar'.format(username), files=files, **kwargs)
-
-    def toggle_gravatar(self, username, state=True, **kwargs):
-        """
-
-        Args:
-            username:
-            state:
-            **kwargs:
-
-        Returns:
-
-        """
-        url = '/users/{0}/preferences/avatar/toggle'.format(username)
-        if bool(state):
-            kwargs['use_uploaded_avatar'] = 'true'
-        else:
-            kwargs['use_uploaded_avatar'] = 'false'
-        return self._put(url, **kwargs)
-
-    def pick_avatar(self, username, gravatar=True, generated=False, **kwargs):
-        """
-
-        Args:
-            username:
-            gravatar:
-            generated:
-            **kwargs:
-
-        Returns:
-
-        """
-        url = '/users/{0}/preferences/avatar/pick'.format(username)
-        return self._put(url, **kwargs)
-
-    def update_email(self, username, email, **kwargs):
-        """
-
-        Args:
-            username:
-            email:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._put('/users/{0}/preferences/email'.format(username), email=email, **kwargs)
-
-    def update_user(self, username, **kwargs):
-        """
-
-        Args:
-            username:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._put('/users/{0}'.format(username), **kwargs)
-
-    def update_username(self, username, new_username, **kwargs):
-        """
-
-        Args:
-            username:
-            new_username:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._put('/users/{0}/preferences/username'.format(username),
-                         username=new_username, **kwargs)
-
-    def set_preference(self, username=None, **kwargs):
-        """
-
-        Args:
-            username:
-            **kwargs:
-
-        Returns:
-
-        """
-        if username is None:
-            username = self.api_username
-        return self._put(u'/users/{0}'.format(username), **kwargs)
-
-    def sync_sso(self, **kwargs):
-        """
-
-        expect sso_secret, name, username, email, external_id, avatar_url,
-        avatar_force_update
-
-        Args:
-            **kwargs:
-
-        Returns:
-
-        """
-        sso_secret = kwargs.pop('sso_secret')
-        payload = sso_payload(sso_secret, **kwargs)
-        return self._post('/admin/users/sync_sso?{0}'.format(payload), **kwargs)
-
-    def generate_api_key(self, userid, **kwargs):
-        """
-
-        Args:
-            userid:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._post('/admin/users/{0}/generate_api_key'.format(userid), **kwargs)
-
-    def delete_user(self, userid, **kwargs):
-        """
-
-            block_email='true'
-            block_ip='false'
-            block_urls='false'
-
-        Args:
-            userid:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._delete('/admin/users/{0}.json'.format(userid), **kwargs)
-
-    def users(self, filter=None, **kwargs):
-        """
-
-        Args:
-            filter:
-            **kwargs:
-
-        Returns:
-
-        """
-        if filter is None:
-            filter = 'active'
-
-        return self._get('/admin/users/list/{0}.json'.format(filter), **kwargs)
-
-    def private_messages(self, username=None, **kwargs):
-        """
-
-        Args:
-            username:
-            **kwargs:
-
-        Returns:
-
-        """
-        if username is None:
-            username = self.api_username
-        return self._get('/topics/private-messages/{0}.json'.format(username), **kwargs)
-
-    def private_messages_unread(self, username=None, **kwargs):
-        """
-
-        Args:
-            username:
-            **kwargs:
-
-        Returns:
-
-        """
-        if username is None:
-            username = self.api_username
-        return self._get('/topics/private-messages-unread/{0}.json'.format(username), **kwargs)
-
-    def hot_topics(self, **kwargs):
-        """
-
-        Args:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._get('/hot.json', **kwargs)
-
-    def latest_topics(self, **kwargs):
-        """
-
-        Args:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._get('/latest.json', **kwargs)
-
-    def new_topics(self, **kwargs):
-        """
-
-        Args:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._get('/new.json', **kwargs)
-
-    def topic(self, slug, topic_id, **kwargs):
-        """
-
-        Args:
-            slug:
-            topic_id:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._get('/t/{0}/{1}.json'.format(slug, topic_id), **kwargs)
-
-    def post(self, topic_id, post_id, **kwargs):
-        """
-
-        Args:
-            topic_id:
-            post_id:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._get('/t/{0}/{1}.json'.format(topic_id, post_id), **kwargs)
-
-    def posts(self, topic_id, post_ids=None, **kwargs):
-        """
-        Get a set of posts from a topic
-
-        Args:
-            topic_id:
-            post_ids: a list of post ids from the topic stream
-            **kwargs:
-
-        Returns:
-
-        """
-        if post_ids:
-            kwargs['post_ids[]'] = post_ids
-        return self._get('/t/{0}/posts.json'.format(topic_id), **kwargs)
-
-    def topic_timings(self, topic_id, time, timings={}, **kwargs):
-        """
-        Set time spent reading a post
-
-        A side effect of this is to mark the post as read
-
-        Args:
-            topic_id: { post_number: ms }
-            time: overall time for the topic (in what unit????)
-            timings:
-            **kwargs:
-
-        Returns:
-
-        """
-        kwargs['topic_id'] = topic_id
-        kwargs['topic_time'] = time
-        for post_num, timing in timings.items():
-            kwargs['timings[{0}]'.format(post_num)] = timing
-
-        return self._post('/topics/timings', **kwargs)
-
-    def topic_posts(self, topic_id, **kwargs):
-        """
-
-        Args:
-            topic_id:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._get('/t/{0}/posts.json'.format(topic_id), **kwargs)
-
-    def create_post(self, content, **kwargs):
-        """
-
-        Args:
-            content:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._post('/posts', raw=content, **kwargs)
-
-    def update_post(self, post_id, content, edit_reason='', **kwargs):
-        """
-
-        Args:
-            post_id:
-            content:
-            edit_reason:
-            **kwargs:
-
-        Returns:
-
-        """
-        kwargs['post[raw]'] = content
-        kwargs['post[edit_reason]'] = edit_reason
-        return self._put('/posts/{0}'.format(post_id), **kwargs)
-
-    def topics_by(self, username, **kwargs):
-        """
-
-        Args:
-            username:
-            **kwargs:
-
-        Returns:
-
-        """
-        url = '/topics/created-by/{0}.json'.format(username)
-        return self._get(url, **kwargs)['topic_list']['topics']
-
-    def invite_user_to_topic(self, user_email, topic_id):
-        """
-
-        Args:
-            user_email:
-            topic_id:
-
-        Returns:
-
-        """
-        kwargs = {
-            'email': user_email,
-            'topic_id': topic_id,
-        }
-        return self._post('/t/{0}/invite.json'.format(topic_id), **kwargs)
-
-    def search(self, term, **kwargs):
-        """
-
-        Args:
-            term:
-            **kwargs:
-
-        Returns:
-
-        """
-        kwargs['term'] = term
-        return self._get('/search.json', **kwargs)
-
-    def create_category(self, name, color, text_color='FFFFFF',
-                        permissions=None, parent=None, **kwargs):
-        """
-
-        Args:
-            name:
-            color:
-            text_color:
-            permissions: dict of 'everyone', 'admins', 'moderators', 'staff' with values of ???
-            parent:
-            **kwargs:
-
-        Returns:
-
-        """
-        kwargs['name'] = name
-        kwargs['color'] = color
-        kwargs['text_color'] = text_color
-
-        if permissions is None and 'permissions' not in kwargs:
-            permissions = {'everyone': '1'}
-
-        for key, value in permissions.items():
-            kwargs['permissions[{0}]'.format(key)] = value
-
-        if parent:
-            parent_id = None
-            for category in self.categories():
-                if category['name'] == parent:
-                    parent_id = category['id']
-                    continue
-
-            if not parent_id:
-                raise DiscourseClientError(u'{0} not found'.format(parent))
-            kwargs['parent_category_id'] = parent_id
-
-        return self._post('/categories', **kwargs)
-
-    def categories(self, **kwargs):
-        """
-
-        Args:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._get('/categories.json', **kwargs)['category_list']['categories']
-
-    def category(self, name, parent=None, **kwargs):
-        """
-
-        Args:
-            name:
-            parent:
-            **kwargs:
-
-        Returns:
-
-        """
-        if parent:
-            name = u'{0}/{1}'.format(parent, name)
-
-        return self._get(u'/category/{0}.json'.format(name), **kwargs)
-
-    def site_settings(self, **kwargs):
-        """
-
-        Args:
-            **kwargs:
-
-        Returns:
-
-        """
-        for setting, value in kwargs.items():
-            setting = setting.replace(' ', '_')
-            self._request('PUT', '/admin/site_settings/{0}'.format(setting), {setting: value})
-
-    def _get(self, path, **kwargs):
-        """
-
-        Args:
-            path:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._request('GET', path, kwargs)
-
-    def _put(self, path, **kwargs):
-        """
-
-        Args:
-            path:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._request('PUT', path, kwargs)
-
-    def _post(self, path, **kwargs):
-        """
-
-        Args:
-            path:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._request('POST', path, kwargs)
-
-    def _delete(self, path, **kwargs):
-        """
-
-        Args:
-            path:
-            **kwargs:
-
-        Returns:
-
-        """
-        return self._request('DELETE', path, kwargs)
-
-    def _request(self, verb, path, params):
-        """
-
-        Args:
-            verb:
-            path:
-            params:
-
-        Returns:
-
-        """
-        params['api_key'] = self.api_key
-        if 'api_username' not in params:
-            params['api_username'] = self.api_username
-        url = self.host + path
-
-        headers = {'Accept': 'application/json; charset=utf-8'}
-
-        response = requests.request(
-            verb, url, allow_redirects=False, params=params, 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)
-
-            if 400 <= response.status_code < 500:
-                raise DiscourseClientError(msg, response=response)
-
-            raise DiscourseServerError(msg, response=response)
-
-        if response.status_code == 302:
-            raise DiscourseError(
-                'Unexpected Redirect, invalid api key or host?', response=response)
-
-        json_content = 'application/json; charset=utf-8'
-        content_type = response.headers['content-type']
-        if content_type != json_content:
-            # some calls return empty html documents
-            if not response.content.strip():
-                return None
-
-            raise DiscourseError('Invalid Response, expecting "{0}" got "{1}"'.format(
-                                 json_content, content_type), response=response)
-
-        try:
-            decoded = response.json()
-        except ValueError:
-            raise DiscourseError('failed to decode response', response=response)
-
-        if 'errors' in decoded:
-            message = decoded.get('message')
-            if not message:
-                message = u','.join(decoded['errors'])
-            raise DiscourseError(message, response=response)
-
-        return decoded

pydiscourse/exceptions.py

@@ -1,13 +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 """

pyproject.toml

@@ -0,0 +1,49 @@
+[tool.black]
+line-length=120
+target-version = ["py311"]
+
+[tool.ruff]
+exclude = [
+    ".tox",
+    ".git",
+    "build",
+    "dist",
+    "docs",
+    ".ropeproject",
+]
+ignore = [
+    "S101",  # Assertions good, actually
+    "TRY003",  # For now not worth back tracking
+]
+line-length = 240
+select = [
+    "S",  # Security (formerly B when using Bandit directly)
+    "E",
+    "F",
+    "N",
+    "W",
+    "COM",  # commas
+    "PT",  # pytest
+    "UP",  # Upgrade Python syntax
+    "T",
+    "A",  # built-in shadowing
+    "FBT",  # Boolean traps
+    "BLE",  # Blind exceptions
+    "PIE",
+    "TRY",
+    "ERA",  # eradicate commented out code
+]
+
+[tool.ruff.flake8-pytest-style]
+fixture-parentheses = false
+mark-parentheses = true
+parametrize-names-type = "tuple"
+parametrize-values-row-type = "tuple"
+
+[tool.ruff.mccabe]
+# Unlike Flake8, default to a complexity level of 10.
+max-complexity = 10
+
+[tool.coverage.run]
+include = ["src/pydiscourse/*"]
+

requirements.txt

@@ -0,0 +1,9 @@
+pre-commit==3.3.3
+ruff==0.0.286
+pytest==7.4.0
+pytest-cov==4.1.0
+pytest-mock==3.11.1  # https://github.com/pytest-dev/pytest-mock/
+pytest-socket==0.6.0  # https://github.com/miketheman/pytest-socket
+requests-mock==1.11.0  # https://github.com/jamielennox/requests-mock
+pytest-subtests==0.11.0  # https://github.com/pytest-dev/pytest-subtests
+pytest-icdiff==0.6  # https://pypi.org/project/pytest-icdiff/

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
+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
+    Programming Language :: Python :: 3.12
+
+[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,49 +1,6 @@
-from setuptools import setup, find_packages
+"""
+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.0.0',
-    ],
-    tests_require=[
-        'mock',
-    ],
-    test_suite='tests',
-    entry_points={
-        'console_scripts': [
-            'pydiscoursecli = pydiscourse.main:main'
-        ]
-    },
-    classifiers=[
-        "Development Status :: 3 - Alpha",
-        "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 :: 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.7.0"
+
+from pydiscourse.client import DiscourseClient
+
+
+__all__ = ["DiscourseClient"]

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,30 +14,36 @@ from pydiscourse.client import DiscourseClient, DiscourseError
 
 
 class DiscourseCmd(cmd.Cmd):
-    prompt = 'discourse>'
+    """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
+        self.prompt = "%s>" % self.client.host
 
     def __getattr__(self, attr):
-        if attr.startswith('do_'):
+        """Gets attributes with dynamic name handling"""
+        if attr.startswith("do_"):
             method = getattr(self.client, attr[3:])
 
             def wrapper(arg):
                 args = arg.split()
-                kwargs = dict(a.split('=') for a in args if '=' in a)
-                args = [a for a in args if '=' not in a]
+                kwargs = dict(a.split("=") for a in args if "=" in a)
+                args = [a for a in args if "=" not in a]
                 try:
                     return method(*args, **kwargs)
+
                 except DiscourseError as e:
-                    print(e, e.response.text)
+                    sys.stderr.write(f"{e}, {e.response.text}\n")
                     return e.response
+
             return wrapper
 
-        elif attr.startswith('help_'):
+        elif attr.startswith("help_"):
             method = getattr(self.client, attr[5:])
 
             def wrapper():
@@ -46,25 +54,33 @@ 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=(',', ': '))
+            json.dump(
+                result,
+                self.output,
+                sort_keys=True,
+                indent=4,
+                separators=(",", ": "),
+            )
         except TypeError:
             self.output.write(result.text)
 
 
 def main():
+    """Runs the CLI application"""
     op = optparse.OptionParser()
-    op.add_option('--host', default='http://localhost:4000')
-    op.add_option('--api-user', default='system')
-    op.add_option('-v', '--verbose', action='store_true')
+    op.add_option("--host", default="http://localhost:4000")
+    op.add_option("--api-user", default="system")
+    op.add_option("-v", "--verbose", action="store_true")
 
     options, args = op.parse_args()
-    if not options.host.startswith('http'):
-        op.error('host must include protocol, eg http://')
+    if not options.host.startswith("http"):
+        op.error("host must include protocol, eg http://")
 
-    api_key = os.environ.get('DISCOURSE_API_KEY')
+    api_key = os.environ.get("DISCOURSE_API_KEY")
     if not api_key:
-        op.error('please set DISCOURSE_API_KEY')
+        op.error("please set DISCOURSE_API_KEY")
 
     client = DiscourseClient(options.host, options.api_user, api_key)
 
@@ -74,12 +90,12 @@ def main():
 
     c = DiscourseCmd(client)
     if args:
-        line = ' '.join(args)
+        line = " ".join(args)
         result = c.onecmd(line)
         c.postcmd(result, line)
     else:
         c.cmdloop()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()

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,71 +24,77 @@ 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.')
+        raise DiscourseError("No SSO payload or signature.")
 
     if not secret:
-        raise DiscourseError('Invalid secret..')
+        raise DiscourseError("Invalid secret.")
 
     payload = unquote(payload)
     if not payload:
-        raise DiscourseError('Invalid payload..')
+        raise DiscourseError("Invalid payload.")
 
-    decoded = b64decode(payload.encode('utf-8')).decode('utf-8')
-    if 'nonce' not in decoded:
-        raise DiscourseError('Invalid payload..')
+    decoded = b64decode(payload.encode("utf-8")).decode("utf-8")
+    if "nonce" not in decoded:
+        raise DiscourseError("Invalid payload.")
 
-    h = hmac.new(secret.encode('utf-8'), payload.encode('utf-8'), digestmod=hashlib.sha256)
+    h = hmac.new(
+        secret.encode("utf-8"),
+        payload.encode("utf-8"),
+        digestmod=hashlib.sha256,
+    )
     this_signature = h.hexdigest()
 
     if this_signature != signature:
-        raise DiscourseError('Payload does not match signature.')
+        raise DiscourseError("Payload does not match signature.")
 
     # Discourse returns querystring encoded value. We only need `nonce`
     qs = parse_qs(decoded)
-    return qs['nonce'][0]
+    return qs["nonce"][0]
 
 
 def sso_payload(secret, **kwargs):
-    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()})
+    """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()})
     return query_string
 
 
 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({
-        'nonce': nonce,
-        'email': email,
-        'external_id': external_id,
-        'username': username
-    })
+    kwargs.update(
+        {
+            "nonce": nonce,
+            "email": email,
+            "external_id": external_id,
+            "username": username,
+        },
+    )
 
-    return '/session/sso_login?%s' % sso_payload(secret, **kwargs)
+    return "/session/sso_login?%s" % sso_payload(secret, **kwargs)

tests/conftest.py

@@ -0,0 +1,136 @@
+"""Test fixtures."""
+
+import datetime
+
+import pytest
+from pydiscourse import client
+
+
+@pytest.fixture(scope="session")
+def sso_secret():
+    return "d836444a9e4084d5b224a60c208dce14"
+
+
+@pytest.fixture(scope="session")
+def sso_nonce():
+    return "cb68251eefb5211e58c00ff1395f0c0b"
+
+
+@pytest.fixture(scope="session")
+def sso_payload():
+    return "bm9uY2U9Y2I2ODI1MWVlZmI1MjExZTU4YzAwZmYxMzk1ZjBjMGI%3D%0A"
+
+
+@pytest.fixture(scope="session")
+def sso_signature():
+    return "2828aa29899722b35a2f191d34ef9b3ce695e0e6eeec47deb46d588d70c7cb56"
+
+
+@pytest.fixture(scope="session")
+def name():
+    return "sam"
+
+
+@pytest.fixture(scope="session")
+def username():
+    return "samsam"
+
+
+@pytest.fixture(scope="session")
+def external_id():
+    return "hello123"
+
+
+@pytest.fixture(scope="session")
+def email():
+    return "test@test.com"
+
+
+@pytest.fixture(scope="session")
+def redirect_url(sso_payload):
+    return f"/session/sso_login?sso={sso_payload}YW0mdXNlcm5hbWU9c2Ftc2FtJmVtYWlsPXRlc3QlNDB0ZXN0LmNvbSZleHRl%0Acm5hbF9pZD1oZWxsbzEyMw%3D%3D%0A&sig=1c884222282f3feacd76802a9dd94e8bc8deba5d619b292bed75d63eb3152c0b"
+
+
+@pytest.fixture(scope="session")
+def discourse_host():
+    return "http://testhost"
+
+
+@pytest.fixture(scope="session")
+def discourse_api_username():
+    return "testuser"
+
+
+@pytest.fixture(scope="session")
+def discourse_api_key():
+    return "testkey"
+
+
+@pytest.fixture(scope="session")
+def discourse_client(discourse_host, discourse_api_username, discourse_api_key):
+    return client.DiscourseClient(
+        discourse_host,
+        discourse_api_username,
+        discourse_api_key,
+    )
+
+
+@pytest.fixture
+def _frozen_time(mocker):
+    now = mocker.patch("pydiscourse.client.now")
+    now.return_value = datetime.datetime(
+        2023,
+        8,
+        13,
+        12,
+        30,
+        15,
+        tzinfo=datetime.timezone.utc,
+    )
+
+
+@pytest.fixture
+def discourse_request(discourse_host, discourse_client, requests_mock):
+    """Fixture for mocking Discourse API requests.
+
+    The only request arguments are the method and the path.
+
+    Example:
+
+    >>> def test_something(discourse_request):
+    >>>     request = discourse_request(
+    >>>         "put",  # the method, case-insensitive
+    >>>         "/the-path.json?q=4",  # the absolute path with query, NO host
+    >>>         headers={'content-type': 'text/plain'},  # override default headers
+    >>>         content=b"ERROR",  # override bytestring response
+    >>>     )
+
+    If `content` is provided, that will be used as the response body.
+    If `json` is provided, then the body will return the given JSON-
+        compatable Python structure (e.g. dictionary).
+    If neither is given then the return `json` will be an empty
+        dictionary (`{}`).
+
+    Returns a function for inserting sensible default values.
+    """
+
+    def inner(method, path, headers=None, json=None, content=None):
+        full_path = f"{discourse_host}{path}"
+        if not headers:
+            headers = {
+                "Content-Type": "application/json; charset=utf-8",
+                "Api-Key": discourse_client.api_key,
+                "Api-Username": discourse_client.api_username,
+            }
+
+        kwargs = {}
+        if content:
+            kwargs["content"] = content
+        elif json:
+            kwargs["json"] = json
+        else:
+            kwargs["json"] = {}
+
+        return requests_mock.request(method, full_path, headers=headers, **kwargs)
+
+    return inner

tests/test_client.py

@@ -1,177 +1,220 @@
-import sys
-import unittest
-import mock
+"""Tests for the client methods."""
 
-from pydiscourse import client
+import urllib.parse
 
-import sys
-if sys.version_info < (3,):
-    def b(x):
-        return x
-else:
-    import codecs
-    def b(x):
-        return codecs.latin_1_encode(x)[0]
+import pytest
 
 
-def prepare_response(request):
-    # we need to mocked response to look a little more real
-    request.return_value = mock.MagicMock(headers={'content-type': 'application/json; charset=utf-8'})
+def test_empty_content_http_ok(discourse_host, discourse_client, discourse_request):
+    """Empty content should not raise error
 
-
-class ClientBaseTestCase(unittest.TestCase):
+    Critical to test against *bytestrings* rather than unicode
     """
+    discourse_request(
+        "get",
+        "/users/admin/1/unsuspend",
+        headers={"Content-Type": "text/plain; charset=utf-8"},
+        content=b" ",
+    )
 
-    """
+    resp = discourse_client._request("GET", "/users/admin/1/unsuspend", {})
 
-    def setUp(self):
-        self.host = 'http://testhost'
-        self.api_username = 'testuser'
-        self.api_key = 'testkey'
-
-        self.client = client.DiscourseClient(self.host, self.api_username, self.api_key)
-
-    def assertRequestCalled(self, request, verb, url, **params):
-        self.assertTrue(request.called)
-
-        args, kwargs = request.call_args
-
-        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)
-        self.assertEqual(kwargs, params)
+    assert resp is None
 
 
+class TestUserManagement:
+    def test_get_user(self, discourse_host, discourse_client, discourse_request):
+        request = discourse_request(
+            "get",
+            "/users/someuser.json",
+            json={"user": "someuser"},
+        )
+        discourse_client.user("someuser")
 
-class TestClientRequests(ClientBaseTestCase):
-    """
-    Tests for common request handling
-    """
+        assert request.called_once
 
-    @mock.patch('pydiscourse.client.requests')
-    def test_empty_content_http_ok(self, mocked_requests):
-        """Empty content should not raise error
+    def test_users(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/admin/users/list/active.json")
+        discourse_client.users()
+        assert request.called_once
 
-        Critical to test against *bytestrings* rather than unicode
-        """
-        mocked_response = mock.MagicMock()
-        mocked_response.content = b(' ')
-        mocked_response.status_code = 200
-        mocked_response.headers = {"content-type": "text/plain; charset=utf-8"}
+    def test_create_user(self, discourse_host, discourse_client, discourse_request):
+        session_request = discourse_request(
+            "get",
+            "/session/hp.json",
+            json={"challenge": "challenge", "value": "value"},
+        )
+        user_request = discourse_request("post", "/users")
+        discourse_client.create_user(
+            "Test User",
+            "testuser",
+            "test@example.com",
+            "notapassword",
+        )
 
-        assert "content-type" in mocked_response.headers
+        assert session_request.called_once
+        assert user_request.called_once
 
-        mocked_requests.request = mock.MagicMock()
-        mocked_requests.request.return_value = mocked_response
+    def test_update_email(self, discourse_host, discourse_client, discourse_request):
+        request = discourse_request("put", "/users/someuser/preferences/email")
+        discourse_client.update_email("someuser", "newmeail@example.com")
 
-        resp = self.client._request('GET', '/users/admin/1/unsuspend', {})
-        self.assertIsNone(resp)
+        assert request.called_once
+
+    def test_update_user(self, discourse_client, discourse_request):
+        request = discourse_request("put", "/users/someuser")
+        discourse_client.update_user("someuser", a="a", b="b")
+
+        assert request.called_once
+
+    def test_update_username(self, discourse_client, discourse_request):
+        request = discourse_request("put", "/users/someuser/preferences/username")
+        discourse_client.update_username("someuser", "newname")
+
+        assert request.called_once
+
+    def test_by_external_id(self, discourse_client, discourse_request):
+        request = discourse_request(
+            "get",
+            "/users/by-external/123",
+            json={"user": "123"},
+        )
+        discourse_client.by_external_id(123)
+
+        assert request.called_once
+
+    def test_anonymize(self, discourse_client, discourse_request):
+        request = discourse_request("put", "/admin/users/123/anonymize")
+        discourse_client.anonymize(123)
+
+        assert request.called_once
+
+    @pytest.mark.usefixtures("_frozen_time")
+    def test_suspend_user(self, discourse_client, discourse_request):
+        request = discourse_request("put", "/admin/users/123/suspend")
+        discourse_client.suspend(123, 1, "Testing")
+
+        assert request.called_once
+        assert request.last_request.method == "PUT"
+
+        request_payload = urllib.parse.parse_qs(request.last_request.text)
+
+        assert request_payload["reason"] == ["Testing"]
+        assert request_payload["suspend_until"] == ["2023-08-14T12:30:15+00:00"]
+
+    def test_unsuspend_user(self, discourse_client, discourse_request):
+        request = discourse_request("put", "/admin/users/123/unsuspend")
+        discourse_client.unsuspend(123)
+
+        assert request.called_once
+
+    def test_user_bagdes(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/user-badges/myusername.json")
+        discourse_client.user_badges("myusername")
+
+        assert request.called_once
 
 
-@mock.patch('requests.request')
-class TestUser(ClientBaseTestCase):
+class TestTopics:
+    def test_hot_topics(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/hot.json")
+        discourse_client.hot_topics()
+        assert request.called_once
 
-    def test_user(self, request):
-        prepare_response(request)
-        self.client.user('someuser')
-        self.assertRequestCalled(request, 'GET', '/users/someuser.json')
+    def test_latest_topics(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/latest.json")
+        discourse_client.latest_topics()
 
-    def test_create_user(self, request):
-        prepare_response(request)
-        self.client.create_user('Test User', 'testuser', 'test@example.com', 'notapassword')
-        self.assertEqual(request.call_count, 2)
-        # XXX incomplete
+        assert request.called_once
 
-    def test_update_email(self, request):
-        prepare_response(request)
-        email = 'test@example.com'
-        self.client.update_email('someuser', email)
-        self.assertRequestCalled(request, 'PUT', '/users/someuser/preferences/email', email=email)
+    def test_new_topics(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/new.json")
+        discourse_client.new_topics()
+        assert request.called_once
 
-    def test_update_user(self, request):
-        prepare_response(request)
-        self.client.update_user('someuser', a='a', b='b')
-        self.assertRequestCalled(request, 'PUT', '/users/someuser', a='a', b='b')
+    def test_topic(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/t/some-test-slug/22.json")
+        discourse_client.topic("some-test-slug", 22)
+        assert request.called_once
 
-    def test_update_username(self, request):
-        prepare_response(request)
-        self.client.update_username('someuser', 'newname')
-        self.assertRequestCalled(request, 'PUT',
-                                 '/users/someuser/preferences/username',
-                                 username='newname')
+    def test_topics_by(self, discourse_client, discourse_request):
+        request = discourse_request(
+            "get",
+            "/topics/created-by/someuser.json",
+            json={"topic_list": {"topics": []}},
+        )
+        discourse_client.topics_by("someuser")
 
-    def test_by_external_id(self, request):
-        prepare_response(request)
-        self.client.by_external_id(123)
-        self.assertRequestCalled(request, 'GET',
-                                 '/users/by-external/123')
+        assert request.called_once
 
-    def test_suspend_user(self, request):
-        prepare_response(request)
-        self.client.suspend(123, 1, "Testing")
-        self.assertRequestCalled(request, 'PUT', '/admin/users/123/suspend',
-                                 duration=1, reason="Testing")
+    def test_invite_user_to_topic(self, discourse_client, discourse_request):
+        request = discourse_request("post", "/t/22/invite.json")
+        discourse_client.invite_user_to_topic("test@example.com", 22)
+        assert request.called_once
 
-    def test_unsuspend_user(self, request):
-        prepare_response(request)
-        self.client.unsuspend(123)
-        self.assertRequestCalled(request, 'PUT', '/admin/users/123/unsuspend')
+        request_payload = urllib.parse.parse_qs(request.last_request.text)
+
+        assert request_payload["email"] == ["test@example.com"]
+        assert request_payload["topic_id"] == ["22"]
 
 
-@mock.patch('requests.request')
-class TestTopics(ClientBaseTestCase):
+class TestPosts:
+    def test_latest_posts(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/posts.json?before=54321")
+        discourse_client.latest_posts(before=54321)
+        assert request.called_once
 
-    def test_hot_topics(self, request):
-        prepare_response(request)
-        self.client.hot_topics()
-        self.assertRequestCalled(request, 'GET', '/hot.json')
-
-    def test_latest_topics(self, request):
-        prepare_response(request)
-        self.client.latest_topics()
-        self.assertRequestCalled(request, 'GET', '/latest.json')
-
-    def test_new_topics(self, request):
-        prepare_response(request)
-        self.client.new_topics()
-        self.assertRequestCalled(request, 'GET', '/new.json')
-
-    def test_topic(self, request):
-        prepare_response(request)
-        self.client.topic('some-test-slug', 22)
-        self.assertRequestCalled(request, 'GET', '/t/some-test-slug/22.json')
-
-    def test_topics_by(self, request):
-        prepare_response(request)
-        r = self.client.topics_by('someuser')
-        self.assertRequestCalled(request, 'GET', '/topics/created-by/someuser.json')
-        self.assertEqual(r, request().json()['topic_list']['topics'])
-
-    def invite_user_to_topic(self, request):
-        prepare_response(request)
-        email = 'test@example.com'
-        self.client.invite_user_to_topic(email, 22)
-        self.assertRequestCalled(request, 'POST', '/t/22/invite.json', email=email, topic_id=22)
+    def test_post_by_number(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/posts/by_number/8796/5")
+        discourse_client.post_by_number(8796, 5)
+        assert request.called_once
 
 
-@mock.patch('requests.request')
-class MiscellaneousTests(ClientBaseTestCase):
+class TestSearch:
+    def test_search(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/search.json?q=needle")
+        discourse_client.search(q="needle")
+        assert request.called_once
 
-    def test_search(self, request):
-        prepare_response(request)
-        self.client.search('needle')
-        self.assertRequestCalled(request, 'GET', '/search.json', term='needle')
 
-    def test_categories(self, request):
-        prepare_response(request)
-        r = self.client.categories()
-        self.assertRequestCalled(request, 'GET', '/categories.json')
-        self.assertEqual(r, request().json()['category_list']['categories'])
+class TestCategories:
+    def test_categories(self, discourse_client, discourse_request):
+        request = discourse_request(
+            "get",
+            "/categories.json",
+            json={"category_list": {"categories": []}},
+        )
+        discourse_client.categories()
+        assert request.called_once
 
-    def test_users(self, request):
-        prepare_response(request)
-        self.client.users()
-        self.assertRequestCalled(request, 'GET', '/admin/users/list/active.json')
+    def test_update_category(self, discourse_client, discourse_request):
+        request = discourse_request("put", "/categories/123")
+        discourse_client.update_category(123, a="a", b="b")
+
+        request_payload = request.last_request.json()
+
+        assert request_payload["a"] == "a"
+        assert request_payload["b"] == "b"
+
+
+class TestBadges:
+    def test_badges(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/admin/badges.json")
+        discourse_client.badges()
+        assert request.called_once
+
+    def test_grant_badge_to(self, discourse_client, discourse_request):
+        request = discourse_request("post", "/user_badges")
+        discourse_client.grant_badge_to("username", 1)
+
+        request_payload = urllib.parse.parse_qs(request.last_request.text)
+
+        assert request_payload["username"] == ["username"]
+        assert request_payload["badge_id"] == ["1"]
+
+
+class TestAbout:
+    def test_about(self, discourse_client, discourse_request):
+        request = discourse_request("get", "/about.json")
+        discourse_client.about()
+        assert request.called_once

tests/test_sso.py

@@ -1,74 +1,95 @@
 from base64 import b64decode
+from urllib.parse import unquote
+from urllib.parse import urlparse, parse_qs
 
-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 pytest
 
 from pydiscourse import sso
 from pydiscourse.exceptions import DiscourseError
 
 
-class SSOTestCase(unittest.TestCase):
-    def setUp(self):
-        # values from https://meta.discourse.org/t/official-single-sign-on-for-discourse/13045
-        self.secret = 'd836444a9e4084d5b224a60c208dce14'
-        self.nonce = 'cb68251eefb5211e58c00ff1395f0c0b'
-        self.payload = 'bm9uY2U9Y2I2ODI1MWVlZmI1MjExZTU4YzAwZmYxMzk1ZjBjMGI%3D%0A'
-        self.signature = '2828aa29899722b35a2f191d34ef9b3ce695e0e6eeec47deb46d588d70c7cb56'
+def test_sso_validate_missing_payload():
+    with pytest.raises(DiscourseError) as excinfo:
+        sso.sso_validate(None, "abc", "123")
 
-        self.name = u'sam'
-        self.username = u'samsam'
-        self.external_id = u'hello123'
-        self.email = u'test@test.com'
-        self.redirect_url = u'/session/sso_login?sso=bm9uY2U9Y2I2ODI1MWVlZmI1MjExZTU4YzAwZmYxMzk1ZjBjMGImbmFtZT1z%0AYW0mdXNlcm5hbWU9c2Ftc2FtJmVtYWlsPXRlc3QlNDB0ZXN0LmNvbSZleHRl%0Acm5hbF9pZD1oZWxsbzEyMw%3D%3D%0A&sig=1c884222282f3feacd76802a9dd94e8bc8deba5d619b292bed75d63eb3152c0b'
+    assert excinfo.value.args[0] == "No SSO payload or signature."
 
-    def test_missing_args(self):
-        with self.assertRaises(DiscourseError):
-            sso.sso_validate(None, self.signature, self.secret)
 
-        with self.assertRaises(DiscourseError):
-            sso.sso_validate('', self.signature, self.secret)
+def test_sso_validate_empty_payload():
+    with pytest.raises(DiscourseError) as excinfo:
+        sso.sso_validate("", "abc", "123")
 
-        with self.assertRaises(DiscourseError):
-            sso.sso_validate(self.payload, None, self.secret)
+    assert excinfo.value.args[0] == "Invalid payload."
 
-    def test_invalid_signature(self):
-        with self.assertRaises(DiscourseError):
-            sso.sso_validate(self.payload, 'notavalidsignature', self.secret)
 
-    def test_valid_nonce(self):
-        nonce = sso.sso_validate(self.payload, self.signature, self.secret)
-        self.assertEqual(nonce, self.nonce)
+def test_sso_validate_missing_signature():
+    with pytest.raises(DiscourseError) as excinfo:
+        sso.sso_validate("sig", None, "123")
 
-    def test_valid_redirect_url(self):
-        url = sso.sso_redirect_url(self.nonce, self.secret, self.email, self.external_id, self.username, name='sam')
+    assert excinfo.value.args[0] == "No SSO payload or signature."
 
-        self.assertIn('/session/sso_login', url[:20])
 
-        # check its valid, using our own handy validator
-        params = parse_qs(urlparse(url).query)
-        payload = params['sso'][0]
-        sso.sso_validate(payload, params['sig'][0], self.secret)
+@pytest.mark.parametrize("bad_secret", [None, ""])
+def test_sso_validate_missing_secret(bad_secret):
+    with pytest.raises(DiscourseError) as excinfo:
+        sso.sso_validate("payload", "signature", bad_secret)
 
-        # check the params have all the data we expect
-        payload = b64decode(payload.encode('utf-8')).decode('utf-8')
-        payload = unquote(payload)
-        payload = dict((p.split('=') for p in payload.split('&')))
+    assert excinfo.value.args[0] == "Invalid secret."
 
-        self.assertEqual(payload, {
-            'username': self.username,
-            'nonce': self.nonce,
-            'external_id': self.external_id,
-            'name': self.name,
-            'email': self.email
-        })
+
+def test_sso_validate_invalid_signature(sso_payload, sso_signature, sso_secret):
+    with pytest.raises(DiscourseError) as excinfo:
+        sso.sso_validate("Ym9i", sso_signature, sso_secret)
+
+    assert excinfo.value.args[0] == "Invalid payload."
+
+
+def test_sso_validate_invalid_payload_nonce(sso_payload, sso_secret):
+    with pytest.raises(DiscourseError) as excinfo:
+        sso.sso_validate(sso_payload, "notavalidsignature", sso_secret)
+
+    assert excinfo.value.args[0] == "Payload does not match signature."
+
+
+def test_valid_nonce(sso_payload, sso_signature, sso_secret, sso_nonce):
+    generated_nonce = sso.sso_validate(sso_payload, sso_signature, sso_secret)
+    assert generated_nonce == sso_nonce
+
+
+def test_valid_redirect_url(
+    sso_secret,
+    sso_nonce,
+    name,
+    email,
+    username,
+    external_id,
+    redirect_url,
+):
+    url = sso.sso_redirect_url(
+        sso_nonce,
+        sso_secret,
+        email,
+        external_id,
+        username,
+        name="sam",
+    )
+
+    assert "/session/sso_login" in url[:20]
+
+    # check its valid, using our own handy validator
+    params = parse_qs(urlparse(url).query)
+    payload = params["sso"][0]
+    sso.sso_validate(payload, params["sig"][0], sso_secret)
+
+    # check the params have all the data we expect
+    payload = b64decode(payload.encode("utf-8")).decode("utf-8")
+    payload = unquote(payload)
+    payload = dict(p.split("=") for p in payload.split("&"))
+
+    assert payload == {
+        "username": username,
+        "nonce": sso_nonce,
+        "external_id": external_id,
+        "name": name,
+        "email": email,
+    }

tox.ini

@@ -1,21 +1,28 @@
 [tox]
-envlist = py27, py34, py35, pypy, pypy3
+envlist = py38, py39, py310, py311
+
+[gh-actions]
+python =
+    3.8: py38
+    3.9: py39
+    3.10: py310
+    3.11: py311
+    3.12: py312
 
 [testenv]
 setenv =
     PYTHONPATH = {toxinidir}:{toxinidir}/pydiscourse
-commands = python setup.py test
+commands =
+    pytest {posargs} --cov=pydiscourse
+    coverage report -m --include='**/pydiscourse/client.py' --fail-under=46
+    coverage report -m --include='**/pydiscourse/sso.py' --fail-under=100
+deps =
+    -r{toxinidir}/requirements.txt
 
-[testenv:flake8]
+[testenv:ruff]
 basepython=python
+skip_install=true
 deps=
-    flake8
-    flake8_docstrings
+    ruff
 commands=
-    flake8 pydiscourse
-
-[flake8]
-ignore = E126,E128
-max-line-length = 99
-exclude = .ropeproject
-max-complexity = 10
+    ruff .