Add Documentation

[clintonb]

You link to a 37 minute long video. While the video may hold useful information, few will spend time viewing it.

[mindflayer]

Yes, you are right. It's also true sources are plenty of tests, you can start with them to understand how mocket works.

[clintonb]

Nah. I simply found an alternative to mocket. If I had to look thorough the
code/tests of every package I would never get any work done.

Clinton

[mindflayer]

Good luck. 👍

[quasipedia]

@clintonb - What alternative have you found? I simply can't propose my team to work with something undocumented. (No offence guys: yours seem a cool project!)

[mindflayer]

No offence at all, really. It's a bad period and we can't contribute as we wish to mocket (@z4r is becoming dad) .

[mindflayer]

We use mocket at the office but we have no time to improve it during our work time.

[clintonb]

It's been a while, so I cannot recall what we ended up using. This was around the time I was building a new API. I think I ended up simply mocking the call to the API client instead of going deep into the socket layer.

[mindflayer]

As far as I know, the only library similar to mocket is HTTPretty (https://github.com/gabrielfalcao/HTTPretty) - the one that inspired us - but it's only for HTTP call, no alternatives for other protocols. That's why we wrote mocket.

[quasipedia]

Congratulations to Andrea/@z4r then! :)

The cool thing about Mocket is that it works with regular sockets (great for my usercase where I am using msgpack as the transport layer), this is how I found your project.

I took a look at the internals and it seems quite smartly done, although I must say I haven't really understood why you went with Mocket being used as a class (I understand the need to have a singleton-like behaviour for a socket-mocker, but I didn't understand if there's some other requirements that made a class a preferred option over the more idiomatic borg pattern). Just honest curiosity, not a criticism! :)

[ThreeQuarterCoder]

The explanation is not clear.
"for all kinds of socket animals, web-clients included - with gevent/asyncio/SSL support"
doesn't explain what mocket does.

[mindflayer]

Hi @saksham-kumar, there are a couple of blog posts I've written recently that should help:
https://medium.com/@mindflayer/mocket-is-alive-and-is-fighting-with-us-b2810d52597a
https://hackernoon.com/make-development-great-again-faab769d264e#.pokdigch1

The README published here should also help.

[git-staus]

I don't mean to nag nor be entitled, but I think this issue deserves reopening. Perhaps a more specific one should be opened instead? What do the maintainers prefer?

The current state

I like the enthusiastic tone of the many articles linked from the README, but most of them are from 2017 and the latest one is three years old. Narrative form also do not support quick referencing of the details of specific functionality either, like "proper" documentation usually does. IMHO it is not an exaggeration to say that the current documentation is unorganised and (seemingly) outdated and that this hurts the adoption of this package.

Labour required

Given the excellent test coverage and the active maintainance I assume most of the information gathering has already been performed. Collecting that knowledge into something like Read the Docs or a better system that generates documentation from the source code should not be as much work as it would be for the average code base. This situation probably also means documenting could even be delegated to outside contributors.

Place in the ecosystem

Given how httpretty is abandoned nowadays, and responses does not support anything besides requests, mocket seems to be the only viable option within the Python ecosystem for all the "less prominent" HTTP things like urllib (part of the Python standard library!)

Because of this I think there should be a large number of documentation-expecting users (and maybe willing contributors) coming this way.

Visibility of mocket

Despite of what I judge to be a central position in the ecosystem, it took me quite a lot of browsing to even find mocket. I judge it to have a visibility problem, which I expect could be ameliorated with (more) accessible documentation.

A weaker argument: GPT-4o mini does not even list it when prompted for an httpretty alternative. Not that current AI can be expected to give sound advice, but this does give me the impression that the net-wide prominence of this 10+ year-old, actively maintained library is surprisingly low.

---

Given how I do not see any alternative to mocket, I will now invest time in finding and understanding the relevant test code while trying to get my use case to work. This is probably trivial once I get the hang of it, but getting to that point is probably still going to take me a whole lot longer than the people who wrote the code base (as @clintonb hinted eleven years ago). I can imagine the time spent on this by every single new user – of which only a small minority even bothers to comment here – cumulatively adds up to a lot of manhours. (Nobody is entitled to hand-held programming of course, but we would all benefit from reducing this)

If there was a consensus on a desired documentation workflow I would have been able to contribute back what I learned afterwards. (For now I can take notes if that is appreciated.) My hope is that at least some of the new users also think like this.

[mindflayer]

First of all, I am not against reopening the issue. The fact that an issue is open does not imply that the related problem gets solved though. A proof of it is the back and forth with typing.

I like the enthusiastic tone of the many articles linked from the README, but most of them are from 2017 and the latest one is three years old.

Mocket has NEVER changed its interfaces. So, the fact that the articles are old is kinda irrelevant. I used the example from one of the articles months ago to present Mocket to some colleagues and all went fine.

This situation probably also means documenting could even be delegated to outside contributors.

There are no outside contributors, unfortunately. The only PRs that I received, in case they shipped code, were to solve specific problems people were experiencing (mostly about Mocket packaging from distro maintainers).

Because of this I think there should be a large number of documentation-expecting users

My perception is quite different though, I co-authored Mocket in 2013 and I've been the only maintainer for ages. Many people don't use Mocket because today there are simpler alternatives. With simpler I don't mean they have simpler APIs, I mean the way they work is closer to the way people normally mock their code (unittest.mock style). Back in the day, when httpretty was born, it was the only alternative available. It quickly became very famous just because of that, and I am sorry but the project was never well-kept (e.g. Python 3 support arrived late and incomplete).

I judge it to have a visibility problem, which I expect could be ameliorated with (more) accessible documentation.

Same thing here, you assume many people need Mocket while the reality is different. People want to use simple client-side mocking techniques. Mocket is the only alternative if you are developing a client for a new protocol, or something like that. For mocking a few API calls there are simpler solutions. Of course, they way Mocket works make your tests more reliable, but this is not something that many people care nor understand.

This said. If you are offering to contribute to the project with documentation, feel free to do it. I'll reopen the issue if this makes you happier. But I am sorry I have no time to invest in writing more documentation, considering that all use-cases are covered by meaningful examples. The internals of Mocket don't interest to many people.