=========== pydiscourse

.. image:: https://github.com/bennylope/pydiscourse/workflows/Tests/badge.svg :alt: Build Status :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.

This is a fork of the original Tindie version. It was forked to include fixes, additional functionality, and to distribute a package on PyPI.

Goals

• Exceptional documentation
• Support all supported Python versions
• Provide functional parity with the Discourse API, for the currently supported version of Discourse (something of a moving target)

The order here is important. The Discourse API is itself poorly documented so the level of documentation in the Python client is critical.

Installation

::

pip install pydiscourse

Examples

Create a client connection to a Discourse server::

from pydiscourse import DiscourseClient
client = DiscourseClient(
        'http://example.com',
        api_username='username',
        api_key='areallylongstringfromdiscourse')

Get info about a user::

user = client.user('eviltrout')
print user

user_topics = client.topics_by('johnsmith')
print user_topics

Create a new user::

user = client.create_user('The Black Knight', 'blacknight', 'knight@python.org', 'justafleshwound')

Implement SSO for Discourse with your Python server::

@login_required
def discourse_sso_view(request):
    payload = request.GET.get('sso')
    signature = request.GET.get('sig')
    nonce = sso_validate(payload, signature, SECRET)
    url = sso_redirect_url(nonce, SECRET, request.user.email, request.user.id, request.user.username)
    return redirect('http://discuss.example.com' + url)

Command line

To help experiment with the Discourse API, pydiscourse provides a simple command line client::

export DISCOURSE_API_KEY=your_master_key
pydiscoursecli --host-http://yourhost --api-user-system latest_topics
pydiscoursecli --host-http://yourhost --api-user-system topics_by johnsmith
pydiscoursecli --host-http://yourhost --api-user-system user eviltrout

.. :changelog:

Release history

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

• SSO functionality fixes

0.3.1

• Fix how empty responses are handled

0.3.0

• Added method to unsuspend suspended user

0.2.0

• Inital fork, including gberaudo's changes
• Packaging cleanup, dropping Python 2.6 support and adding Python 3.5, PyPy, PyPy3
• Packaging on PyPI

0.1.0.dev

All pre-PyPI development