mattermostautodriver 2.0.0

信息

该仓库将努力与https://github.com/mattermost/mattermost/ (子文件夹 api) 中的 api 规范保持一致。mattermostautodriver 中的 API 变更可能是由于参考 mattermost API 文档的变更。

此项目基于 https://github.com/Vaelor/python-mattermost-driver 分支，但使用自动方法从 mattermost OpenAPI 规范生成所有 Python 端点文件。

需要 Python 3.6 或更高版本。

版本和发布

由于 API 经常出现破坏性变更，此仓库使用的版本方案不是严格的 SemanticVersioning。相反，应考虑以下 MAJOR.MINOR.PATCH 版本数字的变化

• PATCH：包括错误修复、非破坏性更改或新端点的添加

• MINOR：包括破坏性更改，如删除单个端点

• MAJOR：包括删除整个模块或端点集合的破坏性更改

在生产环境中，建议将版本锁定到 MINOR 数字（例如 1.3.x）。

安装

pip install mattermostautodriver

文档

文档可在以下网址找到：https://embl-bio-it.github.io/python-mattermost-autodriver/。

用法

from mattermostautodriver import Driver

foo = Driver({
    """
    Required options

    Instead of the login/password, you can also use a personal access token.
    If you have a token, you don't need to pass login/pass.
    It is also possible to use 'auth' to pass a auth header in directly,
    for an example, see:
    https://embl-bio-it.github.io/python-mattermost-autodriver/#authentication
    """
    'url': 'mattermost.server.com',
    'login_id': 'user.name',
    'password': 'verySecret',
    'token': 'YourPersonalAccessToken',

    """
    Optional options

    These options already have useful defaults or are just not needed in every case.
    In most cases, you won't need to modify these, especially the basepath.
    If you can only use a self signed/insecure certificate, you should set
    verify to your CA file or to False. Please double check this if you have any errors while
    using a self signed certificate!
    """
    'scheme': 'https',
    'port': 8065,
    'basepath': '',
    'verify': True,  # Or /path/to/file.pem
    'mfa_token': 'YourMFAToken',
    """
    Setting this will pass the your auth header directly to
    the request libraries 'auth' parameter.
    You probably only want that, if token or login/password is not set or
    you want to set a custom auth header.
    """
    'auth': None,
    """
    If for some reasons you get regular timeouts after a while, try to decrease
    this value. The websocket will ping the server in this interval to keep the connection
    alive.
    If you have access to your server configuration, you can of course increase the timeout
    there.
    """
    'timeout': 30,

    """
    This value controls the request timeout.
    See https://python-requests.org/en/master/user/advanced/#timeouts
    for more information.
    The default value is None here, because it is the default in the
    request library, too.
    """
    'request_timeout': None,

    """
    To keep the websocket connection alive even if it gets disconnected for some reason you
    can set the  keepalive option to True. The keepalive_delay defines how long to wait in seconds
    before attempting to reconnect the websocket.
    """
    'keepalive': False,
    'keepalive_delay': 5,

    """
    This option allows you to provide additional keyword arguments when calling websockets.connect()
    By default it is None, meaning we will not add any additional arguments. An example of an
    additional argument you can pass is one used to  disable the client side pings:
    'websocket_kw_args': {"ping_interval": None},
    """
    'websocket_kw_args': None,

    """
    Setting debug to True, will activate a very verbose logging.
    This also activates the logging for the requests package,
    so you can see every request you send.

    Be careful. This SHOULD NOT be active in production, because this logs a lot!
    Even the password for your account when doing driver.login()!
    """
    'debug': False
})

"""
Most of the requests need you to be logged in, so calling login()
should be the first thing you do after you created your Driver instance.
login() returns the raw response.
If using a personal access token, you still need to run login().
In this case, does not make a login request, but a `get_user('me')`
and sets everything up in the client.
"""
foo.login()

"""
You can make api calls by using calling `Driver.endpointofchoice`.
Using api[''] is deprecated for 5.0.0!

So, for example, if you used `Driver.api['users'].get_user('me')` before,
you now just do `Driver.users.get_user('me')`.
The names of the endpoints and requests are almost identical to
the names on the api.mattermost.com/v4 page.
API calls always return the json the server send as a response.
"""
foo.users.get_user_by_username('another.name')

"""
If the api request needs additional parameters
you can pass them to the function in the following way:
- Path parameters are always simple parameters you pass to the function
"""
foo.users.get_user(user_id='me')

# - Query parameters are always passed by passing a `params` dict to the function
foo.teams.get_teams(params={...})

# - Request Bodies are always passed by passing an `options` dict or array to the function
foo.channels.create_channel(options={...})

# See the mattermost api documentation to see which parameters you need to pass.
foo.channels.create_channel(options={
    'team_id': 'some_team_id',
    'name': 'awesome-channel',
    'display_name': 'awesome channel',
    'type': 'O'
})

"""
If you want to make a websocket connection to the mattermost server
you can call the init_websocket method, passing an event_handler.
Every Websocket event send by mattermost will be send to that event_handler.
See the API documentation for which events are available.
"""
foo.init_websocket(event_handler)

# Use `disconnect()` to disconnect the websocket
foo.disconnect()

# To upload a file you will need to pass a `files` dictionary
channel_id = foo.channels.get_channel_by_name_and_team_name('team', 'channel')['id']
file_id = foo.files.upload_file(
    channel_id=channel_id,
    files={'files': (filename, open(filename, 'rb'))}
)['file_infos'][0]['id']


# track the file id and pass it in `create_post` options, to attach the file
foo.posts.create_post(options={
    'channel_id': channel_id,
    'message': 'This is the important file',
    'file_ids': [file_id]})

# If needed, you can make custom requests by calling `make_request`
foo.client.make_request('post', '/endpoint', options=None, params=None, data=None, files=None, basepath=None)

# If you want to call a webhook/execute it use the `call_webhook` method.
# This method does not exist on the mattermost api AFAIK, I added it for ease of use.
foo.client.call_webhook('myHookId', options) # Options are optional

更新 OpenAPI 规范

首先，我们需要以 OpenAPI JSON 格式获取 Mattermost 的 API。

git clone --depth=1 --filter=tree:0 https://github.com/mattermost/mattermost
cd mattermost/api
make build
./node_modules/.bin/swagger-cli bundle --outfile openapi.json v4/html/static/mattermost-openapi-v4.yaml
cd -

使用上述命令，您将克隆并创建一个用于转换脚本的 openapi.json 文件。

首先在虚拟环境中安装所有必要的依赖项。

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

最后，在虚拟环境仍然加载的状态下执行

./generate_endpoints.sh

以生成更新的端点定义。

cd docs
./update_endpoints.py

需要在更新端点文档后执行。

当前的 API 转换代码是为 Python 3.9 设计的。因为它使用了 Python 的 AST 解析器和生成器，以及 Black，不同的 Python 版本可能会导致生成的代码存在一些差异。完成后，请使用 git diff 进行双重检查。