From michel@digicool.com  Tue May 29 23:38:24 2001
From: michel@digicool.com (Michel Pelletier)
Date: Tue, 29 May 2001 15:38:24 -0700 (PDT)
Subject: [Types-sig] Almost ready for prime time
Message-ID: <Pine.LNX.4.21.0103191235380.9948-100000@localhost.localdomain>

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

,




From michel@digicool.com  Tue May 29 23:40:23 2001
From: michel@digicool.com (Michel Pelletier)
Date: Tue, 29 May 2001 15:40:23 -0700 (PDT)
Subject: [Types-sig] Re: Almost ready for prime time (sorry!)
In-Reply-To: <Pine.LNX.4.21.0103191235380.9948-100000@localhost.localdomain>
Message-ID: <Pine.LNX.4.21.0105291538440.15921-100000@localhost.localdomain>

Ignore this please, emacs key bindings should not be confused with pine
key bindings.

;)

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



From lac@cd.chalmers.se  Wed May 30 09:23:51 2001
From: lac@cd.chalmers.se (Laura Creighton)
Date: Wed, 30 May 2001 10:23:51 +0200 (MET DST)
Subject: [Types-sig] I want to read Scott Cotton's latest proposal
Message-ID: <200105300823.KAA15401@boris.cd.chalmers.se>

But the link refered to on http://www.python.org/sigs/types-sig/ is
stale.  The requested URL
/pipermail/types-sig/2000-January/001310.html was not found on this
server.

Laura Creighton



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: [Types-sig] Re: [Doc-SIG] documenting Python constraints on types
In-Reply-To: <3B143FEB.F6FCC264@arakne.com>
References: <Pine.LNX.4.21.0105291538440.15921-100000@localhost.localdomain>
 <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.  <fdrake at acm.org>
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: [Types-sig] Re: documenting Python constraints on types
References: <Pine.LNX.4.21.0105291538440.15921-100000@localhost.localdomain>
 <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.