diff options
Diffstat (limited to 'sandbox/edloper/docpy')
| -rw-r--r-- | sandbox/edloper/docpy/asyncore.rst | 295 | ||||
| -rwxr-xr-x | sandbox/edloper/docpy/docpy.py | 323 |
2 files changed, 0 insertions, 618 deletions
diff --git a/sandbox/edloper/docpy/asyncore.rst b/sandbox/edloper/docpy/asyncore.rst deleted file mode 100644 index 2eda1647c..000000000 --- a/sandbox/edloper/docpy/asyncore.rst +++ /dev/null @@ -1,295 +0,0 @@ -========== - asyncore -========== - ------------------------------ - Asynchronous socket handler ------------------------------ - -Literal block:: - Synopsis: A base class for developing asynchronous socket - handling services. - Type: module builtin - Module-Author: Sam Rushing <rushing@nightmare.com> - Author: Christopher Petrilli <petrilli@amber.org> - Author: Steve Holden <sholden@holdenweb.com> - -.. Type: ... builtin, standard, various others: any specific usages required? -.. -.. Heavily adapted from original documentation by Sam Rushing. -.. -.. ............................................ -.. This is the (first) RFC822-reader strawman -.. ............................................ -.. Presumes a custom reader appropriate to docpy -.. RFC822 continuation IS allowed (see Synopsis) -.. Needtocheck: RFC822-readers and multiple entities? (Author lines) -.. Dunno about implication of \section in the original -.. Dunno about comments (#?); "Credit: Sam Rushing?" -.. Note in passing: names of new roles and directives made similar to -.. the existing docpy macros on purpose (for existing corpus & community) -.. -.. Markups needed, used, and existing in rst: -.. *emphasis* -.. -.. Markups needed, used, and modified by this strawman: -.. ``code`` -.. -.. Roles needed below by this strawman: -.. :cfunction:`` -.. :module:`` -.. :refmodule:`` -.. :class:`` -.. :function:`` -.. :var:`` -.. :label:`` -.. -.. Directives needed below by this strawman: -.. .. funcdesc:: -.. need to parse for optional argumnents shown as [...] -.. .. classdesc:: -.. .. datadesc:: -.. -.. TBS - formals, e.g., funcdesc - several alternatives proposed -.. below (see funcdesc) in this draft -.. the one shown first seems on track for consensus 04.3.20 -.. (the directive will parse brackets, etc. - easier to use!) - -This module provides the basic infrastructure for writing asynchronous -socket service clients and servers. - -There are only two ways to have a program on a single processor do -"more than one thing at a time." Multi-threaded programming is the -simplest and most popular way to do it, but there is another very -different technique, that lets you have nearly all the advantages of -multi-threading, without actually using multiple threads. It's really -only practical if your program is largely I/O bound. If your program -is processor bound, then pre-emptive scheduled threads are probably what -you really need. Network servers are rarely processor bound, however. - -If your operating system supports the :cfunction:`select()` system call -in its I/O library (and nearly all do), then you can use it to juggle -multiple communication channels at once; doing other work while your -I/O is taking place in the "background." Although this strategy can -seem strange and complex, especially at first, it is in many ways -easier to understand and control than multi-threaded programming. -The :module:`asyncore` module solves many of the difficult problems for -you, making the task of building sophisticated high-performance -network servers and clients a snap. For "conversational" applications -and protocols the companion :refmodule:`asynchat` module is invaluable. - -The basic idea behind both modules is to create one or more network -*channels*, instances of class :class:`asyncore.dispatcher` and -:class:`asynchat.async_chat`. Creating the channels adds them to a global -map, used by the :function:`loop()` function if you do not provide it -with your own :var:`map`. - -Once the initial channel(s) is(are) created, calling the :function:`loop()` -function activates channel service, which continues until the last -channel (including any that have been added to the map during asynchronous -service) is closed. - -.. funcdesc:: loop([timeout [, use_poll [, map]]]) - - Enter a polling loop that only terminates after all open channels - have been closed. All arguments are optional. The :var:`timeout` - argument sets the timeout parameter for the appropriate - :function:`select()` or :function:`poll()` call, measured in seconds; - the default is 30 seconds. The :var:`use_poll` parameter, if true, - indicates that :function:`poll()` should be used in preference to - :function:`select()` (the default is ``False``). The :var:`map` parameter - is a dictionary whose items are the channels to watch. As channels - are closed they are deleted from their map. If :var:`map` is - omitted, a global map is used (this map is updated by the default - class :method:`__init__()` - -- make sure you extend, rather than override, :method:`__init__()` - if you want to retain this behavior). - - Channels (instances of :class:`asyncore.dispatcher`, :class:`asynchat.async_chat` - and subclasses thereof) can freely be mixed in the map. - -.. classdesc:: dispatcher() - - The :class:`dispatcher` class is a thin wrapper around a low-level socket object. - To make it more useful, it has a few methods for event-handling which are called - from the asynchronous loop. - Otherwise, it can be treated as a normal non-blocking socket object. - - Two class attributes can be modified, to improve performance, - or possibly even to conserve memory. - - .. datadesc:: ac_in_buffer_size - - The asynchronous input buffer size (default ``4096``). - - .. datadesc:: ac_out_buffer_size - - The asynchronous output buffer size (default ``4096``). - - The firing of low-level events at certain times or in certain connection - states tells the asynchronous loop that certain higher-level events have - taken place. For example, if we have asked for a socket to connect to - another host, we know that the connection has been made when the socket - becomes writable for the first time (at this point you know that you may - write to it with the expectation of success). The implied higher-level - events are: - - ===================== =============================================== - ``Event`` Description - --------------------- ----------------------------------------------- - ``handle_connect()`` Implied by the first write event - ``handle_close()`` Implied by a read event with no data available - ``handle_accept()`` Implied by a read event on a listening socket - ===================== =============================================== - - - During asynchronous processing, each mapped channel's :method:`readable()` - and :method:`writable()` methods are used to determine whether the channel's - socket should be added to the list of channels :cfunction:`select()`\ ed or - :cfunction:`poll()`\ ed for read and write events. - -Thus, the set of channel events is larger than the basic socket events. -The full set of methods that can be overridden in your subclass follows: - -.. methoddesc:: handle_read() - - Called when the asynchronous loop detects that a :method:`read()` - call on the channel's socket will succeed. - -.. methoddesc:: handle_write() - - Called when the asynchronous loop detects that a writable socket - can be written. - Often this method will implement the necessary buffering for - performance. For example:: - - - def handle_write(self): - sent = self.send(self.buffer) - self.buffer = self.buffer[sent:] - -.. methoddesc:: handle_expt() - - Called when there is out of band (OOB) data for a socket - connection. This will almost never happen, as OOB is - tenuously supported and rarely used. - -.. methoddesc:: handle_connect() - - Called when the active opener's socket actually makes a connection. - Might send a "welcome" banner, or initiate a protocol - negotiation with the remote endpoint, for example. - -.. methoddesc:: handle_close() - - Called when the socket is closed. - -.. methoddesc:: handle_error() - - Called when an exception is raised and not otherwise handled. The default - version prints a condensed traceback. - -.. methoddesc:: handle_accept() - - Called on listening channels (passive openers) when a - connection can be established with a new remote endpoint that - has issued a :method:`connect()` call for the local endpoint. - -.. methoddesc:: readable() - - Called each time around the asynchronous loop to determine whether a - channel's socket should be added to the list on which read events can - occur. The default method simply returns ``True``, - indicating that by default, all channels will be interested in - read events. - -.. methoddesc:: writable() - - Called each time around the asynchronous loop to determine whether a - channel's socket should be added to the list on which write events can - occur. The default method simply returns ``True``, - indicating that by default, all channels will be interested in - write events. - -In addition, each channel delegates or extends many of the socket methods. -Most of these are nearly identical to their socket partners. - -.. methoddesc:: create_socket(family, type) - - This is identical to the creation of a normal socket, and - will use the same options for creation. Refer to the - :refmodule:`socket` documentation for information on creating - sockets. - -.. methoddesc:: connect(address) - - As with the normal socket object, :var:`address` is a - tuple with the first element the host to connect to, and the - second the port number. - -.. methoddesc:: send(data) - - Send :var:`data` to the remote end-point of the socket. - -.. methoddesc:: recv(buffer_size) - - Read at most :var:`buffer_size` bytes from the socket's remote end-point. - An empty string implies that the channel has been closed from the other - end. - -.. methoddesc:: listen(backlog) - - Listen for connections made to the socket. The :var:`backlog` - argument specifies the maximum number of queued connections - and should be at least 1; the maximum value is - system-dependent (usually 5). - -.. methoddesc:: bind(address) - - Bind the socket to :var:`address`. The socket must not already - be bound. (The format of :var:`address` depends on the address - family --- see above.) - -.. methoddesc:: accept() - - Accept a connection. The socket must be bound to an address - and listening for connections. The return value is a pair - ``(conn , address)`` where :var:`conn` is a - *new* socket object usable to send and receive data on - the connection, and :var:`address` is the address bound to the - socket on the other end of the connection. - -.. methoddesc:: close() - - Close the socket. All future operations on the socket object - will fail. The remote end-point will receive no more data (after - queued data is flushed). Sockets are automatically closed - when they are garbage-collected. - - -asyncore Example basic HTTP client :label:`asyncore-example` ------------------------------------------------------------- -As a basic example, below is a very basic HTTP client that uses the -:class:`dispatcher` class to implement its socket handling:: - - class http_client(asyncore.dispatcher): - def __init__(self, host,path): - asyncore.dispatcher.__init__(self) - self.path = path - self.create_socket(socket.AF_INET, socket.SOCK_STREAM) - self.connect( (host, 80) ) - self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % self.path - - def handle_connect(self): - pass - - def handle_read(self): - data = self.recv(8192) - print data - - def writable(self): - return (len(self.buffer) > 0) - - def handle_write(self): - sent = self.send(self.buffer) - self.buffer = self.buffer[sent:] diff --git a/sandbox/edloper/docpy/docpy.py b/sandbox/edloper/docpy/docpy.py deleted file mode 100755 index 450a9b735..000000000 --- a/sandbox/edloper/docpy/docpy.py +++ /dev/null @@ -1,323 +0,0 @@ -#!/usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -:todo: role-labeled inline text -:todo: generate output (subclass LaTeXTransformer) -:todo later: macros (susbtitution refs) -""" -from docutils import nodes -from docutils.parsers.rst import directives -from docutils.parsers.rst.directives import admonitions -from docutils.parsers.rst import states -from docutils.writers import latex2e -import re, tokenize - -###################################################################### -# New nodes -###################################################################### - -class funcdesc(nodes.Admonition, nodes.Element): pass -class classdesc(nodes.Admonition, nodes.Element): pass -class methoddesc(nodes.Admonition, nodes.Element): pass -class datadesc(nodes.Admonition, nodes.Element): pass -class desc_name(nodes.Part, nodes.Inline, nodes.TextElement): pass - -# We might use pynodes instead. -class func_signature(nodes.Part, nodes.Inline, nodes.TextElement): pass -class func_name(nodes.Part, nodes.Inline, nodes.TextElement): pass -class func_parameterlist(nodes.Part, nodes.Inline, nodes.TextElement): pass -class func_parameter(nodes.Part, nodes.Inline, nodes.TextElement): pass -class func_optional(nodes.Part, nodes.Inline, nodes.TextElement): pass - -# These are the inline things. -class docpy_function(nodes.Inline, nodes.TextElement): pass -class docpy_manpage(nodes.Inline, nodes.TextElement): pass -class docpy_regexp(nodes.Inline, nodes.TextElement): pass -class docpy_file(nodes.Inline, nodes.TextElement): pass -class docpy_label(nodes.Inline, nodes.TextElement): pass -class docpy_class(nodes.Inline, nodes.TextElement): pass -class docpy_method(nodes.Inline, nodes.TextElement): pass -class docpy_cfunction(nodes.Inline, nodes.TextElement): pass -class docpy_refmodule(nodes.Inline, nodes.TextElement): pass -class docpy_module(nodes.Inline, nodes.TextElement): pass -class docpy_var(nodes.Inline, nodes.TextElement): pass -inline_docpy_elements = { # Maps roles to entitites - 'function':docpy_function, - 'manpage':docpy_manpage, - 'regexp':docpy_regexp, - 'file':docpy_file, - 'label': docpy_label, - 'class': docpy_class, - 'method': docpy_method, - 'cfunction': docpy_cfunction, - 'refmodule': docpy_refmodule, - 'module': docpy_module, - 'var': docpy_var, - } - -for (role, element) in inline_docpy_elements.items(): - states.register_inliner_role(role, element) - - -###################################################################### -# Directives -###################################################################### - -# Transform a python signature into RST. -def parse_signature(s): - """ - A straw-man implementation. (Might be sufficient) - """ - s = s.strip() - m = re.match(r'^(\w+)\s*\((.*)\)$', s) - if m is None: raise ValueError(`s`) - name, arglist = m.groups() - - sig = func_signature(s,'') - - sig.append(func_name(name,name)) - sig.append(func_parameterlist()) - - stack = [sig[-1]] - for token in re.split(r'(\*{0,2}\w+|[\[\],])', arglist): - #print `token`, stack - if token == '[': - opt = func_optional() - stack[-1].append(opt) - stack.append(opt) - elif token == ']': - stack.pop() - elif token == ',': - pass - elif re.match(r'^\s*$', token): - pass - elif re.match(r'^\*{0,2}\w+$', token): - stack[-1].append(func_parameter(token,token)) - else: - raise ValueError(s) - if len(stack) != 1: raise ValueError(s) - return sig - -def funcdesc_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - rv = admonitions.make_admonition(funcdesc, name, [], options, content, - lineno, content_offset, block_text, - state, state_machine) - rv[0].insert(0, parse_signature(arguments[0])) - return rv -funcdesc_directive.content = 1 -funcdesc_directive.arguments = (1,0,1) # 1 required arg with spaces. - -def methoddesc_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - rv = admonitions.make_admonition(methoddesc, name, [], options, content, - lineno, content_offset, block_text, - state, state_machine) - rv[0].insert(0, parse_signature(arguments[0])) - return rv -methoddesc_directive.content = 1 -methoddesc_directive.arguments = (1,0,1) # 1 required arg with spaces. - -def classdesc_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - rv = admonitions.make_admonition(classdesc, name, [], options, content, - lineno, content_offset, block_text, - state, state_machine) - rv[0].insert(0, parse_signature(arguments[0])) - return rv -classdesc_directive.content = 1 -classdesc_directive.arguments = (1,0,1) # 1 required arg with spaces. - -def datadesc_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - rv = admonitions.make_admonition(datadesc, name, [], options, content, - lineno, content_offset, block_text, - state, state_machine) - rv[0].insert(0, desc_name(arguments[0], arguments[0])) - return rv -datadesc_directive.content = 1 -datadesc_directive.arguments = (1,0,1) # 1 required arg with spaces. - -# Register the directives -directives.register_directive('funcdesc', funcdesc_directive) -directives.register_directive('methoddesc', methoddesc_directive) -directives.register_directive('classdesc', classdesc_directive) -directives.register_directive('datadesc', datadesc_directive) - -###################################################################### -# Writer -###################################################################### - -class DocpyWriter(latex2e.Writer): - def translate(self): - visitor = DocpyTranslator(self.document) - self.document.walkabout(visitor) - self.output = visitor.astext() - self.head_prefix = visitor.head_prefix - self.head = visitor.head - self.body_prefix = visitor.body_prefix - self.body = visitor.body - self.body_suffix = visitor.body_suffix - -class DocpyTranslator(latex2e.LaTeXTranslator): - """ - Incompatibilities: - - latex docs uses \subsection, we generate \subsection* - (e.g., \subsection{asyncore Exampe ...}) - - we generate header & footer info that we don't need - - we don't handle RFC822 stuff & generate a top-level \section - - in a function signature, we escape underscores but latex docs - don't. e.g., funcdesc (line 46 of asyncore). - - in role-labeled text, we escape underscore but latex docs - don't. - - table rendering is completely different. - """ - - def __init__(self, *args): - latex2e.LaTeXTranslator.__init__(self, *args) - self.section_level = 1 - self.first_paramter_visited = 0 - - - #------------------------------------------------------------ - # Directives - #------------------------------------------------------------ - def visit_funcdesc(self, node): - self.body.append('\n'+r'\begin{funcdesc}') - def depart_funcdesc(self, node): - self.body.append(r'\end{funcdesc}'+'\n') - - def visit_methoddesc(self, node): - self.body.append('\n'+r'\begin{methoddesc}') - def depart_methoddesc(self, node): - self.body.append(r'\end{methoddesc}'+'\n') - - def visit_classdesc(self, node): - self.body.append('\n'+r'\begin{classdesc}') - def depart_classdesc(self, node): - self.body.append(r'\end{classdesc}'+'\n') - - def visit_datadesc(self, node): - self.body.append('\n'+r'\begin{datadesc}') - def depart_datadesc(self, node): - self.body.append(r'\end{datadesc}'+'\n') - - def visit_desc_name(self, node): - self.body.append('{') - def depart_desc_name(self, node): - self.body.append('}') - - def visit_func_name(self, node): - self.body.append('{') - def depart_func_name(self, node): - self.body.append('}') - - def visit_func_signature(self, node): pass - def depart_func_signature(self, node): pass - - def visit_func_parameterlist(self, node): - self.body.append('{') - self.first_parameter_visited = 0 - def depart_func_parameterlist(self, node): - self.body.append('}') - - def visit_func_parameter(self, node): - if self.first_parameter_visited: - self.body.append(', ') - self.first_parameter_visited = 1 - def depart_func_parameter(self, node): pass - - def visit_func_optional(self, node): - self.body.append(r'\optional{') - if self.first_paramter_visited: - self.body.append(',') - def depart_func_optional(self, node): - self.body.append('}') - - - #------------------------------------------------------------ - # Inline Roles - #------------------------------------------------------------ - def visit_docpy_function(self, node): - self.body.append(r'\function{') - def depart_docpy_function(self, node): - self.body.append(r'}') - - def visit_docpy_manpage(self, node): - self.body.append(r'\manpage{') - def depart_docpy_manpage(self, node): - self.body.append(r'}') - - def visit_docpy_regexp(self, node): - self.body.append(r'\regexp{') - def depart_docpy_regexp(self, node): - self.body.append(r'}') - - def visit_docpy_file(self, node): - self.body.append(r'\file{') - def depart_docpy_file(self, node): - self.body.append(r'}') - - def visit_docpy_label(self, node): - self.body.append(r'\label{') - def depart_docpy_label(self, node): - self.body.append(r'}') - - def visit_docpy_class(self, node): - self.body.append(r'\class{') - def depart_docpy_class(self, node): - self.body.append(r'}') - - def visit_docpy_method(self, node): - self.body.append(r'\method{') - def depart_docpy_method(self, node): - self.body.append(r'}') - - def visit_docpy_cfunction(self, node): - self.body.append(r'\cfunction{') - def depart_docpy_cfunction(self, node): - self.body.append(r'}') - - def visit_docpy_refmodule(self, node): - self.body.append(r'\refmodule{') - def depart_docpy_refmodule(self, node): - self.body.append(r'}') - - def visit_docpy_module(self, node): - self.body.append(r'\module{') - def depart_docpy_module(self, node): - self.body.append(r'}') - - def visit_docpy_var(self, node): - self.body.append(r'\var{') - def depart_docpy_var(self, node): - self.body.append(r'}') - - #------------------------------------------------------------ - # Etc. - #------------------------------------------------------------ - def visit_literal(self, node): - self.literal = 1 - self.body.append('\\code{') - -###################################################################### -# Front-end code -###################################################################### -if __name__ == '__main__': - import locale - try: - locale.setlocale(locale.LC_ALL, '') - except: - pass - - from docutils.core import publish_cmdline, default_description - description = default_description - publish_cmdline(writer=DocpyWriter(), description=description) - #publish_cmdline(writer_name='pseudoxml', description=description) - |