A Python wrapper for Matrix Synapse admin API

Overview

Synapse-admin-api-python

Pypi License MIT Python Synapse Tests

A Python wrapper for Matrix Synapse admin API.

Versioning

This library now supports up to Synapse 1.45.0, any Admin API introduced after 1.45.0 may not be included in this version. However, newer changes to Admin API are planned to be included in this library. For planned update, see TODO.md. In the future, the version numbering convention will follow the version this library up to, for example, if this library supports up to 1.45.0, then the version number of this library will be 1.45.0. And the minor number will be reserved for bug fixes in this repo.

Releases older than 0.1.5 only work with HTTP/2

Get Started

Install from PyPi

pip install matrix-synapse-admin

Provide the connection information and access token in the first time of execution. You can either enter the information interactively or as arguments:

Interactively

>>> from synapse_admin import User
>>> user = User()
# The config creator is smart enough to determine the protocol and port by providing either one.
Enter the homeserver URL with port(e.g. https://example.com:443): https://example.com # Only need to be entered in the first time
Enter the access token (leave blank to get the access token by logging in): <access token or leave blank> # Only need to be entered in the first time
# If access token is left blank
Enter a username: admin
Enter a password:
Token retrieved successfully
Save to a config file? (Y/n)
>>> details_of_users = user.lists()
>>> print(details_of_users)
[{'name': '@admin:example.com', 'user_type': None, 'is_guest': 0, 'admin': 1, 'deactivated': 0, 'shadow_banned': False, 'displayname': 'Admin', 'avatar_url': 'mxc://example.com/ABCDEFG'}]
>>> print(details_of_users.total)
1

As arguments

", "https://") >>> details_of_users = user.lists() >>> print(details_of_users) [{'name': '@admin:example.com', 'user_type': None, 'is_guest': 0, 'admin': 1, 'deactivated': 0, 'shadow_banned': False, 'displayname': 'Admin', 'avatar_url': 'mxc://example.com/ABCDEFG'}] >>> print(details_of_users.total) 1 ">
>>> from synapse_admin import User
>>> user = User("example.com", 443, "
   
    "
   , "https://")
>>> details_of_users = user.lists()
>>> print(details_of_users)
[{'name': '@admin:example.com', 'user_type': None, 'is_guest': 0, 'admin': 1, 'deactivated': 0, 'shadow_banned': False, 'displayname': 'Admin', 'avatar_url': 'mxc://example.com/ABCDEFG'}]
>>> print(details_of_users.total)
1

Documentation

Docstrings are present now in most methods and classes. If you see /equivalent to ".*"/, it's mean that you may want to refer back to the Synapse Admin API documentation.

More documentation are coming...

Additional features

In addition to the wrapper that wraps the official admin APIs, this wrapper also provides serval unofficial helper methods or admin APIs, they include:

  • Reactivate an deactivated account (User.reactivate)
  • Create a room (Room.create)
  • Send an announcement to everyone (Management.announce_all)
  • Delete media by id or by condition (Media.delete_media)

Contribution

If you want to help me to improve the quality of this project, you can submit an issue.

If you want to collaborate with us, feel free to Fork this project and open a pull request.

What can you do?

  • For Issue

    • Report any Error.
    • Request new features based on the Synapse Admin API
    • Ask questions if you do not understand something.
  • For Pull request

    • Add comments to source code.
    • Add new features based on the Synapse Admin API
    • Correct any Error.
You might also like...
A Python wrapper around Bacting

pybacting Python wrapper around bacting. Usage Based on the example from the bacting page, you can do: from pybacting import cdk print(cdk.fromSMILES

Python wrapper to different clients to determine how a particular term is used.

Python wrapper to different clients to determine how a particular term is used.

Xbps-install wrapper written in Python that doesn't care about case sensitiveness and package versions
Xbps-install wrapper written in Python that doesn't care about case sensitiveness and package versions

xbi Xbps-install wrapper written in Python that doesn't care about case sensitiveness and package versions. Description This Python script can be easi

🤖🧭Creates google-like navigation menu using python-telegram-bot wrapper

python telegram bot menu pagination Makes a google style pagination line for a list of items. In other words it builds a menu for navigation if you ha

An html wrapper for python

MessySoup What is it? MessySoup is a python wrapper for html elements. While still a ways away, the main goal is to be able to build a wesbite straigh

A simple wrapper for joy library
A simple wrapper for joy library

Joy CodeGround A simple wrapper for joy library to render joy sketches in browser using vs code, (or in other words, for those who are allergic to Jup

Installer, package manager, build wrapper and version manager for Piccolo

Piccl Installer, package manager, build wrapper and version manager for Piccolo

Wrapper around anjlab's Android In-app Billing Version 3 to be used in Kivy apps

IABwrapper Wrapper around anjlab's Android In-app Billing Version 3 to be used in Kivy apps Install pip install iabwrapper Important ( Add these into

Custom SLURM wrapper scripts to make finding job histories and system resource usage more easily accessible

SLURM Wrappers Executables job-history A simple wrapper for grabbing data for completed and running jobs. nodes-busy Developed for the HPC systems at

Comments
  • "Iterable bodies must always iterate in bytestrings"

    I just started testing your wrapper.

    So far I can connect to our matrix server, get information (e.g. version, user list). As soon as I try to send a body to the server (i.e. to create a user, send an announcement, ...), I get an error:

    "Iterable bodies must always iterate in bytestrings"

    Maybe I am just doing something wrong - is there any documentation or could you provide an example of user creation?

    Thanks and best regards Thomas

    bug 
    opened by thoschi 15
  • Avoid the anti flood

    Avoid the anti flood

    Hey, I've used your code and it worked very well, nice job ! In my opinion it would be useful to insert a command that avoids running into the antiflood of synapse For example: I wrote a script with which I generated about 60 rooms starting from a txt file that contained their names. The server after the fifth / sixth room started giving some errors To solve this, I inserted a 60-second sleep between the creation of one room and the next one

    In my opinion it would be useful if this library will be able to disable the antiflood with a python command, or at least make it more flexible.

    enhancement 
    opened by DamianoP 6
  • Running tests

    Running tests

    When i was trying to run the tests to find if there were any flaky tests in the project I got the error saying that "no such file or directory: 'synapse_test/admin.token'". Just wondering where this file locates.

    question 
    opened by XinyuLiu5566 3
  • FYI: https://github.com/JOJ0/synadm

    FYI: https://github.com/JOJ0/synadm

    .. just had a look at current status of synapse admin tools (~medium impressive xD) and found a few, amongst which I like yours and https://github.com/JOJ0/synadm which already seems to have quite the endpoint coverage (haven't tried either yet). So this issue is just to let you know synadm is out there, maybe there's some synergy potential :cowboy_hat_face:

    generic 
    opened by eMPee584 3
Releases(0.7.0)
  • 0.7.0(Jun 9, 2022)

    As mentioned in Synapse 1.58.0 release notes, groups feature will be remove in 1.61.0. Therefore, this will be the last version that support groups related API.

    Changes since 0.6.7

    1. Implemented two new APIs introduced in 1.52.0.
    2. Added an alias (Media.delete) for Media.delete_media.
    3. Media.delete_media accept a list of media id in "mediaid" argument now.

    Bug fixed

    1. When "admin" & "deactivated" in User.create_modify is False, the program does not pass the boolean value to the request body.
    Source code(tar.gz)
    Source code(zip)
  • 0.6.7(Feb 1, 2022)

  • 0.6.5(Dec 15, 2021)

    Changes since 0.6.0

    1. Implemented new delete room API.
    2. Implemented un-shadow ban API.
    3. Implemented block room APIs.
    4. Implemented APIs related to federation.
    5. Implemented APIs related to background update.
    6. Updated dependency HTTPX from 0.20.0 to 0.21.1.
    7. Added ability to add offset to current time in Utility.get_current_time.
    Source code(tar.gz)
    Source code(zip)
  • 0.6.0(Nov 18, 2021)

    Changes since 0.5.6

    1. Support Python 3.10.0
    2. Updated dependency HTTPX from 0.18.2 to 0.20.0
    3. Show an error when timestamp in seconds is provided to the Media.purge_remote_media API.
    4. ClientAPI.admin_login will now perform auto-retry when HTTP 429 occurs.
    5. Added support for changing user type in User.create_modify.
    6. Added support for background updates status admin API.
    Source code(tar.gz)
    Source code(zip)
  • 0.5.6(Sep 11, 2021)

  • 0.5.5(Aug 25, 2021)

    Changes since 0.5.0

    1. Added unit testing
    2. Added checking for argument order_by in User.lists
    3. Added username availability checking API
    4. Added delete media uploaded by a user API
    5. Added a new parameter called "external_ids" to User.create_modify
    6. Updated dependency httpx to 0.18.2
    7. Implemented a simple MIME type guessing based on magic
    8. Support sending media in an announcement
    9. Management.announce is now a helper method for old Management.announce and Management.announce_all
    10. Some PEP8
    Source code(tar.gz)
    Source code(zip)
  • 0.5.0(Jul 30, 2021)

    This version has incompatibility with the previous version

    • Any methods that will return total number and/or next token will now return a new class, named Contents and ContentsDict, instance
      • The returned data (list/dict) can be accessed by Contents and ContentsDict itself
      • The total number can be accessed through Contents.total and ContensDict.total
      • The next token can be accessed through Contents.next and ContensDict.next

    Changes since 0.3.0

    1. Added homeserver alias validation
    2. Added default value for size_gt in Media.delete_media
    3. Added type checking on argument "timestamp" in Media.delete_local_media_by_condition
    4. Added checking for the conflict values of members and leave in Room.create
    5. Added some alias for Room, Management, Media and ClientAPI
    6. Added an option for non-admin login in ClientAPI
    7. Added a new class named "Contents" to handle returned data with the total number and/or next token
    8. Replaced all return data which contain a total number and/or next token
    9. Converted some tuple in return data of some methods to NamedTuple
    10. Improved docstrings
    11. Re-implemented User._generate_mac
    12. Handled error in User.deactivate, User.active_sessions and User.query
    13. Renamed the package name in __init__
    14. Renamed ClientAPI.client_create to client_create_room and ClientAPI.client_leave to client_leave_room
    15. Made argument "userid" in Room.set_admin optional to implement the feature of granting power to the user themself
    16. Set the default value of size_gt to 0 in Media.delete_local_media_by_condition
    17. Support encryption when creating room
    18. Raise SynapseException instead of just returning False when an error occurs in _Device.delete and _Device._delete_multiple
    19. Accept a mxc URI as media id in class Media

    Bug fixed

    1. User() and ClientAPI() read configuration when connection information is provided in initial variable
    2. Suppression of exception in _Device is missing
    3. The key, purge_id, is being accessed too early in Management.purge_history
    4. Wrong key being accessed in Room.lists and ClientAPI.client_create
    5. Parameter members in Room.create is not being checked for None before goes to the for loop
    Source code(tar.gz)
    Source code(zip)
  • 0.3.0(Jul 5, 2021)

    Changes since 0.2.0

    1. Implement the whole media statistics API
    2. Room.lists will now return dict item individually instead of returning the whole dict
    3. Return next_token in Management.event_reports
    4. Return a dict with user id as key and the event id as value in Management.announce_all
    5. Return bool instead of a list in Media.delete_local_media
    6. More docstrings
    7. Refactored some return line
    8. Removed SynapseAPIError

    Bug fixed

    1. User.lists return one more value now, hence Management.announce_all is broken
    2. Fix some broken docstring contents
    Source code(tar.gz)
    Source code(zip)
  • 0.2.2(Jun 30, 2021)

    Changes since 0.2.0

    1. Force the user to enter only "y" or "n" or leave it blank in saving config dialog

    Bug fixed

    1. Failure to authenticate the user after invoking Admin.modify_config
    2. Even the user chose not to save the config in the dialog, the config still being saved
    Source code(tar.gz)
    Source code(zip)
  • 0.2.0(Jun 16, 2021)

    Changes since 0.2.0rc2

    1. Development status changed from alpha to beta!
    2. Added a helper method for deleting local and remote media
    3. Refactored some code
    4. Made kwargs in User.create() keyword-only arguments
    5. More and better documentation
    6. Returning next_token in User.lists
    7. Support argument "dir" in User.lists
    8. Returning the admin status of the user after invoking User.set_admin
    9. User.validity will now return expiration_ts instead of a dict with only one key

    Bug fixed

    1. server_name in Media.quarantine_remove should be optional
    Source code(tar.gz)
    Source code(zip)
  • 0.2.0rc2(Jun 10, 2021)

    Changes since 0.2.0rc1

    1. Allow user to get the access token by logging in their admin account
    2. Correct the data type of argument "federation" in ClientAPI.client_create and Room.create
    3. Separated the client API to another module
    4. Added 'Mgt' as an alias for Management
    5. Unprotected two new APIs introduced in 1.36.0
    6. Added more type hints

    Bug fixed

    1. Wrong Pypi classifier
    2. No exception information available when the user authenticated successfully but not an admin
    Source code(tar.gz)
    Source code(zip)
  • 0.2.0rc1(Jun 6, 2021)

    Changes since 0.1.5:

    1. Support automatically set or revoke admin in User.set_admin
    2. Support enter password interactively
    3. Re-implemented Admin.modify_config
    4. Added context managers (with User() as user)
    5. Added some type hints
    6. Added some documentation strings
    7. Added docs
    Source code(tar.gz)
    Source code(zip)
  • 0.1.5(Jun 3, 2021)

    As the original HTTP client library Hyper is no longer maintained, this update migrated the HTTP client from Hyper to HTTPX.

    Changes since 0.1.5rc2:

    1. Tested all API endpoints after the HTTP library migrated.
    2. Changed the User.modify from a method to an alias.
    3. Removed redundant validation of username in User.
    4. Separated the endpoint of getting nonce for register.
    5. Changed type hint in Room.create.
    6. Renamed a variable in Management.
    7. Added validate_group method.
    8. Support argument "valid_until_ms" in User.login.

    Bug fixed

    1. Exception will be raised when DELETE requests have a body.
    2. Unusable _Device class.
    3. Some returned status_code variables are incorrect in Management and Room.
    Source code(tar.gz)
    Source code(zip)
  • 0.1.5rc2(May 30, 2021)

    As the original HTTP client library Hyper is no longer maintained, this update migrated the HTTP client from Hyper to HTTPX. This update is not yet tested heavily, use it at your own risk.

    Changes since 0.1.5rc1:

    1. Allow the connection information not to be saved after the prompt of asking for the information.
    2. Support protocol selection in the connection information
    3. Refactored code
    4. Added some type hints
    5. Added some documentation
    6. Requires at least Python 3.7
    Source code(tar.gz)
    Source code(zip)
  • 0.1.5rc1(May 21, 2021)

    Major update

    As the original HTTP client library Hyper is no longer maintained, this major update migrated the HTTP client from Hyper to HTTPX. This update is not yet tested heavily, use it at your own risk.

    Bug fixed:

    1. Configuration creation function will be invoked even connection information is provided in the instantiation of classes.
    2. HTTP/1 was not supported properly.
    Source code(tar.gz)
    Source code(zip)
  • 0.1.1(May 19, 2021)

    Description of the fixed bug: The function goes into the exception section instead of returning True when user is created successfully.

    No other changes since 0.1.0.

    Source code(tar.gz)
    Source code(zip)
  • 0.1.0(May 19, 2021)

Owner
Knugi
Hong Kong Software Developer.
Knugi
Heisenbridge a bouncer-style Matrix IRC bridge

Heisenbridge brings IRC to Matrix by creating an environment where every user connects to each network individually like they would with a traditional IRC bouncer

Toni Spets 152 Dec 28, 2022
A maubot plugin to invite users to Matrix rooms according to LDAP groups

LDAP Inviter Bot This is a maubot plugin that invites users to Matrix rooms according to their membership in LDAP groups.

David Mehren 14 Dec 9, 2022
A dot matrix rendered using braille characters.

⣿ dotmatrix A dot matrix rendered using braille characters. Description This library provides class called Matrix which represents a dot matrix that c

Tim Fischer 25 Dec 12, 2022
A module to prevent invites and joins to Matrix rooms by checking the involved server(s)' domain.

Synapse Domain Rule Checker A module to prevent invites and joins to Matrix rooms by checking the involved server(s)' domain. Installation From the vi

matrix.org 4 Oct 24, 2022
A Github Action for sending messages to a Matrix Room.

matrix-commit A Github Action for sending messages to a Matrix Room. Screenshot: Example Usage: # .github/workflows/matrix-commit.yml on: push:

null 3 Sep 11, 2022
A GUI love Calculator which saves all the User Data in text file(sql based script will be uploaded soon). Interative GUI. Even For Admin Panel

Love-Calculator A GUI love Calculator which saves all the User Data in text file(sql based script will be uploaded soon). Interative GUI, even For Adm

Adithya Krishnan 1 Mar 22, 2022
An async API wrapper for Dress To Impress written in Python.

dti.py An async API wrapper for Dress To Impress written in Python. Some notes: For the time being, there are no front-facing docs for this beyond doc

Steve C 1 Dec 14, 2022
A Python wrapper API for operating and working with the Neo4j Graph Data Science (GDS) library

gdsclient NOTE: This is a work in progress and many GDS features are known to be missing or not working properly. This repo hosts the sources for gdsc

Neo4j 100 Dec 20, 2022
Wrapper for the undocumented CodinGame API. Can be used both synchronously and asynchronlously.

codingame API wrapper Pythonic wrapper for the undocumented CodinGame API. Installation Python 3.6 or higher is required. Install codingame with pip:

Takos 19 Jun 20, 2022
API wrapper for VCS hosting system.

PythonVCS API wrapper for VCS hosting system. Supported platforms Gitea Github, Gitlab, Bitbucket support will not, until that packages is not updated

MisileLaboratory 1 Apr 2, 2022