inspect.py, and pydoc.py. Specifically, this allows for querying the type of
an object against these built-in C types and more importantly, for getting
their docstrings printed in the interactive interpreter's help() function.
This patch includes a new built-in module called _types which provides
definitions of getset and member descriptors for use by the types.py module.
These types are exposed as types.GetSetDescriptorType and
types.MemberDescriptorType. Query functions are provided as
inspect.isgetsetdescriptor() and inspect.ismemberdescriptor(). The
implementations of these are robust enough to work with Python implementations
other than CPython, which may not have these fundamental types.
The patch also includes documentation and test suite updates.
I commit these changes now under these guiding principles:
1. Silence is assent. The release manager has not said "no", and of the few
people that cared enough to respond to the thread, the worst vote was "0".
2. It's easier to ask for forgiveness than permission.
3. It's so dang easy to revert stuff in svn, that you could view this as a
forcing function. :)
Windows build patches will follow.
to share common PEP 302 support code, as described here:
http://mail.python.org/pipermail/python-dev/2006-April/063724.html
pydoc now supports PEP 302 importers, by way of utility functions in
pkgutil, such as 'walk_packages()'. It will properly document
modules that are in zip files, and is backward compatible to Python
2.3 (setuptools installs for Python <2.5 will bundle it so pydoc
doesn't break when used with eggs.)
What has not changed is that pydoc command line options do not support
zip paths or other importer paths, and the webserver index does not
support sys.meta_path. Those are probably okay as limitations.
Tasks remaining: write docs and Misc/NEWS for pkgutil/pydoc changes,
and update setuptools to use pkgutil wherever possible, then add it
to the stdlib.
This change implements a new bytecode compiler, based on a
transformation of the parse tree to an abstract syntax defined in
Parser/Python.asdl.
The compiler implementation is not complete, but it is in stable
enough shape to run the entire test suite excepting two disabled
tests.
Thanks to Robert Dick <dickrp@ece.northwestern.edu> for reporting this bug
and submitting a patch.
Adjust doc(object) to display useful documentation for plain values (e.g.
help([]) now shows the methods on the list instead of just printing "[]").
(This change has been tested interactively, by generating docs for the
standard library, and by running the module documentation webserver.)
properties, and custom descriptors.
* removed special handling of properties
* added special handling of data descriptors - All data descriptors are grouped
together in a section. For each item, the attribute name and doc string, if
present, is displayed.
* disabled display of __slots__ attribute - since slots are descriptors, they
are listed in the section described above
Thanks to John Belmonte for the patch!
Clean up section headings; make the bars on the left less fat.
Adjust the display of properties slightly.
Don't show stuff inherited from the base 'object' type.
Reverting one of those irritating "security fixes". fdopen() opens
files in binary mode. That makes pydoc skip the \r\n on Windows that's
need to make the output readable in the shell. Screw it.
The GUI-mode code to display properties blew up if the property functions
(get, set, etc) weren't simply methods (or functions).
"The problem" here is really that the generic document() method dispatches
to one of .doc{routine, class, module, other}(), but all of those require
a different(!) number of arguments. Thus document isn't general-purpose
at all: you have to know exactly what kind of thing is it you're going
to document first, in order to pass the correct number of arguments to
.document for it to pass on. As an expedient hack, just tacked "*ignored"
on to the end of the formal argument lists for the .docXXX routines so
that .document's caller doesn't have to know in advance which path
.document is going to take.
getting displayed, due to a special case here whose purpose I didn't
understand. So just disabled the doc suppression here.
Another special case here skips the docs when picking apart a method
and finding that the im_func is also in the class __dict__ under
the same name. That one I understood. It has a curious consequence,
though, wrt inherited properties: a static class copies inherited stuff
into the inheriting class's dict, and that affects whether or not this
special case triggers. The upshoot is that pydoc doesn't show the
function docstrings of getter/setter/deleter functions of inherited
properties in the property section when the class is static, but does
when the class is dynamic (bring up Lib/test/pydocfodder.py under
GUI pydoc to see this).
property() (get, set, del; not set, get, del).
+ Change "Data defined/inherited in ..." header lines to
"Data and non-method functions defined/inherited in ...". Things like
the value of __class__, and __new__, and class vrbls like the i in
class C:
i = int
show up in this section too. I don't think it's worth a separate
section to distinguish them from non-callable attrs, and there's no
obvious reliable way to distinguish callable from non-callable attrs
anyway.
always been close to useless, because the <small>-ified docstrings
were too small to read, even after cranking up my default font size
just for pydoc. Now it reads fine under my defaults (as does most
of the web <0.5 wink>). If it's thought important to play tricks
with font size, tough, then someone should rework pydoc to use style
sheets, and (more) predictable percentage-of-default size controls.
+ Tried to ensure that all <dt> and <dd> tags are closed. I've read (but
don't know) that some browsers get confused if they're not, and esp.
when style sheets are in use too.
properties: the docstring (if any) is displayed, and the getter, setter
and deleter (if any) functions are named. All that is shown indented
after the property name.
+ Text-mode pydoc class display now draws a horizontal line between
class attribute groups (similar to GUI mode -- while visually more
intrusive in text mode, it's still an improvement).
+ Minor code cleanup, generalization and simplification.
+ "Do something" to make the attribute aggregation more apparent:
- In text mode, stick a "* " at the front of subgroup header lines.
- In GUI mode, display a horizontal rule between subgroups.
For GUI mode, this is a huge improvement, at least under IE.
mode (identify the source class for class attrs; segregate attrs according
to source class, and whether class method, static method, property, plain
method, or data; display data attrs; display docstrings for data attrs
when possible).
Alas, this is mondo ugly, and I'm no HTML guy. Part of the problem is
that pydoc's GUI mode has always been ugly under IE, largely because
<small> under IE renders docstrings unreadably small (while sometimes
non-docstring text is painfully large). Another part is that these
segregated listings of attrs would *probably* look much better as bulleted
lists. Alas, when I tried that, the bullets all ended up on lines by
themselves, before the method names; this is apparently because pydoc
(ab?)uses definition lists for format effects, and at least under IE
if a definition list is the first chunk of a list item, it gets rendered
on a line after the <li> bullet.
An HTML wizard would certainly be welcomed here.
This almost entirely replaces how pydoc pumps out class docs, but only
in text mode (like help(whatever) from a Python shell), not in GUI mode.
A class C's attrs are now grouped by the class in which they're defined,
attrs defined by C first, then inherited attrs grouped by alphabetic order
of the defining classes' names.
Within each of those groups, the attrs are subgrouped according to whether
they're plain methods, class methods, static methods, properties, or data.
Note that pydoc never dumped class data attrs before. If a class data
attr is implemented via a data descriptor, the data docstring (if any)
is also displayed (e.g., file.softspace).
Within a subgroup, the attrs are listed alphabetically.
This is a friggin' mess, and there are bound to be glitches. Please
beat on it and complain! Here are three glitches:
1. __new__ gets classifed as 'data', for some reason. This will
have to get fixed in inspect.py, but since the latter is already
looking for any clue that something is a method, pydoc will
almost certainly not know what to do with it when its classification
changes.
2. properties are special-cased to death. Unlike any other kind of
function or method, they don't have a __name__ attr, so none of
pydoc's usual code can deal with them. Worse, the getter and
setter and del'er methods associated with a property don't appear
to be discoverable from Python, so there's really nothing I can
think of to do here beyond just listing their names.
Note that a property can't be given a docstring, either (or at least
I've been unable to sneak one in) -- perhaps the property()
constructor could take an optional doc argument?
3. In a nested-scopes world, pydoc still doesn't know anything about
nesting, so e.g. classes nested in functions are effectively invisible.
inspect.getargspec(obj), test isfunction() directly in pydoc.py instead
of trying to indirectly deduce isfunction() in pydoc by virtue of
failing a combination of other tests. This shouldn't have any visible
effect, except perhaps to squash a TypeError death if there was some path
thru this code that was inferring isfunction() by mistake.
Make synopsis() load modules as '__temp__' so they don't clobber anything.
Change "constants" section to "data" section.
Don't show __builtins__ or __doc__ in "data" section.
For Bob Weiner: don't boldface text in Emacs shells or dumb terminals.
Remove Helper.__repr__ (it really belongs in site.py, and should be guarded by a check for len(inspect.stack) <= 2).
Fix so that docother() doesn't blow up.
Eliminate man() function since doc() and man() did nearly the same thing.
Various other code cleanup and refactoring to reduce duplication.
Simplify and rewrite freshimport() so modules are always up to date,
even within packages (where reload() doesn't work).
Add finalization callback to the server (so that if the server fails to
start for some reason, the main thread isn't left hanging).
Avoid ever using popen on Windows, since it's broken there.
Factor out the business of getting the summary line into splitdoc().
Use the modulename() routine in inspect.
Show all members of modules and classes rather than filtering on leading '_'.
Small typo and formtating fixes.
Don't show warnings when running "pydoc -k".
Georg Brandl
Ka-Ping Yee
Andrew M. Kuchling
Barry Warsaw
Phillip J. Eby
Fred Drake
Jeremy Hylton
Raymond Hettinger
Johannes Gijsbers
Martin v. Löwis
Brett Cannon
Skip Montanaro
Neal Norwitz
Guido van Rossum
Tim Peters
Jack Jansen
Neil Schemenauer
Andrew MacIntyre