Types

- name : type -- description

 tag, and to
> externalise the formatting into a css. That would allow people download
> the
> document and to muck about with the format to their heart's content.
> 
> But I'm actually thinking of going one step further, and keeping the
> master
> document in XML format (possibly using DocBook?) and transforming to HTML
> as
> required. And indeed into PDF using your own wonderful ReportLab tool.
> 
> But I don't know *anything* about this stuff - I've just bought 'XML in a
> Nutshell', so we'll see how I get on. But if anyone has any advice, don't
> be
> shy!

Any suggestions? In what format are the master versions of the Python
Documentation? Any good tools knocking around?

Cheers,
Simon Brunning
TriSystems Ltd.
sbrunning@trisystems.co.uk

-----------------------------------------------------------------------
The information in this email is confidential and may be legally privileged.
It is intended solely for the addressee. Access to this email by anyone else
is unauthorised. If you are not the intended recipient, any disclosure,
copying, distribution, or any action taken or omitted to be taken in
reliance on it, is prohibited and may be unlawful. TriSystems Ltd. cannot
accept liability for statements made which are clearly the senders own.

From fdrake@acm.org  Fri May 25 15:48:39 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 25 May 2001 10:48:39 -0400 (EDT)
Subject: [Doc-SIG] RE: Python 2.0 quick reference...
In-Reply-To: <31575A892FF6D1118F5800600846864D78BC8C@intrepid>
References: <31575A892FF6D1118F5800600846864D78BC8C@intrepid>
Message-ID: <15118.28871.146550.992383@cj42289-a.reston1.va.home.com>

Simon Brunning writes:
 > The new version of the Python Quick Reference is at
 > . It occurs to me that
 > members of this list would be best placed to advise me as to future
 > directions...

  I'm not sure what you mean by "future directions" -- changes in
organization? content?

 > > I'm not going to make any further changes to the 2.0 version, but I'm
 > > planning to extensively revamp the whole document for the 2.1 version. At
 > > very least, I'm going to get rid of nearly every  tag, and to
 > > externalise the formatting into a css. That would allow people download
 > > the
 > > document and to muck about with the format to their heart's content.

  I agree that moving the styling into CSS is a laudable goal, but I
don't think that means getting rid of PRE sections (assuming those are
code examples or interactive sessions).

 > > But I'm actually thinking of going one step further, and keeping the
 > > master
 > > document in XML format (possibly using DocBook?) and transforming to HTML
 > > as
 > > required. And indeed into PDF using your own wonderful ReportLab tool.
...
 > Any suggestions? In what format are the master versions of the Python
 > Documentation? Any good tools knocking around?

  The Python docs are in LaTeX using fairly extensive custom markup.
I don't expect that would be appropriate for the QuickRef, but perhaps
if you wrote it using the "howto" document class and formatted it to
use a single HTML page.  You'd also get PostScript and PDF formatting
for free that way.  Information on the LaTeX markup for Python
documentation is available at:

	http://www.python.org/doc/current/doc/doc.html

  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Digital Creations

From SBrunning@trisystems.co.uk  Fri May 25 16:02:15 2001
From: SBrunning@trisystems.co.uk (Simon Brunning)
Date: Fri, 25 May 2001 16:02:15 +0100
Subject: [Doc-SIG] RE: Python 2.0 quick reference...
Message-ID: <31575A892FF6D1118F5800600846864D78BC93@intrepid>

> From:	Fred L. Drake, Jr. [SMTP:fdrake@acm.org]
> Simon Brunning writes:
>  > The new version of the Python Quick Reference is at
>  > . It occurs to me
> that
>  > members of this list would be best placed to advise me as to future
>  > directions...
> 
>   I'm not sure what you mean by "future directions" -- changes in
> organization? content?

Changes in *format*. Hand coded HTML is liable to get messy, especially when
passed from hand to hand. The Quick Reference as it stands is a perfect
example of this! I'm looking for a better format to keep the master version
of the quick reference in.

>  I agree that moving the styling into CSS is a laudable goal, but I
> don't think that means getting rid of PRE sections (assuming those are
> code examples or interactive sessions).

I don't have a problem with the  sections used for code examples and so
on. But the tag is used extensively as a way of presenting *tabular* data.
'Real' tables using the  tag are *much* easier to work with
programmatically.

>  The Python docs are in LaTeX using fairly extensive custom markup.
> I don't expect that would be appropriate for the QuickRef, but perhaps
> if you wrote it using the "howto" document class and formatted it to
> use a single HTML page.  You'd also get PostScript and PDF formatting
> for free that way.  Information on the LaTeX markup for Python
> documentation is available at:
> 
> 	http://www.python.org/doc/current/doc/doc.html

Doh!  Thanks, Fred, for being too kind to tell me to RTFM. But
that's what I'll do!

Cheers,
Simon Brunning
TriSystems Ltd.
sbrunning@trisystems.co.uk

-----------------------------------------------------------------------
The information in this email is confidential and may be legally privileged.
It is intended solely for the addressee. Access to this email by anyone else
is unauthorised. If you are not the intended recipient, any disclosure,
copying, distribution, or any action taken or omitted to be taken in
reliance on it, is prohibited and may be unlawful. TriSystems Ltd. cannot
accept liability for statements made which are clearly the senders own.

From fdrake@acm.org  Fri May 25 16:17:13 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 25 May 2001 11:17:13 -0400 (EDT)
Subject: [Doc-SIG] RE: Python 2.0 quick reference...
In-Reply-To: <31575A892FF6D1118F5800600846864D78BC93@intrepid>
References: <31575A892FF6D1118F5800600846864D78BC93@intrepid>
Message-ID: <15118.30585.817850.810408@cj42289-a.reston1.va.home.com>

Simon Brunning writes:
 > Changes in *format*. Hand coded HTML is liable to get messy, especially when
 > passed from hand to hand. The Quick Reference as it stands is a perfect
 > example of this! I'm looking for a better format to keep the master version
 > of the quick reference in.

  Considering the document is fairly short, HTML doesn't seem too bad,
but some XML-based solution might be a little easier to maintain, and
use an XSLT stylesheet to convert to HTML.  A separate CSS stylesheet
can then be used to fine-tune little things like colors, font, etc.
Things like bold, italic, and code should be generated by the XSLT so
even older browsers that don't do well with CSS can handle the result.

 > on. But the tag is used extensively as a way of presenting *tabular* data.
 > 'Real' tables using the  tag are *much* easier to work with
 > programmatically.

  Agreed.  And they are more susceptible to styling from CSS as well,
which is nice.

 > Doh!  Thanks, Fred, for being too kind to tell me to RTFM. But
 > that's what I'll do!

  Don't worry; that's not the first reference to that document I've
handed out in the last 24 hours!

  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Digital Creations

From frederic.giacometti@arakne.com  Wed May 30 01:33:47 2001
From: frederic.giacometti@arakne.com (Frederic Giacometti)
Date: Tue, 29 May 2001 20:33:47 -0400
Subject: [Doc-SIG] documenting Python constraints on types
References: 
Message-ID: <3B143FEB.F6FCC264@arakne.com>

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 <> 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"

   iPhrase Python documentation conventions

Python Documentation Strings
Python attaches documentation strings to every:

module

function

method

class

In Python, these strings are defined as the first element within the local
scope of the object documented.

Similar strings can also be defined in the C/C++ Python extensions.

The following formalism is designed to:

enhance readability by providing a documentation language common to everybody

provide a support facilitating complete documentation/specification while
keeping verbosity at a minimum

enable the use of documentation extraction tools

Summary
module:
Public:
- name : type -- description

function and method:
Arguments:
- name : type [|type] [input|update] -- description [--
constraint: ...]
Keyword Arguments:
- name : type|type [= default_value] -- description [--
constraint: ...]
Return:
- type [|type] -- description
Effect:
description
Raise:
- type -- description

    argument section

method:
Private --
class:
Attributes:

- name : type -- description
Class Attributes:
- name : type -- description

Other section titles:
Usage:

Generic format
Documentation strings are defined as plain ASCII text.

This text is composed as follows:

The first line is the descriptive title to be used in the object in documentation
summaries

Any number of sections (see below)

Descriptive text (object intent, particular references...)

Section
A section is defined as:

a section title, defined as a one-word section title, followed with a column
(e.g.: 'Arguments:')

indented text

A section can contain other sections, with propoer indentation (the Emacs
Python mode will automatically maintain indentation).

Module

Public
The module documentation will defined the published and exportable symbols
(section name: 'Public:'). A module documentation will allways
have a Public section.
Only symbols listed in the Public section can be referred or
imported from other modules.

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:
- name : type -- description
Publication of imported classes and functions
Whenever possible, the origin of public imported objects should be documented.

Example
"""Grammar class and related definitions
Public:

    Grammar : ClassType -- imported from iphrase.nl.grammar.model

    MaxXXX : IntegerType -- max value for XXX
Usage:

    Cf. Grammar class documentation

"""

Functions and Methods

Arguments
Function and method arguments are documented in the 'Argument:'
section.
Each entry of the Arguments section is of the form:
- name : type [|type] [input|update] -- description [--
constraint: ...]
where

name is the argument name

type 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. Sequence[ StringType] for a sequence of strings,
Dict[
StringType : iphrase.nl.parser.parser.FSMType] for a dictionary of
FSM objects indexed with strings).

input or update explicitely specifies that the argument will
not be modified (input), or it is expected to be modified (update). [Note:
in the case of complex objects, we will consider modification by direct
effect in the function code only.]

description decribe the argument purpose and role

the constraint phrase will explicit any constraint on the argument
value (e.g.: positive, not null ...).

Notes:

Do not document the 'self' argument of a method

Do not document the return value of the __init__ methods

....

Keyword Arguments
The 'Keyword Arguments:' section describe keyword arguments of
a function.
- name : type|type [= default_value] -- description [--
constraint: ...]

Return
In Python, when no return statement is executed, the None
value is returned.

In other cases, one or more (tuple) values are returned.

The Return: section will describe the type and value of the
one or many values returned.

For each entry, the format is of the form:
- type [|type] -- description

Effect
Actions of the function persisting beyond the function call (e.g.: side
effects...) are described in the Effect: section (free text).

Raise
The Raise: section is used to document exceptions of a particular
interest which can be raised.
The format of each entry is as:
- type -- description

    argument section
Examples:
    def someMethod( self, names, options=0):

        """sample method
        Arguments:

- names : ListType[ StringType] -- list of names

- options : IntegerType -- options flags (cf. ....)
        Effect:

update 'names'
        Return:

- IntegerType -- number of new elements in 'names'

- IntegerType -- number of elements removed from 'names'
        Raise:

- CustomError -- custom error condition detected

        """
def someFunction( *args, **kw):

    """sample function
    Arguments:

        - args : TupleType --
description...
    Keyword Arguments :

        - names : sequence[
StringType] = [] -- list of marked names

        - color : StringType
= 'green' -- background color
    Effect:

        update the upper window

    """

Methods

Private
Some methods are used for development purposeonly, and are not bound to
be reused.

Such methods will be labeled with the definition of a Private -
section.
Example
    def privateMethod( self):

        """sample private method

        Private --
        Return:

TupleType[ TupleType[ IntegerType] -- normalized matrix

        """

Class

Attributes
Locally-defined instance attributes are described in the Attributes:
section.

The format of each entry is as:
- name : type -- description

Class Attributes
Locally-defined instance attributes are described in the Class Attributes:
section.

The format of each entry is as:
- name : type -- description

__getattr__ and __setattr__ special methods
Names or categories of attributes with special treatement (ex: dynamically
defined attributes) will be listed in the documentation of the __getattr__
and __setattr__ special methods.
Example
class sampleClass( UserList):

    """sample class
    Attributes:

        dependents : MappingType[
ListType[ Symbol]] -- symbols dependency graph

        timeStamp : IntegerType
-- current time stamp
    Usage:

        sampleClass is a list
of otherClass objects.

        ...

    """

Other Possible Types of Section

Usage
Usage information (use case, example, hints...) is strongly encouraged
in the documentation.

It will be documented in the Usage: section.

Documentation strings in C/C++

Module
The __doc__ string must be defined in the module dictionary; its
format
This is done by adding the following code in the XXX module initialization
function:
void initXXX( void)

{

    PyObject* module, *docstring;
    module = Py_InitModule( "XXX", XXX_methods);
    docstring = PyString_FromString( "module short
description

Public:

    - yyyType : TypeType -- yyy extenstion type

    ...

");

    PyObject_SetAttrString( module, "__doc__",
docstring);

    Py_DECREF( docstring);

    ....

}

Functions and Methods
The fourth field of the PyMethodDef structure (used to define
Python methods and functions) defines the documentation string, and should
always be initialized.
The function or method definition is explicited in the first line of
the string, exactly as it would be defined in Python.

The remaining of the string follows the same documentation format as
in Python.
Example:
static PyMethodDef XXX_methods =

{

    { XXX_yyy_create, "yyy", METH_VARARGS,

      "def yyy( arg1, arg2, arg3=None)

Arguments:

    - arg1 : IntegerType -- ...

    ...

Return:

    - XXX.yyyType -- new yyy object

"},

    ...

};

Examples

iphrase.nl.grammar (extracted from iphrase/nl/grammar/__init__.py stripped
from source code)

"""Grammar Tools Module
Public:
  - Package : ClassType -- class iphrase.nl.grammar.package.Package
  - Grammar : ClassType -- class iphrase.nl.grammar.Grammar
  - defaultRootName : StringType -- default root rule name
  - maxframes : IntegerType --

    limit on number of frames for an ambiguity search
path
  - MaxAmbigSearchCount : IntegerType --

    limit of ambiguities retrieved in an ambiguity
search
Option flags that can be OR'd in an integer variable:
  - VERIFY_GET_UNUSED -- will check of unused rules
  - AMBIG_PRUNE_MARKED -- will not visit marked objexts
  - VERIFY_AMBIGUITY -- do ambiguity search
  - SEARCH_PRODUCTIONS -- search for production mode
  - SEARCH_RULES -- search for rules mode
  - SEARCH_USING -- search for under rule constraint
  - VISIT_NODEPTH -- do not visit sub rules
  - GRAM_SAVE -- save compiled grammar for later reuse
  - MODE_VERBOSE -- verbose mode enabled

"""
class GrammarError( StandardError):

  """Abstract class for grammar errors
  Attributes:

    msg : StringType -- message text

    errorvalue : Object -- arbitrary object attached
to the error

  """
  def __init__( self, msg, errorvalue=None):

    """

    Arguments:

       msg : StringType -- set msg
attribute

       errorvalue : Object -- set
errorvalue attribute

    """
  def __repr__( self):

    """

    Return:

      - StringType : 'self.msg: self.errorvalue'

    """
  def __str__( self):

    """

    Return:

      - StringType : 'self.msg: self.errorvalue'

    """
class GrammarListError( UserList, GrammarError):

  """Mechanism for collecting GrammarError exceptions up to
Maxitems
  Class Attributes:

    - Maxitems : IntegerType --

      max number of items collected; default
is 0x10000

  """
  def __init__( self, lst=[]):

    """

    Arguments:

      - lst : ListType[ GrammarError]
-- initial list of errors

    """
  def __repr__( self):

    """

    Return:

      StringType -- formatted list of
errors

    """
  def __str__( self):

    """

    Return:

      StringType -- formatted list of
errors

    """
  def append( self, item):

    """

    Arguments:

      - item : GrammarError -- error to
append
    Raise

      - self -- self will be raised when
self.MaxItems <= len( self)

    """

iphrase.nl.grammar.model (iphrase/nl/grammar/model.py stripped from source
code)
"""Grammar class and immediately connected structures
Public:
  - anglerules : TupleType[ StringType] --  angle symbols
refering a rule
  - hardcodedrules : TupleType[ StringType] --

    non-terminal symbols for which a default rule
is defined
  - trace : IntegerType -- trace level; default is 0

"""
class MultiplyIncludedError( GrammarError):

  """error raised when a package is detected to be included
more than once

  """

  def __init__( self, name):

    """

    Arguments:

      - name : StringType -- name of the
faulting package

    """
class CycleError( GrammarError):

  """error raised when rule cycle detected

  """
  def __init__( self, rulename, path):

    """

    Arguments:

      - rulename : StringType -- name
of cycling rule

      - path : sequence[ Productions]
--

        sequence of Production
objects occuring in the cycle

    """
  def __repr__( self):

    """

    Return:

      - StringType -- formated message

    """
class UndefinedReferenceError( GrammarError):

  """error raised when detecting an undefined rulename

  Attributes:

    - refname : StringType -- faulting reference

    - path : sequence[ Productions] --

      sequence of Production objects leading
to the undefined reference

  """
  def __init__( self, refname, path):

    """

    Arguments:

      - refname : StringType -- faulting
reference

      - path : sequence[ Productions]
--

        sequence of Production
objects leading to the undefined reference

    """
  def __str__( self):

    """

    Return:

      - StringType : formatted message
with all path elements

    """
  def __repr__( self):

    """

    Return:

      - StringType : formatted message
with faulting production

    """
class FsmError( GrammarError):

  """abstract class for FSM-related errors

  """

  def __init__( self, msg, path, fsmkey):

    """

    Arguments:

      - msg : StringType  -- companion
message

      - path : sequence[Production] --
current hops sequence

    """
class EmptyFsmError( FsmError):

  """error raised when detecting an expression FSM node simultanously

  initial and final

  """

  def __init__( self, path, fsmkey):

    """

    Arguments:

      - path : sequence[Production] --
current hops sequence

      - fsmkey : Production --

        Production object associated
to the faulting FSM

    """
class AmbiguousFinalFsmError( FsmError):

  """error raised when detecting ambiguity associated to final
states

  """

  def __init__( self, path, fsmkey):

    """

    Arguments:

      - path : sequence[Production] --
current hops sequence

      - fsmkey : Production -- Production
object associated to the faulting FSM

    """
class UnboundProduction:

  """Production without package context
  Attributes:

    - name : StringType -- rule name

    - expression : Expression -- expression (right-hand
side)

    - comment : StringType | None -- optional comment
text
  Class Attributes:

    - alllowercase : IntegerType

      -- boolean indicating conversion
of all grammar definition to lower case;

         default is 1

  """
  def __init__( self, name, expression, comment=None):

    """

    Arguments:

      - name : StringType -- rule name

      - expression : StringType -- expression
text

      - comment : StringType | None --
optional comment text
    Raise:

      - GrammarError --

        raised with adequate
message when illegal values detected

    """
  def __repr__( self):

    """

    Return:

      - StringType -- production formatted
in cfg grammar format

    """
  def __cmp__( self, other):

    """

    Return:

      - IntegerType -- comparaison first
on rule name, then on expression

    """
class Production( UnboundProduction, package.Bound):

  """Production with package context

  """
  def __init__( self, name, expression, comment, packageName,
lineno):

    """

    Arguments:

      - name : StringType -- rule name

      - expression : StringType -- expression
text

      - comment : StringType | None --
comment text

      - packageName : StringType -- package
name

      - lineno : IntegerType -- position
    Raise:

      - package.PackageError --

        GrammarError caught
are replaced with PackageError exceptions
        Arguments:

          - GrammarError
-- keep current exception value

          - StringType
-- 'packageName' arg

          - IntegerType
-- 'lineno' arg

    """
  def __repr__( self):

    """

    Return:

      - StringType -- packageName:lineno
+ formatted production

    """
  def __hash__( self):

    """

    Return:

      - IntegerType -- hashing on in-memory
unique object id

    """
  def __cmp__( self, other):

    """

    Argument:

      - other : Production -- right side
of the comparison pair

    Return:

      - IntegerType -- comparison on object
id's

    """
  def __copy__( self):

    """Will always raise RuntimeError exception

    Raise:

      - RuntimeError -- Production objects
must remain unique in memory

        Arguments:

          - StringType
-- errormessage

    """
class Rule( UserList):

  """A rule instance is a list of Productions referring to
a same rule name

  Attributes:

    - name : StringType -- rule name

    - prods : ListType -- list of productions at
creation time

  """
  def __init__( self, name, prods=[]):

    """

    Arguments:

      - name : StringType -- rule name

      - prods : ListType -- list of productions
at creation time

    """
class StopRuleAmbiguity( Exception):

  """used to stop ambiguity search on current rule, and pass
to the next rule

  """
class AmbiguousContext:

  """used in argument Grammar.ambiguities() argument list

  Attributes:

    - count : IntegerType -- number of times ambiguities()
has returned values

    - maxcount : IntegerType -- limit on 'count'

  """

  def __init__( self):

    """

    Effect:

      Initialize self.maxcount to iphrase.nl.grammar.MaxAmbigSearchCount

    """
  def visited( self, frames1, frames2):

    """

    Effect:

      Increment self.count by 1

    Raise:

      - StopRuleAmbiguity -- raised when
self.maxcount < self.count

        Arguments:

          - frames1:
ListType[ frame.frame] -- frame 1

          - frames2:
ListType[ frame.frame] -- frame 2

    """
class Grammar( UserDict):

  """A Grammar instance is a dictinary of Rule instances
  Attributes:

    - package : Package -- root package defining
the grammar

    - rootname : StringType -- root rule name

    - name : StringType -- name of the root package
defining the grammar

    - tree_dict : DicType[ StringType : ListType[
StringType]] --

      rule tree from the root rule

    - using : DicType[ StringType : DicType[StringType
: None]] --

      lists of symbols used by any given
rule
  Class Attributes:

    - maxprunecount : IntegerType -- max pruning
count when

       searching for ambiguity in
one Production

    - maxpruningcoef : FloatType --

      ratio between maxprunecount and
number of rules

    - maxrecurselevel : IntegerType --

      limit on the recursivity call for
ambiguities()

    - maxruleamb : IntegerType --

      limit on ambiguities detected on
any given Production

  """
  def __init__( self, package, rootname=None, lexicon=None):

    """

    Arguments:

      - package : Package -- root package
defining the grammar

      - rootname : StringType | None --
root rule name

        (None will get iphrase.nl.grammar.defaultRootName,
e.g. '__parse')

      - lexicon : None -- not implemented

    """
  def __getattr__( self, attr):

    """Dynamic attributes:

      - name

      - data

      - tree_dict

      - using
    Raise:

      - GrammarError: raised when grammar
error detected

    """
  def save( self):

    """save compiled grammar object for later reuse
(not implemented)

    """

    pass
  def free_references( self):

    """

    Return:

      ListType[ StringType] -- list of
references not not used by the root rule

    """
  def nodestempaths( self, production, nodeid=None):

    """

    Private --
    Arguments:

      - production : Production -- production
instance

      - nodeid : IntegerType | None --

        FSM node id (None indicates
the initial node)
    Return:

      - ListType[ frame.path] --

        paths for each stems
reachable from the current node
    Effect:

      returned value is cached in the
'__fsmambdict' private

      dictionary attribute.
    Raise:

      - GramamrError -- raised when grammar
error detected

    """
  def rulestempaths( self, rulename):

    """

    Private --
    Arguments:

      - rulename : StringType -- rule
name
    Return:

      - DicType[ StringType:ListType[
frame.path]]

        -- dictionary of path
lists for each stem leaving 'rulename'
    Effect:

      Returned value is cached in the
'__ruleambdict' private

      dictionary attribute.

    """
  def nextstempaths( self, stack):

    """

    Private --
    Arguments:

      - stack : frame.Stack -- current
stack

    Return:

      - DictType[ StringType : ListType[
frame.path] --

        dictionary of path lists
for each departing stem

    """
  def ambiguities( self, frames1, frames2,

ambiguousstacks, ambcontext, options,

recurslevel=0):

    """

    Arguments:

      - frames1 : ListType[ frame.frame]
-- path1

      - frames2 : ListType[ frame.frame]
-- path2

      - ambiguousstacks : DicType[ frame.StackPair]
--

        dictionary of stack
pairs where ambiguity was detected

      - ambcontext : AmbiguousContext
-- ambiguous context object

      - options : IntegerType -- grammar
option flags

      - recurselevel: IntegerType -- current
recursivity level
    Return:

      - DicType[ IntegerType : ListType[
(frame.frame, frame.frame)]] --

        dictionary of pairs
of ambiguous frame lists with same score
    Raise:

      - StopRuleAmbiguity -- raised to
unwind current rule ambiguity search,

        and pass to next rule

    """
  def visit( self, rulename, options):

    """

    Arguments:

      - rulename : StringType -- rule
name

      - options : IntegerType -- grammar
option flags
    Effect:

      visit rulename - look for ambiguities
starting from this rule

      Ambiguous paths are reported using
frame.frames_publish_ambiguity()

    """
  def verify( self, options):

    """Grammar verification routine
    Arguments:

      - options : IntegerType -- grammar
option flags

    Raise:

      - GrammarError: raised after grammar
errors have been detected

    """

--------------AD5D43B3D93F8309E179B97F
Content-Type: text/html; charset=us-ascii;
 name="doc-types.html"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="doc-types.html"

   types in Python documentation

Types
Types are considered in their broadest sense:

the type of an object is:

its Python class if applicable (InstanceType other)

its Python internal type, otherwise (ex: IntegerType...)

the notion of "abstract type" is considered which, in some sense,
corresponds to the interface concept in Java (see below)

Derivability
We will say that an object is derivable from a type
when:

the Python call isinstance( object, type) returns true (cf.
Python documentation)

type is an abstract type and all its features (protocol...) are
implemented by object

Abstract types
The following types are defined in reference to Python's standard documentation:

Object : Generic - represents any type

None : the Python None type (actually, this is not an abstract type,
it is a particular case)

Boolean

Numeric

Integer : C long

UnlimitedInteger : unlimited arithmetic precision

Float

Complex

Sequence : series or items, not editable; like a Python tuple

String

Vector : items can be modified, but length is fixed

List : variable length

Mapping : not editable

Dict : editable

Callable : can be called like a regular function

Writable : has a write( str) method, like the Python File objects

Comparable : a type defined so that the cmp() Python
function defines a total order relation in the set of instances of this
type
- i.e., so that the sort() method can be applied with statisfaction over
Vectors of instances of this type

Hashable : can be used as key to a dictionary (e.g. __hash__ and
__cmp__ methods adequately defined)

...

Compound types
The definition of types assembling other objects together can usually be
refined by further specifying the type of the assembled objects.
Three most current cases are concerned:

sequence types

map types

Python tuples with explicit items

Sequence types
Examples:

list of strings: Sequence[ String]

2D matrix: Vector[ Vector[ Float]]

Mapping types
Examples:

string to string mapping: Mapping[ String : String]

integer to list of stirngs mappting: Mapping[ Integer : List[ String]]

the most generic mapping (default): Mapping[ Hashable : Object]

Tuples with explicit items
Examples:

integer pair: (Integer, Integer)

integer - string - stem list triplet: (Stem is a class): (Integer,
String, List[ Stem])

--------------AD5D43B3D93F8309E179B97F--

From fdrake@cj42289-a.reston1.va.home.com  Wed May 30 06:31:01 2001
From: fdrake@cj42289-a.reston1.va.home.com (Fred Drake)
Date: Wed, 30 May 2001 01:31:01 -0400 (EDT)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20010530053101.4985F28A10@cj42289-a.reston1.va.home.com>

The development version of the documentation has been updated:

	http://python.sourceforge.net/devel-docs/

Incremental update for development version of Python (2.2).

Mostly small updates, but I've worked on new markup for grammar
productions used in the Reference Manual.  Currently, only the lexical
productions in Chapter 2 of the manual have been converted to the new
markup and layout.  Please take a look and send comments to
doc-sig@python.org; the first page containing these changes is at:

    http://python.sourceforge.net/devel-docs/ref/identifiers.html

The changes needed to implement the markup have not been checked in
yet, and there are some bugs in the implementation (both for HTML and
PDF), but this should make the productions easier to navigate.

I've tested the HTML version on Linux only with Mozilla 0.9, Opera
5.0b8, and Netscape Navigator 4.77.  Navigator is definately lagging
behind in CSS support!

Also added Michel Pelletier's documentation for the HTMLParser module,
with some small changes.

From tim.one@home.com  Wed May 30 06:51:04 2001
From: tim.one@home.com (Tim Peters)
Date: Wed, 30 May 2001 01:51:04 -0400
Subject: [Doc-SIG] [development doc updates]
In-Reply-To: <20010530053101.4985F28A10@cj42289-a.reston1.va.home.com>
Message-ID: 

[Fred Drake]
> The development version of the documentation has been updated:
>
> 	http://python.sourceforge.net/devel-docs/
>
> Incremental update for development version of Python (2.2).
>
> Mostly small updates, but I've worked on new markup for grammar
> productions used in the Reference Manual.  Currently, only the lexical
> productions in Chapter 2 of the manual have been converted to the new
> markup and layout.  Please take a look and send comments to
> doc-sig@python.org; the first page containing these changes is at:
>
>     http://python.sourceforge.net/devel-docs/ref/identifiers.html
>
> The changes needed to implement the markup have not been checked in
> yet, and there are some bugs in the implementation (both for HTML and
> PDF), but this should make the productions easier to navigate.

Let me suggest starting with

    http://python.sourceforge.net/devel-docs/ref/integers.html

instead, and clicking on "digit" in the "hexdigit" production.  The problem
with the originally suggested page is that all the links point into the same
paragraph, so "nothing happens" when you click one.  But "digit" was the
cause of a bogus bug report, as the submitter didn't realize "digit" had
been defined earlier in the docs, and without something like these mondo
cool new links it's almost impossible to find cross-section production
definitions.

Stumbled into one glitch:  nonzerodigit doesn't resolve correctly; the
node24.html page it refers to doesn't seem to exist.

From fdrake@acm.org  Wed May 30 06:53:23 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 30 May 2001 01:53:23 -0400 (EDT)
Subject: [Python-Dev] RE: [Doc-SIG] [development doc updates]
In-Reply-To: 
References: <20010530053101.4985F28A10@cj42289-a.reston1.va.home.com>

Message-ID: <15124.35539.53551.52668@cj42289-a.reston1.va.home.com>

Tim Peters writes:
 > Stumbled into one glitch:  nonzerodigit doesn't resolve correctly; the
 > node24.html page it refers to doesn't seem to exist.

  That was the bug alluded to.  The digit* grouped with the
nonzerodigit also doesn't work, although the other two uses of digit
on that page (floating.html) work properly.  I'll investigate
tomorrow; just too tired tonight.

  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Digital Creations

From fdrake@acm.org  Wed May 30 16:44:40 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 30 May 2001 11:44:40 -0400 (EDT)
Subject: [Doc-SIG] documenting Python constraints on types
In-Reply-To: <3B143FEB.F6FCC264@arakne.com>
References: 
 <3B143FEB.F6FCC264@arakne.com>
Message-ID: <15125.5480.380570.78206@cj42289-a.reston1.va.home.com>

Frederic Giacometti writes:
 > - 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".

  I don't think that's quite it, though it certainly has an affect on
the interest in documenting the types.  Part of the lack of type
information is a matter of there not being a shared set of names for
abstract types that is also sufficient to be precise.  (For example:
What does it mean for an object to be a "mapping"?  Perhaps has_key()
is sufficient in one context, but get() and setdefault() are needed in
another.)  In practice, documenting the input types for highly
polymorphic code can be tedious, which certainly cuts down on the ease
of writing documentation which is useful, specific, and better than
just reading the sources.

[From the C/C++ example in the first document...]
 > void initXXX(void)
 > {
 >     PyObject* module, *docstring;
 >     module = Py_InitModule("XXX", XXX_methods);
 >     docstring = PyString_FromString("module short description
 > Public:
 >     - yyyType : TypeType -- yyy extenstion type
 >     ...
 > ");
 >     PyObject_SetAttrString(module, "__doc__", docstring);
 >     Py_DECREF(docstring);

  It's much easier to use Py_InitModule3():

void initXXX(void) {
    PyObject* module;

    module = Py_InitModule3("XXX", XXX_methods
                            "module short description
Public:
    - yyyType : TypeType -- yyy extenstion type
    ...
");

  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Digital Creations

From frederic.giacometti@arakne.com  Wed May 30 18:56:07 2001
From: frederic.giacometti@arakne.com (Frederic Giacometti)
Date: Wed, 30 May 2001 13:56:07 -0400
Subject: [Doc-SIG] Re: documenting Python constraints on types
References: 
 <3B143FEB.F6FCC264@arakne.com> <15125.5480.380570.78206@cj42289-a.reston1.va.home.com>
Message-ID: <3B153436.EB8FAECE@arakne.com>

"Fred L. Drake, Jr." wrote:

> Frederic Giacometti writes:
>  > - 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".
>
>   I don't think that's quite it, though it certainly has an affect on
> the interest in documenting the types.  Part of the lack of type
> information is a matter of there not being a shared set of names for
> abstract types that is also sufficient to be precise.  (For example:
> What does it mean for an object to be a "mapping"?  Perhaps has_key()
> is sufficient in one context, but get() and setdefault() are needed in
> another.)

A 'mapping' is an object that 'implements' the object protocol
(PyMapping_Check()... ok).
I think that everybody's interessest is in working for a small set of
standard interface definitions.
At most, one could work with 'writable and 'read-only maps. This should
cover 98% of the needs (for the 2% remaining, one can always afford
verbosity and extra documentation effort...).

In this case, has_key() and get() would be part for a minimal set of
services provided by read-only map objects that declare conformity with
the 'read-only' map protocol.

> In practice, documenting the input types for highly
> polymorphic code can be tedious, which certainly cuts down on the ease
> of writing documentation which is useful, specific, and better than
> just reading the sources.

Yes. This is why I had the following in mind when writing the
documentation guidelines 6 months ago:
- simplicity
- small
- 80/20-type solution (i.e.: covers most needs at a least effort)

Some guys I worked with even wrote their custom emacs macro that would
automatically insert a definition template each time they created a new
module, class, function, or method :)))
Documenting from templates then becomes fairly straightforward.

>
>   It's much easier to use Py_InitModule3():

Thanks for the hint; these seem like recently-introduced functions.

Frederic Giacometti

PS:
[This is outside the topic of the doc/type group, but since I'm on it...]

About Py_InitModule4():
What would be expected is the ability to pass the module object at the
'self' argument to the methods; unfortunately this is not possible with
Py_InitModule4(). On the other hand setting 'self' to an object other than
the module open the door to inconsistant (i.e. bug prone) behavior, when
for instance applying setattr() / getattr() to 'self'...

Instead, a function like
"PyObject* Py_InitModuleType( PyType* typedefinition)"
would replace Py_InitModule[34]() while providing the ability to define
full object capability on the module object, homogeneously with the Python
type extension practice....
(If somebody wants to make a PEP titled "Providing module objects with
full object service...").
By default of such a capability, I usually add artificially an type with a
single instance and tie this up together in a wrapping Python source
module.
The extended capability would dispense these 'dirty' tricks.

From fdrake@cj42289-a.reston1.va.home.com  Wed May 30 22:51:22 2001
From: fdrake@cj42289-a.reston1.va.home.com (Fred Drake)
Date: Wed, 30 May 2001 17:51:22 -0400 (EDT)
Subject: [Doc-SIG] [development doc updates]
Message-ID: <20010530215122.3738C28849@cj42289-a.reston1.va.home.com>

The development version of the documentation has been updated:

    http://python.sourceforge.net/devel-docs/

Update for development version of Python (2.2).

This update substantially re-works the prototype support for
productions of a formal grammar.  They look better, support forward
references to symbol definitions, and allow download of an all-text
version of the complete grammar (with productions ordered the same way
as they are in the documentation sources).

"Documeting Python" now includes documentation for the LaTeX markup
used to describe productions:

    http://python.sourceforge.net/devel-docs/doc/grammar-displays.html

From fdrake@acm.org  Wed May 30 23:00:15 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 30 May 2001 18:00:15 -0400 (EDT)
Subject: [Doc-SIG] Most recent documentation update
Message-ID: <15125.28015.611763.968854@cj42289-a.reston1.va.home.com>

  One thing I forgot to mention in my announcement of the update to
the development documnetation which I just posted is that I went ahead
and converted all but one of the productions in the Reference Manual
to the new markup.  The print_stmt production, unfortunately, is given
twice instead of using a single model for the statement.  The
formatting tools don't support that (yet), and it's not clear that
they should.
  (No, Barry, don't go changing it...!)

  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Digital Creations

From barry@digicool.com  Wed May 30 23:05:37 2001
From: barry@digicool.com (Barry A. Warsaw)
Date: Wed, 30 May 2001 18:05:37 -0400
Subject: [Doc-SIG] Re: [Python-Dev] Most recent documentation update
References: <15125.28015.611763.968854@cj42289-a.reston1.va.home.com>
Message-ID: <15125.28337.938136.505675@anthem.wooz.org>

>>>>> "Fred" == Fred L Drake, Jr  writes:

    Fred> (No, Barry, don't go changing it...!)

Oh darn, three whole days work wasted...

:)

Python Documentation Strings

Summary

Generic format

Section

Module

Public

Functions and Methods

Arguments

Keyword Arguments

Return

Effect

Raise

Methods

Private

Class

Attributes

Class Attributes

getattr and setattr special methods

Other Possible Types of Section

Usage

Documentation strings in C/C++

Module

Functions and Methods

Examples

iphrase.nl.grammar (extracted from iphrase/nl/grammar/init.py stripped from source code)

iphrase.nl.grammar.model (iphrase/nl/grammar/model.py stripped from source code)

Types

Derivability

Abstract types

Compound types

Sequence types

Mapping types

Tuples with explicit items

Python Documentation Strings

Summary

Generic format

Section

Module

Public

Functions and Methods

Arguments

Keyword Arguments

Return

Effect

Raise

Methods

Private

Class

Attributes

Class Attributes

__getattr__ and __setattr__ special methods

Other Possible Types of Section

Usage

Documentation strings in C/C++

Module

Functions and Methods

Examples

iphrase.nl.grammar (extracted from iphrase/nl/grammar/__init__.py stripped from source code)

iphrase.nl.grammar.model (iphrase/nl/grammar/model.py stripped from source code)

Types

Derivability

Abstract types

Compound types

Sequence types

Mapping types

Tuples with explicit items

getattr and setattr special methods

iphrase.nl.grammar (extracted from iphrase/nl/grammar/init.py stripped from source code)