Testers and Contributors for updated Plankapy (v2)

[hwelch-fle]

I've been re-writing the plankapy python module over the past few months when I get the chance to make it more usable. The current re-write is living here under the v2-working main branch.

I think the new version is more usable and extensible than the original that I threw together in a weekend. However as I'm currently the only one working on this branch, I can't really get any good feedback or reports. If anyone here is interested in taking a look or playing around with it to let me know if it's useful or not that would be greatly appreciated.

Because there are currently several forks of the original code and the new code is incompatible with anything that uses v1, I'm not sure exactly what to do. I have an open issue here for discussion with the community on how I should handle these conflicting implementations of the API in Python. I've decided to move the old code to it's own branch v1 and move the new version into main.

As of now it requires no dependencies (not even requests), but I've moved all request handling to a handlers.py submodule and created a BaseHandler protocol so alternate handlers can be written foe edge cases (the current implementation can't render Javascript clientside, so a few of the endpoints that require that are dead).

Here's a quick peek at how it's used:

import plankapy as pk

auth = pk.PasswordAuth('username", "password")
planka = pk.Planka("planka.com", auth)

projects = planka.projects

for project in project:
    print(project.name)
    print('\t\n'.join(board.name for board in project.boards))

>>> Project 1
>>>    Board A
>>>    Board B
>>> Project 2
>>>     Board A
...

project = planka.projects[0]
board = project.boards[0]
list = board.lists[0]
card =list.cards[0]

labels = { label.name: label for label in board.labels }

with card.editor():
    card.description = "Please Review"
    card.add_label(labels['Review'])

[seals187]

Hi there,

I dont know how to programm but If I can help , just tell me what to do.
(I have the plankapp running on a aws ec2 vps) buts thats production, not a test env. for tests.
But I could put up a linux srv and test stuff on it with a other planka version, if thats what you need/want.. ?

best regards
seals187

[hwelch-fle]

Any testing would be great! I tried to write it in a way where you can install it and basically let VS Code or your intelisense editor of choice do most of the work.

Go ahead and join the discussion on the repo and I'll let you know when I publish the first v2 package to PyPi. That way you can just pip install it and start using it.

The idea would be to publish a container that lets you run it alongside Planka to handle doing automation or batch operations in a few lines of Python.

[seals187]

ok thanks, I will do so..

[John-Gear]

Hi, I've been working on a long time project of migrating boards from trello to planka. I'm writing in python. Implemented: json export of boards with more than 1000 actions. Export of all attachments. But at the moment I can't do anything about importing attachments into planka. Because there is no api for working with attachments yet? How can I join the development? My goal is to create a universal python tool for mass migration of boards from trello to planka with all attachments/structure.

[hwelch-fle]

I will create a public repository and post my work on mass importing boards/attachments from trello there. When I was working with your api, I noticed that there was no entry point for attachments, as I understand now this is due to the limitations of planka v1. As far as I understand, the development of planka v1 is stopped, as planka v2 is being prepared for release. We should probably ask the developer at this stage to implement functionality for working with attachments. Have you thought about getting involved in the development of the api in planka v2?

I've actually got it working now with their help. I'll version bump and make a new release soon!

I also tried to write plankapy in a way that will let me just implement their new API if they have one and extend the interfaces. All communication with the API is hidden from the end user, they just treat it like a reguar Python object.

[John-Gear]

That's great! Looking forward to updating your repository. Thank you for your work, it is much appreciated

[hwelch-fle]

That's great! Looking forward to updating your repository. Thank you for your work, it is much appreciated

As long as you're using 3.11+, you can pip install it. Latest version in 2.2.1 with minor version 2 being the added attachment functionality and the patch 1 being some last second updates to allow for managing user avatars and allowing webassets to be used instead of local filepaths.

for user in planka.users:
    user.set_avatar('http://<url-to-avatar>.png')

Would set all user avatars to some image on the web

for user in planka.users:
    user.download_avatar(f'/home/user/avatars/{user.name}_avatar.png')

Would download all user avatars to a local folder.

This also works with project backgrounds and attachments, though with attachments you'd want to use the stored filename so the filetype is captured correctly.

My next step will be re-writing some of the typing stuff to make it compatible with 3.8 at least. I went really aggressive with the new typing features to make IDE auto-completion and static checks work everywhere. That means you need 3.11 with the Self and Optional types currently, but I can just defer those imports depending on version. Other than that there are no dependencies and it all runs on the standard library.

[John-Gear]

Thank you dear friend. If you have indeed implemented attachment handling in your api, I will urgently start developing a python migration script using your api. However, I can't find the api documentation page, I used to have it in my bookmarks - https://hwelch-fle.github.io/plankapy/plankapy.html#Card.template. But now the response is 404 - Not Found.

[hwelch-fle]

Thank you dear friend. If you have indeed implemented attachment handling in your api, I will urgently start developing a python migration script using your api. However, I can't find the api documentation page, I used to have it in my bookmarks - https://hwelch-fle.github.io/plankapy/plankapy.html#Card.template. But now the response is 404 - Not Found.

I updated the docs with hardlinks instead of autorefs: https://hwelch-fle.github.io/plankapy/interfaces/Card/

You can also just click API in the title bar from the 404 page and it'll drop you on the API docs

I'm rebuilding the docs now, there was still a Danger tag in there saying Attachments weren't supported

[hwelch-fle]

@meltyshev I've been actively working on updating plankapy to support the v2 API.

Current work is happening in the v2.0.0_refactor branch with a trickle of PRs one one of the older branches.

The current goal is to utilize your published swagger/open API spec to auto-build an interface that uses httpx client sessions.

I've got the paths done and only need to work on rebuilding the interfaces for the user side, but you can definitely use the PlankaEndpoints and AayncPlankaEndpoints classes as is for testing.

I'm going to keep the original v1 code as is with all v2 related code in a submodule.

Since this is built directly from your spec, I may be opening some minor PRs to keep that spec consistent and correct when I run into issues since my old approach of writing the API typing by hand was a pain and led to issues when new features were added.

This new module is fully type hinted and all docs written in the API spec are directly exposed in Python docstrings and will be published to the plankapy documentation site using mkdocs when I make the first release.

Would definitely appreciate feedback from the team here if you have any!

[meltyshev]

Hey! Thanks for working on this ❤️

I tried generating the full SDK once using https://openapi-generator.tech, and it worked pretty well. The only issue I ran into was that uploading files required using dictionaries to pass the data instead of models. So yes, this would definitely be the best approach - to update it automatically based on the Swagger spec :)

Since this is built directly from your spec, I may be opening some minor PRs to keep that spec consistent and correct when I run into issues since my old approach of writing the API typing by hand was a pain and led to issues when new features were added.

Absolutely, feel free to open any PR - we'd be happy to merge it.

Would definitely appreciate feedback from the team here if you have any!

We'll definitely check it soon! Also, in the final v2, there will be the ability to generate API keys per user (already merged), which should make it easier to use plankapy.

[hwelch-fle]

I think having a fully type hinted API will be crazy useful. Especially if it's following the swagger spec exactly. There will of course be divergences from the api backend when implementing interfaces (the whole point of plankapy is to make Planka abide by Python object types and behaviors), but those are easier to deal with if the type system highlights them when the backend gets rebuilt.

Here's a quick example of the current working api portion (required attributes are marked as such so a type checker will yell at you if they aren't filled out):

All exposed attributes are typed and allow for easy navigation of the response dictionary. The models will inherit the direct response for each object to build type conversion in for the final public interface:

[meltyshev]

Omg, it looks very cool!

[hwelch-fle]

Very excited to get it completed, we're finally upgrading to v2 soon so I have the time to update the package.

Managed to get a minimal interface up and running today, just have to finish implementation and write the tests now!

[hwelch-fle]

New documentation is up at https://hwelch-fle.github.io/plankapy/v2/interface/

The v2 branch is being merged in this PR hwelch-fle/plankapy#38

The commit history is a mess, and I will likely squash it when I merge

[meltyshev]

Hey, congrats - you've done a great job!

[hwelch-fle]

Hey, congrats - you've done a great job!

Thanks! I've gone ahead and published a new release with the current code and made a PR on the docs repo with the updated README

Next big thing is setting up a docker container that runs a small webserver that accepts hooks from planka and runs automations.