[Python-Dev] RE: Iterators, map, xreadlines and docs

[Michel Pelletier]

On Sat, 28 Apr 2001, Tim Peters wrote:

> What do those have in common?  Objects and types are the wrong way to
> approach this one:  it's really of no interest that, e.g., iter(list) and
> iter(dict) return objects of different types; what *is* interesting is that
> iter(whatever) returns *an* object that conforms to the iterator protocol (or
> "implements the iterator interface" -- all the same to me).  

I have added a notional iter interface to the PEP 245 prototype and will
be making another release of it later tonight.

> "file-like objects" is the bad doc experience I'm hoping we don't repeat.
> The phrase "file-like object" is indeed used freely in the docs, but it's not
> (AFAICT) *defined* anywhere, and doesn't even appear in the index.  Besides,
> the notion that "file-like object" refers to section
> 
>     Buitin-in Types, Exceptions and Functions ->
>      Other Built-in Types ->
>       File Objects
> 
> was news to me.  I see the individual method descriptions there sometimes
> refer to "file-like objects", and other times "objects implementing a
> file-like interface".  The latter phrase appears uniquely in the description
> of .readlines(), and may be the clearest explanation in the docs of wtf
> "file-like object" means.  If so, it shouldn't be buried in the bowels of one
> method description.

245 takes a couple stabs at File interfaces, trying to satisfy the
bare-bones kind of file, a Python File, StringI, StringO etc...

> >   I think we need some re-organization of the built-in types section
> > to separate abstract protocols from specific implementations,
> 
> Yes.

FYI, 245 defines the following interfaces.  Some of them may be wrong,
I took most of this straight from the Pydocs and stuff done by Jim:

  Mutable
  
  Comparable

  Orderable(Comparable)

  Hashable
  
  Hashkey(Comparable, Hashable)

  Membership

  Mapping

  Sized

  MutableMapping(Mutable)    

  Sequence(Mapping)

  Sequential(Sequential)

  Type

  Null

  String(Sequence, Sized)

  Tuple(Sequence, Sized)

  List(Mapping, MutableMapping, Sequence, Sized)

  Dictionary(Mapping, MutableMapping, Sized)

  File - and the various specific file functionality

  Module

  Class

  Function

  InstanceMethod

  Exception

  Number - Real, Compex, Exact, others....

Here are some examples from the current prototype.  The primary
utility function from PEP 245 is 'does':

    Python 2.1 (#1, Apr 22 2001, 06:33:07) 
    [GCC egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)] on linux2
    Type "copyright", "credits" or "license" for more information.
    >>> from Interface import does

'does' can be used two ways.  The first way is to pass imp an object
and it will return the interfaces that the object implements:

    >>> does({})
    [<Interface Dictionary at 82e288c>]
    >>> does([])
    [<Interface List at 82c71f4>]
    >>> does(sys.stdin)
    [<Interface PyFile at 8261e54>]
    >>> def f(): pass
    ...
    >>> does(f)
    [<Interface Function at 82ff134>]

Here, we see that a dictionary and a list do the 'Dictionary' and
'List' interfaces respectively, and that files and functions also
implement interfaces.  'does' can also be used with another argument,
to ask whether the object implements a certain interface:

    >>> from Interface.Protocols import Mapping, Sequence, Mutable
    >>> from Interface.File import File
    >>> does({}, Mapping)
    1
    >>> does([], Sequence)
    1
    >>> does((), Mutable)
    0
    >>> does({}, Dictionary)
    1
    >>> does(sys.stdin, File)
    1

Note that PEP 245 requires NO changes to Python.  You can download it
now and try this stuff out.

-Michel