[Doc-SIG] Re: documenting Python constraints on types

[Frederic Giacometti]

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