Path: csiph.com!usenet.pasdenom.info!gegeweb.org!aioe.org!news.stack.nl!newsfeed.xs4all.nl!newsfeed5.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
Return-Path: <d@davea.name>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.002
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'explicitly': 0.04; 'case.': 0.05; 'arguments': 0.07; 'objects,': 0.07; 'underscore': 0.09; 'cc:addr:python-list': 0.10; 'aug': 0.13; 'library': 0.15; '"does': 0.16; 'incomplete': 0.16; 'modules,': 0.16; 'subject: \n ': 0.16; 'unsupported': 0.16; 'wrote:': 0.17; 'certainly': 0.17; 'documented': 0.17; 'module,': 0.17; "shouldn't": 0.17; 'thu,': 0.17; 'examples': 0.18; '>>>': 0.18; 'code,': 0.18; 'module': 0.19; 'file.': 0.20; 'all,': 0.21; 'visible': 0.22; 'defined': 0.22; 'cc:2**0': 0.23; 'chapter': 0.23; 'elements': 0.23; 'thus': 0.24; 'cc:no real name:2**0': 0.24; 'cc:addr:python.org': 0.25; 'header:In-Reply-To:1': 0.25; 'header:User-Agent:1': 0.26; 'older': 0.27; 'question': 0.27; 'authors': 0.27; 'library.': 0.27; "doesn't": 0.28; '+0100,': 0.29; 'documenting': 0.29; 'publicly': 0.29; 'class': 0.29; 'maybe': 0.29; 'classes': 0.30; 'normally': 0.30; 'code': 0.31; 'anywhere': 0.33; 'skip:s 30': 0.33; 'apply,': 0.33; 'platforms.': 0.33; 'likely': 0.33; 'version': 0.34; 'exist': 0.35; 'generic': 0.35; 'expected': 0.35; 'pm,': 0.35; 'there': 0.35; 'but': 0.36; "i'll": 0.36; 'should': 0.36; 'does': 0.37; 'detail': 0.37; 'far': 0.37; 'subject:: ': 0.38; 'fact': 0.38; 'mean': 0.38; 'some': 0.38; 'received:192': 0.39; 'received:192.168': 0.40; 'leading': 0.61; 'necessarily': 0.63; 'more': 0.63; 'header:Reply-To:1': 0.68; 'received:74.208': 0.71; 'reply-to:no real name:2**0': 0.72; 'future,': 0.72; 'to:addr:yahoo.co.uk': 0.84; 'dennis': 0.91; 'kat': 0.91
Date: Thu, 09 Aug 2012 15:45:57 -0400
From: Dave Angel <d@davea.name>
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:14.0) Gecko/20120714 Thunderbird/14.0
MIME-Version: 1.0
To: lipska the kat <lipskathekat@yahoo.co.uk>
Subject: Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs
References: <34WdnQ8_38yFSb7NnZ2dnUVZ8qCdnZ2d@bt.com> <mailman.3104.1344534013.4697.python-list@python.org> <ZcCdnWGRFsLxnrnNnZ2dnUVZ7rCdnZ2d@bt.com>
In-Reply-To: <ZcCdnWGRFsLxnrnNnZ2dnUVZ7rCdnZ2d@bt.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
X-Provags-ID: V02:K0:oIRQgq1cSDXS1P/DFHKdXZiTcHvNNbum9JmIYSIWrZK QtI7tHoOhB44TNAdDl5A+hN9car5z+hzA8V+74encvdcMdD90X TPoDbyHA3SFBXo4mBtUmnIvyPR0s7GedfpZZ+DOGSsj3lJRGhP B502OYH/VHLczDcGa+Kz8NdQKHDTTYJC66wIVYMyE6htqs7S4z 737U3jsnY9djKYP5ayqE4eVzqsUL6lFsyeSUJmBaSmWJyDeL4W CJRXQogHuNSQZOWnLPd72b17D3W1/TnxsSS/vLlP4MP2ybKwAp zI8wKYkAAAbCz1UxoL94J2PpGj1jxXQN0CY6efiQH/6OpB+0w= =
Cc: python-list@python.org
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.12
Precedence: list
Reply-To: d@davea.name
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <http://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <http://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.3107.1344541590.4697.python-list@python.org>
Lines: 56
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1344541590 news.xs4all.nl 6877 [2001:888:2000:d::a6]:39283
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:26803

On 08/09/2012 02:37 PM, lipska the kat wrote:
> On 09/08/12 18:39, Dennis Lee Bieber wrote:
>> On Thu, 09 Aug 2012 16:15:33 +0100, lipska the kat
>> <lipskathekat@yahoo.co.uk>  declaimed the following in
>> gmane.comp.python.general:
>>
>>
>>> in the examples in this chapter we see usage examples for
>>> socketserver.BaseRequestHandler
>>> <SNIP>
>

I don't know this module at all, so I'll make more generic comments.

> socketserver.RequestHandler is EXPLICITLY documented in section
> "20.19.3 RequestHandler Objects" yet does not exist in socketserver.py
> Does this not strike you as odd. I certainly strikes me as odd. Maybe
> it should be socketserver.BaseRequestHandler that is documented here.
>

The question should not be "is it in socketserver.py," but "does it work
as documented" ?   Some of the code is likely in C modules, and thus not
visible in any py file.

> The CLASSES socketserver.StreamRequestHandler and
> socketserver.DatagramRequestHandler are DEFINED in socketserver.py
> They are NOT Objects, they are CLASSES yet they are NOT EXPLICITLY
> documented in section 20.19.3 or any other section as far as I can tell.
>
> <SNIP>

The documentation is for the elements that the library authors expected
and intended people to be able to use.  Reasons for not documenting a
particular class or a particular function/method might include the fact
that it's considered obscure, it's unsupported and may not be available
in the future, it's there only for compatibility with an older version
and shouldn't be used in new code, or it's an implementation detail
and/or might not be visible on other platforms.  A single leading
underscore should normally be used for that last case.

 
> Is there anywhere that documents EXPLICITLY all the publicly visible
> classes in the standard library.
>>

Just because it's publicly visible doesn't necessarily mean it's part of
the intended interface.

Now, for this particular module, perhaps none of my arguments apply,
and/or there's a flawed or incomplete documentation.


-- 

DaveA