+HTTP request handler base class.
+
+The following explanation of HTTP serves to guide you through the
+code as well as to expose any misunderstandings I may have about
+HTTP (so you don't need to read the code to figure out I'm wrong
+:-).
+
+HTTP (HyperText Transfer Protocol) is an extensible protocol on
+top of a reliable stream transport (e.g. TCP/IP). The protocol
+recognizes three parts to a request:
+
+1. One line identifying the request type and path
+2. An optional set of RFC-822-style headers
+3. An optional data part
+
+The headers and data are separated by a blank line.
+
+The first line of the request has the form
+
+<command> <path> <version>
+
+where <command> is a (case-sensitive) keyword such as GET or POST,
+<path> is a string containing path information for the request,
+and <version> should be the string "HTTP/1.0" or "HTTP/1.1".
+<path> is encoded using the URL encoding scheme (using %xx to signify
+the ASCII character with hex code xx).
+
+The specification specifies that lines are separated by CRLF but
+for compatibility with the widest range of clients recommends
+servers also handle LF. Similarly, whitespace in the request line
+is treated sensibly (allowing multiple spaces between components
+and allowing trailing whitespace).
+
+Similarly, for output, lines ought to be separated by CRLF pairs
+but most clients grok LF characters just fine.
+
+If the first line of the request has the form
+
+<command> <path>
+
+(i.e. <version> is left out) then this is assumed to be an HTTP
+0.9 request; this form has no optional headers and data part and
+the reply consists of just the data.
+
+The reply form of the HTTP 1.x protocol again has three parts:
+
+1. One line giving the response code
+2. An optional set of RFC-822-style headers
+3. The data
+
+Again, the headers and data are separated by a blank line.
+
+The response code line has the form
+
+<version> <responsecode> <responsestring>
+
+where <version> is the protocol version ("HTTP/1.0" or "HTTP/1.1"),
+<responsecode> is a 3-digit response code indicating success or
+failure of the request, and <responsestring> is an optional
+human-readable string explaining what the response code means.
+
+This server parses the request and the headers, and then calls a
+function specific to the request type (<command>). Specifically,
+a request SPAM will be handled by a method do_SPAM(). If no
+such method exists the server sends an error response to the
+client. If it exists, it is called with no arguments:
+
+do_SPAM()
+
+Note that the request name is case sensitive (i.e. SPAM and spam
+are different requests).
+
+The various request details are stored in instance variables:
+
+- client_address is the client IP address in the form (host,
+port);
+
+- command, path and version are the broken-down request line;
+
+- headers is an instance of mimetools.Message (or a derived
+class) containing the header information;
+
+- rfile is a file object open for reading positioned at the
+start of the optional input data part;
+
+- wfile is a file object open for writing.
+
+IT IS IMPORTANT TO ADHERE TO THE PROTOCOL FOR WRITING!
+
+The first thing to be written must be the response line. Then
+follow 0 or more header lines, then a blank line, and then the
+actual data (if any). The meaning of the header lines depends on
+the command executed by the server; in most cases, when data is
+returned, there should be at least one header line of the form
+
+Content-type: <type>/<subtype>
+
+where <type> and <subtype> should be registered MIME types,
+e.g. "text/html" or "text/plain".
+
+
+
+
+
+
+
+
Method Summary
+
+
address_string(self)
+
+Return the client address formatted for logging.
+
+
date_time_string(self)
+
+Return the current date and time formatted for a message header.
+
+
end_headers(self)
+
+Send the blank line ending the MIME headers.
+
+
handle(self)
+
+Handle multiple requests if necessary.
+ You normally don't need to override this method; see the class
+ __doc__ string for information on how to handle specific HTTP commands
+ such as GET and POST.
+
+
+
+
+
+
+
log_date_time_string(self)
+
+ Return the current time formatted for logging.
+
+
+
+
+
+
+
log_error(self,
+ *args)
+
+
Log an error.
+
This is called when a request cannot be fulfilled. By default it
+ passes the message on to log_message().
+
Arguments are the same as for log_message().
+ XXX This should go to the separate error log.
+
+
+
+
+
+
+
log_message(self,
+ format,
+ *args)
+
+
Log an arbitrary message.
+
This is used by all other logging functions. Override it if you have
+ specific logging wishes.
+
The first argument, FORMAT, is a format string for the message to be
+ logged. If the format string contains any % escapes requiring
+ parameters, they should be specified as subsequent arguments (it's just
+ like printf!).
+ The client host and current date/time are prefixed to every
+ message.
+
+
+
+
+
+
+
log_request(self,
+ code='-',
+ size='-')
+
+
Log an accepted request.
+ This is called by send_reponse().
+
+
+
+
+
+
+
parse_request(self)
+
+
Parse a request (internal).
+
The request should be stored in self.raw_requestline; the results
+ are in self.command, self.path, self.request_version and
+ self.headers.
+ Return True for success, False for failure; on failure, an error is
+ sent back.
+
+
+
+
+
+
+
send_error(self,
+ code,
+ message=None)
+
+
Send and log an error reply.
+
Arguments are the error code, and a detailed message. The detailed
+ message defaults to the short entry matching the response code.
+ This sends an error response (so it must be called before any output
+ has been generated), logs the error, and finally sends a piece of HTML
+ explaining the error to the user.
+
+
+
+
+
+
+
send_header(self,
+ keyword,
+ value)
+
+ Send a MIME header.
+
+
+
+
+
+
+
send_response(self,
+ code,
+ message=None)
+
+
Send the response header and log the response code.
+ Also send two standard headers with the server software version and
+ the current date.
+
Test whether self.path corresponds to a CGI script.
+
Return a tuple (dir, rest) if self.path requires running a CGI
+ script, None if not. Note that rest begins with a slash if it is not
+ empty.
+ The default implementation tests whether the path begins with one of
+ the strings in the list self.cgi_directories (and the next character is
+ a '/' or the end of the string).
+
+
+
+
+
+
+
is_executable(self,
+ path)
+
+ Test whether argument path is an executable file.
+
+
+
+
+
+
+
is_python(self,
+ path)
+
+ Test whether argument path is a Python script.
+
Simple HTTP request handler with GET and HEAD commands.
+
This serves files from the current directory and any of its
+subdirectories. It assumes that all files are plain text files unless
+they have the extension ".html" in which case it assumes they
+are HTML files.
+The GET and HEAD requests are identical except that the HEAD request
+omits the actual contents of the file.
+
+
+
+
+
+
+
Method Summary
+
+
copyfile(self,
+ source,
+ outputfile)
+
+Copy all data between two file objects.
The SOURCE argument is a file object open for reading (or anything
+ with a read() method) and the DESTINATION argument is a file object
+ open for writing (or anything with a write() method).
+ The only reason for overriding this would be to change the block
+ size or perhaps to replace newlines by CRLF -- note however that this
+ the default server uses this to copy binary data as well.
+
+
+
+
+
+
+
do_GET(self)
+
+ Serve a GET request.
+
+
+
+
+
+
+
do_HEAD(self)
+
+ Serve a HEAD request.
+
+
+
+
+
+
+
guess_type(self,
+ path)
+
+
Guess the type of a file.
+
Argument is a PATH (a filename).
+
Return value is a string of the form type/subtype, usable for a MIME
+ Content-type header.
+ The default implementation looks the file's extension up in the
+ table self.extensions_map, using text/plain as a default; however it
+ would be permissible (if slow) to look inside the data to make a better
+ guess.
+
+
+
+
+
+
+
list_directory(self,
+ path)
+
+
Helper to produce a directory listing (absent index.html).
+ Return value is either a file object, or None (indicating an error).
+ In either case, the headers are sent, making the interface the same as
+ for send_head().
+
+
+
+
+
+
+
send_head(self)
+
+
Common code for GET and HEAD commands.
+
This sends the response code and MIME headers.
+ Return value is either a file object (which has to be copied to the
+ outputfile by the caller unless the command was HEAD, and must be
+ closed by the caller under all circumstances), or None, in which case
+ the caller has nothing further to do.
+
+
+
+
+
+
+
translate_path(self,
+ path)
+
+
Translate a /-separated PATH to the local filename syntax.
+ Components that mean special things to the local file system (e.g.
+ drive or directory names) are ignored. (XXX They should probably be
+ diagnosed.)
+
This class is instantiated for each request to be handled. The
+constructor sets the instance variables request, client_address and
+server, and then calls the handle() method. To implement a specific
+service, all you need to do is to derive a class which defines a handle()
+method.
+The handle() method can find the request as self.request, the client
+address as self.client_address, and the server (in case it needs access
+to per-server information) as self.server. Since a separate instance is
+created for each request, the handle() method can define arbitrary other
+instance variariables.
+
+
+
+
+
+Base class for server classes.
+
+Methods for the caller:
+
+- __init__(server_address, RequestHandlerClass)
+- serve_forever()
+- handle_request() # if you do not use serve_forever()
+- fileno() -> int # for select()
+
+Methods that may be overridden:
+
+- server_bind()
+- server_activate()
+- get_request() -> request, client_address
+- verify_request(request, client_address)
+- server_close()
+- process_request(request, client_address)
+- close_request(request)
+- handle_error()
+
+Methods for derived classes:
+
+- finish_request(request, client_address)
+
+Class variables that may be overridden by derived classes or
+instances:
+
+- address_family
+- socket_type
+- allow_reuse_address
+
+Instance variables:
+
+- RequestHandlerClass
+- socket
+
+Base class for various socket-based server classes.
+
+Defaults to synchronous IP stream (i.e., TCP).
+
+Methods for the caller:
+
+- __init__(server_address, RequestHandlerClass)
+- serve_forever()
+- handle_request() # if you don't use serve_forever()
+- fileno() -> int # for select()
+
+Methods that may be overridden:
+
+- server_bind()
+- server_activate()
+- get_request() -> request, client_address
+- verify_request(request, client_address)
+- process_request(request, client_address)
+- close_request(request)
+- handle_error()
+
+Methods for derived classes:
+
+- finish_request(request, client_address)
+
+Class variables that may be overridden by derived classes or
+instances:
+
+- address_family
+- socket_type
+- request_queue_size (only for stream sockets)
+- allow_reuse_address
+
+Instance variables:
+
+- server_address
+- RequestHandlerClass
+- socket
+
This document contains the API (Application Programming Interface)
+documentation for this project. Documentation for the Python
+objects defined by the project is divided into separate pages for each
+package, module, and class. The API documentation also includes two
+pages containing information about the project as a whole: a trees
+page, and an index page.
+
+
Object Documentation
+
+
Each Package Documentation page contains:
+
+
A description of the package.
+
A list of the modules and sub-packages contained by the
+ package.
+
A summary of the classes defined by the package.
+
A summary of the functions defined by the package.
+
A summary of the variables defined by the package.
+
A detailed description of each function defined by the
+ package.
+
A detailed description of each variable defined by the
+ package.
+
+
+
Each Module Documentation page contains:
+
+
A description of the module.
+
A summary of the classes defined by the module.
+
A summary of the functions defined by the module.
+
A summary of the variables defined by the module.
+
A detailed description of each function defined by the
+ module.
+
A detailed description of each variable defined by the
+ module.
+
+
+
Each Class Documentation page contains:
+
+
A class inheritance diagram.
+
A list of known subclasses.
+
A description of the class.
+
A summary of the methods defined by the class.
+
A summary of the instance variables defined by the class.
+
A summary of the class (static) variables defined by the
+ class.
+
A detailed description of each method defined by the
+ class.
+
A detailed description of each instance variable defined by the
+ class.
+
A detailed description of each class (static) variable defined
+ by the class.
+
+
+
Project Documentation
+
+
The Trees page contains the module and class hierarchies:
+
+
The module hierarchy lists every package and module, with
+ modules grouped into packages. At the top level, and within each
+ package, modules and sub-packages are listed alphabetically.
+
The class hierarchy lists every class, grouped by base
+ class. If a class has more than one base class, then it will be
+ listed under each base class. At the top level, and under each base
+ class, classes are listed alphabetically.
+
+
+
The Index page contains indices of terms and
+ identifiers:
+
+
The term index lists every term indexed by any object's
+ documentation. For each term, the index provides links to each
+ place where the term is indexed.
+
The identifier index lists the (short) name of every package,
+ module, class, method, function, variable, and parameter. For each
+ identifier, the index provides a short description, and a link to
+ its documentation.
+
+
+
The Table of Contents
+
+
The table of contents occupies the two frames on the left side of
+the window. The upper-left frame displays the project
+contents, and the lower-left frame displays the module
+contents:
+
+
+
+
+
+ Project Contents...
+
+ API Documentation Frame
+
+
+
+
+ Module Contents ...
+
+
+
+
+
+
The project contents frame contains a list of all packages
+and modules that are defined by the project. Clicking on an entry
+will display its contents in the module contents frame. Clicking on a
+special entry, labeled "Everything," will display the contents of
+the entire project.
+
+
The module contents frame contains a list of every
+submodule, class, type, exception, function, and variable defined by a
+module or package. Clicking on an entry will display its
+documentation in the API documentation frame. Clicking on the name of
+the module, at the top of the frame, will display the documentation
+for the module itself.
+
+
The "frames" and "no frames" buttons below the top
+navigation bar can be used to control whether the table of contents is
+displayed or not.
+
+
The Navigation Bar
+
+
A navigation bar is located at the top and bottom of every page.
+It indicates what type of page you are currently viewing, and allows
+you to go to related pages. The following table describes the labels
+on the navigation bar. Note that not some labels (such as
+[Parent]) are not displayed on all pages.
+
+
+
+
Label
+
Highlighted when...
+
Links to...
+
+
[Parent]
+
(never highlighted)
+
the parent of the current package
+
[Package]
+
viewing a package
+
the package containing the current object
+
+
[Module]
+
viewing a module
+
the module containing the current object
+
+
[Class]
+
viewing a class
+
the class containing the current object
+
[Trees]
+
viewing the trees page
+
the trees page
+
[Index]
+
viewing the index page
+
the index page
+
[Help]
+
viewing the help page
+
the help page
+
+
+
The "show private" and "hide private" buttons below
+the top navigation bar can be used to control whether documentation
+for private objects is displayed. Private objects are usually defined
+as objects whose (short) names begin with a single underscore, but do
+not end with an underscore. For example, "_x",
+"__pprint", and "epydoc.epytext._tokenize"
+are private objects; but "re.sub",
+"__init__", and "type_" are not. However,
+if a module defines the "__all__" variable, then its
+contents are used to decide which objects are private.
+
+
A timestamp below the bottom navigation bar indicates when each
+page was last updated.
test(HandlerClass=<class i2p.BaseHTTPServer.BaseHTTPRequestHandler at 0x00A...,
+ ServerClass=<class i2p.BaseHTTPServer.HTTPServer at 0x00A2D960>,
+ protocol='HTTP/1.0',
+ session='mytestxxx.i2p')
+
+
Test the HTTP request handler class.
+ This runs an I2P TCP server under SAM session 'session'. If a single
+ command line argument is given, the argument is used instead as the SAM
+ session name.
+
test(HandlerClass=<class i2p.CGIHTTPServer.CGIHTTPRequestHandler at 0x00A2D...,
+ ServerClass=<class i2p.BaseHTTPServer.HTTPServer at 0x00A2D960>,
+ session='mytestxxx.i2p')
+
+
Test the HTTP CGI request handler class.
+ This runs an I2P TCP server under SAM session 'session'. If a single
+ command line argument is given, the argument is used instead as the SAM
+ session name.
+
test(HandlerClass=<class i2p.SimpleHTTPServer.SimpleHTTPRequestHandler at 0...,
+ ServerClass=<class i2p.BaseHTTPServer.HTTPServer at 0x00A2D960>,
+ session='mytestxxx.i2p')
+
+
Test the HTTP simple request handler class.
+ This runs an I2P TCP server under SAM session 'session'. If a single
+ command line argument is given, the argument is used instead as the SAM
+ session name.
+
Checks whether a locally installed router is running. Does nothing
+ if successful, otherwise raises i2p.RouterError.
+ An I2P installation is located by using find(dir). The router.config
+ file is parsed for 'router.adminPort'. This port is queried to
+ determine whether the router is running.
+
+
+
+
+
+
+
find(dir=None)
+
+
Find the absolute path to a locally installed I2P router.
+ An I2P installation is located by looking in the environment I2P,
+ then in PATH, then in the dir argument given to the function. It looks
+ for startRouter.sh or startRouter.bat. Raises ValueError if an I2P
+ installation could not be located.
+
+
+
+
+
+
+
start(dir=None,
+ hidden=False)
+
+
Start a locally installed I2P router. Does nothing if the router has
+ already been started.
+
An I2P installation is located by using find(dir).
+ If hidden is True, do not show a terminal for the router.
+
+
+
+
+
+
+
stop(dir=None,
+ force=False)
+
+
Stop a locally installed I2P router, if it was started by the
+ current Python program. If force is True, stop the router even if it
+ was started by another process. Do nothing if force is False and the
+ router was started by another program.
+
The file 'router.config' is located using the same search process
+ used for find(dir). It is parsed for 'router.shutdownPassword' and
+ 'router.adminPort'. The router is shut down through the admin port.
+ Raises i2p.RouterError if the I2P router is running but cannot be
+ stopped. You must uncomment the 'router.shutdownPassword' line for this
+ command to work.
+
+
+
+
+
+
+
_parse_config(filename)
+
+ Return a dict with (name, value) items for the given I2P
+ configuration file.
+
+
+
+
+
+
+
_run_program(filename)
+
+ Runs the given program in a new process and new terminal.
+
+ Get a single packet. Blocks for up to timeout seconds if n > 0
+ and no packet is available (timeout=None means wait forever). If still
+ no packet is available, raises BlockError or Timeout. Returns the pair
+ (data, address). If peek is True, the data is not removed.
+
+
+
+
+
+
+
send(self,
+ s,
+ dest)
+
+ Send packet with contents s to given destination.
+
+
+
+
+Message-by-message communication with SAM through a single pysocket.
+_on_* messages are dispatched to msgobj.
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self,
+ addr,
+ msgobj)
+
+
+
_poll_loop(self)
+
+Polling loop for incoming messages.
+
+
_samdecode(self,
+ s)
+
+Given a SAM command, returns (a, b), where a is the string at the
+beginning of the command, and b is a dictionary of name, value pairs for
+the command.
+
+
check(self)
+
+Raise an error if terminal was closed, otherwise do nothing.
+
+
check_message(self,
+ kwargs)
+
+Raises an error if kwargs['RESULT'] != 'OK'.
on_message(self,
+ msg,
+ kwargs)
+
+Process a SAM message that was received.
+
+
queue_get(self,
+ q)
+
+Identical to q.get() unless a call to self.check() fails, in which
+case the waiting is cut short with an error.
+
+
send_message(self,
+ msg)
+
+Send a message to the SAM bridge.
+
+
+
+
+
+
+
Method Details
+
+
+
+
+
_poll_loop(self)
+
+ Polling loop for incoming messages.
+
+
+
+
+
+
+
_samdecode(self,
+ s)
+
+ Given a SAM command, returns (a, b), where a is the string at the
+ beginning of the command, and b is a dictionary of name, value pairs
+ for the command.
+
+
+
+
+
+
+
check(self)
+
+ Raise an error if terminal was closed, otherwise do nothing.
+
+
+
+
+
+
+
check_message(self,
+ kwargs)
+
+ Raises an error if kwargs['RESULT'] != 'OK'.
+
+
+
+
+
+
+
close(self)
+
+ Close the SAM terminal.
+
+
+
+
+
+
+
on_message(self,
+ msg,
+ kwargs)
+
+ Process a SAM message that was received. Dispatch to
+ self._on_MESSAGE_NAME(**kwargs).
+
+
+
+
+
+
+
queue_get(self,
+ q)
+
+ Identical to q.get() unless a call to self.check() fails, in which
+ case the waiting is cut short with an error.
+
+
+
+
+
+
+
send_message(self,
+ msg)
+
+ Send a message to the SAM bridge. A newline will be automatically
+ added if none is present.
+
recv(self,
+ n,
+ timeout,
+ peek,
+ waitall)
+
+Reads up to n bytes in a manner identical to socket.recv.
+
+
send(self,
+ s)
+
+Sends the string s, blocking if necessary.
+
+
+
+
+
+
+
Method Details
+
+
+
+
+
__len__(self)
+ (Length operator)
+
+ Current length of read buffer.
+
+
+
+
+
+
+
close(self)
+
+ Close the stream. Threadsafe.
+
+
+
+
+
+
+
recv(self,
+ n,
+ timeout=None,
+ peek=False,
+ waitall=False)
+
+ Reads up to n bytes in a manner identical to socket.recv. Blocks for
+ up to timeout seconds if n > 0 and no data is available
+ (timeout=None means wait forever). If still no data is available,
+ raises BlockError or Timeout. For a closed stream, recv will read the
+ data stored in the buffer until EOF, at which point the read data will
+ be truncated. If peek is True, the data is not removed. If waitall is
+ True, reads exactly n bytes, or raises BlockError or Timeout as
+ appropriate. Returns data.
+
+ Internal command, send data to stream id. Use Stream.send in your
+ code.
+
+
+
+
+
+
+
accept(self,
+ timeout=None)
+
+ Wait for incoming connection, and return a Stream object for it.
+
+
+
+
+
+
+
connect(self,
+ dest,
+ timeout=None)
+
+ Create a stream connected to remote destination 'dest'. The id is
+ random. If the timeout is exceeded, do NOT raise an error; rather,
+ return a Stream object with .didconnect set to False.
+
+ Like read(), but do not remove the data that is returned.
+
+
+
+
+
+
+
prepend(self,
+ s)
+
+ Prepend string data to the beginning of the buffer.
+
+
+
+
+
+
+
read(self,
+ n=None)
+
+ Read n bytes of data (or less if less data available) from the
+ beginning of the buffer. The data is removed. If n is omitted, read the
+ entire buffer.
+
Create a new socket. Argument session should be a session name -- if
+ the name has not yet been used, an I2P Destination will be created for
+ it, otherwise, the existing Destination will be re-used. An empty
+ session string causes a transient session to be created. Argument type
+ is one of SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW.
+ I2P configuration keyword arguments:
+
+
+ in_depth - depth of incoming tunnel (default 2)
+
+
+ out_depth - depth of outgoing tunnel (default 2)
+
+
+
A single session may be shared by more than one socket, if the
+ sockets are the same type, and if the sockets are created within the
+ same Python process. The socket objects are multithread-safe.
+ Examples:
+
+>>> a = i2p.socket('Alice', i2p.SOCK_STREAM)
+>>> b = i2p.socket('Bob', i2p.SOCK_DGRAM,
+in_depth=2, out_depth=5)
+ The created object behaves identically to a socket from module
+ socket, with the following exceptions:
+
+
+ I2P Destinations are used as address arguments [1].
+
+
+ bind is a no-op: sockets are always bound.
+
+
+ send* methods send all data and are non-blocking.
+
+
+
A given session name can only be open in a single Python program at
+ a time. If you need to overcome this limitation, consider patching
+ I2P.
+
[1]. Alternatively, a host name can be used as an address. It will
+ be resolved using hosts.txt.
+
For details on how to use socket objects, see
+ http://www.python.org/doc/current/lib/socket-objects.html
+ Make a session object (eg samclasses.StreamSession). Same arguments
+ as socket(). Return an existing session object if one has been
+ previously created under the given name.
+
+
+
+
+
+
+
_wrap_stream(stream,
+ parent_socket)
+
+ Wraps a Socket object around a samclasses.Stream object.
+
+
+
+
+Network error occurred within I2P. The error object is a 2-tuple:
+(errtag, errdesc). errtag is a SAM error string, errdesc is a human
+readable error description.
+
+
+
+
+
listen(self,
+ backlog)
+
+Listen for connections made to the socket.
+
+
makefile(self,
+ mode,
+ bufsize)
+
+Return a file object for the socket.
+
+
recv(self,
+ bufsize,
+ flags)
+
+Receive string data from the socket.
+
+
recvfrom(self,
+ bufsize,
+ flags)
+
+Like recv(), but returns a tuple (data, remoteaddr), where data is the
+string data received, and remoteaddr is the remote Destination.
+
+
send(self,
+ string,
+ flags)
+
+Sends string data to a remote Destination.
+
+
sendall(self,
+ string,
+ flags)
+
+Identical to send().
+
+
sendto(self,
+ string,
+ flags,
+ address)
+
+Send a packet to the given Destination.
+
+
setblocking(self,
+ flag)
+
+Set blocking or non-blocking mode for the socket.
+
+
settimeout(self,
+ value)
+
+Set a timeout for the socket.
+
+
_verify_connected(self,
+ needs_to_be_connected)
+
+Raise an error if socket is not a connected stream socket.
+
+
_verify_not_connected(self)
+
+Verify that the socket is not currently connected, and is not in the
+process of connecting.
+
+
_verify_open(self)
+
+Verify that the socket has not been closed.
+
+
_verify_stream(self)
+
+Raise an error if socket is not a SOCK_STREAM.
Accept an incoming connection. The socket must be type SOCK_STREAM,
+ and listen() must be called prior to this command. The return value is
+ (conn, remotedest), where conn is a new socket object made for the
+ connection, and remotedest is the remote Destination from which the
+ connection was made.
+ Example:
+
+>>> from i2p import socket
+>>> s = socket.socket('Alice', socket.SOCK_STREAM)
+>>> s.listen(10)
+ This prepares the server. Now accept an incoming connection:
+
+ If accept() is called on a socket that is in non-blocking mode or
+ has a timeout, i2p.socket.BlockError or i2p.socket.Timeout may be
+ raised. This indicates that no incoming connection is currently
+ available.
+
+
+
+
+
+
+
bind(self,
+ address)
+
+ Does nothing. Provided for compatibility with the Python socket
+ command bind(), which binds a server to a port.
+
+
+
+
+
+
+
close(self)
+
+ Closes the socket. It is an error to call any method other than
+ recv() or recvfrom() on a closed socket. For streams, the receive
+ methods return data that was received prior to the closing of the
+ socket. For datagram and raw sockets, the receive methods cannot be
+ used on a closed socket.
+
+
+
+
+
+
+
connect(self,
+ address)
+
+
Connect to a remote dest, identified in local SAM bridge's hosts
+ file as host 'address'.
+ For example:
+
+>>> s.connect('duck.i2p')
+
Alternatively, you can use a full base64 Destination:
+ Example:
+
+>>> s.connect('238797sdfh2k34kjh....AAAA')
+ If connect() is called on a socket that is in non-blocking mode or
+ has a timeout, i2p.socket.BlockError or i2p.socket.Timeout may be
+ raised. This indicates that the connection is still being initiated.
+ Use i2p.select.select() to determine when the connection is ready.
+
+
+
+
+
+
+
connect_ex(self,
+ address)
+
+ Like connect(), but return any error that is raised. Returns None if
+ no error is raised.
+
+
+
+
+
+
+
getpeername(self)
+
+ Get the remote Destination associated with the socket. This is
+ equivalent to s.remotedest, and is provided for compatibility with the
+ Python socket module.
+
+
+
+
+
+
+
getsockname(self)
+
+ Get the local Destination associated with the socket. This is
+ equivalent to s.dest, and is provided for compatibility with the Python
+ socket module.
+
+
+
+
+
+
+
gettimeout(self)
+
+ Get the timeout value.
+
+
+
+
+
+
+
listen(self,
+ backlog)
+
+ Listen for connections made to the socket. This method must be
+ called before accept(). The backlog argument specifies the maximum
+ number of queued incoming connections.
+
+
+
+
+
+
+
makefile(self,
+ mode='r',
+ bufsize=-1)
+
+ Return a file object for the socket. See socket.makefile() in the
+ Python documentation for more information.
+
+
+
+
+
+
+
recv(self,
+ bufsize,
+ flags=0)
+
+
Receive string data from the socket.
+
The maximum amount of data to be received is given by bufsize. If
+ bufsize is zero, this function returns an empty string immediately. If
+ bufsize is nonzero, this function blocks until at least one character
+ is available for reading. If the socket has been closed, an empty
+ string is returned as an end of file indicator.
+
If recv() is called on a socket that is in non-blocking mode or has
+ a timeout, i2p.socket.BlockError or i2p.socket.Timeout will be raised
+ if data is not available within the given timeframe.
+
For a datagram or raw socket, the first bufsize characters of the
+ packet are read, and the remainder of the packet is discarded. To read
+ the entire packet, use bufsize = -1.
+
For datagram and raw sockets, the packet may originate from any
+ Destination. Use recvfrom() with datagrams to determine the Destination
+ from which the packet was received.
+ The flags argument can be a bitwise OR of MSG_PEEK, MSG_WAITALL,
+ and/or MSG_DONTWAIT. MSG_PEEK indicates that any data read should not
+ be removed from the socket's incoming buffer. MSG_WAITALL indicates to
+ wait for exactly bufsize characters or an error. MSG_DONTWAIT indicates
+ that the recv() command should not block execution.
+
+
+
+
+
+
+
recvfrom(self,
+ bufsize,
+ flags=0)
+
+ Like recv(), but returns a tuple (data, remoteaddr), where data is
+ the string data received, and remoteaddr is the remote Destination.
+
+
+
+
+
+
+
send(self,
+ string,
+ flags=0)
+
+
Sends string data to a remote Destination.
+
For a stream, connect() must be called prior to send(). Once close()
+ is called, no further data can be sent, and the stream cannot be
+ re-opened.
+
For datagram and raw sockets, connect() only specifies a Destination
+ to which packets are sent to. send() will then send a packet to the
+ given Destination. connect() can be used multiple times.
+ The send() command never blocks execution. The flags argument is
+ ignored.
+
+
+
+
+
+
+
sendall(self,
+ string,
+ flags=0)
+
+ Identical to send().
+
+
+
+
+
+
+
sendto(self,
+ string,
+ flags,
+ address)
+
+
Send a packet to the given Destination.
+
Only valid for datagram and raw sockets. The address argument should
+ be either a name from the hosts file, or a base64 Destination.
+ The sendto() command never blocks execution. The flags argument is
+ ignored.
+
+
+
+
+
+
+
setblocking(self,
+ flag)
+
+
Set blocking or non-blocking mode for the socket.
+
If flag is True, any method called on the socket will hang until the
+ method has completed. If flag is False, all methods will raise
+ i2p.socket.BlockError() if they cannot complete instantly.
+ s.setblocking(False) is equivalent to s.settimeout(0);
+ s.setblocking(True) is equivalent to s.settimeout(None).
+
+
+
+
+
+
+
settimeout(self,
+ value)
+
+
Set a timeout for the socket.
+
The value argument should be a timeout value in seconds, or None.
+ None is equivalent to an infinite timeout.
+ A socket operation will raise a i2p.socket.Timeout if the operation
+ cannot complete within in the specified time limit.
+
A Tunnel relays connections from a 'receive' socket to one or more
+ 'send' sockets. The receive socket must be bound and listening. For
+ each incoming connection, a new send socket is created by calling
+ make_send(). Data is then exchanged between the created streams until
+ one socket is closed. nconnect is the maximum number of simultaneous
+ connections (-1 for infinite), and timeout is the time that a single
+ connection can last for (None allows a connection to last forever).
+
Sockets must accept stream traffic and support the Python socket
+ interface. A separate daemonic thread is created to manage the tunnel.
+ For high performance, make_send() should make a socket and connect in
+ non-blocking mode (you should catch and discard the socket.BlockError
+ or socket.error due to executing connect on a non-blocking socket).
+
Security Note: A firewall is needed to maintain the end user's
+ anonymity. An attacker could keep a tunnel socket open by pinging it
+ regularly. The accepted sockets from 'receive' must prevent this by
+ closing down eventually.
+ Socket errors do not cause the Tunnel to shut down.
+
+ A session named 'session' is created locally, for purposes of
+ routing to 'dest'. nconnect and timeout are the maximum number of
+ connections and maximum time per connection. All other arguments are
+ passed to socket.socket(). This call blocks until the tunnel is
+ ready.
+
+ nconnect and timeout are the maximum number of connections and
+ maximum time per connection. All other arguments are passed to
+ socket.socket(). This call blocks until the tunnel is ready.
+
+ Note: This is not a perfect inversion of __getitem__, because any
+ changed headers get stuck at the end of the raw-headers list rather
+ than where the altered header was.
+
+
+
+
+
+
+
get(self,
+ name,
+ default=None)
+
+
Get the header value for a name.
+ This is the normal interface: it returns a stripped version of the
+ header value for a given header name, or None if it doesn't exist. This
+ uses the dictionary version which finds the *last* such header.
+
+
+
+
+
+
+
getaddr(self,
+ name)
+
+
Get a single address from a header, as a tuple.
+ An example return value: ('Guido van Rossum',
+ 'guido@cwi.nl')
+
+
+
+
+
+
+
getaddrlist(self,
+ name)
+
+
Get a list of addresses from a header.
+ Retrieves a list of addresses from a header, where each address is a
+ tuple as returned by getaddr(). Scans all named headers, so it works
+ properly with multiple To: or Cc: headers for example.
+
+
+
+
+
+
+
getallmatchingheaders(self,
+ name)
+
+
Find all header lines matching a given header name.
+ Look through the list of headers and find all lines matching a given
+ header name (and their continuation lines). A list of the lines is
+ returned, without interpretation. If the header does not occur, an
+ empty list is returned. If the header occurs multiple times, all
+ occurrences are returned. Case is not important in the header name.
+
+
+
+
+
+
+
getdate(self,
+ name)
+
+
Retrieve a date field from a header.
+ Retrieves a date field from the named header, returning a tuple
+ compatible with time.mktime().
+
+
+
+
+
+
+
getdate_tz(self,
+ name)
+
+
Retrieve a date field from a header as a 10-tuple.
+ The first 9 elements make up a tuple compatible with time.mktime(),
+ and the 10th is the offset of the poster's time zone from GMT/UTC.
+
+
+
+
+
+
+
getfirstmatchingheader(self,
+ name)
+
+
Get the first header line matching name.
+ This is similar to getallmatchingheaders, but it returns only the
+ first matching header (and its continuation lines).
+
+
+
+
+
+
+
getheader(self,
+ name,
+ default=None)
+
+
Get the header value for a name.
+ This is the normal interface: it returns a stripped version of the
+ header value for a given header name, or None if it doesn't exist. This
+ uses the dictionary version which finds the *last* such header.
+
+
+
+
+
+
+
getheaders(self,
+ name)
+
+
Get all values for a header.
+ This returns a list of values for headers given more than once; each
+ value in the result list is stripped in the same way as the result of
+ getheader(). If the header is not given, return an empty list.
+
+
+
+
+
+
+
getrawheader(self,
+ name)
+
+
A higher-level interface to getfirstmatchingheader().
+ Return a string containing the literal text of the header but with
+ the keyword stripped. All leading, trailing and embedded whitespace is
+ kept in the string, however. Return None if the header does not
+ occur.
+
+
+
+
+
+
+
has_key(self,
+ name)
+
+ Determine whether a message contains the named header.
+
+
+
+
+
+
+
iscomment(self,
+ line)
+
+
Determine whether a line should be skipped entirely.
+ You may override this method in order to use Message parsing on
+ tagged data in RFC 2822-like formats that support embedded comments or
+ free-text data.
+
+
+
+
+
+
+
isheader(self,
+ line)
+
+
Determine whether a given line is a legal header.
+ This method should return the header name, suitably canonicalized.
+ You may override this method in order to use Message parsing on tagged
+ data in RFC 2822-like formats with special header formats.
+
+
+
+
+
+
+
islast(self,
+ line)
+
+
+Determine whether a line is a legal end of RFC 2822 headers.
+
+ You may override this method if your application wants to bend the
+ rules, e.g. to strip trailing whitespace, or to recognize MH template
+ separators ('--------'). For convenience (e.g. for code reading from
+ sockets) a line consisting of
+also matches.
+
+
+
+
+
+
+
+
items(self)
+
+
Get all of a message's headers.
+ Returns a list of name, value tuples.
+
+
+
+
+
+
+
keys(self)
+
+ Get all of a message's header field names.
+
+
+
+
+
+
+
readheaders(self)
+
+
Read header lines.
+
Read header lines up to the entirely blank line that terminates
+ them. The (normally blank) line that ends the headers is skipped, but
+ not included in the returned list. If a non-header line ends the
+ headers, (which is an error), an attempt is made to backspace over it;
+ it is never included in the returned list.
+ The variable self.status is set to the empty string if all went
+ well, otherwise it is an error message. The variable self.headers is a
+ completely uninterpreted list of lines contained in the header (so
+ printing them will reproduce the header exactly as it appears in the
+ file).
+
+
+
+
+
+
+
rewindbody(self)
+
+ Rewind the file to the start of the body (if seekable).
+
rfc822.Message:
+Represents a single RFC 2822-compliant message.
+
+
mimetools.Message:
+A derived class of rfc822.Message that knows about MIME headers and
+contains some hooks for decoding encoded and multipart messages.
+
+HTTP request handler base class.
+
+The following explanation of HTTP serves to guide you through the
+code as well as to expose any misunderstandings I may have about
+HTTP (so you don't need to read the code to figure out I'm wrong
+:-).
+
+HTTP (HyperText Transfer Protocol) is an extensible protocol on
+top of a reliable stream transport (e.g. TCP/IP). The protocol
+recognizes three parts to a request:
+
+1. One line identifying the request type and path
+2. An optional set of RFC-822-style headers
+3. An optional data part
+
+The headers and data are separated by a blank line.
+
+The first line of the request has the form
+
+<command> <path> <version>
+
+where <command> is a (case-sensitive) keyword such as GET or POST,
+<path> is a string containing path information for the request,
+and <version> should be the string "HTTP/1.0" or "HTTP/1.1".
+<path> is encoded using the URL encoding scheme (using %xx to signify
+the ASCII character with hex code xx).
+
+The specification specifies that lines are separated by CRLF but
+for compatibility with the widest range of clients recommends
+servers also handle LF. Similarly, whitespace in the request line
+is treated sensibly (allowing multiple spaces between components
+and allowing trailing whitespace).
+
+Similarly, for output, lines ought to be separated by CRLF pairs
+but most clients grok LF characters just fine.
+
+If the first line of the request has the form
+
+<command> <path>
+
+(i.e. <version> is left out) then this is assumed to be an HTTP
+0.9 request; this form has no optional headers and data part and
+the reply consists of just the data.
+
+The reply form of the HTTP 1.x protocol again has three parts:
+
+1. One line giving the response code
+2. An optional set of RFC-822-style headers
+3. The data
+
+Again, the headers and data are separated by a blank line.
+
+The response code line has the form
+
+<version> <responsecode> <responsestring>
+
+where <version> is the protocol version ("HTTP/1.0" or "HTTP/1.1"),
+<responsecode> is a 3-digit response code indicating success or
+failure of the request, and <responsestring> is an optional
+human-readable string explaining what the response code means.
+
+This server parses the request and the headers, and then calls a
+function specific to the request type (<command>). Specifically,
+a request SPAM will be handled by a method do_SPAM(). If no
+such method exists the server sends an error response to the
+client. If it exists, it is called with no arguments:
+
+do_SPAM()
+
+Note that the request name is case sensitive (i.e. SPAM and spam
+are different requests).
+
+The various request details are stored in instance variables:
+
+- client_address is the client IP address in the form (host,
+port);
+
+- command, path and version are the broken-down request line;
+
+- headers is an instance of mimetools.Message (or a derived
+class) containing the header information;
+
+- rfile is a file object open for reading positioned at the
+start of the optional input data part;
+
+- wfile is a file object open for writing.
+
+IT IS IMPORTANT TO ADHERE TO THE PROTOCOL FOR WRITING!
+
+The first thing to be written must be the response line. Then
+follow 0 or more header lines, then a blank line, and then the
+actual data (if any). The meaning of the header lines depends on
+the command executed by the server; in most cases, when data is
+returned, there should be at least one header line of the form
+
+Content-type: <type>/<subtype>
+
+where <type> and <subtype> should be registered MIME types,
+e.g. "text/html" or "text/plain".
+
+
+
+
+
+
+
+
Method Summary
+
+
address_string(self)
+
+Return the client address formatted for logging.
+
+
date_time_string(self)
+
+Return the current date and time formatted for a message header.
+
+
end_headers(self)
+
+Send the blank line ending the MIME headers.
+
+
handle(self)
+
+Handle multiple requests if necessary.
+ You normally don't need to override this method; see the class
+ __doc__ string for information on how to handle specific HTTP commands
+ such as GET and POST.
+
+
+
+
+
+
+
log_date_time_string(self)
+
+ Return the current time formatted for logging.
+
+
+
+
+
+
+
log_error(self,
+ *args)
+
+
Log an error.
+
This is called when a request cannot be fulfilled. By default it
+ passes the message on to log_message().
+
Arguments are the same as for log_message().
+ XXX This should go to the separate error log.
+
+
+
+
+
+
+
log_message(self,
+ format,
+ *args)
+
+
Log an arbitrary message.
+
This is used by all other logging functions. Override it if you have
+ specific logging wishes.
+
The first argument, FORMAT, is a format string for the message to be
+ logged. If the format string contains any % escapes requiring
+ parameters, they should be specified as subsequent arguments (it's just
+ like printf!).
+ The client host and current date/time are prefixed to every
+ message.
+
+
+
+
+
+
+
log_request(self,
+ code='-',
+ size='-')
+
+
Log an accepted request.
+ This is called by send_reponse().
+
+
+
+
+
+
+
parse_request(self)
+
+
Parse a request (internal).
+
The request should be stored in self.raw_requestline; the results
+ are in self.command, self.path, self.request_version and
+ self.headers.
+ Return True for success, False for failure; on failure, an error is
+ sent back.
+
+
+
+
+
+
+
send_error(self,
+ code,
+ message=None)
+
+
Send and log an error reply.
+
Arguments are the error code, and a detailed message. The detailed
+ message defaults to the short entry matching the response code.
+ This sends an error response (so it must be called before any output
+ has been generated), logs the error, and finally sends a piece of HTML
+ explaining the error to the user.
+
+
+
+
+
+
+
send_header(self,
+ keyword,
+ value)
+
+ Send a MIME header.
+
+
+
+
+
+
+
send_response(self,
+ code,
+ message=None)
+
+
Send the response header and log the response code.
+ Also send two standard headers with the server software version and
+ the current date.
+
Test whether self.path corresponds to a CGI script.
+
Return a tuple (dir, rest) if self.path requires running a CGI
+ script, None if not. Note that rest begins with a slash if it is not
+ empty.
+ The default implementation tests whether the path begins with one of
+ the strings in the list self.cgi_directories (and the next character is
+ a '/' or the end of the string).
+
+
+
+
+
+
+
is_executable(self,
+ path)
+
+ Test whether argument path is an executable file.
+
+
+
+
+
+
+
is_python(self,
+ path)
+
+ Test whether argument path is a Python script.
+
Simple HTTP request handler with GET and HEAD commands.
+
This serves files from the current directory and any of its
+subdirectories. It assumes that all files are plain text files unless
+they have the extension ".html" in which case it assumes they
+are HTML files.
+The GET and HEAD requests are identical except that the HEAD request
+omits the actual contents of the file.
+
+
+
+
+
+
+
Method Summary
+
+
copyfile(self,
+ source,
+ outputfile)
+
+Copy all data between two file objects.
The SOURCE argument is a file object open for reading (or anything
+ with a read() method) and the DESTINATION argument is a file object
+ open for writing (or anything with a write() method).
+ The only reason for overriding this would be to change the block
+ size or perhaps to replace newlines by CRLF -- note however that this
+ the default server uses this to copy binary data as well.
+
+
+
+
+
+
+
do_GET(self)
+
+ Serve a GET request.
+
+
+
+
+
+
+
do_HEAD(self)
+
+ Serve a HEAD request.
+
+
+
+
+
+
+
guess_type(self,
+ path)
+
+
Guess the type of a file.
+
Argument is a PATH (a filename).
+
Return value is a string of the form type/subtype, usable for a MIME
+ Content-type header.
+ The default implementation looks the file's extension up in the
+ table self.extensions_map, using text/plain as a default; however it
+ would be permissible (if slow) to look inside the data to make a better
+ guess.
+
+
+
+
+
+
+
list_directory(self,
+ path)
+
+
Helper to produce a directory listing (absent index.html).
+ Return value is either a file object, or None (indicating an error).
+ In either case, the headers are sent, making the interface the same as
+ for send_head().
+
+
+
+
+
+
+
send_head(self)
+
+
Common code for GET and HEAD commands.
+
This sends the response code and MIME headers.
+ Return value is either a file object (which has to be copied to the
+ outputfile by the caller unless the command was HEAD, and must be
+ closed by the caller under all circumstances), or None, in which case
+ the caller has nothing further to do.
+
+
+
+
+
+
+
translate_path(self,
+ path)
+
+
Translate a /-separated PATH to the local filename syntax.
+ Components that mean special things to the local file system (e.g.
+ drive or directory names) are ignored. (XXX They should probably be
+ diagnosed.)
+
This class is instantiated for each request to be handled. The
+constructor sets the instance variables request, client_address and
+server, and then calls the handle() method. To implement a specific
+service, all you need to do is to derive a class which defines a handle()
+method.
+The handle() method can find the request as self.request, the client
+address as self.client_address, and the server (in case it needs access
+to per-server information) as self.server. Since a separate instance is
+created for each request, the handle() method can define arbitrary other
+instance variariables.
+
+
+
+
+
+Base class for various socket-based server classes.
+
+Defaults to synchronous IP stream (i.e., TCP).
+
+Methods for the caller:
+
+- __init__(server_address, RequestHandlerClass)
+- serve_forever()
+- handle_request() # if you don't use serve_forever()
+- fileno() -> int # for select()
+
+Methods that may be overridden:
+
+- server_bind()
+- server_activate()
+- get_request() -> request, client_address
+- verify_request(request, client_address)
+- process_request(request, client_address)
+- close_request(request)
+- handle_error()
+
+Methods for derived classes:
+
+- finish_request(request, client_address)
+
+Class variables that may be overridden by derived classes or
+instances:
+
+- address_family
+- socket_type
+- request_queue_size (only for stream sockets)
+- allow_reuse_address
+
+Instance variables:
+
+- server_address
+- RequestHandlerClass
+- socket
+
This document contains the API (Application Programming Interface)
+documentation for this project. Documentation for the Python
+objects defined by the project is divided into separate pages for each
+package, module, and class. The API documentation also includes two
+pages containing information about the project as a whole: a trees
+page, and an index page.
+
+
Object Documentation
+
+
Each Package Documentation page contains:
+
+
A description of the package.
+
A list of the modules and sub-packages contained by the
+ package.
+
A summary of the classes defined by the package.
+
A summary of the functions defined by the package.
+
A summary of the variables defined by the package.
+
A detailed description of each function defined by the
+ package.
+
A detailed description of each variable defined by the
+ package.
+
+
+
Each Module Documentation page contains:
+
+
A description of the module.
+
A summary of the classes defined by the module.
+
A summary of the functions defined by the module.
+
A summary of the variables defined by the module.
+
A detailed description of each function defined by the
+ module.
+
A detailed description of each variable defined by the
+ module.
+
+
+
Each Class Documentation page contains:
+
+
A class inheritance diagram.
+
A list of known subclasses.
+
A description of the class.
+
A summary of the methods defined by the class.
+
A summary of the instance variables defined by the class.
+
A summary of the class (static) variables defined by the
+ class.
+
A detailed description of each method defined by the
+ class.
+
A detailed description of each instance variable defined by the
+ class.
+
A detailed description of each class (static) variable defined
+ by the class.
+
+
+
Project Documentation
+
+
The Trees page contains the module and class hierarchies:
+
+
The module hierarchy lists every package and module, with
+ modules grouped into packages. At the top level, and within each
+ package, modules and sub-packages are listed alphabetically.
+
The class hierarchy lists every class, grouped by base
+ class. If a class has more than one base class, then it will be
+ listed under each base class. At the top level, and under each base
+ class, classes are listed alphabetically.
+
+
+
The Index page contains indices of terms and
+ identifiers:
+
+
The term index lists every term indexed by any object's
+ documentation. For each term, the index provides links to each
+ place where the term is indexed.
+
The identifier index lists the (short) name of every package,
+ module, class, method, function, variable, and parameter. For each
+ identifier, the index provides a short description, and a link to
+ its documentation.
+
+
+
The Table of Contents
+
+
The table of contents occupies the two frames on the left side of
+the window. The upper-left frame displays the project
+contents, and the lower-left frame displays the module
+contents:
+
+
+
+
+
+ Project Contents...
+
+ API Documentation Frame
+
+
+
+
+ Module Contents ...
+
+
+
+
+
+
The project contents frame contains a list of all packages
+and modules that are defined by the project. Clicking on an entry
+will display its contents in the module contents frame. Clicking on a
+special entry, labeled "Everything," will display the contents of
+the entire project.
+
+
The module contents frame contains a list of every
+submodule, class, type, exception, function, and variable defined by a
+module or package. Clicking on an entry will display its
+documentation in the API documentation frame. Clicking on the name of
+the module, at the top of the frame, will display the documentation
+for the module itself.
+
+
The "frames" and "no frames" buttons below the top
+navigation bar can be used to control whether the table of contents is
+displayed or not.
+
+
The Navigation Bar
+
+
A navigation bar is located at the top and bottom of every page.
+It indicates what type of page you are currently viewing, and allows
+you to go to related pages. The following table describes the labels
+on the navigation bar. Note that not some labels (such as
+[Parent]) are not displayed on all pages.
+
+
+
+
Label
+
Highlighted when...
+
Links to...
+
+
[Parent]
+
(never highlighted)
+
the parent of the current package
+
[Package]
+
viewing a package
+
the package containing the current object
+
+
[Module]
+
viewing a module
+
the module containing the current object
+
+
[Class]
+
viewing a class
+
the class containing the current object
+
[Trees]
+
viewing the trees page
+
the trees page
+
[Index]
+
viewing the index page
+
the index page
+
[Help]
+
viewing the help page
+
the help page
+
+
+
The "show private" and "hide private" buttons below
+the top navigation bar can be used to control whether documentation
+for private objects is displayed. Private objects are usually defined
+as objects whose (short) names begin with a single underscore, but do
+not end with an underscore. For example, "_x",
+"__pprint", and "epydoc.epytext._tokenize"
+are private objects; but "re.sub",
+"__init__", and "type_" are not. However,
+if a module defines the "__all__" variable, then its
+contents are used to decide which objects are private.
+
+
A timestamp below the bottom navigation bar indicates when each
+page was last updated.
test(HandlerClass=<class i2p.BaseHTTPServer.BaseHTTPRequestHandler at 0x00A...,
+ ServerClass=<class i2p.BaseHTTPServer.HTTPServer at 0x00A2D960>,
+ protocol='HTTP/1.0',
+ session='mytestxxx.i2p')
+
+
Test the HTTP request handler class.
+ This runs an I2P TCP server under SAM session 'session'. If a single
+ command line argument is given, the argument is used instead as the SAM
+ session name.
+
test(HandlerClass=<class i2p.CGIHTTPServer.CGIHTTPRequestHandler at 0x00A2D...,
+ ServerClass=<class i2p.BaseHTTPServer.HTTPServer at 0x00A2D960>,
+ session='mytestxxx.i2p')
+
+
Test the HTTP CGI request handler class.
+ This runs an I2P TCP server under SAM session 'session'. If a single
+ command line argument is given, the argument is used instead as the SAM
+ session name.
+
test(HandlerClass=<class i2p.SimpleHTTPServer.SimpleHTTPRequestHandler at 0...,
+ ServerClass=<class i2p.BaseHTTPServer.HTTPServer at 0x00A2D960>,
+ session='mytestxxx.i2p')
+
+
Test the HTTP simple request handler class.
+ This runs an I2P TCP server under SAM session 'session'. If a single
+ command line argument is given, the argument is used instead as the SAM
+ session name.
+
Checks whether a locally installed router is running. Does nothing
+ if successful, otherwise raises i2p.RouterError.
+ An I2P installation is located by using find(dir). The router.config
+ file is parsed for 'router.adminPort'. This port is queried to
+ determine whether the router is running.
+
+
+
+
+
+
+
find(dir=None)
+
+
Find the absolute path to a locally installed I2P router.
+ An I2P installation is located by looking in the environment I2P,
+ then in PATH, then in the dir argument given to the function. It looks
+ for startRouter.sh or startRouter.bat. Raises ValueError if an I2P
+ installation could not be located.
+
+
+
+
+
+
+
start(dir=None,
+ hidden=False)
+
+
Start a locally installed I2P router. Does nothing if the router has
+ already been started.
+
An I2P installation is located by using find(dir).
+ If hidden is True, do not show a terminal for the router.
+
+
+
+
+
+
+
stop(dir=None,
+ force=False)
+
+
Stop a locally installed I2P router, if it was started by the
+ current Python program. If force is True, stop the router even if it
+ was started by another process. Do nothing if force is False and the
+ router was started by another program.
+
The file 'router.config' is located using the same search process
+ used for find(dir). It is parsed for 'router.shutdownPassword' and
+ 'router.adminPort'. The router is shut down through the admin port.
+ Raises i2p.RouterError if the I2P router is running but cannot be
+ stopped. You must uncomment the 'router.shutdownPassword' line for this
+ command to work.
+
Create a new socket. Argument session should be a session name -- if
+ the name has not yet been used, an I2P Destination will be created for
+ it, otherwise, the existing Destination will be re-used. An empty
+ session string causes a transient session to be created. Argument type
+ is one of SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW.
+ I2P configuration keyword arguments:
+
+
+ in_depth - depth of incoming tunnel (default 2)
+
+
+ out_depth - depth of outgoing tunnel (default 2)
+
+
+
A single session may be shared by more than one socket, if the
+ sockets are the same type, and if the sockets are created within the
+ same Python process. The socket objects are multithread-safe.
+ Examples:
+
+>>> a = i2p.socket('Alice', i2p.SOCK_STREAM)
+>>> b = i2p.socket('Bob', i2p.SOCK_DGRAM,
+in_depth=2, out_depth=5)
+ The created object behaves identically to a socket from module
+ socket, with the following exceptions:
+
+
+ I2P Destinations are used as address arguments [1].
+
+
+ bind is a no-op: sockets are always bound.
+
+
+ send* methods send all data and are non-blocking.
+
+
+
A given session name can only be open in a single Python program at
+ a time. If you need to overcome this limitation, consider patching
+ I2P.
+
[1]. Alternatively, a host name can be used as an address. It will
+ be resolved using hosts.txt.
+
For details on how to use socket objects, see
+ http://www.python.org/doc/current/lib/socket-objects.html
+
+
+
+Network error occurred within I2P. The error object is a 2-tuple:
+(errtag, errdesc). errtag is a SAM error string, errdesc is a human
+readable error description.
+
+
+
+
+
listen(self,
+ backlog)
+
+Listen for connections made to the socket.
+
+
makefile(self,
+ mode,
+ bufsize)
+
+Return a file object for the socket.
+
+
recv(self,
+ bufsize,
+ flags)
+
+Receive string data from the socket.
+
+
recvfrom(self,
+ bufsize,
+ flags)
+
+Like recv(), but returns a tuple (data, remoteaddr), where data is the
+string data received, and remoteaddr is the remote Destination.
+
+
send(self,
+ string,
+ flags)
+
+Sends string data to a remote Destination.
+
+
sendall(self,
+ string,
+ flags)
+
+Identical to send().
+
+
sendto(self,
+ string,
+ flags,
+ address)
+
+Send a packet to the given Destination.
+
+
setblocking(self,
+ flag)
+
+Set blocking or non-blocking mode for the socket.
+
+
settimeout(self,
+ value)
+
+Set a timeout for the socket.
Accept an incoming connection. The socket must be type SOCK_STREAM,
+ and listen() must be called prior to this command. The return value is
+ (conn, remotedest), where conn is a new socket object made for the
+ connection, and remotedest is the remote Destination from which the
+ connection was made.
+ Example:
+
+>>> from i2p import socket
+>>> s = socket.socket('Alice', socket.SOCK_STREAM)
+>>> s.listen(10)
+ This prepares the server. Now accept an incoming connection:
+
+ If accept() is called on a socket that is in non-blocking mode or
+ has a timeout, i2p.socket.BlockError or i2p.socket.Timeout may be
+ raised. This indicates that no incoming connection is currently
+ available.
+
+
+
+
+
+
+
bind(self,
+ address)
+
+ Does nothing. Provided for compatibility with the Python socket
+ command bind(), which binds a server to a port.
+
+
+
+
+
+
+
close(self)
+
+ Closes the socket. It is an error to call any method other than
+ recv() or recvfrom() on a closed socket. For streams, the receive
+ methods return data that was received prior to the closing of the
+ socket. For datagram and raw sockets, the receive methods cannot be
+ used on a closed socket.
+
+
+
+
+
+
+
connect(self,
+ address)
+
+
Connect to a remote dest, identified in local SAM bridge's hosts
+ file as host 'address'.
+ For example:
+
+>>> s.connect('duck.i2p')
+
Alternatively, you can use a full base64 Destination:
+ Example:
+
+>>> s.connect('238797sdfh2k34kjh....AAAA')
+ If connect() is called on a socket that is in non-blocking mode or
+ has a timeout, i2p.socket.BlockError or i2p.socket.Timeout may be
+ raised. This indicates that the connection is still being initiated.
+ Use i2p.select.select() to determine when the connection is ready.
+
+
+
+
+
+
+
connect_ex(self,
+ address)
+
+ Like connect(), but return any error that is raised. Returns None if
+ no error is raised.
+
+
+
+
+
+
+
getpeername(self)
+
+ Get the remote Destination associated with the socket. This is
+ equivalent to s.remotedest, and is provided for compatibility with the
+ Python socket module.
+
+
+
+
+
+
+
getsockname(self)
+
+ Get the local Destination associated with the socket. This is
+ equivalent to s.dest, and is provided for compatibility with the Python
+ socket module.
+
+
+
+
+
+
+
gettimeout(self)
+
+ Get the timeout value.
+
+
+
+
+
+
+
listen(self,
+ backlog)
+
+ Listen for connections made to the socket. This method must be
+ called before accept(). The backlog argument specifies the maximum
+ number of queued incoming connections.
+
+
+
+
+
+
+
makefile(self,
+ mode='r',
+ bufsize=-1)
+
+ Return a file object for the socket. See socket.makefile() in the
+ Python documentation for more information.
+
+
+
+
+
+
+
recv(self,
+ bufsize,
+ flags=0)
+
+
Receive string data from the socket.
+
The maximum amount of data to be received is given by bufsize. If
+ bufsize is zero, this function returns an empty string immediately. If
+ bufsize is nonzero, this function blocks until at least one character
+ is available for reading. If the socket has been closed, an empty
+ string is returned as an end of file indicator.
+
If recv() is called on a socket that is in non-blocking mode or has
+ a timeout, i2p.socket.BlockError or i2p.socket.Timeout will be raised
+ if data is not available within the given timeframe.
+
For a datagram or raw socket, the first bufsize characters of the
+ packet are read, and the remainder of the packet is discarded. To read
+ the entire packet, use bufsize = -1.
+
For datagram and raw sockets, the packet may originate from any
+ Destination. Use recvfrom() with datagrams to determine the Destination
+ from which the packet was received.
+ The flags argument can be a bitwise OR of MSG_PEEK, MSG_WAITALL,
+ and/or MSG_DONTWAIT. MSG_PEEK indicates that any data read should not
+ be removed from the socket's incoming buffer. MSG_WAITALL indicates to
+ wait for exactly bufsize characters or an error. MSG_DONTWAIT indicates
+ that the recv() command should not block execution.
+
+
+
+
+
+
+
recvfrom(self,
+ bufsize,
+ flags=0)
+
+ Like recv(), but returns a tuple (data, remoteaddr), where data is
+ the string data received, and remoteaddr is the remote Destination.
+
+
+
+
+
+
+
send(self,
+ string,
+ flags=0)
+
+
Sends string data to a remote Destination.
+
For a stream, connect() must be called prior to send(). Once close()
+ is called, no further data can be sent, and the stream cannot be
+ re-opened.
+
For datagram and raw sockets, connect() only specifies a Destination
+ to which packets are sent to. send() will then send a packet to the
+ given Destination. connect() can be used multiple times.
+ The send() command never blocks execution. The flags argument is
+ ignored.
+
+
+
+
+
+
+
sendall(self,
+ string,
+ flags=0)
+
+ Identical to send().
+
+
+
+
+
+
+
sendto(self,
+ string,
+ flags,
+ address)
+
+
Send a packet to the given Destination.
+
Only valid for datagram and raw sockets. The address argument should
+ be either a name from the hosts file, or a base64 Destination.
+ The sendto() command never blocks execution. The flags argument is
+ ignored.
+
+
+
+
+
+
+
setblocking(self,
+ flag)
+
+
Set blocking or non-blocking mode for the socket.
+
If flag is True, any method called on the socket will hang until the
+ method has completed. If flag is False, all methods will raise
+ i2p.socket.BlockError() if they cannot complete instantly.
+ s.setblocking(False) is equivalent to s.settimeout(0);
+ s.setblocking(True) is equivalent to s.settimeout(None).
+
+
+
+
+
+
+
settimeout(self,
+ value)
+
+
Set a timeout for the socket.
+
The value argument should be a timeout value in seconds, or None.
+ None is equivalent to an infinite timeout.
+ A socket operation will raise a i2p.socket.Timeout if the operation
+ cannot complete within in the specified time limit.
+
+
+
+
+
+
+
+
+
+
Property Details
+
+
+
+
+
dest
+Local I2P Destination of socket
+
+
+
+
session
+Session name
+
+
+
+
type
+Socket type: SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW.
+
A Tunnel relays connections from a 'receive' socket to one or more
+ 'send' sockets. The receive socket must be bound and listening. For
+ each incoming connection, a new send socket is created by calling
+ make_send(). Data is then exchanged between the created streams until
+ one socket is closed. nconnect is the maximum number of simultaneous
+ connections (-1 for infinite), and timeout is the time that a single
+ connection can last for (None allows a connection to last forever).
+
Sockets must accept stream traffic and support the Python socket
+ interface. A separate daemonic thread is created to manage the tunnel.
+ For high performance, make_send() should make a socket and connect in
+ non-blocking mode (you should catch and discard the socket.BlockError
+ or socket.error due to executing connect on a non-blocking socket).
+
Security Note: A firewall is needed to maintain the end user's
+ anonymity. An attacker could keep a tunnel socket open by pinging it
+ regularly. The accepted sockets from 'receive' must prevent this by
+ closing down eventually.
+ Socket errors do not cause the Tunnel to shut down.
+
+ A session named 'session' is created locally, for purposes of
+ routing to 'dest'. nconnect and timeout are the maximum number of
+ connections and maximum time per connection. All other arguments are
+ passed to socket.socket(). This call blocks until the tunnel is
+ ready.
+
+ nconnect and timeout are the maximum number of connections and
+ maximum time per connection. All other arguments are passed to
+ socket.socket(). This call blocks until the tunnel is ready.
+
+ Note: This is not a perfect inversion of __getitem__, because any
+ changed headers get stuck at the end of the raw-headers list rather
+ than where the altered header was.
+
+
+
+
+
+
+
get(self,
+ name,
+ default=None)
+
+
Get the header value for a name.
+ This is the normal interface: it returns a stripped version of the
+ header value for a given header name, or None if it doesn't exist. This
+ uses the dictionary version which finds the *last* such header.
+
+
+
+
+
+
+
getaddr(self,
+ name)
+
+
Get a single address from a header, as a tuple.
+ An example return value: ('Guido van Rossum',
+ 'guido@cwi.nl')
+
+
+
+
+
+
+
getaddrlist(self,
+ name)
+
+
Get a list of addresses from a header.
+ Retrieves a list of addresses from a header, where each address is a
+ tuple as returned by getaddr(). Scans all named headers, so it works
+ properly with multiple To: or Cc: headers for example.
+
+
+
+
+
+
+
getallmatchingheaders(self,
+ name)
+
+
Find all header lines matching a given header name.
+ Look through the list of headers and find all lines matching a given
+ header name (and their continuation lines). A list of the lines is
+ returned, without interpretation. If the header does not occur, an
+ empty list is returned. If the header occurs multiple times, all
+ occurrences are returned. Case is not important in the header name.
+
+
+
+
+
+
+
getdate(self,
+ name)
+
+
Retrieve a date field from a header.
+ Retrieves a date field from the named header, returning a tuple
+ compatible with time.mktime().
+
+
+
+
+
+
+
getdate_tz(self,
+ name)
+
+
Retrieve a date field from a header as a 10-tuple.
+ The first 9 elements make up a tuple compatible with time.mktime(),
+ and the 10th is the offset of the poster's time zone from GMT/UTC.
+
+
+
+
+
+
+
getfirstmatchingheader(self,
+ name)
+
+
Get the first header line matching name.
+ This is similar to getallmatchingheaders, but it returns only the
+ first matching header (and its continuation lines).
+
+
+
+
+
+
+
getheader(self,
+ name,
+ default=None)
+
+
Get the header value for a name.
+ This is the normal interface: it returns a stripped version of the
+ header value for a given header name, or None if it doesn't exist. This
+ uses the dictionary version which finds the *last* such header.
+
+
+
+
+
+
+
getheaders(self,
+ name)
+
+
Get all values for a header.
+ This returns a list of values for headers given more than once; each
+ value in the result list is stripped in the same way as the result of
+ getheader(). If the header is not given, return an empty list.
+
+
+
+
+
+
+
getrawheader(self,
+ name)
+
+
A higher-level interface to getfirstmatchingheader().
+ Return a string containing the literal text of the header but with
+ the keyword stripped. All leading, trailing and embedded whitespace is
+ kept in the string, however. Return None if the header does not
+ occur.
+
+
+
+
+
+
+
has_key(self,
+ name)
+
+ Determine whether a message contains the named header.
+
+
+
+
+
+
+
iscomment(self,
+ line)
+
+
Determine whether a line should be skipped entirely.
+ You may override this method in order to use Message parsing on
+ tagged data in RFC 2822-like formats that support embedded comments or
+ free-text data.
+
+
+
+
+
+
+
isheader(self,
+ line)
+
+
Determine whether a given line is a legal header.
+ This method should return the header name, suitably canonicalized.
+ You may override this method in order to use Message parsing on tagged
+ data in RFC 2822-like formats with special header formats.
+
+
+
+
+
+
+
islast(self,
+ line)
+
+
+Determine whether a line is a legal end of RFC 2822 headers.
+
+ You may override this method if your application wants to bend the
+ rules, e.g. to strip trailing whitespace, or to recognize MH template
+ separators ('--------'). For convenience (e.g. for code reading from
+ sockets) a line consisting of
+also matches.
+
+
+
+
+
+
+
+
items(self)
+
+
Get all of a message's headers.
+ Returns a list of name, value tuples.
+
+
+
+
+
+
+
keys(self)
+
+ Get all of a message's header field names.
+
+
+
+
+
+
+
readheaders(self)
+
+
Read header lines.
+
Read header lines up to the entirely blank line that terminates
+ them. The (normally blank) line that ends the headers is skipped, but
+ not included in the returned list. If a non-header line ends the
+ headers, (which is an error), an attempt is made to backspace over it;
+ it is never included in the returned list.
+ The variable self.status is set to the empty string if all went
+ well, otherwise it is an error message. The variable self.headers is a
+ completely uninterpreted list of lines contained in the header (so
+ printing them will reproduce the header exactly as it appears in the
+ file).
+
+
+
+
+
+
+
rewindbody(self)
+
+ Rewind the file to the start of the body (if seekable).
+
rfc822.Message:
+Represents a single RFC 2822-compliant message.
+
+
mimetools.Message:
+A derived class of rfc822.Message that knows about MIME headers and
+contains some hooks for decoding encoded and multipart messages.
+