Code Annoyance - mocker mock Mocker Mock

The documentation of the Python Mocker library sucks. The example codes doesn't show the import statements at the beginning of the example, and they use the mocker (which is also the name of the package) as a variable inside the example, so you get double frustrated.

here is the example directly taken from the documentation of the library:
>>> mocker = Mocker()
>>> obj = mocker.mock()

>>> obj.hello()
>>> mocker.result("Hi!")

>>> mocker.replay()

>>> obj.hello()
'Hi!'

>>> obj.bye()
Traceback (most recent call last):
...
mocker.MatchError: [Mocker] Unexpected expression: obj.bye

>>> mocker.restore()
>>> mocker.verify()

the first weird thing is also the first line of the example code:
mocker = Mocker()

the second one is also the second line of the example code:
obj = mocker.mock()

all right, I can see that because the statement mocker now corresponds to a Mocker object the mocker.mock() should be returning a mock object (did you get my frustration, mocker mock Mocker Mock, wtf!)

what those guys written this documentation has forgotten should be a line of:
from mocker import *

and knowing this really doesn't help me too much, cause I don't code in this way. Really, who is importing everything to the module namespace should be doing something evil.

and also using the package name as a variable to hold an object which is produced by one of the classes of that package means you are really shitting in the namespace...

and I see a lot of this kind of namespace killer statements in package documentations, I think they think that is much clearer, but it is wrong, cause it really breaks the way I construct things in my mind.

I'm frustrated... or am I missing something...

EDIT:
As muhuk warned me about contributing an OpenSource package before complaining about its defects I created a bug report explaining my concerns. You can find the bug report here:
https://bugs.launchpad.net/mocker/+bug/663821

I need to thank to muhuk

Comments

muhuk said…
Have you found a dev in IRC to discuss this? Or have you sent them an email? Or at least have you left a ticket on their tracker?


IRC: irc.freenode.net/#python
email: gustavo at niemeyer dot net
tracker: https://bugs.launchpad.net/mocker


Yes, existing documentation sucks. But this is free software; free as in you-are-free-to-contribute-if-you-care-enough.

Best wishes,
Ok, I get your point and you are right I shouldn't have complained about it before trying to fix it where I was able to fix it.