Proof-of-concept API derived from OpenAPI docs

[unode]

This is an incomplete attempt at implementing #60

Currently missing:

• arguments in cases where files need to be uploaded
• auto-generated docstrings

For the remaining first point, it may be possible to extract info from requestBody > content > multipart/form-data.

At the moment, what was:

def upload_brand_image(self, files):
    return self.client.post(
        self.endpoint + '/image',
        files=files
    )

became

def upload_brand_image(self):
    return self.client.post(
        "/brand/image"
    )

How to use

Generate OpenAPI json file

This creates mattermost-api-reference/openapi.json.

bin/update-openapi.sh

Generate API driver code

python3 -m venv venv
source venv/bin/activate
pip install jinja2 inflection
python3 bin/generate_endpoints.py

[unode]

The formatting code may be simplified if we can use f-strings.
However we will need Python 3.6 for this (see also #99)

[unode]

Feedback and contributions to this PR are welcome.

There are currently many API endpoints that aren't implemented in the latest version of this driver so this, or a similar solution, is much needed.

[Vaelor]

@unode Thanks for this, that is great. I will try to have a look at this as soon as I can, because having this feature would help a lot!
Also, sorry for my late reply. Life is rather busy at the moment.

[fried]

I was looking at this also we should definitely be able to figure out the arguments from the api definition.

[unode]

Hi @fried, just to let you and everyone here know that I have some progress from my last PoC. I think I managed to get all the details out and some edge cases as well, missing only some implementation bits.
There will be some new commits pushed before the end of the week.

[unode]

Hi everyone!

Finally had a chance to complete this.
The code now generates a complete conversion of the OpenAPI JSON specification.

The generated code produces function names also derived from the OpenAPI docs.
This means we will break with older function names. If we want to maintain a compatibility we will need some middle layer with old function names calling the newer functions.

For the time being I'm considering the current alpha quality.

Feedback is very much welcome!

[unode]

Things that need polishing include docstrings that are also currently autogenerated.
The syntax is sometimes a bit rough and may fail to compile under sphinx.

[unode]

Now at python-mattermost-autodriver under a new name python-mattermost-autodriver (notice the auto).

[Vaelor]

Hi @unode,

I feel like I really have to react already, sorry for the long delay. I have too much going on which results in this project not getting the attention it needs. Since you already felt the need to make a fork, I was wondering if your fork is the better way forward then? I already realized that I should probably look for a maintainer or something like that, since I just don't get around to properly deal with issues here, but I also don't have a clue how one would do that.

Also, I really, really appreciate the work you put into this!

[unode]

Hi @Vaelor,

No worries. We all know how getting busy can leave little to no time for side-projects. Same is true over here.

At the moment I created the fork mostly to allow easier testing and feedback if anyone in this thread wants to give it a try.
Quite a few function calls now have different names so if we don't want to break completely with the previous interface, we will need a compatibility layer. I had thought of something that would raise a deprecation warning and then call the appropriate method (similar to Teams.get_public_channels()).
This however will be a somewhat daunting task, requiring to manually go through 230 endpoints and map them to the 420 new ones.

Regarding finding a maintainer, I'd say start with a disclaimer in the README. Alternatively it may be worth considering moving the repository to a separate organization to simplify adding new maintainers. It may also be that the mattermost python community may be interested in picking up from where we left.

That said, with the OpenAPI parsing script I wrote, maintenance will likely be centered on the script itself. Besides that one only needs to ensure that the autogenerated code is correct and not utterly broken. There's the option of writing unit tests but I'm not sure how to go about that either.

[unode]

I'm leaving this open for the present time but would like to let everyone know that I started moving ahead with https://github.com/embl-bio-it/python-mattermost-autodriver which is now also available through PyPi at https://pypi.org/project/mattermostautodriver/ .

Notably, the auto-generated code doesn't currently provide a backwards compatibility layer. Old code using mattermostdriver will need to rename API calls. mattermostautodriver will follow a semantic versioning scheme starting with version 1.1.4.

Calling the new repository a fork is a bit of a stretch given that all the code in the endpoints folder is now auto-generated.

I already invited @Vaelor to co-maintain the auto-generated project. If any of the past contributors would like to help maintaining the new project, please reply in this thread and an invitation will follow.