[Zope3-dev] Re: [Method specification] (new)

[Larry Maccherone]

The text says that the third parameter is not required but wouldn't that call for a "z.required = False"?
 
Also, you mention that "[t]his is the Nevow style of parameter definition."  Is there a relationship betweent you (as an individual or as Mr. Zope) to Nevow or do you just like the idea?  Nevow is a part of the div-mod package built on twisted right?

jim <zope3-dev at zope.org> wrote:
Status: IsDraftProposal

Author

JimFulton

Problem

Currently, interface method descriptions carry very little useful
information. The only information beyond standard attribute
information is a signature string.

Richer information about methods, especially parameters and return
values would provide a number of benefits:

- Provide more formal, and thus consistent, mehod documentation

- Make it easier to implement statically-typed RPC mechansisms, such
as WSDL

- Make certain types of introspection, such as:
http://dev.zope.org/Zope3/ContainmentConstraints

Proposal

Extend standard method meta data to include parameters and return
values. (Note that, to reduce the scope of this proposal,
preconditions and postconditions are excluded. It would, of course,
be interesting to model these in the future.)

This proposal builds on SpecificationUnification.

Methods will grow the following attributes:

- 'parameters', a tuple of parameter specifications

- 'returns', a return-value specification

When a python function is adapted to a method specification, the
function will be called, passing parameter objects. The function can
set attributes on the paramter objects to refine parameter
specifications.

Let's look at an example:

def foo(x, y, z=None):
x.type = zope.schema.Int(min=1, max=10)
y.type = IFoo
y.keyword = True
z.type = float
z.keyword = True
return IBar

In this example, the function 'foo' takes 3 parameters. The first
is requied, must be provided positionally, and must be an
integer between 1 and 10. The second parameter is required, may be
provided positionally or as a keyword argument, and must be an
'IFoo'. The third argument is not required, may be provided
positionally or as a keyword, can be either a float or 'None', and
defaults to 'None'. The function returns an 'IBar'.

Functions can have default parameter values that are 'Parameter'
objects. In this case, the default values do not indicate that the
parameter is optional, but simply provide initial parameter
specifications. The function definition::

def foo(x=Parameter(type=zope.schema.Int(min=1, max=10)), 
y=Parameter(type=IFoo, keyword=True), 
z=Parameter(type=float, keyword=True, default=None),
):
return IBar

Is equivalent to the one above. One could, perhaps, provide
convenience functions that allowed an equivalent definition, like::

from myparameters import Int, Float, Foo, Bar

def foo(x=Int(min=1, max=10), y=Foo(keyword=True), 
z=Float(keyword=True, default=None),
):
return Bar()

(This is the Nevow style of parameter definition.)

Parameter objects will have a number of attributes, which can be set
via keyword arguments to the constructor, including:

- 'type'

The value specification. If not 'None', this will be adapted to
'IInterface'. A value of 'None' means unknown.

- 'keyword'

A flag indicating whether the parameter may be given as a 'keyword'
parameter. If 'True', then the parameter name is significant. The
default is 'False'. If any parameters have a 'True' 'keyword'
attribute, then all parameters after that parameter in the
'parameters' tuple must have 'True' keyword attributes.

- 'positional'

A flag indicating whether the parameter may be given positionally.
If 'True', then the parameter order in the signature is
significant. The default is 'True'. If any parameters have a 'True'
'positional' attribute, then all parameters before that parameter in
the 'parameters' tuple must have 'True' positional attributes.

- 'variable'

A flag indicating whether the parameter represents variable
arguments. A 'parameters' tuple may have at most two variable
parameters. Variable parameters must come after non-variable
parameters. Variable parameters may be keyword or non-keyword
variable parameters, depending on the setting of the keyword
paramter attribute. At most one variable parameter can be either
keyword or non-keyword. For example, they function:

def foo(*args, **kw):
"Does something ..."

Can be modelled as

def foo(args=Paramater(variable=True), 
kw=Parameter(varable=True, keyword=True),
):
"Does something ..."

args.description = "...."

The advantage of the second form is that the body of the function
has access to Parameter objects for args and kw, rather than an
empty tuple and an empty dictionary.

- 'description'

A textual description of the attribute

- 'default'

A default value for the parameter. This value is unused if
the 'required' attribute is 'True', however, giving a 'default'
argument to the parameter constructor or giving a non- 'Parameter'
default value for a function parameter implies that the parameter
is not required. 

- required

A flag indicating whether the parameter is required. This defaults
to 'True'.

--
forwarded from http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/MethodSpecification
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.zope.org/pipermail/zope3-dev/attachments/20040615/13c492b8/attachment-0001.html