We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

An Alternative Python Reference: Targets

Fredrik Lundh | January 2006

(This page belongs to the Alternative Python Reference project.)

The Target Space

The semantic markup centers around the concepts of targets, and links to such targets. A library target is any concept in the Python library that can be accessed by name, and the target description is simply the path to that object.

Some examples:

sys.platform
cgi.escape
zipfile.ZipFile.write # the write method of the ZipFile class
xml.dom.minidom.parse # the parse method in the minidom module

The target syntax combines the module path (the name you would use in an import statement) with the object path inside the module itself. To find the right module for a full target path, you can either start at the left end, and add parts until import fails, or start at the right end, and strip off parts as long as import fails.

Defining Targets

In PyREF markup, targets are defined via special section markers in the source code. The following markers are currently supported:

@@module modulename
The full name, including package prefix, of the module that this source file documents. The full target name is modulename.
@@function name
The name of a function in this module. The full target name is modulename.name.
@@variable name
The name of a variable in this module. The full target name is modulename.name.
@@class classname
The name of a class in this module. The full target name is modulename.classname.
@@method classname.name
The name of a method (or other callable attribute) in the given class. The full target name is modulename.classname.name.
@@attribute classname.name
The name of an attribute (or property) in the given class. The full target name is modulename.classname.name.

Additional target markers may be added in the future (e.g. @@interface, @@constant, @@property).

Linking to Targets

You can use inline @link tags to explicitly link to targets. Some link examples:

{@link sys.platform}
{@link cgi.escape}
{@link zipfile.ZipFile.write}

To read XML data from a file, use {@link xml.dom.minidom.parse}.

For convenience, and to simplify simple renderers, links to functions and methods should be written with trailing parentheses (e.g. cgi.escape()). More advanced renderers will ignore these, and use information about the actual target to determine how to render the link.

Links use the same name resolution rules as Python itself. This means that the target for a given name will be searched for first in the current class, then in the current module, then in the built-in namespace (see below), and finally in the full library space.

To skip the local search, you can prefix the search with “python:“. In the following example, all links in the read section points to the write section.

@@method MyClass.read(bytes=...)

  {@link write}
  {@link MyClass.write}
  {@link mymodule.MyClass.write}
  {@link python:mymodule.MyClass.write}

@@method MyClass.write(data)

  All links above point to this entry!

Parsers should expand links to their full form, and use render rules to decide how to render them. For example, the above links should usually be rendered as write when written inside a method in the same class, and MyClass.write when written inside the same module. (To get more control over the rendering, use the @linkplain tag instead of @link. See the PythonDoc documentation for details.)

The Built-in Namespace

The built-in namespace contains all names from the __builtin__ and exceptions modules, just like in ordinary Python. To refer to a built-in name from a module or class that contains objects with the same name, use the full name (e.g. __builtin__.len) or the prefix form or (e.g. python:len or python:__builtin__.len).

Notes

Since the renderer knows what a link points to, there’s no need to repeat this information over and over again in the markup. This makes the markup a lot easier to read in many cases, as can be seen in the following examples:

    # latex
    Call the \method{gettype()} method 
    Use the \code{\refmodule{sys}.platform} variable.
    \function{\refmodule{cgi}.escape} replaces entities.

    # pythondoc
    Call the {@link gettype} method.
    Use the {@link sys.platform} variable.
    {@link cgi.escape} replaces entities.

To avoid potential name clashes, JavaDoc uses #-separators between modules and object names:

    sys#platform
    cgi#escape
    zipfile#ZipFile.write
    xml.dom.minidom#parse

PythonDoc supports this syntax, but the current Python Reference toolchain doesn’t. I’m not sure we should require this syntax, but it would probably be a good idea to support it.