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:

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 #

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.