[Doc-SIG] documenting Python constraints on types
Frederic Giacometti
frederic.giacometti@arakne.com
Tue, 29 May 2001 20:33:47 -0400
This is a multi-part message in MIME format.
--------------AD5D43B3D93F8309E179B97F
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Michel Pelletier wrote:
> Ignore this please, emacs key bindings should not be confused with pine
> key bindings.
Well, too late :)))
My remarks:
A) "The Problem":
Michel lists much relevant items, but then he forgets to resume what the
problem is (from the listed elements):
The problem Michel describes in a <<documentation>> problem.
B) The proposed solution:
In my experience, in 80% of the cases relevant to the 'problem', the two
issues are:
- what is required from the objects passed as argument
- what is returned by the function/methods
- what are the exceptions of interest
Michel's proposal just misses this.
So, for completeness's sake, the should be completed with the ability to
prefix argument and functions ('def ...') with one or several 'interfaces'.
FYI, I'm attaching a Python documentation convention I wrote 6 months ago.
It has been successfully used in 2 industrial projects; it is now used in JPE
too.
I guess I should update it with the retour d'experience; but this gives an
idea upon what is practically feasible.
The underlying reasoning is as follows:
- Types are 'documented' in typed languages because they are required
(e.g.: not specifying a type in Java, C++ or Eiffel give a syntax error)
- Type documentation is not required in Python. Astonishingly enough, this is
to be considered by 99,9% of the python programming population "Thou shallt
not document argument and return types".
- There is maybe an intermediate position stating "documenting types is part
of the python source documentation", and for some, including this constraint
in quality assurance procedures.
The attached documents are derived from this; it is an attempt at defining a
standardized framework for programmers for documenting the types at a 'least
cost' (The threat being: If you don't respect that, you'll be sentenced to 1
year in Java :))
Frederic Giacometti
Disclaimer:
I am the original author of the documents, and I am authorizing whoever to do
whatever with them, without my responsability being engaged in any way.
>
>
> ;)
>
> -Michel
>
> On Tue, 29 May 2001, Michel Pelletier wrote:
>
> >
> > Folks,
> >
> > I'm almost ready to distribute my PEP for wider discussion in the Python
> > community;
> >
> > http://www.zope.org/Members/michel/InterfacesPEP/PEP.txt
> >
> > ,
> >
> >
> >
>
> _______________________________________________
> Types-SIG mailing list
> Types-SIG@python.org
> http://mail.python.org/mailman/listinfo/types-sig
--------------AD5D43B3D93F8309E179B97F
Content-Type: text/plain; charset=us-ascii;
name="docplates.py"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="docplates.py"
## standard documentation templates
## module template
"""
Public:
- : --
"""
##function template
def ():
"""
Arguments:
- : --
Return:
- --
Effect:
"""
##class template
class :
"""
Attributes:
- : --
Class Attributes:
- : --
Usage:
"""
##method template
def ( self, ):
"""
Private --
Arguments:
- : --
Return:
- --
Effect:
"""
--------------AD5D43B3D93F8309E179B97F
Content-Type: text/html; charset=us-ascii;
name="doc-conventions.html"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="doc-conventions.html"
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Frederic Giacometti">
<meta name="GENERATOR" content="Mozilla/4.76 [en] (WinNT; U) [Netscape]">
<title>iPhrase Python documentation conventions</title>
</head>
<body>
<h2>
Python Documentation Strings</h2>
Python attaches documentation strings to every:
<ul>
<li>
module</li>
<li>
function</li>
<li>
method</li>
<li>
class</li>
</ul>
In Python, these strings are defined as the first element within the local
scope of the object documented.
<br>Similar strings can also be defined in the C/C++ Python extensions.
<br>The following formalism is designed to:
<ul>
<li>
enhance readability by providing a documentation language common to everybody</li>
<li>
provide a support facilitating complete documentation/specification while
keeping verbosity at a minimum</li>
<li>
enable the use of documentation extraction tools</li>
</ul>
<h3>
<hr WIDTH="100%">Summary</h3>
<u>module:</u>
<blockquote><tt>Public:</tt>
<blockquote><i>- name : type -- description</i></blockquote>
</blockquote>
<u>function and method:</u>
<blockquote><tt>Arguments:</tt>
<blockquote><i>- name : type [|type] [input|update] -- description [--
constraint: ...]</i></blockquote>
<tt>Keyword Arguments:</tt>
<blockquote><i>- name : type|type [= default_value] -- description [--
constraint: ...]</i></blockquote>
<tt>Return:</tt>
<blockquote><i>- type [|type] -- description</i></blockquote>
<tt>Effect:</tt>
<blockquote><i>description</i></blockquote>
<tt>Raise:</tt>
<blockquote><i>- type -- description</i>
<br><i> argument section</i></blockquote>
</blockquote>
<u>method:</u>
<blockquote><tt>Private --</tt></blockquote>
<u>class:</u>
<blockquote><tt>Attributes:</tt></blockquote>
<blockquote>
<blockquote><i>- name : type -- description</i></blockquote>
<tt>Class Attributes:</tt>
<blockquote><i>- name : type -- description</i></blockquote>
</blockquote>
<u>Other section titles</u>:
<blockquote><tt>Usage:</tt></blockquote>
<p><br>
<hr WIDTH="100%">
<h3>
Generic format</h3>
Documentation strings are defined as plain ASCII text.
<br>This text is composed as follows:
<ul>
<li>
The first line is the descriptive title to be used in the object in documentation
summaries</li>
<li>
Any number of sections (see below)</li>
<li>
Descriptive text (object intent, particular references...)</li>
</ul>
<h3>
<hr WIDTH="100%">Section</h3>
A section is defined as:
<ul>
<li>
a section title, defined as a one-word section title, followed with a column
(e.g.: '<tt>Arguments:</tt>')</li>
<li>
indented text</li>
</ul>
A section can contain other sections, with propoer indentation (the Emacs
Python mode will automatically maintain indentation).
<h3>
<hr WIDTH="100%">Module</h3>
<h5>
Public</h5>
The module documentation will defined the published and exportable symbols
(section name: '<tt>Public:</tt>'). A module documentation will allways
have a <tt>Public</tt> section.
<p>Only symbols listed in the <tt>Public</tt> section can be referred or
imported from other modules.
<br>If the current module is a Python package, sub-module names can listed
in the public section.The format of each entry is as follow:
<blockquote><i>- name : type -- description</i></blockquote>
<i>Publication of imported classes and functions</i>
<p>Whenever possible, the origin of public imported objects should be documented.
<br> <i></i>
<p><i>Example</i>
<p><tt>"""Grammar class and related definitions</tt><tt></tt>
<p><tt>Public:</tt>
<br><tt> Grammar : ClassType -- imported from iphrase.nl.grammar.model</tt>
<br><tt> MaxXXX : IntegerType -- max value for XXX</tt><tt></tt>
<p><tt>Usage:</tt>
<br><tt> Cf. Grammar class documentation</tt>
<br><tt>"""</tt>
<h3>
<hr WIDTH="100%">Functions and Methods</h3>
<h5>
Arguments</h5>
Function and method arguments are documented in the '<tt>Argument:</tt>'
section.
<p>Each entry of the <tt>Arguments</tt> section is of the form:
<blockquote><i>- name : type [|type] [input|update] -- description [--
constraint: ...]</i></blockquote>
where
<ul>
<li>
<i>name</i> is the argument name</li>
<li>
<i>type</i> describes the expected type of the argument; several types
can be given (e.g. None). Types can be a class name, a Python type name,
or an abstract descriptor (e.g.: Map, Sequence), or a complex descriptor
(e.g. <nobr><tt>Sequence[ StringType] </tt>for a sequence of strings</nobr>,
<nobr><tt>Dict[
StringType : iphrase.nl.parser.parser.FSMType]</tt> for a dictionary of
FSM objects indexed with strings</nobr>).</li>
<li>
<i>input</i> or <i>update</i> explicitely specifies that the argument will
not be modified (input), or it is expected to be modified (update). [<i>Note</i>:
in the case of complex objects, we will consider modification by direct
effect in the function code only.]</li>
<li>
<i>description</i> decribe the argument purpose and role</li>
<li>
the <i>constraint</i> phrase will explicit any constraint on the argument
value (e.g.: positive, not null ...).</li>
</ul>
<i>Notes</i>:
<ul>
<li>
Do not document the '<tt>self</tt>' argument of a method</li>
<li>
Do not document the return value of the __init__ methods</li>
<li>
....</li>
</ul>
<h5>
Keyword Arguments</h5>
The '<tt>Keyword Arguments:</tt>' section describe keyword arguments of
a function.
<blockquote><i>- name : type|type [= default_value] -- description [--
constraint: ...]</i></blockquote>
<h5>
Return</h5>
In Python, when no <tt>return</tt> statement is executed, the <tt>None</tt>
value is returned.
<br>In other cases, one or more (tuple) values are returned.
<br>The <tt>Return:</tt> section will describe the type and value of the
one or many values returned.
<br>For each entry, the format is of the form:
<blockquote><i>- type [|type] -- description</i></blockquote>
<h5>
Effect</h5>
Actions of the function persisting beyond the function call (e.g.: side
effects...) are described in the <tt>Effect:</tt> section (free text).
<h5>
Raise</h5>
The <tt>Raise:</tt> section is used to document exceptions of a particular
interest which can be raised.
<p>The format of each entry is as:
<blockquote><i>- type -- description</i>
<br><i> argument section</i></blockquote>
<i>Examples:</i><tt></tt>
<p><tt> def someMethod( self, names, options=0):</tt>
<br><tt> """sample method</tt><tt></tt>
<p><tt> Arguments:</tt>
<br><tt>
- names : ListType[ StringType] -- list of names</tt>
<br><tt>
- options : IntegerType -- options flags (cf. ....)</tt><tt></tt>
<p><tt> Effect:</tt>
<br><tt>
update 'names'</tt><tt></tt>
<p><tt> Return:</tt>
<br><tt>
- IntegerType -- number of new elements in 'names'</tt>
<br><tt>
- IntegerType -- number of elements removed from 'names'</tt><tt></tt>
<p><tt> Raise:</tt>
<br><tt>
- CustomError -- custom error condition detected</tt>
<br><tt> """</tt><tt></tt>
<p><tt>def someFunction( *args, **kw):</tt>
<br><tt> """sample function</tt><tt></tt>
<p><tt> Arguments:</tt>
<br><tt> - args : TupleType --
description...</tt><tt></tt>
<p><tt> Keyword Arguments :</tt>
<br><tt> - names : sequence[
StringType] = [] -- list of marked names</tt>
<br><tt> - color : StringType
= 'green' -- background color</tt><tt></tt>
<p><tt> Effect:</tt>
<br><tt> update the upper window</tt>
<br><tt> """</tt>
<h3>
<hr WIDTH="100%">Methods</h3>
<h5>
Private</h5>
Some methods are used for development purposeonly, and are not bound to
be reused.
<br>Such methods will be labeled with the definition of a <tt>Private -
</tt>section.
<p><i>Example</i><i></i>
<p><tt><i> </i>def privateMethod( self):</tt>
<br><tt> """sample private method</tt>
<br><tt> Private --</tt><tt></tt>
<p><tt> Return:</tt>
<br><tt>
TupleType[ TupleType[ IntegerType] -- normalized matrix</tt>
<br><tt> """</tt>
<h3>
<hr WIDTH="100%">Class</h3>
<h5>
Attributes</h5>
Locally-defined instance attributes are described in the <tt>Attributes:</tt>
section.
<br>The format of each entry is as:
<blockquote><i>- name : type -- description</i></blockquote>
<h5>
Class Attributes</h5>
Locally-defined instance attributes are described in the <tt>Class Attributes:</tt>
section.
<br>The format of each entry is as:
<blockquote><i>- name : type -- description</i></blockquote>
<h6>
__getattr__ and __setattr__ special methods</h6>
Names or categories of attributes with special treatement (ex: dynamically
defined attributes) will be listed in the documentation of the <i>__getattr__</i>
and <i>__setattr__</i> special methods.
<p><i>Example</i><i></i>
<p><tt>class sampleClass( UserList):</tt>
<br><tt> """sample class</tt><tt></tt>
<p><tt> Attributes:</tt>
<br><tt> dependents : MappingType[
ListType[ Symbol]] -- symbols dependency graph</tt>
<br><tt> timeStamp : IntegerType
-- current time stamp</tt><tt></tt>
<p><tt> Usage:</tt>
<br><tt> sampleClass is a list
of otherClass objects.</tt>
<br><tt> ...</tt>
<br><tt> """</tt>
<p>
<hr WIDTH="100%">
<h3>
Other Possible Types of Section</h3>
<h5>
Usage</h5>
Usage information (use case, example, hints...) is strongly encouraged
in the documentation.
<br>It will be documented in the <tt>Usage: </tt>section.
<p>
<hr WIDTH="100%">
<h2>
Documentation strings in C/C++</h2>
<h4>
Module</h4>
The <tt>__doc__</tt> string must be defined in the module dictionary; its
format
<p>This is done by adding the following code in the XXX module initialization
function:
<p><tt>void initXXX( void)</tt>
<br><tt>{</tt>
<br><tt> PyObject* module, *docstring;</tt>
<p><tt> module = Py_InitModule( "XXX", XXX_methods);</tt>
<p><b><tt> docstring = PyString_FromString( "module short
description</tt></b>
<br><b><tt>Public:</tt></b>
<br><b><tt> - yyyType : TypeType -- yyy extenstion type</tt></b>
<br><b><tt> ...</tt></b>
<br><b><tt>");</tt></b>
<br><b><tt> PyObject_SetAttrString( module, "__doc__",
docstring);</tt></b>
<br><b><tt> Py_DECREF( docstring);</tt></b>
<br><tt> ....</tt>
<br><tt>}</tt>
<br>
<h4>
Functions and Methods</h4>
The fourth field of the <tt>PyMethodDef</tt> structure (used to define
Python methods and functions) defines the documentation string, and should
always be initialized.
<p>The function or method definition is explicited in the first line of
the string, exactly as it would be defined in Python.
<br>The remaining of the string follows the same documentation format as
in Python.
<p>Example:
<p><tt>static PyMethodDef XXX_methods =</tt>
<br><tt>{</tt>
<br><tt> { XXX_yyy_create, "yyy", METH_VARARGS,</tt>
<br><tt> <b>"def yyy( arg1, arg2, arg3=None)</b></tt>
<br><b><tt>Arguments:</tt></b>
<br><b><tt> - arg1 : IntegerType -- ...</tt></b>
<br><b><tt> ...</tt></b>
<br><b><tt>Return:</tt></b>
<br><b><tt> - XXX.yyyType -- new yyy object</tt></b>
<br><tt><b>"</b>},</tt>
<br><tt> ...</tt>
<br><tt>};</tt>
<br>
<br>
<br>
<p>
<hr WIDTH="100%">
<h2>
Examples</h2>
<h4>
iphrase.nl.grammar (extracted from iphrase/nl/grammar/__init__.py stripped
from source code)</h4>
<p><br><tt>"""Grammar Tools Module</tt>
<p><tt>Public:</tt>
<p><tt> - Package : ClassType -- class iphrase.nl.grammar.package.Package</tt>
<p><tt> - Grammar : ClassType -- class iphrase.nl.grammar.Grammar</tt>
<p><tt> - defaultRootName : StringType -- default root rule name</tt>
<p><tt> - maxframes : IntegerType --</tt>
<br><tt> limit on number of frames for an ambiguity search
path</tt>
<p><tt> - MaxAmbigSearchCount : IntegerType --</tt>
<br><tt> limit of ambiguities retrieved in an ambiguity
search</tt>
<p><tt>Option flags that can be OR'd in an integer variable:</tt>
<p><tt> - VERIFY_GET_UNUSED -- will check of unused rules</tt>
<p><tt> - AMBIG_PRUNE_MARKED -- will not visit marked objexts</tt>
<p><tt> - VERIFY_AMBIGUITY -- do ambiguity search</tt>
<p><tt> - SEARCH_PRODUCTIONS -- search for production mode</tt>
<p><tt> - SEARCH_RULES -- search for rules mode</tt>
<p><tt> - SEARCH_USING -- search for under rule constraint</tt>
<p><tt> - VISIT_NODEPTH -- do not visit sub rules</tt>
<p><tt> - GRAM_SAVE -- save compiled grammar for later reuse</tt>
<p><tt> - MODE_VERBOSE -- verbose mode enabled</tt>
<br><tt>"""</tt>
<p><tt>class GrammarError( StandardError):</tt>
<br><tt> """Abstract class for grammar errors</tt>
<p><tt> Attributes:</tt>
<br><tt> msg : StringType -- message text</tt>
<br><tt> errorvalue : Object -- arbitrary object attached
to the error</tt>
<br><tt> """</tt>
<p><tt> def __init__( self, msg, errorvalue=None):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> msg : StringType -- set msg
attribute</tt>
<br><tt> errorvalue : Object -- set
errorvalue attribute</tt>
<br><tt> """</tt>
<p><tt> def __repr__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> - StringType : 'self.msg: self.errorvalue'</tt>
<br><tt> """</tt>
<p><tt> def __str__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> - StringType : 'self.msg: self.errorvalue'</tt>
<br><tt> """</tt>
<p><tt>class GrammarListError( UserList, GrammarError):</tt>
<br><tt> """Mechanism for collecting GrammarError exceptions up to
Maxitems</tt>
<p><tt> Class Attributes:</tt>
<br><tt> - Maxitems : IntegerType --</tt>
<br><tt> max number of items collected; default
is 0x10000</tt>
<br><tt> """</tt>
<p><tt> def __init__( self, lst=[]):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - lst : ListType[ GrammarError]
-- initial list of errors</tt>
<br><tt> """</tt>
<p><tt> def __repr__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> StringType -- formatted list of
errors</tt>
<br><tt> """</tt>
<p><tt> def __str__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> StringType -- formatted list of
errors</tt>
<br><tt> """</tt>
<p><tt> def append( self, item):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - item : GrammarError -- error to
append</tt>
<p><tt> Raise</tt>
<br><tt> - self -- self will be raised when
self.MaxItems <= len( self)</tt>
<br><tt> """</tt>
<h4>
iphrase.nl.grammar.model (iphrase/nl/grammar/model.py stripped from source
code)</h4>
<tt>"""Grammar class and immediately connected structures</tt>
<p><tt>Public:</tt>
<p><tt> - anglerules : TupleType[ StringType] -- angle symbols
refering a rule</tt>
<p><tt> - hardcodedrules : TupleType[ StringType] --</tt>
<br><tt> non-terminal symbols for which a default rule
is defined</tt>
<p><tt> - trace : IntegerType -- trace level; default is 0</tt>
<br><tt>"""</tt>
<p><tt>class MultiplyIncludedError( GrammarError):</tt>
<br><tt> """error raised when a package is detected to be included
more than once</tt>
<br><tt> """</tt>
<br><tt> def __init__( self, name):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - name : StringType -- name of the
faulting package</tt>
<br><tt> """</tt>
<p><tt>class CycleError( GrammarError):</tt>
<br><tt> """error raised when rule cycle detected</tt>
<br><tt> """</tt>
<p><tt> def __init__( self, rulename, path):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - rulename : StringType -- name
of cycling rule</tt>
<br><tt> - path : sequence[ Productions]
--</tt>
<br><tt> sequence of Production
objects occuring in the cycle</tt>
<br><tt> """</tt>
<p><tt> def __repr__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> - StringType -- formated message</tt>
<br><tt> """</tt>
<p><tt>class UndefinedReferenceError( GrammarError):</tt>
<br><tt> """error raised when detecting an undefined rulename</tt>
<br><tt> Attributes:</tt>
<br><tt> - refname : StringType -- faulting reference</tt>
<br><tt> - path : sequence[ Productions] --</tt>
<br><tt> sequence of Production objects leading
to the undefined reference</tt>
<br><tt> """</tt>
<p><tt> def __init__( self, refname, path):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - refname : StringType -- faulting
reference</tt>
<br><tt> - path : sequence[ Productions]
--</tt>
<br><tt> sequence of Production
objects leading to the undefined reference</tt>
<br><tt> """</tt>
<p><tt> def __str__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> - StringType : formatted message
with all path elements</tt>
<br><tt> """</tt>
<p><tt> def __repr__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> - StringType : formatted message
with faulting production</tt>
<br><tt> """</tt>
<p><tt>class FsmError( GrammarError):</tt>
<br><tt> """abstract class for FSM-related errors</tt>
<br><tt> """</tt>
<br><tt> def __init__( self, msg, path, fsmkey):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - msg : StringType -- companion
message</tt>
<br><tt> - path : sequence[Production] --
current hops sequence</tt>
<br><tt> """</tt>
<p><tt>class EmptyFsmError( FsmError):</tt>
<br><tt> """error raised when detecting an expression FSM node simultanously</tt>
<br><tt> initial and final</tt>
<br><tt> """</tt>
<br><tt> def __init__( self, path, fsmkey):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - path : sequence[Production] --
current hops sequence</tt>
<br><tt> - fsmkey : Production --</tt>
<br><tt> Production object associated
to the faulting FSM</tt>
<br><tt> """</tt>
<p><tt>class AmbiguousFinalFsmError( FsmError):</tt>
<br><tt> """error raised when detecting ambiguity associated to final
states</tt>
<br><tt> """</tt>
<br><tt> def __init__( self, path, fsmkey):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - path : sequence[Production] --
current hops sequence</tt>
<br><tt> - fsmkey : Production -- Production
object associated to the faulting FSM</tt>
<br><tt> """</tt>
<p><tt>class UnboundProduction:</tt>
<br><tt> """Production without package context</tt>
<p><tt> Attributes:</tt>
<br><tt> - name : StringType -- rule name</tt>
<br><tt> - expression : Expression -- expression (right-hand
side)</tt>
<br><tt> - comment : StringType | None -- optional comment
text</tt>
<p><tt> Class Attributes:</tt>
<br><tt> - alllowercase : IntegerType</tt>
<br><tt> -- boolean indicating conversion
of all grammar definition to lower case;</tt>
<br><tt> default is 1</tt>
<br><tt> """</tt>
<p><tt> def __init__( self, name, expression, comment=None):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - name : StringType -- rule name</tt>
<br><tt> - expression : StringType -- expression
text</tt>
<br><tt> - comment : StringType | None --
optional comment text</tt>
<p><tt> Raise:</tt>
<br><tt> - GrammarError --</tt>
<br><tt> raised with adequate
message when illegal values detected</tt>
<br><tt> """</tt>
<p><tt> def __repr__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> - StringType -- production formatted
in cfg grammar format</tt>
<br><tt> """</tt>
<p><tt> def __cmp__( self, other):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> - IntegerType -- comparaison first
on rule name, then on expression</tt>
<br><tt> """</tt>
<p><tt>class Production( UnboundProduction, package.Bound):</tt>
<br><tt> """Production with package context</tt>
<br><tt> """</tt>
<p><tt> def __init__( self, name, expression, comment, packageName,
lineno):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - name : StringType -- rule name</tt>
<br><tt> - expression : StringType -- expression
text</tt>
<br><tt> - comment : StringType | None --
comment text</tt>
<br><tt> - packageName : StringType -- package
name</tt>
<br><tt> - lineno : IntegerType -- position</tt>
<p><tt> Raise:</tt>
<br><tt> - package.PackageError --</tt>
<br><tt> GrammarError caught
are replaced with PackageError exceptions</tt>
<p><tt> Arguments:</tt>
<br><tt> - GrammarError
-- keep current exception value</tt>
<br><tt> - StringType
-- 'packageName' arg</tt>
<br><tt> - IntegerType
-- 'lineno' arg</tt>
<br><tt> """</tt>
<p><tt> def __repr__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> - StringType -- packageName:lineno
+ formatted production</tt>
<br><tt> """</tt>
<p><tt> def __hash__( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> - IntegerType -- hashing on in-memory
unique object id</tt>
<br><tt> """</tt>
<p><tt> def __cmp__( self, other):</tt>
<br><tt> """</tt>
<br><tt> Argument:</tt>
<br><tt> - other : Production -- right side
of the comparison pair</tt>
<br><tt> Return:</tt>
<br><tt> - IntegerType -- comparison on object
id's</tt>
<br><tt> """</tt>
<p><tt> def __copy__( self):</tt>
<br><tt> """Will always raise RuntimeError exception</tt>
<br><tt> Raise:</tt>
<br><tt> - RuntimeError -- Production objects
must remain unique in memory</tt>
<br><tt> Arguments:</tt>
<br><tt> - StringType
-- errormessage</tt>
<br><tt> """</tt>
<p><tt>class Rule( UserList):</tt>
<br><tt> """A rule instance is a list of Productions referring to
a same rule name</tt>
<br><tt> Attributes:</tt>
<br><tt> - name : StringType -- rule name</tt>
<br><tt> - prods : ListType -- list of productions at
creation time</tt>
<br><tt> """</tt>
<p><tt> def __init__( self, name, prods=[]):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - name : StringType -- rule name</tt>
<br><tt> - prods : ListType -- list of productions
at creation time</tt>
<br><tt> """</tt>
<p><tt>class StopRuleAmbiguity( Exception):</tt>
<br><tt> """used to stop ambiguity search on current rule, and pass
to the next rule</tt>
<br><tt> """</tt>
<p><tt>class AmbiguousContext:</tt>
<br><tt> """used in argument Grammar.ambiguities() argument list</tt>
<br><tt> Attributes:</tt>
<br><tt> - count : IntegerType -- number of times ambiguities()
has returned values</tt>
<br><tt> - maxcount : IntegerType -- limit on 'count'</tt>
<br><tt> """</tt>
<br><tt> def __init__( self):</tt>
<br><tt> """</tt>
<br><tt> Effect:</tt>
<br><tt> Initialize self.maxcount to iphrase.nl.grammar.MaxAmbigSearchCount</tt>
<br><tt> """</tt>
<p><tt> def visited( self, frames1, frames2):</tt>
<br><tt> """</tt>
<br><tt> Effect:</tt>
<br><tt> Increment self.count by 1</tt>
<br><tt> Raise:</tt>
<br><tt> - StopRuleAmbiguity -- raised when
self.maxcount < self.count</tt>
<br><tt> Arguments:</tt>
<br><tt> - frames1:
ListType[ frame.frame] -- frame 1</tt>
<br><tt> - frames2:
ListType[ frame.frame] -- frame 2</tt>
<br><tt> """</tt>
<p><tt>class Grammar( UserDict):</tt>
<br><tt> """A Grammar instance is a dictinary of Rule instances</tt>
<p><tt> Attributes:</tt>
<br><tt> - package : Package -- root package defining
the grammar</tt>
<br><tt> - rootname : StringType -- root rule name</tt>
<br><tt> - name : StringType -- name of the root package
defining the grammar</tt>
<br><tt> - tree_dict : DicType[ StringType : ListType[
StringType]] --</tt>
<br><tt> rule tree from the root rule</tt>
<br><tt> - using : DicType[ StringType : DicType[StringType
: None]] --</tt>
<br><tt> lists of symbols used by any given
rule</tt>
<p><tt> Class Attributes:</tt>
<br><tt> - maxprunecount : IntegerType -- max pruning
count when</tt>
<br><tt> searching for ambiguity in
one Production</tt>
<br><tt> - maxpruningcoef : FloatType --</tt>
<br><tt> ratio between maxprunecount and
number of rules</tt>
<br><tt> - maxrecurselevel : IntegerType --</tt>
<br><tt> limit on the recursivity call for
ambiguities()</tt>
<br><tt> - maxruleamb : IntegerType --</tt>
<br><tt> limit on ambiguities detected on
any given Production</tt>
<br><tt> """</tt>
<p><tt> def __init__( self, package, rootname=None, lexicon=None):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - package : Package -- root package
defining the grammar</tt>
<br><tt> - rootname : StringType | None --
root rule name</tt>
<br><tt> (None will get iphrase.nl.grammar.defaultRootName,
e.g. '__parse')</tt>
<br><tt> - lexicon : None -- not implemented</tt>
<br><tt> """</tt>
<p><tt> def __getattr__( self, attr):</tt>
<br><tt> """Dynamic attributes:</tt>
<br><tt> - name</tt>
<br><tt> - data</tt>
<br><tt> - tree_dict</tt>
<br><tt> - using</tt>
<p><tt> Raise:</tt>
<br><tt> - GrammarError: raised when grammar
error detected</tt>
<br><tt> """</tt>
<p><tt> def save( self):</tt>
<br><tt> """save compiled grammar object for later reuse
(not implemented)</tt>
<br><tt> """</tt>
<br><tt> pass</tt>
<p><tt> def free_references( self):</tt>
<br><tt> """</tt>
<br><tt> Return:</tt>
<br><tt> ListType[ StringType] -- list of
references not not used by the root rule</tt>
<br><tt> """</tt>
<p><tt> def nodestempaths( self, production, nodeid=None):</tt>
<br><tt> """</tt>
<br><tt> Private --</tt>
<p><tt> Arguments:</tt>
<br><tt> - production : Production -- production
instance</tt>
<br><tt> - nodeid : IntegerType | None --</tt>
<br><tt> FSM node id (None indicates
the initial node)</tt>
<p><tt> Return:</tt>
<br><tt> - ListType[ frame.path] --</tt>
<br><tt> paths for each stems
reachable from the current node</tt>
<p><tt> Effect:</tt>
<br><tt> returned value is cached in the
'__fsmambdict' private</tt>
<br><tt> dictionary attribute.</tt>
<p><tt> Raise:</tt>
<br><tt> - GramamrError -- raised when grammar
error detected</tt>
<br><tt> """</tt>
<p><tt> def rulestempaths( self, rulename):</tt>
<br><tt> """</tt>
<br><tt> Private --</tt>
<p><tt> Arguments:</tt>
<br><tt> - rulename : StringType -- rule
name</tt>
<p><tt> Return:</tt>
<br><tt> - DicType[ StringType:ListType[
frame.path]]</tt>
<br><tt> -- dictionary of path
lists for each stem leaving 'rulename'</tt>
<p><tt> Effect:</tt>
<br><tt> Returned value is cached in the
'__ruleambdict' private</tt>
<br><tt> dictionary attribute.</tt>
<br><tt> """</tt>
<p><tt> def nextstempaths( self, stack):</tt>
<br><tt> """</tt>
<br><tt> Private --</tt>
<p><tt> Arguments:</tt>
<br><tt> - stack : frame.Stack -- current
stack</tt>
<br><tt> Return:</tt>
<br><tt> - DictType[ StringType : ListType[
frame.path] --</tt>
<br><tt> dictionary of path lists
for each departing stem</tt>
<br><tt> """</tt>
<p><tt> def ambiguities( self, frames1, frames2,</tt>
<br><tt>
ambiguousstacks, ambcontext, options,</tt>
<br><tt>
recurslevel=0):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - frames1 : ListType[ frame.frame]
-- path1</tt>
<br><tt> - frames2 : ListType[ frame.frame]
-- path2</tt>
<br><tt> - ambiguousstacks : DicType[ frame.StackPair]
--</tt>
<br><tt> dictionary of stack
pairs where ambiguity was detected</tt>
<br><tt> - ambcontext : AmbiguousContext
-- ambiguous context object</tt>
<br><tt> - options : IntegerType -- grammar
option flags</tt>
<br><tt> - recurselevel: IntegerType -- current
recursivity level</tt>
<p><tt> Return:</tt>
<br><tt> - DicType[ IntegerType : ListType[
(frame.frame, frame.frame)]] --</tt>
<br><tt> dictionary of pairs
of ambiguous frame lists with same score</tt>
<p><tt> Raise:</tt>
<br><tt> - StopRuleAmbiguity -- raised to
unwind current rule ambiguity search,</tt>
<br><tt> and pass to next rule</tt>
<br><tt> """</tt>
<p><tt> def visit( self, rulename, options):</tt>
<br><tt> """</tt>
<br><tt> Arguments:</tt>
<br><tt> - rulename : StringType -- rule
name</tt>
<br><tt> - options : IntegerType -- grammar
option flags</tt>
<p><tt> Effect:</tt>
<br><tt> visit rulename - look for ambiguities
starting from this rule</tt>
<br><tt> Ambiguous paths are reported using
frame.frames_publish_ambiguity()</tt>
<br><tt> """</tt>
<p><tt> def verify( self, options):</tt>
<br><tt> """Grammar verification routine</tt>
<p><tt> Arguments:</tt>
<br><tt> - options : IntegerType -- grammar
option flags</tt>
<br><tt> Raise:</tt>
<br><tt> - GrammarError: raised after grammar
errors have been detected</tt>
<br><tt> """</tt>
<br>
</body>
</html>
--------------AD5D43B3D93F8309E179B97F
Content-Type: text/html; charset=us-ascii;
name="doc-types.html"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="doc-types.html"
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Frederic Giacometti">
<meta name="GENERATOR" content="Mozilla/4.73 [en] (Windows NT 5.0; I) [Netscape]">
<title>types in Python documentation</title>
</head>
<body>
<h1>
Types</h1>
Types are considered in their broadest sense:
<ul>
<li>
the type of an object is:</li>
<ul>
<li>
its Python class if applicable (InstanceType other)</li>
<li>
its Python internal type, otherwise (ex: IntegerType...)</li>
</ul>
<li>
the notion of "<i>abstract type</i>" is considered which, in some sense,
corresponds to the interface concept in Java (see below)</li>
</ul>
<h2>
Derivability</h2>
We will say that an <i>object</i> is <i>derivable</i> from a <i>type</i>
when:
<ul>
<li>
the Python call <i>isinstance( object, type) </i>returns <i>true </i>(cf.
Python documentation)</li>
<li>
<i>type</i> is an abstract type and all its features (protocol...) are
implemented by <i>object</i></li>
</ul>
<h2>
Abstract types</h2>
The following types are defined in reference to Python's standard documentation:
<ul>
<li>
<b>Object</b> : Generic - represents any type</li>
<li>
<b>None</b> : the Python None type (actually, this is not an abstract type,
it is a particular case)</li>
<li>
<b>Boolean</b></li>
<li>
<b>Numeric</b></li>
<ul>
<li>
<b>Integer</b> : C long</li>
<li>
<b>UnlimitedInteger</b> : unlimited arithmetic precision</li>
<li>
<b>Float</b></li>
<li>
<b>Complex</b></li>
</ul>
<li>
<b>Sequence</b> : series or items, not editable; like a Python tuple</li>
<ul>
<li>
<b>String</b></li>
<li>
<b>Vector</b> : items can be modified, but length is fixed</li>
<ul>
<li>
<b>List</b> : variable length</li>
</ul>
</ul>
<li>
<b>Mapping</b> : not editable</li>
<ul>
<li>
<b>Dict</b> : editable</li>
</ul>
<li>
<b>Callable</b> : can be called like a regular function</li>
<li>
<b>Writable</b> : has a write( str) method, like the Python File objects</li>
<li>
<b>Comparable</b> : a <i>type</i> defined so that the <i>cmp()</i> Python
function defines a total order relation in the set of instances of this
<i>type</i>
- i.e., so that the sort() method can be applied with statisfaction over
Vectors of instances of this type</li>
<li>
<b>Hashable</b> : can be used as key to a dictionary (e.g. __hash__ and
__cmp__ methods adequately defined)</li>
<li>
...</li>
</ul>
<h2>
Compound types</h2>
The definition of types assembling other objects together can usually be
refined by further specifying the type of the assembled objects.
<p>Three most current cases are concerned:
<ul>
<li>
sequence types</li>
<li>
map types</li>
<li>
Python tuples with explicit items</li>
</ul>
<h3>
Sequence types</h3>
<i>Examples</i>:
<br>list of strings: <i><tt>Sequence[ String]</tt></i>
<br>2D matrix: <i><tt>Vector[ Vector[ Float]]</tt></i>
<br>
<h3>
Mapping types</h3>
<i>Examples</i>:
<br>string to string mapping: <i>Mapping[ String : String]</i>
<br>integer to list of stirngs mappting: <i>Mapping[ Integer : List[ String]]</i>
<br>the most generic mapping (default): <i>Mapping[ Hashable : Object]</i>
<h3>
Tuples with explicit items</h3>
<i>Examples</i>:
<br>integer pair: <i>(Integer, Integer)</i>
<br>integer - string - stem list triplet: (Stem is a class):<i> (Integer,
String, List[ Stem])</i>
<br>
</body>
</html>
--------------AD5D43B3D93F8309E179B97F--