[Python-Dev] random.jumpback?

[Tim Peters]

[Skip]
> I interpreted Guido's comment to mean, "why include a useless example in
> documentation?"  I guess that was my implicit assumption as well (again,
> ignoring the missed "just for fun" quote).  Either it's a useful example
> embedded in the documentation or it's a test case that is perhaps not
> likely to be useful to an end user in which case it should be accessed
> via the module's __test__ dictionary.

The example is not useful in practice, but is useful pedagogically, for
someone who reads the example *in context*:

+ It makes concrete that .jumpahead() is fast for even monstrously large
arguments (try it!  it didn't even make you curious?).

+ It makes concrete that the period of the RNG definitely can be exhausted
(something which earlier docstring text warned about in the context of
threads, but abstractly).

+ It concretely demonstrates that the true period is at worst a factor of
the documented period, something paranoid users want assurance about because
they know from bitter experience that documented periods are often wrong
(indeed, Wichmann and Hill made a bogus claim about the period of *this*
generator when they first introduced it).  A knowledgable user can build on
that example to prove to themself quickly that the period is exactly as
documented.

+ If anyone is under the illusion (and many are) that this kind of RNG is
good for crypto work, the demonstrated trivial ease with which .jumpahead
can move to any point in the sequence-- even trillions of elements
ahead --should give them strong cause for healthy doubt.

Cranking out cookies is useful, but teaching the interested reader something
about the nature of the cookie machine is also useful, albeit in a different
sense.

unrepentantly y'rs  - tim