From akuchlin@mems-exchange.org  Wed Aug  2 20:57:09 2000
From: akuchlin@mems-exchange.org (Andrew Kuchling)
Date: Wed, 2 Aug 2000 15:57:09 -0400
Subject: [Doc-SIG] Python HOWTO project created
Message-ID: <20000802155709.D28691@kronos.cnri.reston.va.us>

[CC'ed to python-dev and doc-sig -- followups set to doc-sig]

I've created a py-howto project on SourceForge to hold the Python
HOWTO documents.  

http://sourceforge.net/projects/py-howto/

Currently me, Fred, Moshe, and ESR are listed as developers and have
write access to CVS; if you want write access, drop me a note.  Web
pages and a py-howto-checkins mailing list will be coming soon, after
a bit more administrative fiddling around on my part.

Should I also create a py-howto-discuss list for discussing revisions,
or is the doc-sig OK?  Fred, what's your ruling about this?

--amk


From fdrake@beopen.com  Wed Aug  2 22:05:20 2000
From: fdrake@beopen.com (Fred L. Drake, Jr.)
Date: Wed, 2 Aug 2000 17:05:20 -0400 (EDT)
Subject: [Doc-SIG] Python HOWTO project created
In-Reply-To: <20000802155709.D28691@kronos.cnri.reston.va.us>
References: <20000802155709.D28691@kronos.cnri.reston.va.us>
Message-ID: <14728.36112.584563.516268@cj42289-a.reston1.va.home.com>

Andrew Kuchling writes:
 > Should I also create a py-howto-discuss list for discussing revisions,
 > or is the doc-sig OK?  Fred, what's your ruling about this?

  It's your project, your choice.  ;)  I've no problem with using the
Doc-SIG for this if you like, but a separate list may be a good thing
since it would have fewer distractions!


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at beopen.com>
BeOpen PythonLabs Team Member



From akuchlin@mems-exchange.org  Wed Aug  9 19:09:55 2000
From: akuchlin@mems-exchange.org (Andrew Kuchling)
Date: Wed, 9 Aug 2000 14:09:55 -0400
Subject: [Doc-SIG] py-howto project now operational
Message-ID: <20000809140955.C4838@kronos.cnri.reston.va.us>

I've just gotten around to setting up the checkin list for the Python
HOWTO project on SourceForge (py-howto.sourceforge.net), so the
project is now fully operational.  People who want to update the
HOWTOs, such as ESR and the curses HOWTO, can now go ahead and make
changes.

And this is the last you'll hear about the HOWTOs on python-dev;
please use the Doc-SIG mailing list (doc-sig@python.org) for further
discussion of the HOWTOs.

--amk



From haynes@sierratel.com  Wed Aug  9 19:12:58 2000
From: haynes@sierratel.com (Matthew Haynes)
Date: Wed, 09 Aug 2000 11:12:58 -0700
Subject: [Doc-SIG] Doc-SIG -- confirmation of subscription -- request 976111
Message-ID: <39919F2A.4A2BD8D9@sierratel.com>

confirm 976111



From mikem@ichips.intel.com  Wed Aug  9 13:30:43 2000
From: mikem@ichips.intel.com (Mike Miller)
Date: Wed, 09 Aug 2000 05:30:43 -0700
Subject: [Doc-SIG] Status of extracting docstrings
Message-ID: <39914EF3.6973FCCC@ichips.intel.com>

I'm in the process of starting up a fairly significant programming
project using Python (first time on Python). And embedded documentation
like the docstrings (or javadoc/POD/Cocoon) is going to be very
important to this particular project. I've taken a look at pythondoc
and it still seems a bit limited in scope. Is there some other
mechanism(s)
or something in version 1.6 that I'm missing? Currently it's looking
like
I'm going to need to extend pythondoc or write something from scratch.

Thanks,

 - Mike Miller
   mikem@ichips.intel.com


From Moshe Zadka <moshez@math.huji.ac.il>  Fri Aug 11 17:58:18 2000
From: Moshe Zadka <moshez@math.huji.ac.il> (Moshe Zadka)
Date: Fri, 11 Aug 2000 19:58:18 +0300 (IDT)
Subject: [Doc-SIG] Documenting "Magic" Methods
Message-ID: <Pine.GSO.4.10.10008111955350.5259-100000@sundial>

I assumed that the Python documentation has a standard way to document
classes which define magic methods. However, on looking through the
documented modules, I saw that it was elegently (and sometimes not so
elegantly) avoided -- "dictionary-like interface" is the only thing (apart
from examples) that can be found about
shelve.shelve.__[get|set|del]item__.

Is there something I missed, or is this area really untouched?

--
Moshe Zadka <moshez@math.huji.ac.il>
There is no IGLU cabal.
http://advogato.org/person/moshez



From fdrake@beopen.com  Fri Aug 11 18:21:12 2000
From: fdrake@beopen.com (Fred L. Drake, Jr.)
Date: Fri, 11 Aug 2000 13:21:12 -0400 (EDT)
Subject: [Doc-SIG] Documenting "Magic" Methods
In-Reply-To: <Pine.GSO.4.10.10008111955350.5259-100000@sundial>
References: <Pine.GSO.4.10.10008111955350.5259-100000@sundial>
Message-ID: <14740.13832.140032.418222@cj42289-a.reston1.va.home.com>

Moshe Zadka writes:
 > I assumed that the Python documentation has a standard way to document
 > classes which define magic methods. However, on looking through the
 > documented modules, I saw that it was elegently (and sometimes not so
 > elegantly) avoided -- "dictionary-like interface" is the only thing (apart
 > from examples) that can be found about
 > shelve.shelve.__[get|set|del]item__.
 > 
 > Is there something I missed, or is this area really untouched?

  You didn't miss anything!
  I'm not sure it makes sense to document the __*__() methods
individually; many of them don't even make that much sense
individually.
  I *think* describing the objects that implement these as
implementing the mapping/numeric/sequence protocols is the right
thing, but there's definately space for debate here.  Did you come
across a reason to document them individually?


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at beopen.com>
BeOpen PythonLabs Team Member



From laurie@eh.org  Fri Aug 11 11:27:04 2000
From: laurie@eh.org (Laurence Tratt)
Date: Fri, 11 Aug 2000 10:27:04 GMT
Subject: [Doc-SIG] Status of extracting docstrings
In-Reply-To: <39914EF3.6973FCCC@ichips.intel.com>
References: <39914EF3.6973FCCC@ichips.intel.com>
Message-ID: <2f9b58ec49.laurie@btinternet.com>

In message <39914EF3.6973FCCC@ichips.intel.com>
          Mike Miller <mikem@ichips.intel.com> wrote:

> I'm in the process of starting up a fairly significant programming project
> using Python (first time on Python). And embedded documentation like the
> docstrings (or javadoc/POD/Cocoon) is going to be very important to this
> particular project. I've taken a look at pythondoc and it still seems a
> bit limited in scope. Is there some other mechanism(s) or something in
> version 1.6 that I'm missing? Currently it's looking like I'm going to
> need to extend pythondoc or write something from scratch.

Depending on whether you're prepared to put up with alpha quality software,
you might be interested in my Crystal program which is available from:

  http://eh.org/~laurie/comp/python/crystal

Please note that at the moment I have not been able to test this with Python
1.6 (it may work, it may not) but it definately works with 1.5.2.


Laurie
-- 
http://eh.org/~laurie/comp/python/


From Moshe Zadka <moshez@math.huji.ac.il>  Fri Aug 11 23:29:38 2000
From: Moshe Zadka <moshez@math.huji.ac.il> (Moshe Zadka)
Date: Sat, 12 Aug 2000 01:29:38 +0300 (IDT)
Subject: [Doc-SIG] Documenting "Magic" Methods
In-Reply-To: <14740.13832.140032.418222@cj42289-a.reston1.va.home.com>
Message-ID: <Pine.GSO.4.10.10008120125040.8099-100000@sundial>

On Fri, 11 Aug 2000, Fred L. Drake, Jr. wrote:

>   I'm not sure it makes sense to document the __*__() methods
> individually; many of them don't even make that much sense
> individually.

Well, certainly __getitem__ makes sense without __setitem__. And,
I think, __[g|s]setitem__ make sense without __delitem__. Other
combinations are perhaps less popular, but certainly exist.

>   I *think* describing the objects that implement these as
> implementing the mapping/numeric/sequence protocols is the right
> thing

Not if they implement some variance on the classic protocol.
Imagine a class which does:

class bar:

	def __init__(self, value):
		self.value = value

class foo:

	def __init__(self):
		self.data = {}

	def __getitem__(self, key):
		return self[key]

	def __setitem__(self, key, value):
		self[key] = bar(value)

How would you document them?

> Did you come
> across a reason to document them individually?

What I've written above is the essence of the problem I'm having with
sketching the documentation for Cookie.py

--
Moshe Zadka <moshez@math.huji.ac.il>
There is no IGLU cabal.
http://advogato.org/person/moshez



From den@analyt.chem.msu.ru  Mon Aug 14 13:04:27 2000
From: den@analyt.chem.msu.ru (Denis S. Otkidach)
Date: Mon, 14 Aug 2000 16:04:27 +0400 (MSD)
Subject: [Doc-SIG] Description for xrange type
In-Reply-To: <14740.13832.140032.418222@cj42289-a.reston1.va.home.com>
Message-ID: <Pine.LNX.4.10.10008141559210.1403-100000@analyt471-2.chem.msu.ru>

Dear Fred,

you have added documentation for unicode and buffer types of sequnces. But
what about xrange? It seems to have an additional, still undocumented in
any way, tolist method.

Sincerely yours,
Denis S. Otkidach



From fdrake@beopen.com  Mon Aug 14 14:11:45 2000
From: fdrake@beopen.com (Fred L. Drake, Jr.)
Date: Mon, 14 Aug 2000 09:11:45 -0400 (EDT)
Subject: [Doc-SIG] Description for xrange type
In-Reply-To: <Pine.LNX.4.10.10008141559210.1403-100000@analyt471-2.chem.msu.ru>
References: <14740.13832.140032.418222@cj42289-a.reston1.va.home.com>
 <Pine.LNX.4.10.10008141559210.1403-100000@analyt471-2.chem.msu.ru>
Message-ID: <14743.61457.697103.892643@cj42289-a.reston1.va.home.com>

Denis S. Otkidach writes:
 > you have added documentation for unicode and buffer types of sequnces. But
 > what about xrange? It seems to have an additional, still undocumented in
 > any way, tolist method.

  Ah, thanks for the reminder!  I'll see what I can do about this.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at beopen.com>
BeOpen PythonLabs Team Member



From fdrake@beopen.com  Mon Aug 14 16:39:42 2000
From: fdrake@beopen.com (Fred L. Drake, Jr.)
Date: Mon, 14 Aug 2000 11:39:42 -0400 (EDT)
Subject: [Doc-SIG] Description for xrange type
In-Reply-To: <Pine.LNX.4.10.10008141559210.1403-100000@analyt471-2.chem.msu.ru>
References: <14740.13832.140032.418222@cj42289-a.reston1.va.home.com>
 <Pine.LNX.4.10.10008141559210.1403-100000@analyt471-2.chem.msu.ru>
Message-ID: <14744.4798.576360.650896@cj42289-a.reston1.va.home.com>

Denis S. Otkidach writes:
 > you have added documentation for unicode and buffer types of sequnces. But
 > what about xrange? It seems to have an additional, still undocumented in
 > any way, tolist method.

  I've checked this documentation into the CVS repository; it will
be part of the Python 2.0 release.
  Thanks!


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at beopen.com>
BeOpen PythonLabs Team Member



From den@analyt.chem.msu.ru  Thu Aug 17 10:46:50 2000
From: den@analyt.chem.msu.ru (Denis S. Otkidach)
Date: Thu, 17 Aug 2000 13:46:50 +0400 (MSD)
Subject: [Doc-SIG] Description for xrange type
In-Reply-To: <14744.4798.576360.650896@cj42289-a.reston1.va.home.com>
Message-ID: <Pine.LNX.4.10.10008171342470.3806-100000@analyt471-2.chem.msu.ru>


On Mon, 14 Aug 2000, Fred L. Drake, Jr. wrote:

FLDJ>  > you have added documentation for unicode and buffer types of sequnces. But
FLDJ>  > what about xrange? It seems to have an additional, still undocumented in
FLDJ>  > any way, tolist method.
FLDJ> 
FLDJ>   I've checked this documentation into the CVS repository; it will
FLDJ> be part of the Python 2.0 release.

Dear Fred,

I guess it would be better to use real name for type:
>>> type(xrange(1)).__name__
'xrange'

Also, current documentation is unclear about what buffer objects can be
used for.

With best regards,
Denis.



From Edward Welbourne <eddy@chaos.org.uk>  Tue Aug 15 20:19:34 2000
From: Edward Welbourne <eddy@chaos.org.uk> (Edward Welbourne)
Date: Tue, 15 Aug 2000 20:19:34 +0100 (BST)
Subject: [Doc-SIG] Documenting "Magic" Methods
In-Reply-To: <Pine.GSO.4.10.10008120125040.8099-100000@sundial> (message from
 Moshe Zadka on Sat, 12 Aug 2000 01:29:38 +0300 (IDT))
References: <Pine.GSO.4.10.10008120125040.8099-100000@sundial>
Message-ID: <m13OmFK-00007cC@vortigen.demon.co.uk>

>>   I'm not sure it makes sense to document the __*__() methods
>> individually;
> Well, certainly __getitem__ makes sense without __setitem__ ...

*Implementing* magic methods individually is a separate matter from
*documenting* them individually.  Aside from (off the top of my head)
__init__ and __call__, the __*__ methods' generic specs (in the language
reference manual) completely specify how each method is called - the
interface by which the python engine implements assorted bits of
syntactic magic.

Given the generic spec, the __*__ methods are best documented by an
announcement, in the class doc-string, of which abstract interfaces the
class implements; the class doc-string is also the right place to
describe (the abstract form of) any local deviation from normality.
Inserting (.data where needed and) doc strings, I'd document your
example as:

class bar:
    """Wrapper class for values stored in foo's dictionary"""
    def __init__(self, value): self.value = value

class foo:
    """Mapping class using bar's packaging for values.

    Implements the get and set aspects of the mapping interface, wrapping its
    values using bar. """

    def __init__(self): self.data = {}
    def __getitem__(self, key): return self.data[key]
    def __setitem__(self, key, value): self.data[key] = bar(value)

Crucially, the doc-string for a __*__ method is the generic spec of what
(part of an) interface that method supports.

If a __*__ method deviates from its generic spec by so much that its
users need to read its doc-string before doing usual things, it's
breaking the python engine's syntactic magic.  This generally makes a
strong case for calling the method something else and not claiming to
implement an interface you don't really support.  Of course, the world
is full of exceptions; and the __*__'s doc-string is the natural place
to record the details of such deviancy (the overview having gone in the
class docstring).  If we all abstain from documenting normal __*__
methods, deferring to the reference manual's generic doc for that name,
the deviants will stand out, increasing our chances of (noticing and so)
Doing The Right Thing when we do run into them.

Ideally, I guess, docgen would document __init__ not as a method with
that name but as the call semantics of the class; and, likewise,
__call__ as that of instances.  Anyone think of any other __*__ which
vary enough to warrant having doc strings in the normal run of events ?

	Eddy.
--
# an occasionally useful tool:
class listBok:
    """Mapping whose entries are lists, defaulting empty.

    Setting an item in the dictionary appends the item to the relevant list.
    """
    def __init__(self): self.__bok = {}
    def __delitem__(self, key): del self.__bok[key]
    def __setitem__(self, key, value): self[key].append(value)

    def __getitem__(self, key):
        try: row = self.__bok[key]
        except KeyError: row = self.__bok[key] = []
        return row


From fdrake@beopen.com  Fri Aug 18 04:15:16 2000
From: fdrake@beopen.com (Fred L. Drake, Jr.)
Date: Thu, 17 Aug 2000 23:15:16 -0400 (EDT)
Subject: [Doc-SIG] Description for xrange type
In-Reply-To: <Pine.LNX.4.10.10008171342470.3806-100000@analyt471-2.chem.msu.ru>
References: <14744.4798.576360.650896@cj42289-a.reston1.va.home.com>
 <Pine.LNX.4.10.10008171342470.3806-100000@analyt471-2.chem.msu.ru>
Message-ID: <14748.43588.554207.221078@cj42289-a.reston1.va.home.com>

Denis S. Otkidach writes:
 > I guess it would be better to use real name for type:
 > >>> type(xrange(1)).__name__
 > 'xrange'

  Ok, fixed in CVS.

 > Also, current documentation is unclear about what buffer objects can be
 > used for.

  I'll pass the request for clarification along to one of the people
responsible for buffer objects; thanks!


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at beopen.com>
BeOpen PythonLabs Team Member



From Moshe Zadka <moshez@math.huji.ac.il>  Fri Aug 18 05:33:54 2000
From: Moshe Zadka <moshez@math.huji.ac.il> (Moshe Zadka)
Date: Fri, 18 Aug 2000 07:33:54 +0300 (IDT)
Subject: [Doc-SIG] Documenting "Magic" Methods
In-Reply-To: <m13OmFK-00007cC@vortigen.demon.co.uk>
Message-ID: <Pine.GSO.4.10.10008180731010.23483-100000@sundial>

On Tue, 15 Aug 2000, Edward Welbourne wrote:

> >>   I'm not sure it makes sense to document the __*__() methods
> >> individually;
> > Well, certainly __getitem__ makes sense without __setitem__ ...
> 
> *Implementing* magic methods individually is a separate matter from
> *documenting* them individually.  Aside from (off the top of my head)
> __init__ and __call__, the __*__ methods' generic specs (in the language
> reference manual) completely specify how each method is called - the
> interface by which the python engine implements assorted bits of
> syntactic magic.
> 
> Given the generic spec, the __*__ methods are best documented by an
> announcement, in the class doc-string, of which abstract interfaces the
> class implements; the class doc-string is also the right place to
> describe (the abstract form of) any local deviation from normality.

I think you lost me a bit here --
I'm talking about the LaTeX documentation -- this is for something that
needs to be out by 2.0, hopefully.

--
Moshe Zadka <moshez@math.huji.ac.il>
There is no IGLU cabal.
http://advogato.org/person/moshez



From den@analyt.chem.msu.ru  Mon Aug 21 09:03:24 2000
From: den@analyt.chem.msu.ru (Denis S. Otkidach)
Date: Mon, 21 Aug 2000 12:03:24 +0400 (MSD)
Subject: [Doc-SIG] Docs for methods of string and unicode objects
Message-ID: <Pine.LNX.4.10.10008211155440.881-100000@analyt471-2.chem.msu.ru>

Dear Fred,

I have noticed that interface of translate method applied to unicode
object differs from interface of the same method applied to string object.
In the former case translation table should be an object with mapping
interface (not a string), and characters to be deleted are denoted by None
value in translation table (not a separate string argument). Hmm... That's
why translate method doesn't work for UserString instances reffering to
unicode object.

The methods encode, isdecimal, and isnumeric are applicable only to
unicode objects. The later two methods are not mentioned in documentation.

With best regards,
Denis.



From mal@lemburg.com  Mon Aug 21 09:15:50 2000
From: mal@lemburg.com (M.-A. Lemburg)
Date: Mon, 21 Aug 2000 10:15:50 +0200
Subject: [Doc-SIG] Docs for methods of string and unicode objects
References: <Pine.LNX.4.10.10008211155440.881-100000@analyt471-2.chem.msu.ru>
Message-ID: <39A0E536.E93B7DA1@lemburg.com>

"Denis S. Otkidach" wrote:
> 
> Dear Fred,
> 
> I have noticed that interface of translate method applied to unicode
> object differs from interface of the same method applied to string object.
> In the former case translation table should be an object with mapping
> interface (not a string), and characters to be deleted are denoted by None
> value in translation table (not a separate string argument). Hmm... That's
> why translate method doesn't work for UserString instances reffering to
> unicode object.

True. 

This should be fixed according to the doc-strings available
on both objects. There should probably also be a note that using
a charmap codec for translating strings/Unicode is the better
way to go...

    "".translate :
        S.translate(table [,deletechars]) -> string
        
        Return a copy of the string S, where all characters occurring
        in the optional argument deletechars are removed, and the
        remaining characters have been mapped through the given
        translation table, which must be a string of length 256.

    u"".translate :
        S.translate(table) -> unicode
        
        Return a copy of the string S, where all characters have been mapped
        through the given translation table, which must be a mapping of
        Unicode ordinals to Unicode ordinals or None. Unmapped characters
        are left untouched. Characters mapped to None are deleted.

> The methods encode, isdecimal, and isnumeric are applicable only to
> unicode objects. The later two methods are not mentioned in documentation.

.encode() is available for strings too. The other two are not,
because the information is not available (there are numeric chars
in many code pages which are not digits, e.g. the fraction chars).

    "".encode :
        S.encode([encoding[,errors]]) -> string
        
        Return an encoded string version of S. Default encoding is the current
        default string encoding. errors may be given to set a different error
        handling scheme. Default is 'strict' meaning that encoding errors raise
        a ValueError. Other possible values are 'ignore' and 'replace'.

-- 
Marc-Andre Lemburg
______________________________________________________________________
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/