[Python-Dev] Checked in...

M.-A. Lemburg mal@lemburg.com
Mon, 17 Jul 2000 10:06:50 +0200


> Okay, I've removed it and attached it to this email but I still think
> that's a pretty cumbersome way to proceed. I've already made one
> modification. Future ones will need to be distributed as email patches.
> As a new module that won't be the basis of anything, and with
> significant interest, I don't see the danger in a checkin.

The standard procedure has always been to put the code and
the docs somewhere up on the web to support future developments.
You only have to publish the pointers every now and then.

It was worked great in the past. I don't see any reason
it shouldn't work now.

I agree with Guido that dist/ shouldn't be used for developing
new software, but also agree with Paul et al. that this is
a valueable addition to the standard lib.
 
> Anyhow, this version should not require the PYTHONDOCS environment
> variable unless you try to refer to a help topic that requires the
> online help. Still, in the future, I don't see the benefit in
> duplicating the documentation for all of the statements and operators.
> If you want that documentation, you'll probably need the HTML installed.

You may want to have a look at my hack.py utility which already
provides a convenient way of printing the doc strings *and*
the published interface:

	http://starship.python.net/Ělemburg/hack.py

It needs to be modified a bit to work with SRE since it
uses the old regs array (the tool was written for regex
which had this array, then ported to re, which also had the
array, but didn't document it; SRE doesn't have it anymore...
sigh).

Here's an example:

>>> hack.docs(os)
Module  :

    _exit :
        _exit(status)
        Exit to the system with specified status, without normal exit processing.

    chdir :
        chdir(path) -> None
        Change the current working directory to the specified path.

    chmod :
        chmod(path, mode) -> None
        Change the access permissions of a file.

    chown :
        chown(path, uid, gid) -> None
        Change the owner and group id of path to the numeric uid and gid.

    close :
        close(fd) -> None
        Close a file descriptor (for low level IO).

    dup :
        dup(fd) -> fd2
        Return a duplicate of a file descriptor.

    dup2 :
        dup2(fd, fd2) -> None
        Duplicate file descriptor.

    execv :
        execv(path, args)
        Execute an executable path with arguments, replacing current process.
        
                path: path of executable file
                args: tuple or list of strings

    execve :
        execve(path, args, env)
        Execute a path with arguments and environment, replacing current process.
        
                path: path of executable file
                args: tuple or list of arguments
                env: dictonary of strings mapping to strings

    fdopen :
        fdopen(fd, [, mode='r' [, bufsize]]) -> file_object
        Return an open file object connected to a file descriptor.

    fork :
        fork() -> pid
        Fork a child process.
        
        Return 0 to child process and PID of child to parent process.

    fstat :
        fstat(fd) -> (mode, ino, dev, nlink, uid, gid, size, atime, mtime, ctime)
        Like stat(), but for an open file descriptor.

    ftruncate :
        ftruncate(fd, length) -> None
        Truncate a file to a specified length.

    getcwd :
        getcwd() -> path
        Return a string representing the current working directory.

    getegid :
        getegid() -> egid
        Return the current process's effective group id.

    geteuid :
        geteuid() -> euid
        Return the current process's effective user id.

    getgid :
        getgid() -> gid
        Return the current process's group id.

    getpgrp :
        getpgrp() -> pgrp
        Return the current process group id.

    getpid :
        getpid() -> pid
        Return the current process id

    getppid :
        getppid() -> ppid
        Return the parent's process id.

    getuid :
        getuid() -> uid
        Return the current process's user id.

    kill :
        kill(pid, sig) -> None
        Kill a process with a signal.

    link :
        link(src, dst) -> None
        Create a hard link to a file.

    listdir :
        listdir(path) -> list_of_strings
        Return a list containing the names of the entries in the directory.
        
                path: path of directory to list
        
        The list is in arbitrary order.  It does not include the special
        entries '.' and '..' even if they are present in the directory.

    lseek :
        lseek(fd, pos, how) -> newpos
        Set the current position of a file descriptor.

    lstat :
        lstat(path) -> (mode,ino,dev,nlink,uid,gid,size,atime,mtime,ctime)
        Like stat(path), but do not follow symbolic links.

    mkdir :
        mkdir(path [, mode=0777]) -> None
        Create a directory.

    mkfifo :
        mkfifo(file, [, mode=0666]) -> None
        Create a FIFO (a POSIX named pipe).

    nice :
        nice(inc) -> new_priority
        Decrease the priority of process and return new priority.

    open :
        open(filename, flag [, mode=0777]) -> fd
        Open a file (for low level IO).

    Module path :
        Common pathname manipulations, Posix version.
        Instead of importing this module
        directly, import os and refer to this module as os.path.

    pipe :
        pipe() -> (read_end, write_end)
        Create a pipe.

    popen :
        popen(command [, mode='r' [, bufsize]]) -> pipe
        Open a pipe to/from a command returning a file object.

    putenv :
        putenv(key, value) -> None
        Change or add an environment variable.

    read :
        read(fd, buffersize) -> string
        Read a file descriptor.

    readlink :
        readlink(path) -> path
        Return a string representing the path to which the symbolic link points.

    remove :
        remove(path) -> None
        Remove a file (same as unlink(path)).

    rename :
        rename(old, new) -> None
        Rename a file or directory.

    rmdir :
        rmdir(path) -> None
        Remove a directory.

    setgid :
        setgid(gid) -> None
        Set the current process's group id.

    setpgid :
        setpgid(pid, pgrp) -> None
        Call the system call setpgid().

    setpgrp :
        setpgrp() -> None
        Make this process a session leader.

    setsid :
        setsid() -> None
        Call the system call setsid().

    setuid :
        setuid(uid) -> None
        Set the current process's user id.

    stat :
        stat(path) -> (mode,ino,dev,nlink,uid,gid,size,atime,mtime,ctime)
        Perform a stat system call on the given path.

    strerror :
        strerror(code) -> string
        Translate an error code to a message string.

    symlink :
        symlink(src, dst) -> None
        Create a symbolic link.

    system :
        system(command) -> exit_status
        Execute the command (a string) in a subshell.

    tcgetpgrp :
        tcgetpgrp(fd) -> pgid
        Return the process group associated with the terminal given by a fd.

    tcsetpgrp :
        tcsetpgrp(fd, pgid) -> None
        Set the process group associated with the terminal given by a fd.

    times :
        times() -> (utime, stime, cutime, cstime, elapsed_time)
        Return a tuple of floating point numbers indicating process times.

    umask :
        umask(new_mask) -> old_mask
        Set the current numeric umask and return the previous umask.

    uname :
        uname() -> (sysname, nodename, release, version, machine)
        Return a tuple identifying the current operating system.

    unlink :
        unlink(path) -> None
        Remove a file (same as remove(path)).

    utime :
        utime(path, (atime, utime)) -> None
        Set the access and modified time of the file to the given values.

    wait :
        wait() -> (pid, status)
        Wait for completion of a child process.

    waitpid :
        waitpid(pid, options) -> (pid, status)
        Wait for completion of a give child process.

    write :
        write(fd, string) -> byteswritten
        Write a string to a file descriptor.

-- 
Marc-Andre Lemburg
______________________________________________________________________
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/