Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add some documentation

  • Loading branch information...
commit 45117418b7569f80a9a9612db6b9c2c1b8ef6b6a 1 parent cf24ec7
@jcollie authored
View
1  .gitignore
@@ -4,5 +4,6 @@
.\#*
/build
/dist
+/doc
/MANIFEST
/_trial_temp
View
17 README.markdown
@@ -37,5 +37,22 @@ examples/simple_udp_query.py):
query_response.addErrback(printerror)
reactor.run()
+Running the Examples
+--------------------
+
+The example code can be run like this:
+
+ PYTHONPATH=src python examples/simple_udp_query.py
+
+Generating API Documentation
+----------------------------
+
+From the root of the source tree run this command:
+
+ PYTHONPATH=src epydoc --html txdnspython
+
+You'll need [epydoc][3] installed of course.
+
[1]: http://www.dnspython.org/ "dnspython"
[2]: http://twistedmatrix.com/ "Twisted"
+[3]: http://epydoc.sourceforge.net/ "epydoc"
View
65 src/txdnspython/generic.py
@@ -30,11 +30,51 @@
class GenericDnsClientProtocol(object):
def __init__(self, reactor, one_rr_per_rrset):
+ """
+ Initialize.
+
+ @param reactor: reactor to use to schedule delayed calls (used to implement timeouts)
+ @type reactor: object that implements L{twisted.internet.interfaces.IReactorTime}
+ @param one_rr_per_rrset: put each RR into its own RRset
+ @type one_rr_per_rrset: C{bool}
+ """
+
self.reactor = reactor
+ """
+ Object that implements
+ L{twisted.internet.interfaces.IReactorTime} - used to schedule
+ delayed calls to implement timeouts.
+ """
+
self.one_rr_per_rrset = one_rr_per_rrset
+ """Whether to put each RR into its own RRset"""
+
self.pending = {}
+ """
+ L{dict} for keeping track of queries that have been sent to
+ the remote nameserver but have not been responded to. The
+ dictionary is indexed by the C{id} parameter of the
+ L{dns.message.Message} object (the query ID). The values are
+ tuples of L{dns.message.Message},
+ L{twisted.internet.defer.Deferred}, and
+ L{twisted.internet.base.DelayedCall} (or C{None} if there is
+ no timeout associated with the query).
+ """
def _process_response(self, wire_data):
+ """
+ Process the raw data retrieved from the remote name server.
+ Match up the response with the original query and fire the
+ L{twisted.internet.defer.Deferred} that is associated with the
+ query. Cancel the L{twisted.internet.base.DelayedCall} that
+ may be associated with the query as well.
+
+ @param wire_data: the raw data received from the remote DNS
+ server, after removing any framing that may be required by the
+ underlying transport.
+ @type wire_data: C{str}
+ """
+
(query_id,) = struct.unpack('!H', wire_data[:2])
if query_id not in self.pending:
@@ -58,6 +98,25 @@ def _process_response(self, wire_data):
query_response.errback(failure.Failure(BadResponse()))
def _send_query(self, wire_data, query, query_response, timeout):
+ """
+ Actually send the query over the wire and handle bookeeping.
+
+ @param wire_data: the raw data that is to be sent over the
+ wire, created by calling to_wire() on the query object, plus
+ any framing that may be needed by the underlying transport.
+ @type wire_data: C{str}
+
+ @param query: the query
+ @type query: L{dns.message.Message}
+
+ @param query_response: a deferred that will be fired when a
+ response is available or a failure has occurred.
+ @type query_response: L{twisted.internet.defer.Deferred}
+
+ @param timeout: The number of seconds to wait before the query
+ times out. If C{None}, the default, wait forever.
+ @type timeout: C{float}
+ """
if timeout:
if timeout <= 0:
query_response.errback(dms.exception.Timeout)
@@ -72,6 +131,12 @@ def _send_query(self, wire_data, query, query_response, timeout):
self.transport.write(wire_data)
def _timeout(self, query_id):
+ """Callback used to implement request timeouts.
+
+ @param query_id: the ID of the query that timed out.
+ @type query_id: C{int}
+ """
+
if self.pending.has_key(query_id):
query, query_response, delayed_call = self.pending.pop(query_id)
query_response.errback(failure.Failure(dns.exception.Timeout()))
View
16 src/txdnspython/tcp.py
@@ -91,19 +91,29 @@ def buildProtocol(self, addr):
class TcpDnsClient(object):
def __init__(self, reactor, address, port = 53, one_rr_per_rrset = False, source = '', source_port = 0):
- """Initialize the client object.
+ """
+ Initialize the client object.
- @param reactor: reactor
- @type reactor: twisted.internet.ReactorBase or subclass
+ @param reactor: Twisted reactor - used to open TCP connections and schedule timeouts
+ @type reactor: object that implements
+ L{twisted.internet.interfaces.IReactorTCP} (used to open TCP
+ connections to DNS servers) and
+ L{twisted.internet.interfaces.IReactorTime} (used to schedule
+ timeouts)
+
@param address: where to send the message
@type address: string containing an IPv4 address
+
@param port: The port to which to send the message. The default is 53.
@type port: int
+
@param source: source address. The default is the IPv4 wildcard address.
@type source: string
+
@param source_port: The port from which to send the message.
The default is 0.
@type source_port: int
+
@param one_rr_per_rrset: Put each RR into its own RRset
@type one_rr_per_rrset: bool
"""
Please sign in to comment.
Something went wrong with that request. Please try again.