[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 ;-) _______________________________________________ For more information about ZODB, see the ZODB Wiki: http://www.zope.org/Wikis/ZODB/ ZODB-Dev mailing list - ZODB-Dev@zope.org http://mail.zope.org/mailman/listinfo/zodb-dev