diff options
Diffstat (limited to 'sandbox/tibs/pysource/notes')
| -rwxr-xr-x | sandbox/tibs/pysource/notes/notes.py | 115 | ||||
| -rw-r--r-- | sandbox/tibs/pysource/notes/notes.txt | 7 | ||||
| -rw-r--r-- | sandbox/tibs/pysource/notes/roles.txt | 61 | ||||
| -rw-r--r-- | sandbox/tibs/pysource/notes/scope.txt | 19 | ||||
| -rwxr-xr-x | sandbox/tibs/pysource/notes/string.html | 225 | ||||
| -rw-r--r-- | sandbox/tibs/pysource/notes/thoughts.txt | 170 |
6 files changed, 0 insertions, 597 deletions
diff --git a/sandbox/tibs/pysource/notes/notes.py b/sandbox/tibs/pysource/notes/notes.py deleted file mode 100755 index a7fd81f51..000000000 --- a/sandbox/tibs/pysource/notes/notes.py +++ /dev/null @@ -1,115 +0,0 @@ -"""Notes (i.e., me working things out...) - -Given the following Python:: - - def func(a,b=1,c='jim',d=None,e=[],f={'a':1},g=(1,2,3)): - -the tree produced by compiler looks like:: - - <Function> 'func' 'a' 'b' 'c' 'd' 'e' 'f' 'g' - <Const> 1 - <Const> 'jim' - <Name> 'None' - <List> - <Dict> - <Const> 'a' - <Const> 1 - <Tuple> - <Const> 1 - <Const> 2 - <Const> 3 0 - -If one has:: - - def func2(a,*args,**kargs): - -one gets:: - - <Function> 'func2' 'a' 'args' 'kargs' 3 None - -and lastly:: - - def func3((a,b,c),d): - -gives:: - - <Function> 'func3' 'a' 'b' 'c' 'd' 0 None - - -`compiler.misc` defines `flatten(tup)` - maybe I should try it? - -""" - - -# compiler.transformer contains this useful set of comments: -# -# -# The output tree has the following nodes: -# -# Source Python line #'s appear at the end of each of all of these nodes -# If a line # doesn't apply, there will be a None instead. -# -# module: doc, node -# stmt: [ node1, ..., nodeN ] -# function: name, argnames, defaults, flags, doc, codeNode -# lambda: argnames, defaults, flags, codeNode -# classdef: name, bases, doc, codeNode -# pass: -# break: -# continue: -# for: assignNode, listNode, bodyNode, elseNode -# while: testNode, bodyNode, elseNode -# if: [ (testNode, suiteNode), ... ], elseNode -# exec: expr1Node, expr2Node, expr3Node -# from: modname, [ name1, ..., nameN ] -# import: [ name1, ..., nameN ] -# raise: expr1Node, expr2Node, expr3Node -# tryfinally: trySuiteNode, finSuiteNode -# tryexcept: trySuiteNode, [ (exprNode, assgnNode, suiteNode), ... ], elseNode -# return: valueNode -# const: value -# print: [ node1, ..., nodeN ] [, dest] -# printnl: [ node1, ..., nodeN ] [, dest] -# discard: exprNode -# augassign: node, op, expr -# assign: [ node1, ..., nodeN ], exprNode -# ass_tuple: [ node1, ..., nodeN ] -# ass_list: [ node1, ..., nodeN ] -# ass_name: name, flags -# ass_attr: exprNode, attrname, flags -# list: [ node1, ..., nodeN ] -# dict: [ (key1, val1), ..., (keyN, valN) ] -# not: exprNode -# compare: exprNode, [ (op, node), ..., (op, node) ] -# name: name -# global: [ name1, ..., nameN ] -# backquote: node -# getattr: exprNode, attrname -# call_func: node, [ arg1, ..., argN ] -# keyword: name, exprNode -# subscript: exprNode, flags, [ sub1, ..., subN ] -# ellipsis: -# sliceobj: [ node1, ..., nodeN ] -# slice: exprNode, flags, lowerNode, upperNode -# assert: expr1, expr2 -# -# Compiled as "binary" ops: -# tuple: [ node1, ..., nodeN ] -# or: [ node1, ..., nodeN ] -# and: [ node1, ..., nodeN ] -# bitor: [ node1, ..., nodeN ] -# bitxor: [ node1, ..., nodeN ] -# bitand: [ node1, ..., nodeN ] -# -# Operations easily evaluateable on constants: -# <<: exprNode, shiftNode -# >>: exprNode, shiftNode -# +: leftNode, rightNode -# -: leftNode, rightNode -# *: leftNode, rightNode -# /: leftNode, rightNode -# %: leftNode, rightNode -# power: leftNode, rightNode -# unary+: node -# unary-: node -# invert: node diff --git a/sandbox/tibs/pysource/notes/notes.txt b/sandbox/tibs/pysource/notes/notes.txt deleted file mode 100644 index 548d792a1..000000000 --- a/sandbox/tibs/pysource/notes/notes.txt +++ /dev/null @@ -1,7 +0,0 @@ -Paul Moore's summary of backquoted markup possibilities:: - - `xxxxx`_ - named hyperlink reference (type 2) - `xxxxx`__ - anonymous hyperlink reference (type 2) - _`xxxx` - inline hyperlink targets - `/xxx/` - substitution reference - `xxxxx` - interpreted text diff --git a/sandbox/tibs/pysource/notes/roles.txt b/sandbox/tibs/pysource/notes/roles.txt deleted file mode 100644 index b063e026d..000000000 --- a/sandbox/tibs/pysource/notes/roles.txt +++ /dev/null @@ -1,61 +0,0 @@ -The following is taken from the DPS document pysource-reader.txt:: - - Interpreted Text - ================ - - DTD elements: package, module, class, method, function, - module_attribute, class_attribute, instance_attribute, variable, - parameter, type, exception_class, warning_class. - - In Python docstrings, interpreted text is used to classify and mark up - program identifiers, such as the names of variables, functions, - classes, and modules. If the identifier alone is given, its role is - inferred implicitly according to the Python namespace lookup rules. - For functions and methods (even when dynamically assigned), - parentheses ('()') may be included:: - - This function uses `another()` to do its work. - - For class, instance and module attributes, dotted identifiers are used - when necessary:: - - class Keeper(Storer): - - """ - Extend `Storer`. Class attribute `instances` keeps track of - the number of `Keeper` objects instantiated. - """ - - instances = 0 - """How many `Keeper` objects are there?""" - - def __init__(self): - """ - Extend `Storer.__init__()` to keep track of instances. - - Keep count in `self.instances` and data in `self.data`. - """ - Storer.__init__(self) - self.instances += 1 - - self.data = [] - """Store data in a list, most recent last.""" - - def storedata(self, data): - """ - Extend `Storer.storedata()`; append new `data` to a list - (in `self.data`). - """ - self.data = data - - To classify identifiers explicitly, the role is given along with the - identifier in either prefix or suffix form:: - - Use :method:`Keeper.storedata` to store the object's data in - `Keeper.data`:instance_attribute:. - - The role may be one of 'package', 'module', 'class', 'method', - 'function', 'module_attribute', 'class_attribute', - 'instance_attribute', 'variable', 'parameter', 'type', - 'exception_class', 'exception', 'warning_class', or 'warning'. Other - roles may be defined. diff --git a/sandbox/tibs/pysource/notes/scope.txt b/sandbox/tibs/pysource/notes/scope.txt deleted file mode 100644 index 1ad889c1b..000000000 --- a/sandbox/tibs/pysource/notes/scope.txt +++ /dev/null @@ -1,19 +0,0 @@ -On finding names -================ - -We are not trying for a general solution to the problem of "find the item -that is being referred to" - we are just trying to provide useful links -between <interpreted> items in docstrings and those things that they -might reasonably be expected to be referring to. - -Some rules thus occur. - -1. We will not show attributes, docstring or not, if they are not - - a. At module level (so a ModuleValue) - b. Within a class (so a ClassValue) - c. Within a method called __init__ or __new__. - - So discard any attributes that do not match these criteria. - -Hmm - is that the only rule? Can it be so simple? diff --git a/sandbox/tibs/pysource/notes/string.html b/sandbox/tibs/pysource/notes/string.html deleted file mode 100755 index e09c30e2b..000000000 --- a/sandbox/tibs/pysource/notes/string.html +++ /dev/null @@ -1,225 +0,0 @@ - -<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN"> -<html><head><title>Python: module string</title> -<style type="text/css"><!-- -TT { font-family: lucidatypewriter, lucida console, courier } ---></style></head><body bgcolor="#f0f0f8"> - -<table width="100%" cellspacing=0 cellpadding=2 border=0> -<tr bgcolor="#7799ee"> -<td valign=bottom><small> <br></small -><font color="#ffffff" face="helvetica, arial"> <br><big><big><strong>string</strong></big></big></font></td -><td align=right valign=bottom -><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:///C|/python21/lib/string.py">c:\python21\lib\string.py</a></font></td></tr></table> - <p><small><tt>A collection of string operations (most are no longer used in Python 1.6).<br> - <br> -Warning: most of the code you see here isn't normally used nowadays. With<br> -Python 1.6, many of these functions are implemented as methods on the<br> -standard string object. They used to be implemented by a built-in module<br> -called strop, but strop is now obsolete itself.<br> - <br> -Public module variables:<br> - <br> -whitespace -- a string containing all characters considered whitespace<br> -lowercase -- a string containing all characters considered lowercase letters<br> -uppercase -- a string containing all characters considered uppercase letters<br> -letters -- a string containing all characters considered letters<br> -digits -- a string containing all characters considered decimal digits<br> -hexdigits -- a string containing all characters considered hexadecimal digits<br> -octdigits -- a string containing all characters considered octal digits<br> -punctuation -- a string containing all characters considered punctuation<br> -printable -- a string containing all characters considered printable</tt></small></p> - -<p><table width="100%" cellspacing=0 cellpadding=2 border=0> -<tr bgcolor="#eeaa77"> -<td colspan=3 valign=bottom><small><small> <br></small></small -><font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr> - -<tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td> -<td width="100%"><dl><dt><a name="-_float"><strong>_float</strong></a> = float(...)<dd><small><tt>float(x) -> floating point number<br> - <br> -Convert a string or number to a floating point number, if possible.</tt></small></dl> - <dl><dt><a name="-_int"><strong>_int</strong></a> = int(...)<dd><small><tt>int(x[, base]) -> integer<br> - <br> -Convert a string or number to an integer, if possible. A floating point<br> -argument will be truncated towards zero (this does not include a string<br> -representation of a floating point number!) When converting a string, use<br> -the optional base. It is an error to supply a base when converting a<br> -non-string.</tt></small></dl> - <dl><dt><a name="-_long"><strong>_long</strong></a> = long(...)<dd><small><tt>long(x) -> long integer<br> -long(x, base) -> long integer<br> - <br> -Convert a string or number to a long integer, if possible. A floating<br> -point argument will be truncated towards zero (this does not include a<br> -string representation of a floating point number!) When converting a<br> -string, use the given base. It is an error to supply a base when<br> -converting a non-string.</tt></small></dl> - <dl><dt><a name="-atof"><strong>atof</strong></a>(s)<dd><small><tt><a href="#-atof">atof</a>(s) -> float<br> - <br> -Return the floating point number represented by the string s.</tt></small></dl> - <dl><dt><a name="-atoi"><strong>atoi</strong></a>(s, base<small><font color="#909090">=10</font></small>)<dd><small><tt><a href="#-atoi">atoi</a>(s [,base]) -> int<br> - <br> -Return the integer represented by the string s in the given<br> -base, which defaults to 10. The string s must consist of one<br> -or more digits, possibly preceded by a sign. If base is 0, it<br> -is chosen from the leading characters of s, 0 for octal, 0x or<br> -0X for hexadecimal. If base is 16, a preceding 0x or 0X is<br> -accepted.</tt></small></dl> - <dl><dt><a name="-atol"><strong>atol</strong></a>(s, base<small><font color="#909090">=10</font></small>)<dd><small><tt><a href="#-atol">atol</a>(s [,base]) -> long<br> - <br> -Return the long integer represented by the string s in the<br> -given base, which defaults to 10. The string s must consist<br> -of one or more digits, possibly preceded by a sign. If base<br> -is 0, it is chosen from the leading characters of s, 0 for<br> -octal, 0x or 0X for hexadecimal. If base is 16, a preceding<br> -0x or 0X is accepted. A trailing L or l is not accepted,<br> -unless base is 0.</tt></small></dl> - <dl><dt><a name="-capitalize"><strong>capitalize</strong></a>(s)<dd><small><tt><a href="#-capitalize">capitalize</a>(s) -> string<br> - <br> -Return a copy of the string s with only its first character<br> -capitalized.</tt></small></dl> - <dl><dt><a name="-capwords"><strong>capwords</strong></a>(s, sep<small><font color="#909090">=None</font></small>)<dd><small><tt><a href="#-capwords">capwords</a>(s, [sep]) -> string<br> - <br> -Split the argument into words using split, capitalize each<br> -word using capitalize, and join the capitalized words using<br> -join. Note that this replaces runs of whitespace characters by<br> -a single space.</tt></small></dl> - <dl><dt><a name="-center"><strong>center</strong></a>(s, width)<dd><small><tt><a href="#-center">center</a>(s, width) -> string<br> - <br> -Return a center version of s, in a field of the specified<br> -width. padded with spaces as needed. The string is never<br> -truncated.</tt></small></dl> - <dl><dt><a name="-count"><strong>count</strong></a>(s, *args)<dd><small><tt><a href="#-count">count</a>(s, sub[, start[,end]]) -> int<br> - <br> -Return the number of occurrences of substring sub in string<br> -s[start:end]. Optional arguments start and end are<br> -interpreted as in slice notation.</tt></small></dl> - <dl><dt><a name="-expandtabs"><strong>expandtabs</strong></a>(s, tabsize<small><font color="#909090">=8</font></small>)<dd><small><tt><a href="#-expandtabs">expandtabs</a>(s [,tabsize]) -> string<br> - <br> -Return a copy of the string s with all tab characters replaced<br> -by the appropriate number of spaces, depending on the current<br> -column, and the tabsize (default 8).</tt></small></dl> - <dl><dt><a name="-find"><strong>find</strong></a>(s, *args)<dd><small><tt><a href="#-find">find</a>(s, sub [,start [,end]]) -> in<br> - <br> -Return the lowest index in s where substring sub is found,<br> -such that sub is contained within s[start,end]. Optional<br> -arguments start and end are interpreted as in slice notation.<br> - <br> -Return -1 on failure.</tt></small></dl> - <dl><dt><a name="-index"><strong>index</strong></a>(s, *args)<dd><small><tt><a href="#-index">index</a>(s, sub [,start [,end]]) -> int<br> - <br> -Like find but raises ValueError when the substring is not found.</tt></small></dl> - <dl><dt><a name="-join"><strong>join</strong></a>(words, sep<small><font color="#909090">=' '</font></small>)<dd><small><tt><a href="#-join">join</a>(list [,sep]) -> string<br> - <br> -Return a string composed of the words in list, with<br> -intervening occurrences of sep. The default separator is a<br> -single space.<br> - <br> -(joinfields and join are synonymous)</tt></small></dl> - <dl><dt><a name="-joinfields"><strong>joinfields</strong></a> = join(words, sep<small><font color="#909090">=' '</font></small>)<dd><small><tt><a href="#-join">join</a>(list [,sep]) -> string<br> - <br> -Return a string composed of the words in list, with<br> -intervening occurrences of sep. The default separator is a<br> -single space.<br> - <br> -(joinfields and join are synonymous)</tt></small></dl> - <dl><dt><a name="-ljust"><strong>ljust</strong></a>(s, width)<dd><small><tt><a href="#-ljust">ljust</a>(s, width) -> string<br> - <br> -Return a left-justified version of s, in a field of the<br> -specified width, padded with spaces as needed. The string is<br> -never truncated.</tt></small></dl> - <dl><dt><a name="-lower"><strong>lower</strong></a>(s)<dd><small><tt><a href="#-lower">lower</a>(s) -> string<br> - <br> -Return a copy of the string s converted to lowercase.</tt></small></dl> - <dl><dt><a name="-lstrip"><strong>lstrip</strong></a>(s)<dd><small><tt><a href="#-lstrip">lstrip</a>(s) -> string<br> - <br> -Return a copy of the string s with leading whitespace removed.</tt></small></dl> - <dl><dt><a name="-maketrans"><strong>maketrans</strong></a>(...)<dd><small><tt><a href="#-maketrans">maketrans</a>(frm, to) -> string<br> - <br> -Return a translation table (a string of 256 bytes long)<br> -suitable for use in string.translate. The strings frm and to<br> -must be of the same length.</tt></small></dl> - <dl><dt><a name="-replace"><strong>replace</strong></a>(s, old, new, maxsplit<small><font color="#909090">=-1</font></small>)<dd><small><tt>replace (str, old, new[, maxsplit]) -> string<br> - <br> -Return a copy of string str with all occurrences of substring<br> -old replaced by new. If the optional argument maxsplit is<br> -given, only the first maxsplit occurrences are replaced.</tt></small></dl> - <dl><dt><a name="-rfind"><strong>rfind</strong></a>(s, *args)<dd><small><tt><a href="#-rfind">rfind</a>(s, sub [,start [,end]]) -> int<br> - <br> -Return the highest index in s where substring sub is found,<br> -such that sub is contained within s[start,end]. Optional<br> -arguments start and end are interpreted as in slice notation.<br> - <br> -Return -1 on failure.</tt></small></dl> - <dl><dt><a name="-rindex"><strong>rindex</strong></a>(s, *args)<dd><small><tt><a href="#-rindex">rindex</a>(s, sub [,start [,end]]) -> int<br> - <br> -Like rfind but raises ValueError when the substring is not found.</tt></small></dl> - <dl><dt><a name="-rjust"><strong>rjust</strong></a>(s, width)<dd><small><tt><a href="#-rjust">rjust</a>(s, width) -> string<br> - <br> -Return a right-justified version of s, in a field of the<br> -specified width, padded with spaces as needed. The string is<br> -never truncated.</tt></small></dl> - <dl><dt><a name="-rstrip"><strong>rstrip</strong></a>(s)<dd><small><tt><a href="#-rstrip">rstrip</a>(s) -> string<br> - <br> -Return a copy of the string s with trailing whitespace<br> -removed.</tt></small></dl> - <dl><dt><a name="-split"><strong>split</strong></a>(s, sep<small><font color="#909090">=None</font></small>, maxsplit<small><font color="#909090">=-1</font></small>)<dd><small><tt><a href="#-split">split</a>(s [,sep [,maxsplit]]) -> list of strings<br> - <br> -Return a list of the words in the string s, using sep as the<br> -delimiter string. If maxsplit is given, splits into at most<br> -maxsplit words. If sep is not specified, any whitespace string<br> -is a separator.<br> - <br> -(split and splitfields are synonymous)</tt></small></dl> - <dl><dt><a name="-splitfields"><strong>splitfields</strong></a> = split(s, sep<small><font color="#909090">=None</font></small>, maxsplit<small><font color="#909090">=-1</font></small>)<dd><small><tt><a href="#-split">split</a>(s [,sep [,maxsplit]]) -> list of strings<br> - <br> -Return a list of the words in the string s, using sep as the<br> -delimiter string. If maxsplit is given, splits into at most<br> -maxsplit words. If sep is not specified, any whitespace string<br> -is a separator.<br> - <br> -(split and splitfields are synonymous)</tt></small></dl> - <dl><dt><a name="-strip"><strong>strip</strong></a>(s)<dd><small><tt><a href="#-strip">strip</a>(s) -> string<br> - <br> -Return a copy of the string s with leading and trailing<br> -whitespace removed.</tt></small></dl> - <dl><dt><a name="-swapcase"><strong>swapcase</strong></a>(s)<dd><small><tt><a href="#-swapcase">swapcase</a>(s) -> string<br> - <br> -Return a copy of the string s with upper case characters<br> -converted to lowercase and vice versa.</tt></small></dl> - <dl><dt><a name="-translate"><strong>translate</strong></a>(s, table, deletions<small><font color="#909090">=''</font></small>)<dd><small><tt><a href="#-translate">translate</a>(s,table [,deletions]) -> string<br> - <br> -Return a copy of the string s, where all characters occurring<br> -in the optional argument deletions are removed, and the<br> -remaining characters have been mapped through the given<br> -translation table, which must be a string of length 256. The<br> -deletions argument is not allowed for Unicode strings.</tt></small></dl> - <dl><dt><a name="-upper"><strong>upper</strong></a>(s)<dd><small><tt><a href="#-upper">upper</a>(s) -> string<br> - <br> -Return a copy of the string s converted to uppercase.</tt></small></dl> - <dl><dt><a name="-zfill"><strong>zfill</strong></a>(x, width)<dd><small><tt><a href="#-zfill">zfill</a>(x, width) -> string<br> - <br> -Pad a numeric string x with zeros on the left, to fill a field<br> -of the specified width. The string x is never truncated.</tt></small></dl> -</td></tr></table> -<p><table width="100%" cellspacing=0 cellpadding=2 border=0> -<tr bgcolor="#55aa55"> -<td colspan=3 valign=bottom><small><small> <br></small></small -><font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr> - -<tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td> -<td width="100%"><strong>_StringType</strong> = <type 'string'><br> -<strong>__file__</strong> = r'c:\Python21\Lib\string.pyc'<br> -<strong>__name__</strong> = 'string'<br> -<strong>_idmap</strong> = '<font color="#c040c0">\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f</font> !"#$%&<font color="#c040c0">\'</font>()*+,-./...<font color="#c040c0">\xcf\xd0\xd1\xd2\xd3\xd4\xd5\xd6\xd7\xd8\xd9\xda\xdb\xdc\xdd\xde\xdf\xe0\xe1\xe2\xe3\xe4\xe5\xe6\xe7\xe8\xe9\xea\xeb\xec\xed\xee\xef\xf0\xf1\xf2\xf3\xf4\xf5\xf6\xf7\xf8\xf9\xfa\xfb\xfc\xfd\xfe\xff</font>'<br> -<strong>_idmapL</strong> = None<br> -<strong>digits</strong> = '0123456789'<br> -<strong>hexdigits</strong> = '0123456789abcdefABCDEF'<br> -<strong>letters</strong> = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'<br> -<strong>lowercase</strong> = 'abcdefghijklmnopqrstuvwxyz'<br> -<strong>octdigits</strong> = '01234567'<br> -<strong>printable</strong> = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!"#$%&<font color="#c040c0">\'</font>()*+,-./:;<=>?@[<font color="#c040c0">\\</font>]^_`{|}~ <font color="#c040c0">\t\n\r\x0b\x0c</font>'<br> -<strong>punctuation</strong> = '!"#$%&<font color="#c040c0">\'</font>()*+,-./:;<=>?@[<font color="#c040c0">\\</font>]^_`{|}~'<br> -<strong>uppercase</strong> = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'<br> -<strong>whitespace</strong> = '<font color="#c040c0">\t\n\x0b\x0c\r</font> '</td></tr></table> -</body></html>
\ No newline at end of file diff --git a/sandbox/tibs/pysource/notes/thoughts.txt b/sandbox/tibs/pysource/notes/thoughts.txt deleted file mode 100644 index 59691717b..000000000 --- a/sandbox/tibs/pysource/notes/thoughts.txt +++ /dev/null @@ -1,170 +0,0 @@ -Thoughts on pysource -==================== - -:Author: Tibs -:Date: 19 Sep 2002 - -.. - - [This is the contents of an email sent from Tibs to me, to tie up - -- or at least identify -- loose ends. When Tibs writes "you", - he's referring to me. It is published with Tibs' permission. I - mostly agree with what Tibs has written. I've added my own notes, - indented in square brackets, like this one. - - --David Goodger] - -Well, having looked back at the pysource sources, I'm confirmed -in my opinion that, if I were to start work on the project again, -I would probably start a new version of pysource from scratch, -using what I have learned (essentially, the content of visit.py), -and taking advantage of all the new technology that is in the -modern DOCUTILS. - -Thus I would (at least): - -1. produce a "frontend" using Optik -2. rewrite visit.py more neatly -3. construct DOCUTILS nodes to match pysource.dtd -4. *possibly* meld those into the classes in visit.py - (but possibly not - some of the stuff in visit.py - seems to me to be, of necessity, a bit messy as it - is constructing stuff, and thus it may be premature - to "DOCUTILS" it before it is necessary). -5. produce an example transform to amend the Python - specific DOCUTILS tree into a generic DOCUTILS - tree. - -That's a fair amount of work, and I'm not convinced that I can -find the sustained effort [1]_, especially if you might be -willing to take the task on (and if I would have been refactoring -anyway, a whole different head may be a significant benefit). - -.. [1] I believe that's called "British understatement". - -Some comments on pysource.txt and pysource.dtd ----------------------------------------------- - -I believe that a <docstring> node is a Good Thing. It's a natural -construct (if one believes that the other nodes are good things -as well!), and it allows the "transform" of the Python specific -tree to be done more sensibly. - - [I think I finally understand what Tibs is getting at here. I - thought he meant to have a <docstring> node in an otherwise - standard Docutils doctree, which just contained the raw docstring. - Instead, I believe he means that the Python-specific Docutils - doctree elements like <class_section> and - <module_section> (see pysource.dtd), should each have a <docstring> - element which contains ``%structure.model;``, instead of the - current ``%structure.model;`` directly inside the element. In - other words, a <docstring> element would be a simple container for - all the parsed elements of the docstring. On second thought, each - Python-specific section element would still have to have - ``%structure.model;``, in order to contain subsections. A - <package_section> would contain <module_section>s, which would - contain <class_section>s, and so on. - - So a <docstring> element may be useful as a convenience to - transforms. It would be a trivial change anyhow. - - The initial (internal) data structure resulting from the parsing - of Python modules & packages is a completely different beast. It - should contain <docstring> nodes, along with <package>, <module>, - <class>, etc., nodes. But these should *not* be subclasses of - docutils.nodes.Node, and this tree should not be a "Docutils - document tree". It should be a separate, parallel structure. - Document tree nodes (docutils.nodes.Node objects) are not suited - for this work. - - --DG] - -I recommend some initial "surgery" on the initial parse tree to -make finding the docstrings for nodes easier. - -I reckon that one produces a Python-specific doctree, and then -chooses one of several transforms to produce generic doctrees. - -By the way, I still vote for "static" introspection - that is, -without actually importing the module. It does limit what one can -do in some respects, but there are modules one might want to -document that one does not wish to import (and indeed, at work we -have some Python files that essentially cannot be introspected in -this manner with any ease - they are "designed" to be imported by -other modules after ``sys.path`` has been mangled suitably, and -just don't work stand-alone). - -I've tried to expand out the ideas you had on how the "pysource" -tool should work below. - - although it occurs to me that this is all terribly obvious, - really. Oh well... - -The pysource tool ------------------ - -The "input mode" should be the "Python Source Reader". - - You can see where I'm starting from in pysource.txt. - -This produces, as its output, a Python-specific doctree, -containing extra nodes as defined in pysource.dtd (etc.). - -One of the tasks undertaken by the Python Source Reader is to -decide what to do with docstrings. For each Python file, it -discovers (from ``__docformat__``) if the input parser is -"reStructuredText". If it is, then the contents of each docstring -in that file will be parsed as such, including sorting out -interpreted text (i.e., rendering it into links across the tree). -If it is not, then each docstring will be treated as a literal -block. - - This admits the posibility of adding other parsers *for - docstrings* at a later date - which I suspect is how HappyDoc - does it. It is just necessary to publicise the API for the - Docstring class, and then someone else can provide alternate - plugins. - -The output of the Python Source Reader is thus a Python-specific -doctree, with all docstrings fully processed (as appropriate), -and held inside <docstring> elements. - -The next stage is handled by the Layout Transformer. - - [What I call "stylist transforms". --DG] - -This determines the layout of the document to be produced - the -*kind* or *style* of output that the user wants (e.g., PyDoc -style, LibRefMan style, generic docutils style, etc.). - -Each layout is represented by a class that walks the -Python-specific doctree, replacing the Python-specific nodes with -appropriate generic nodes. The output of the Layout Transformer -is thus a generic doctree. - -The final stage is thus a normal DOCUTILS Writer - since it is -taking input that is a generic doctree, this makes perfect -sense. This also means that we get maximum leverage from existing -Writers, which is essential (not just a Good Thing). - -As you point out, some layouts will probably only be appropriate -for some output formats. Well, that's OK. On the other hand, if -the output of the Layout stage *is* a generic doctree, we're not -likely to get fatal errors by putting it through the wrong -Writer, so we needn't worry too much. - -Thus one might envisage a command line something like:: - - pysource --layout:book --format:html this_module - -Of course, other command line switches would be options for -particular phases (e.g., to use frames or not for HTML output). I -can see wanting a series of configuration files that one could -reference, to save specifying lots of switches. - -One specific thing to be decided, particularly for HTML, is -whether one is outputting a "cluster" of files (e.g., as javadoc -does). I reckon this can be left for later on, though (as can -such issues as saying "other interesting sources are *over -there*, so reference them if you can" - e.g., the Python -library). |