Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #26789 > unrolled thread

socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs

Back to article view | Back to comp.lang.python

Contents

  socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs lipska the kat <lipskathekat@yahoo.co.uk> - 2012-08-09 16:15 +0100
    Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs Dennis Lee Bieber <wlfraed@ix.netcom.com> - 2012-08-09 13:39 -0400
      Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs lipska the kat <lipskathekat@yahoo.co.uk> - 2012-08-09 19:08 +0100
      Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs lipska the kat <lipskathekat@yahoo.co.uk> - 2012-08-09 19:37 +0100
        Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs Mark Lawrence <breamoreboy@yahoo.co.uk> - 2012-08-09 19:55 +0100
          Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs lipska the kat <lipskathekat@yahoo.co.uk> - 2012-08-09 20:20 +0100
        Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs Peter Otten <__peter__@web.de> - 2012-08-09 21:07 +0200
          Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs lipska the kat <lipskathekat@yahoo.co.uk> - 2012-08-09 20:23 +0100
        Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs Dave Angel <d@davea.name> - 2012-08-09 15:45 -0400
    Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs Terry Reedy <tjreedy@udel.edu> - 2012-08-09 15:45 -0400
      Re: socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs lipska the kat <lipskathekat@yahoo.co.uk> - 2012-08-10 08:46 +0100

#26789 — socketserver.BaseRequestHandler and socketserver.StreamRequestServer docs

First of all sincere apologies if this is blindingly obvious and I just 
missed it

In the documentation at

http://docs.python.org/py3k/library/socketserver.html

mention is made more than once of a class
socketserver.StreamRequestHandler

in the examples in this chapter we see usage examples for
socketserver.BaseRequestHandler

I am trying to find documentation for these two classes as I would like 
to use the former and, well I'd just like to learn more aout the latter.
I've looked in the general index and used Google. The problem is that 
however hard I look I just cannot find it !!!

In Eclipse I have the entire standard library mounted on an explorer 
node. When I find socketserver.py I can navigate to the 
BaseRequestHandler and StreamRequestHandler classes
but I can't find the (documented) class [socketserver].RequestHandler 
class in socketserver.py nor can I find any explicit documentation for 
the classes socketserver.StreamRequestHandler
and socketserver.BaseRequestHandler.

I'm probably being INCREDIBLY dense here but what am I missing ?

Incidently if I read the code for these two classes I CAN understand 
what they do but this is not always the case and anyway, how many other 
potentially useful classes are lurking undocumented in the library

This is NOT intended as a criticism but it is frustrating.

many thanks

lipska
-- 
Lipska the Kat: Troll hunter, sandbox destroyer
and farscape dreamer of Aeryn Sun

[toc] | [next] | [standalone]

#26792

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
>
	 So far as I can tell, all RequestHandler objects are covered in
section "20.19.3 RequestHandler Objects"

> 
> In Eclipse I have the entire standard library mounted on an explorer 
> node. When I find socketserver.py I can navigate to the 
> BaseRequestHandler and StreamRequestHandler classes
> but I can't find the (documented) class [socketserver].RequestHandler 
> class in socketserver.py nor can I find any explicit documentation for 
> the classes socketserver.StreamRequestHandler
> and socketserver.BaseRequestHandler.
>

	There is no "RequestHandler" class. The section is general to all
RequestHandler OBJECTS (Base, Stream, and Datagram).

	Stream and Datagram request handlers are subclasses of Base, in
which the setup/finish methods handle the creation/destruction of
"file-like" attributes -- allowing one to just do read/write operations
within the core handle() method, instead of having to be concerned with
the type of connection and performing actual socket recv()/send()
operations. They are documented in the second paragraph of the .handle()
method in sectin 20.19.3

	In all cases, you are responsible for providing the contents of the
handle() method.

	
 
-- 
	Wulfraed                 Dennis Lee Bieber         AF6VN
        wlfraed@ix.netcom.com    HTTP://wlfraed.home.netcom.com/

[toc] | [prev] | [next] | [standalone]

#26793

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
>>
> 	So far as I can tell, all RequestHandler objects are covered in
> section "20.19.3 RequestHandler Objects"
>
>>
>> In Eclipse I have the entire standard library mounted on an explorer
>> node. When I find socketserver.py I can navigate to the
>> BaseRequestHandler and StreamRequestHandler classes
>> but I can't find the (documented) class [socketserver].RequestHandler
>> class in socketserver.py nor can I find any explicit documentation for
>> the classes socketserver.StreamRequestHandler
>> and socketserver.BaseRequestHandler.
>>
>
> 	There is no "RequestHandler" class. The section is general to all
> RequestHandler OBJECTS (Base, Stream, and Datagram).
>
> 	Stream and Datagram request handlers are subclasses of Base, in
> which the setup/finish methods handle the creation/destruction of
> "file-like" attributes -- allowing one to just do read/write operations
> within the core handle() method, instead of having to be concerned with
> the type of connection and performing actual socket recv()/send()
> operations. They are documented in the second paragraph of the .handle()
> method in sectin 20.19.3
>
> 	In all cases, you are responsible for providing the contents of the
> handle() method.
>
> 	
>


-- 
Lipska the Kat: Troll hunter, sandbox destroyer
and farscape dreamer of Aeryn Sun

[toc] | [prev] | [next] | [standalone]

#26794

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
>>
> 	So far as I can tell, all RequestHandler objects are covered in
> section "20.19.3 RequestHandler Objects"

Yes, I know, I've read it. Thank you.

> 	There is no "RequestHandler" class. The section is general to all
> RequestHandler OBJECTS (Base, Stream, and Datagram).

Yes I know, I've read socketserver.py. Thank you.
Why do I find myself getting annoyed here ?

This is hard work but I'll try again.

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

This is the question I was asking. I am quite capable of extracting the 
slightly obtuse documentation in the section and confirming my 
assumptions by reading the code.

So, I'll try again.

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

If there is I'd be most grateful if you could point me to it as I can't 
find it

If there isn't how does one go about
contributing to the documentation.

Thank you for taking the time to reply

lipska

-- 
Lipska the Kat: Troll hunter, sandbox destroyer
and farscape dreamer of Aeryn Sun

[toc] | [prev] | [next] | [standalone]

#26795

On 09/08/2012 19:37, 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
>>>
>>     So far as I can tell, all RequestHandler objects are covered in
>> section "20.19.3 RequestHandler Objects"
>
> Yes, I know, I've read it. Thank you.
>
>>     There is no "RequestHandler" class. The section is general to all
>> RequestHandler OBJECTS (Base, Stream, and Datagram).
>
> Yes I know, I've read socketserver.py. Thank you.
> Why do I find myself getting annoyed here ?
>
> This is hard work but I'll try again.
>
> 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 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.
>
> This is the question I was asking. I am quite capable of extracting the
> slightly obtuse documentation in the section and confirming my
> assumptions by reading the code.
>
> So, I'll try again.
>
> Is there anywhere that documents EXPLICITLY all the publicly visible
> classes in the standard library.
>
> If there is I'd be most grateful if you could point me to it as I can't
> find it
>
> If there isn't how does one go about
> contributing to the documentation.
>
> Thank you for taking the time to reply
>
> lipska
>

Dennis was only trying to help so please don't shout, thanks.

-- 
Cheers.

Mark Lawrence.

[toc] | [prev] | [next] | [standalone]

#26798

On 09/08/12 19:55, Mark Lawrence wrote:
> On 09/08/2012 19:37, 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
>>>>
>>> So far as I can tell, all RequestHandler objects are covered in
>>> section "20.19.3 RequestHandler Objects"
>>
>> Yes, I know, I've read it. Thank you.
>
> Dennis was only trying to help so please don't shout, thanks.

I appreciate that he was trying to help but quoting entire sections of 
text that I have already stated that I have read is pointless and wastes 
everybody's time.

I asked a specific question which he failed to answer.
I also thanked him for his time

lipska

-- 
Lipska the Kat: Troll hunter, sandbox destroyer
and farscape dreamer of Aeryn Sun

[toc] | [prev] | [next] | [standalone]

#26796

lipska the kat wrote:

> If there isn't how does one go about
> contributing to the documentation.

http://docs.python.org/dev/py3k/bugs.html

A similar link should be right there in the footer of the socketserver 
documentation.

[toc] | [prev] | [next] | [standalone]

#26800

On 09/08/12 20:07, Peter Otten wrote:
> lipska the kat wrote:
>
>> If there isn't how does one go about
>> contributing to the documentation.
>
> http://docs.python.org/dev/py3k/bugs.html
>
> A similar link should be right there in the footer of the socketserver
> documentation.

It is indeed, thank you.

lipska.

-- 
Lipska the Kat: Troll hunter, sandbox destroyer
and farscape dreamer of Aeryn Sun

[toc] | [prev] | [next] | [standalone]

#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

[toc] | [prev] | [next] | [standalone]

#26802

On 8/9/2012 1:39 PM, 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
>>
> 	 So far as I can tell, all RequestHandler objects are covered in
> section "20.19.3 RequestHandler Objects"
>
>>
>> In Eclipse I have the entire standard library mounted on an explorer
>> node. When I find socketserver.py I can navigate to the
>> BaseRequestHandler and StreamRequestHandler classes
>> but I can't find the (documented) class [socketserver].RequestHandler
>> class in socketserver.py nor can I find any explicit documentation for
>> the classes socketserver.StreamRequestHandler
>> and socketserver.BaseRequestHandler.
>>
>
> 	There is no "RequestHandler" class. The section is general to all
> RequestHandler OBJECTS (Base, Stream, and Datagram).
>
> 	Stream and Datagram request handlers are subclasses of Base, in
> which the setup/finish methods handle the creation/destruction of
> "file-like" attributes -- allowing one to just do read/write operations
> within the core handle() method, instead of having to be concerned with
> the type of connection and performing actual socket recv()/send()
> operations. They are documented in the second paragraph of the .handle()
> method in sectin 20.19.3
>
> 	In all cases, you are responsible for providing the contents of the
> handle() method.

I think the doc can be improved a bit and opened an issue to "Improve 
socketserver doc"
http://bugs.python.org/issue15608

-- 
Terry Jan Reedy

[toc] | [prev] | [next] | [standalone]

#26842

On 09/08/12 20:45, Terry Reedy wrote:
> On 8/9/2012 1:39 PM, 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 think the doc can be improved a bit and opened an issue to "Improve
> socketserver doc"
> http://bugs.python.org/issue15608

Thank you for your reasonable responses
I have sent an email to docs@python.org
politely suggesting a couple of improvements to
the socketserver documentation

lipska

-- 
Lipska the Kat: Troll hunter, sandbox destroyer
and farscape dreamer of Aeryn Sun

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web