documentation problems (was Re: Newbie - EOF question)

[Alex Martelli]

<maalokam at my-deja.com> wrote in message news:8s2u9p$767$1 at nnrp1.deja.com...
> Hi,
>
> I just started programming in python and the following piece of code
> gives me an EOFError. Was wondering if someone could help ?
    [snip]
> --- CODE ---
> f = open("tmpfile")
> x = cPickle.load(f)
> while x:
>    print x
>    x = cPickle.load(f)
>
> --- ERROR LOG ---
> Traceback (innermost last):
>   File "./test.py", line 16, in ?
>     Main()
>   File "./test.py", line 14, in Main
>     x = cPickle.load(f1)
> EOFError

I do not think it's clearly specified what happens when load() is
called on an Unpickler more times than dump() was originally called;
all I can see in the docs is:
"""
It is possible to make multiple calls to the dump() method of
the same Pickler instance. These must then be matched to the same
number of calls to the load() method of the corresponding Unpickler
instance
"""

It could be argued that "must" is a strong constraint, so it's
implicit that an exception will be raised if the constraint is
violated; but I think it would be better to make it explicit, by
adding a simple sentence such as ", else an EOFError will result"
at the end of the above-quoted snippet.

It gets subtler because here it's not clear that we _are_ talking
to "the SAME Pickler instance"; indeed, the docs for pickle.load
make it appear that a new pickler instance is built for each
call, so, what IS the semantic for multiple load calls then...?
Here, I believe the key issue is that the instances are built
on top of the _same_ file object -- but this should be explicit
in the documentation, too, it seems to me.

Any chance to get these documentation issues fixed...?


Once the actual behavior of the .load is well understood, the
fix to the code is clearly simple:

f = open("tmpfile")
while 1:
    try:
        x = cPickle.load(f)
    except EOFError: break
    print x


The best/clearer wrapping of this behavior might be done
through an auxiliary object ("so, what else is new"!-):

class DePickler:
    def __init__(self, fileobj):
        self.fileobj = fileobj
    def __getitem__(self, i):
        try: return cPickle.load(fileobj)
        except EOFError: return IndexError

With this class-definition available, you can do:

for x in DePickler(open("tmpfile")):
    print x


Alex