mwclient 1.0 release

[RheingoldRiver]

Following up from this comment, what should a 1.0 release of mwclient look like?

Things to consider:

• The "gold standard" for MediaWiki libraries, see Follow "gold standard" #76
  • Biggest thing missing seems to be documentation
• long-term stability of usage, even if implementation will change

One other thing I'd like to consider is that Discord bots are becoming more and more popular, with discord.py and discord.js being the two main libraries. mwclient should be the go-to library for dpy, however, we don't have any async capability making it ill-suited for discord. Maybe we can add async functions for at least login, read, edit? This client does exist and I think it would be great for it to be merged into mwclient proper. I just spoke to @Wadu436 and he's interested in at least discussing the issue, even if not necessarily contributing code. It's possible that it doesn't make sense to combine these into one library; however, if they remain separate projects I think one is more likely to go unmaintained, which I think is unfortunate.

[AdamWill]

I'd say we de facto have "long-term stability of usage" - anyone using mwclient now has to be pretty used to how it works at present =) I guess I wouldn't want to make any overly radical changes. Improving documentation would definitely be a good idea.

I have never written much async stuff and don't have any interest in discord bots myself, so I'm not sure I have a lot of opinions about that side. It seems like aiomwclient is basically....mwclient, only with async def everything? As I said, I'm not that familiar with async, so...how disruptive would it be to merge that kind of thing into mwclient proper, but preserving the synchronous interface for users who have no interest in async usage?

[RheingoldRiver]

One thing to consider regarding stability is that in a 1.0 release, if we retain page.save, we will certainly need to keep it forever - currently both page.save and page.edit do the same thing. IMO there is no question that we should keep both (I've personally always used page.save) but if there's some reason to use edit only, this change should be made in 1.0 I think.

I'm not sure if there's any other similar aliases that exist.

See:

mwclient/mwclient/page.py

Line 177 in b1eb977

def save(self, *args, **kwargs):

[Wadu436]

It seems like aiomwclient is basically....mwclient, only with async def everything?

It's been a while since I worked on it, but most of the logic is (or should be) the same. The main difference is that all the HTTP requests are performed using an async library (aiohttp) instead of a sync one (requests).

To have both in one package, there's a few options, the most prominent in my opinion are

1. Move common logic off into their own synchronous functions, and maintain two versions of every function that performs HTTP requests. They would both call common logic, but perform their requests with either requests or aiohttp (or some other sync/async network libraries)
2. Move everything to async, and provide a sync interface by running the async functions in an executor for the user (asyncio.run())

Option 1 would likely perform the best as there doesn't have to be a new event loop for every synchronous request.
Both would probably perform the same for async calls.

Downside is that you'll need to have async libraries as dependencies (asyncio, aiohttp) even when a user only wants synchronous code.

I'm not super familiar with what Python packages can do, but if they have something like Rust's crate features, you might be able to avoid needing the async dependencies for the sync API.

[AdamWill]

I'm gonna suggest we go ahead and do a 1.0 release with more or less what we have now (we will need to come up with a new way of doing releases, though, as I think the old way was tied to travis; we can use a script like I do for my personal projects, or a GHA workflow maybe). I don't think it makes sense to delay a new release to meet all the 'gold standard' requirements - though we should still work towards that! - and I don't think it makes any sense for the project to be versioned 0.x, really. Practically speaking this is a stable library that downstreams have been relying on for years (I'm one of them). 1.x versioning would be appropriate.

I agree with @RheingoldRiver that we should keep page.save and page.edit and just accept that both will exist forever. It's fine, there's no shortage of verbs. :)

[AdamWill]

Similarly on the async stuff, I don't think it should hold up doing a 1.x release now. I think we can definitely look at it, though. I'll file a separate ticket for that.

[RheingoldRiver]

I'm out of town at the moment, so my involvement will be quite low for the next few weeks, but agreed with all the above!

[AdamWill]

Heads up on this for other maintainers @waldyrious @btongminh @marcfrederick - I've finally got a bit of spare time and am trying to set up a release workflow now following the guide at https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/ . You'll probably see some notifications from pypi and github related to this.

[AdamWill]

#331 adds a release workflow.