[issue8543] asynchat documentation issues

[Giampaolo Rodola']

New submission from Giampaolo Rodola' <g.rodola at gmail.com>:

I recently took a look at asynchat doc and found out it has some issues which should be addressed.
In my opinion the following methods and functions should NOT be mentioned:


- async_chat.refill_buffer()

this has been removed in Python 2.6 and no longer exists, plus there was no reason to override it in the first place as it was an internal method


 - asynchat.find_prefix_at_end(haystack, needle)

there's really no reason to mention this one, it is just used internally by async_chat class to implement the terminator logic


- async_chat.handle_close()
- async_chat.readable()
- async_chat.writable()
- async_chat.handle_read()
- async_chat.handle_write()

all inherited from asyncore, plus, aside from handle_close(), they should *NOT* be overridden as they implement the entire logic behind asynchat module


- class asynchat.simple_producer(data[, buffer_size=512])
- class asynchat.fifo([list=None])

as discussed in issue 6916 these are very old classes which are no longer used; imho not worth to be mentioned in the doc


- async_chat._collect_incoming_data(data)
- async_chat._get_data()

both added in 2.6 (this isn't mentioned), not sure if it's worth mentioning them (I wouldn't) but they're basically private methods which are never used in the base class and only provide a sample implementation


I think asynchat documentation should focus more on showing those parts of the API which are really going to be used, basically push*(), close_when_done() and terminator-related methods.
All other methods like handle_*(), etc..., are deliberately not supposed to be used and only create confusion.

I think I'm going to attach a patch tomorrow but I'd like to hear the opinion of Josiah Carlson before doing anything.

----------
assignee: docs at python
components: Documentation
messages: 104292
nosy: docs at python, giampaolo.rodola, josiah.carlson, josiahcarlson, r.david.murray
priority: normal
severity: normal
status: open
title: asynchat documentation issues
versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue8543>
_______________________________________