Random string of digits?

[Roy Smith]

On Mon, 26 Dec 2011 03:11:56 +1100, Chris Angelico wrote:
> > I prefer not to rely on the source. That tells me what happens, not
> > what's guaranteed to happen. 

Steven D'Aprano <steve+comp.lang.python at pearwood.info> wrote:
> In this case, the source explicitly tells you that the API includes 
> support for arbitrary large ranges if you include a getrandbits() method:
> 
>      Optionally, implement a getrandbits() method so that randrange()
>      can cover arbitrarily large ranges.
> 
> I call that a pretty strong guarantee.

I think you mis-understood Chris's point.  The documentation is the 
specification of how something behaves.  If the documentation doesn't 
say it, you can't rely on it.  The user should never have to read the 
source to know how to use a function, or what they can depend on.  Now, 
I'm not saying that reading the source isn't useful for a deeper 
understanding, but it should be understood that any insights you glean 
from doing that are strictly implementation details.

If you're saying that there are guarantees made by the implementation of 
getrandbits() which are not documented, then one of two things are true:

1) It is intended that users can depend on that behavior, in which case 
it's a bug in the docs, and the docs should be updated.

or

2) It is not intended that users can depend on that behavior, in which 
case they would be foolish to do so.