[Edu-sig] Top 5 All Time Novice Obstacles => #2 Helping help

[Jason Cunliffe]

Title: ['Nine hours to Rama', '12 steps to help()']

---Scenario: Novice Pythonista {NP} is exploring---

1. >>> import os

2. >>> os
    <module 'os' from 'C:\PYTHON22\lib\os.pyc'>

3. >>> dir(os)
['F_OK', 'O_APPEND', 'O_BINARY', 'O_CREAT', 'O_EXCL', 'O_RDONLY', 'O_RDWR',
'O_TEXT', 'O_TRUNC', 'O_WRONLY', 'P_DETACH', 'P_NOWAIT', 'P_NOWAITO',
'P_OVERLAY', 'P_WAIT', 'R_OK', 'TMP_MAX', 'UserDict', 'W_OK', 'X_OK',
'_Environ', '__all__', '__builtins__', '__doc__', '__file__', '__name__',
'_copy_reg', '_execvpe', '_exists', '_exit', '_get_exports_list',
'_make_stat_result', '_make_statvfs_result', '_notfound', '_pickle_stat_result',
'_pickle_statvfs_result', 'abort', 'access', 'altsep', 'chdir', 'chmod',
'close', 'curdir', 'defpath', 'dup', 'dup2', 'environ', 'error', 'execl',
'execle', 'execlp', 'execlpe', 'execv', 'execve', 'execvp', 'execvpe', 'extsep',
'fdopen', 'fstat', 'getcwd', 'getenv', 'getpid', 'i', 'isatty', 'linesep',
'listdir', 'lseek', 'lstat', 'makedirs', 'mkdir', 'name', 'open', 'pardir',
'path', 'pathsep', 'pipe', 'popen', 'popen2', 'popen3', 'popen4', 'putenv',
'read', 'remove', 'removedirs', 'rename', 'renames', 'rmdir', 'sep', 'spawnl',
'spawnle', 'spawnv', 'spawnve', 'startfile', 'stat', 'stat_result',
'statvfs_result', 'strerror', 'sys', 'system', 'tempnam', 'times', 'tmpfile',
'tmpnam', 'umask', 'unlink', 'unsetenv', 'utime', 'write']

---{NP thinks:} "hmmm.. I wonder what that 'lstat' is?"

4. >>> os.lstat
    <built-in function lstat>

5. >>> os.lstat()
    Traceback (most recent call last):
      File "<pyshell#10>", line 1, in ?
        os.lstat()
    TypeError: lstat() takes exactly 1 argument (0 given)

---{NP:} "[sigh].. I need some help"

6. >>> ? os.lstat()
    SyntaxError: invalid syntax

---{NP:} "oops1 wrong language ;-) [Rebol]

7. >>> help
    Type help() for interactive help, or help(object) for help about object.

---{NP:} "thanks!"

8. >>> help(os.lstat())
    Traceback (most recent call last):
      File "<pyshell#24>", line 1, in ?
        help(os.lstat())
    TypeError: lstat() takes exactly 1 argument (0 given)

---{NP:} "What the f*** ?"

9. >>> help(os.lstat)
    Help on built-in function lstat:

    lstat(...)
        lstat(path) -> (st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid,
                         st_size, st_atime, st_mtime, st_ctime)
        Like stat(path), but do not follow symbolic links.

---{NP:} "Aha.. :-)"
[just then NP remembers about that wierd looking __doc__ thingie]

10. >>> os.lstat()__doc__
    SyntaxError: invalid syntax

---{NP:} "..sheesh!doh well maybe I should try it this way => "

11. >>> os.lstat.__doc__
'lstat(path) -> (st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid,\n
st_size, st_atime, st_mtime, st_ctime)\nLike stat(path), but do not follow
symbolic links.'

---{NP:} "hmm almost but it looks messy. I liked help() better"

12. >>> print os.lstat.__doc__
lstat(path) -> (st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid,
                 st_size, st_atime, st_mtime, st_ctime)
Like stat(path), but do not follow symbolic links.

---{NP:} [smiles]

NP SUGGESTION

When Novice Pythonistas get to steps 5. and 8. above, surely Python can help by
jumping in with help(os.lstat)?

./Jason