NOT ALL OF THIS IS IMPLEMENTED YET. (This file was originally called
plan.txt but I renamed it for GitHub's benefit.)


readdir(directory, glob="*", extra_filters=[],
        [transaction=None, limit_information=None])

    Lists all files in directory that match glob and all filters in
    extra_filters. The glob pattern uses the syntax of the fnmatch
    module, which supports *, ?, and [...] and [!...] character
    classes. (On POSIX, this will be emulated by just filtering the
    resulting list of files. On Windows, the * and ? wildcards can be
    dealt with by the system, but character classes will have to be
    replaced by ? and then filtered later.)

    extra_filters is a sequence of predicates which will be called
    with each file; if a predicate returns false, that file will not
    be returned. The library will have a pre-defined filter which will
    check whether a file is a directory; on Windows, readdir will
    detect that filter and pass that request down to the file system.

    transaction is only available on Windows and will result in a call
    to the transacted version with the given handle.

    limit_information is also only avaliable on Windows and can be any
    one of a predefined list of values which will get passed down to
    Windows. The fields which have no meaning will be dropped from the
    iterator's items.


readdir returns a sequence, each item of which will be an object with
the following attributes:

    name: the file name

    kind, available on most systems: one of a set of predefined
    values: regular file, directory, device (on POSIX, an attribute of
    the kind field itself will indicate block or character), and
    symbol link (on Windows, an attribute of the kind field itself
    will indicate the type of symlink) will be available across all
    kind-capable systems. On POSIX, other options are FIFO, socket,
    and unknown. On Windows, reparse point. (Reparse points with the
    SYMLINK tag will count as a symlink. Other tags will be available
    as an attribute of kind itself.)

    inode, available on POSIX.

    d_off, available on some POSIX.

    attributes, available on Windows. An object with a bunch of
    boolean fields for: hidden, system, archive, read-only,
    compressed, encrypted, indexed, offline, sparse, temporary,
    virtual.

    creation_time, access_time, modification_time, available on
    Windows. Each is adatetime. (Exceptions: if the file system
    doesn't support this, then Windows sets the field to 0; I will
    omit it this attribute from the resulting object in that case.)

    size, available on Windows. The size of the file.

    short_name, available on Windows. An 8.3 filename. (Exception:
    this attribute will be omitted if it is not set in the result from
    Windows.)