[ZODB-Dev] oids, numbers, hex and 8-byte strings

[Tim Peters]

[Tim Peters]
>> You found ZODB.utils, which was a sensible place to look.  I don't
>> really understand how you found ZODB.utils but didn't manage to find
>> p64, because p64 is the first function in the file.

[Chris Withers]
> Because its name means nothing to me...

I'll buy that ;-)  But by the same token, when you sent your functions named
"oid_unrepr" and "oidr2obj", those names meant to nothing to me, and I had
no idea what _they_ were for either (until I read the code and
reverse-engineered what they did).

I would welcome docstring improvements for all functions in ZODB.  I'm not
sure if you're the guy to do that, since the functions you sent didn't have
any docstrings ;-)  If you can overcome that reluctance, please feel
encouraged to beef up the p64 docstring.  I think it would be good if it,
e.g., explicitly said a common use was to change the integer form of an oid
to its 8-byte string form -- and that u64 went the other direction.

...

> Yes, but for that to be meaningful, you have to know that:
>
> - 0xSomething is an integer or long (it read "hex number" in my head"

Come on, that's just Python.  0x12, 012, and 12 are all integers in Python.
Give examples in the docstring if that needs clarification.

> - oids are 8-byte strings

They may not be, but the oids that _are_ 8-byte strings fit well here ;-)

> Neither of things that sit in my brain :-(

Please add some docs then.

...

>> It would be possible to add an alias.  I'm -0 on that (would violate
>> TOOWTDI in exchange for ... well, not sure it would really help anyone
>> anyway).

> TOOWTDI?

There's Only One Way To Do It.  If that way is poorly documented, improve
the documentation.  Adding additional poorly documented ways to spell the
same thing is a losing direction, increasing confusion for everyone over the
long term.
 
> It might help some people (would have helped me ;-) ) and would it hurt
> anyone?

Had the time we've burned talking about it been devoted to improving the
docstring & comments for the existing function(s) instead, a major
improvement would already have been made.  If you had added your oid_unrepr
and oidr2obj functions instead, we would just have gained two more poorly
documented functions that only made sense to Chris Withers ;-)