Latest doc updates

14 files changed, 178 insertions, 69 deletions

diff --git a/doc/index.rst b/doc/index.rst
index b680929..ec6bc69 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -21,37 +21,45 @@ Indices and tables
 API Documentation
 =================
 
+Front-end Modules
+-----------------
+These modules are the ones that you will need to use directly to implement a
+TFTP client or server.
+
 TFTPy Module
-------------
+~~~~~~~~~~~~
 .. automodule:: tftpy
    :members:
 
 tftpy.TftpClient
-----------------
+~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpClient
    :members:
 
+tftpy.TftpServer
+~~~~~~~~~~~~~~~~
+.. automodule:: tftpy.TftpServer
+   :members:
+
+Back-end Modules
+----------------
+
 tftpy.TftpPacketFactory
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpPacketFactory
    :members:
 
 tftpy.TftpPacketTypes
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpPacketTypes
    :members:
 
-tftpy.TftpServer
-----------------
-.. automodule:: tftpy.TftpServer
-   :members:
-
 tftpy.TftpShared
-----------------
+~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpShared
    :members:
 
 tftpy.TftpStates
-----------------
+~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpStates
    :members:
diff --git a/html/sphinx/_sources/index.txt b/html/sphinx/_sources/index.txt
index b680929..ec6bc69 100644
--- a/html/sphinx/_sources/index.txt
+++ b/html/sphinx/_sources/index.txt
@@ -21,37 +21,45 @@ Indices and tables
 API Documentation
 =================
 
+Front-end Modules
+-----------------
+These modules are the ones that you will need to use directly to implement a
+TFTP client or server.
+
 TFTPy Module
-------------
+~~~~~~~~~~~~
 .. automodule:: tftpy
    :members:
 
 tftpy.TftpClient
-----------------
+~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpClient
    :members:
 
+tftpy.TftpServer
+~~~~~~~~~~~~~~~~
+.. automodule:: tftpy.TftpServer
+   :members:
+
+Back-end Modules
+----------------
+
 tftpy.TftpPacketFactory
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpPacketFactory
    :members:
 
 tftpy.TftpPacketTypes
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpPacketTypes
    :members:
 
-tftpy.TftpServer
-----------------
-.. automodule:: tftpy.TftpServer
-   :members:
-
 tftpy.TftpShared
-----------------
+~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpShared
    :members:
 
 tftpy.TftpStates
-----------------
+~~~~~~~~~~~~~~~~
 .. automodule:: tftpy.TftpStates
    :members:
diff --git a/html/sphinx/_static/default.css b/html/sphinx/_static/default.css
index 42ed6ec..3725744 100644
--- a/html/sphinx/_static/default.css
+++ b/html/sphinx/_static/default.css
@@ -166,6 +166,18 @@ div.admonition p.admonition-title + p {
     display: inline;
 }
 
+div.admonition p {
+    margin-bottom: 5px;
+}
+
+div.admonition pre {
+    margin-bottom: 5px;
+}
+
+div.admonition ul, div.admonition ol {
+    margin-bottom: 5px;
+}
+
 div.note {
     background-color: #eee;
     border: 1px solid #ccc;
diff --git a/html/sphinx/genindex.html b/html/sphinx/genindex.html
index 67b8f85..fdda253 100644
--- a/html/sphinx/genindex.html
+++ b/html/sphinx/genindex.html
@@ -255,7 +255,7 @@
     </div>
     <div class="footer">
       &copy; Copyright 2010, Michael P. Soulier.
-      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.5.
     </div>
   </body>
 </html>
\ No newline at end of file
diff --git a/html/sphinx/index.html b/html/sphinx/index.html
index da3967a..c17336e 100644
--- a/html/sphinx/index.html
+++ b/html/sphinx/index.html
@@ -56,21 +56,30 @@
 </div>
 <div class="section" id="api-documentation">
 <h1>API Documentation<a class="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="front-end-modules">
+<h2>Front-end Modules<a class="headerlink" href="#front-end-modules" title="Permalink to this headline">¶</a></h2>
+<p>These modules are the ones that you will need to use directly to implement a
+TFTP client or server.</p>
 <div class="section" id="module-tftpy">
-<h2>TFTPy Module<a class="headerlink" href="#module-tftpy" title="Permalink to this headline">¶</a></h2>
+<h3>TFTPy Module<a class="headerlink" href="#module-tftpy" title="Permalink to this headline">¶</a></h3>
 <p>This library implements the tftp protocol, based on rfc 1350.
 <a class="reference external" href="http://www.faqs.org/rfcs/rfc1350.html">http://www.faqs.org/rfcs/rfc1350.html</a>
 At the moment it implements only a client class, but will include a server,
 with support for variable block sizes.</p>
+<p>As a client of tftpy, this is the only module that you should need to import
+directly. The TftpClient and TftpServer classes can be reached through it.</p>
 </div>
 <div class="section" id="module-tftpy.TftpClient">
-<h2>tftpy.TftpClient<a class="headerlink" href="#module-tftpy.TftpClient" title="Permalink to this headline">¶</a></h2>
-<p>This module implements the TFTP Client functionality.</p>
+<h3>tftpy.TftpClient<a class="headerlink" href="#module-tftpy.TftpClient" title="Permalink to this headline">¶</a></h3>
+<p>This module implements the TFTP Client functionality. Instantiate an
+instance of the client, and then use its upload or download method. Logging is
+performed via a standard logging object set in TftpShared.</p>
 <dl class="class">
 <dt id="tftpy.TftpClient.TftpClient">
 <em class="property">class </em><tt class="descclassname">tftpy.TftpClient.</tt><tt class="descname">TftpClient</tt><big>(</big><em>host</em>, <em>port</em>, <em>options={}</em><big>)</big><a class="headerlink" href="#tftpy.TftpClient.TftpClient" title="Permalink to this definition">¶</a></dt>
 <dd><p>This class is an implementation of a tftp client. Once instantiated, a
-download can be initiated via the download() method.</p>
+download can be initiated via the download() method, or an upload via the
+upload() method.</p>
 <dl class="method">
 <dt id="tftpy.TftpClient.TftpClient.download">
 <tt class="descname">download</tt><big>(</big><em>filename</em>, <em>output</em>, <em>packethook=None</em>, <em>timeout=5</em><big>)</big><a class="headerlink" href="#tftpy.TftpClient.TftpClient.download" title="Permalink to this definition">¶</a></dt>
@@ -88,13 +97,52 @@ wait for a receive packet to arrive.</p>
 <dl class="method">
 <dt id="tftpy.TftpClient.TftpClient.upload">
 <tt class="descname">upload</tt><big>(</big><em>filename</em>, <em>input</em>, <em>packethook=None</em>, <em>timeout=5</em><big>)</big><a class="headerlink" href="#tftpy.TftpClient.TftpClient.upload" title="Permalink to this definition">¶</a></dt>
-<dd>Note: If input is a hyphen then stdin is used.</dd></dl>
+<dd><p>This method initiates a tftp upload to the configured remote host,
+uploading the filename passed.  If a packethook is provided, it must
+be a function that takes a single parameter, which will be a copy of
+each DAT packet sent in the form of a TftpPacketDAT object. The
+timeout parameter may be used to override the default SOCK_TIMEOUT
+setting, which is the amount of time that the client will wait for a
+DAT packet to be ACKd by the server.</p>
+<p>Note: If output is a hyphen then stdout is used.</p>
+</dd></dl>
 
 </dd></dl>
 
 </div>
+<div class="section" id="module-tftpy.TftpServer">
+<h3>tftpy.TftpServer<a class="headerlink" href="#module-tftpy.TftpServer" title="Permalink to this headline">¶</a></h3>
+<p>This module implements the TFTP Server functionality. Instantiate an
+instance of the server, and then run the listen() method to listen for client
+requests. Logging is performed via a standard logging object set in
+TftpShared.</p>
+<dl class="class">
+<dt id="tftpy.TftpServer.TftpServer">
+<em class="property">class </em><tt class="descclassname">tftpy.TftpServer.</tt><tt class="descname">TftpServer</tt><big>(</big><em>tftproot='/tftpboot'</em>, <em>dyn_file_func=None</em><big>)</big><a class="headerlink" href="#tftpy.TftpServer.TftpServer" title="Permalink to this definition">¶</a></dt>
+<dd><p>This class implements a tftp server object. Run the listen() method to
+listen for client requests.  It takes two optional arguments. tftproot is
+the path to the tftproot directory to serve files from and/or write them
+to. dyn_file_func is a callable that must return a file-like object to
+read from during downloads. This permits the serving of dynamic
+content.</p>
+<dl class="method">
+<dt id="tftpy.TftpServer.TftpServer.listen">
+<tt class="descname">listen</tt><big>(</big><em>listenip=''</em>, <em>listenport=69</em>, <em>timeout=5</em><big>)</big><a class="headerlink" href="#tftpy.TftpServer.TftpServer.listen" title="Permalink to this definition">¶</a></dt>
+<dd>Start a server listening on the supplied interface and port. This
+defaults to INADDR_ANY (all interfaces) and UDP port 69. You can also
+supply a different socket timeout value, if desired.</dd></dl>
+
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="back-end-modules">
+<h2>Back-end Modules<a class="headerlink" href="#back-end-modules" title="Permalink to this headline">¶</a></h2>
 <div class="section" id="module-tftpy.TftpPacketFactory">
-<h2>tftpy.TftpPacketFactory<a class="headerlink" href="#module-tftpy.TftpPacketFactory" title="Permalink to this headline">¶</a></h2>
+<h3>tftpy.TftpPacketFactory<a class="headerlink" href="#module-tftpy.TftpPacketFactory" title="Permalink to this headline">¶</a></h3>
+<p>This module implements the TftpPacketFactory class, which can take a binary
+buffer, and return the appropriate TftpPacket object to represent it, via the
+parse() method.</p>
 <dl class="class">
 <dt id="tftpy.TftpPacketFactory.TftpPacketFactory">
 <em class="property">class </em><tt class="descclassname">tftpy.TftpPacketFactory.</tt><tt class="descname">TftpPacketFactory</tt><a class="headerlink" href="#tftpy.TftpPacketFactory.TftpPacketFactory" title="Permalink to this definition">¶</a></dt>
@@ -112,7 +160,7 @@ the network.</dd></dl>
 
 </div>
 <div class="section" id="module-tftpy.TftpPacketTypes">
-<h2>tftpy.TftpPacketTypes<a class="headerlink" href="#module-tftpy.TftpPacketTypes" title="Permalink to this headline">¶</a></h2>
+<h3>tftpy.TftpPacketTypes<a class="headerlink" href="#module-tftpy.TftpPacketTypes" title="Permalink to this headline">¶</a></h3>
 <p>This module implements the packet types of TFTP itself, and the
 corresponding encode and decode methods for them.</p>
 <dl class="class">
@@ -282,24 +330,9 @@ values.</dd></dl>
 code should be in this class.</dd></dl>
 
 </div>
-<div class="section" id="module-tftpy.TftpServer">
-<h2>tftpy.TftpServer<a class="headerlink" href="#module-tftpy.TftpServer" title="Permalink to this headline">¶</a></h2>
-<dl class="class">
-<dt id="tftpy.TftpServer.TftpServer">
-<em class="property">class </em><tt class="descclassname">tftpy.TftpServer.</tt><tt class="descname">TftpServer</tt><big>(</big><em>tftproot='/tftpboot'</em>, <em>dyn_file_func=None</em><big>)</big><a class="headerlink" href="#tftpy.TftpServer.TftpServer" title="Permalink to this definition">¶</a></dt>
-<dd><p>This class implements a tftp server object.</p>
-<dl class="method">
-<dt id="tftpy.TftpServer.TftpServer.listen">
-<tt class="descname">listen</tt><big>(</big><em>listenip=''</em>, <em>listenport=69</em>, <em>timeout=5</em><big>)</big><a class="headerlink" href="#tftpy.TftpServer.TftpServer.listen" title="Permalink to this definition">¶</a></dt>
-<dd>Start a server listening on the supplied interface and port. This
-defaults to INADDR_ANY (all interfaces) and UDP port 69. You can also
-supply a different socket timeout value, if desired.</dd></dl>
-
-</dd></dl>
-
-</div>
 <div class="section" id="module-tftpy.TftpShared">
-<h2>tftpy.TftpShared<a class="headerlink" href="#module-tftpy.TftpShared" title="Permalink to this headline">¶</a></h2>
+<h3>tftpy.TftpShared<a class="headerlink" href="#module-tftpy.TftpShared" title="Permalink to this headline">¶</a></h3>
+<p>This module holds all objects shared by all other modules in tftpy.</p>
 <dl class="class">
 <dt id="tftpy.TftpShared.TftpErrors">
 <em class="property">class </em><tt class="descclassname">tftpy.TftpShared.</tt><tt class="descname">TftpErrors</tt><a class="headerlink" href="#tftpy.TftpShared.TftpErrors" title="Permalink to this definition">¶</a></dt>
@@ -329,7 +362,16 @@ by refactoring.</dd></dl>
 
 </div>
 <div class="section" id="module-tftpy.TftpStates">
-<h2>tftpy.TftpStates<a class="headerlink" href="#module-tftpy.TftpStates" title="Permalink to this headline">¶</a></h2>
+<h3>tftpy.TftpStates<a class="headerlink" href="#module-tftpy.TftpStates" title="Permalink to this headline">¶</a></h3>
+<p>This module implements all state handling during uploads and downloads, the
+main interface to which being the TftpContext base class and the TftpState
+base class.</p>
+<p>The concept is simple. Each context object represents a single upload or
+download, and the state object in the context object represents the current
+state of that transfer. The state object has a handle() method that expects
+the next packet in the transfer, and returns a state object until the transfer
+is complete, at which point it returns None. That is, unless there is a fatal
+error, in which case a TftpException is returned instead.</p>
 <dl class="class">
 <dt id="tftpy.TftpStates.TftpContext">
 <em class="property">class </em><tt class="descclassname">tftpy.TftpStates.</tt><tt class="descname">TftpContext</tt><big>(</big><em>host</em>, <em>port</em>, <em>timeout</em>, <em>dyn_file_func=None</em><big>)</big><a class="headerlink" href="#tftpy.TftpStates.TftpContext" title="Permalink to this definition">¶</a></dt>
@@ -581,6 +623,7 @@ will commit to one of them once we interpret the initial packet.</p>
 
 </div>
 </div>
+</div>
 
 
           </div>
@@ -595,16 +638,22 @@ will commit to one of them once we interpret the initial packet.</p>
 </li>
 <li><a class="reference external" href="#indices-and-tables">Indices and tables</a></li>
 <li><a class="reference external" href="#api-documentation">API Documentation</a><ul>
+<li><a class="reference external" href="#front-end-modules">Front-end Modules</a><ul>
 <li><a class="reference external" href="#module-tftpy">TFTPy Module</a></li>
 <li><a class="reference external" href="#module-tftpy.TftpClient">tftpy.TftpClient</a></li>
+<li><a class="reference external" href="#module-tftpy.TftpServer">tftpy.TftpServer</a></li>
+</ul>
+</li>
+<li><a class="reference external" href="#back-end-modules">Back-end Modules</a><ul>
 <li><a class="reference external" href="#module-tftpy.TftpPacketFactory">tftpy.TftpPacketFactory</a></li>
 <li><a class="reference external" href="#module-tftpy.TftpPacketTypes">tftpy.TftpPacketTypes</a></li>
-<li><a class="reference external" href="#module-tftpy.TftpServer">tftpy.TftpServer</a></li>
 <li><a class="reference external" href="#module-tftpy.TftpShared">tftpy.TftpShared</a></li>
 <li><a class="reference external" href="#module-tftpy.TftpStates">tftpy.TftpStates</a></li>
 </ul>
 </li>
 </ul>
+</li>
+</ul>
 
             <h3>This Page</h3>
             <ul class="this-page-menu">
@@ -642,7 +691,7 @@ will commit to one of them once we interpret the initial packet.</p>
     </div>
     <div class="footer">
       &copy; Copyright 2010, Michael P. Soulier.
-      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.5.
     </div>
   </body>
 </html>
\ No newline at end of file
diff --git a/html/sphinx/modindex.html b/html/sphinx/modindex.html
index 18e890b..119f7f7 100644
--- a/html/sphinx/modindex.html
+++ b/html/sphinx/modindex.html
@@ -118,7 +118,7 @@
     </div>
     <div class="footer">
       &copy; Copyright 2010, Michael P. Soulier.
-      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.5.
     </div>
   </body>
 </html>
\ No newline at end of file
diff --git a/html/sphinx/search.html b/html/sphinx/search.html
index 59767e8..ff110ae 100644
--- a/html/sphinx/search.html
+++ b/html/sphinx/search.html
@@ -89,7 +89,7 @@
   
     <div class="footer">
       &copy; Copyright 2010, Michael P. Soulier.
-      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.5.
     </div>
   <script type="text/javascript" src="searchindex.js"></script>
 
diff --git a/html/sphinx/searchindex.js b/html/sphinx/searchindex.js
index befa8bb..d8056f8 100644
--- a/html/sphinx/searchindex.js
+++ b/html/sphinx/searchindex.js
@@ -1 +1 @@
-Search.setIndex({desctypes:{"0":"method","1":"exception","2":"class","3":"attribute","4":"function"},terms:{all:0,code:0,chain:0,tftpclient:0,last_upd:0,inaddr_ani:0,disk:0,readabl:0,send:0,sent:0,string:0,fals:0,faq:0,tftpstateserverstart:0,util:0,tri:0,tftpshare:0,tftppacketwrq:0,tftpexcept:0,setloglevel:0,list:0,upload:0,blocknumb:0,sync:0,pass:0,download:0,port:0,rrq:0,index:0,compar:0,section:0,tftppacketiniti:0,access:0,"new":0,method:0,next_block:0,full:0,gener:0,here:0,address:0,sinc:0,valu:0,wait:0,search:0,serveriniti:0,amount:0,loop:0,permit:0,action:0,implement:0,tftppacketdat:0,via:0,modul:0,filenam:0,api:0,sendack:0,opcod:0,from:0,next:0,call:0,value1:0,msg:0,type:0,more:0,diamond:0,desir:0,tftpstateserverrecvrrq:0,indic:0,must:0,none:0,valuen:0,setup:0,work:0,tftpsession:0,can:0,root:0,listenip:0,overrid:0,share:0,accept:0,alwai:0,end:0,goal:0,add_dup:0,negoti:0,opt1:0,updat:0,after:0,mai:0,tftppacketrrq:0,data:0,alloc:0,optn:0,stdin:0,explicit:0,correspond:0,caus:0,perform:0,order:0,tftpy:0,over:0,paramet:0,tftppackettyp:0,better:0,whether:0,wrq:0,them:0,"return":0,thei:0,handl:0,initi:0,dat:0,packethook:0,now:0,name:0,simpl:0,level:0,mode:0,timeout:0,each:0,found:0,mean:0,tftpcontextclientdownload:0,expect:0,out:0,variabl:0,network:0,content:0,suitabl:0,tftppacketack:0,tftpstateexpectdat:0,tftpcontextclientupload:0,base:0,dictionari:0,put:0,org:0,"byte":0,unwant:0,tftppacketwithopt:0,first:0,oper:0,directli:0,onc:0,number:0,alreadi:0,done:0,tftppacket:0,size:0,differ:0,unknown:0,messag:0,transitori:0,illeg:0,conveni:0,listen:0,udp:0,option:0,copi:0,specifi:0,part:0,pars:0,than:0,keyword:0,provid:0,tftpstateserverrecvwrq:0,cleaner:0,rfc1350:0,argument:0,raw:0,tftppacketoack:0,tabl:0,self:0,violat:0,note:0,also:0,take:0,which:0,notset:0,singl:0,buffer:0,object:0,"class":0,don:0,request:0,doe:0,getter:0,pkt:0,session:0,find:0,setter:0,current:0,onli:0,configur:0,should:0,dict:0,local:0,tftpassert:0,senddat:0,gethost:0,requir:0,resend:0,rfc:0,remot:0,common:0,contain:0,senderror:0,set:0,packet:0,see:0,result:0,respons:0,fail:0,tftpcontext:0,wire:0,hopefulli:0,someth:0,state:0,parent:0,cycl:0,entir:0,popul:0,tftpmetric:0,handleoack:0,instanc:0,context:0,tftp:0,point:0,instanti:0,hyphen:0,arriv:0,dispatch:0,suppli:0,tftpstatesentrrq:0,throughout:0,quit:0,compos:0,been:0,destructor:0,interpret:0,dup:0,"abstract":0,ani:0,those:0,ident:0,listenport:0,properti:0,defin:0,error:0,errmsg:0,pack:0,file:0,stdout:0,metric:0,itself:0,rport:0,welcom:0,receiv:0,make:0,same:0,html:0,decod:0,document:0,finish:0,http:0,tftpcontextserv:0,moment:0,rais:0,user:0,chang:0,appropri:0,off:0,checktimeout:0,inherit:0,client:0,thi:0,unchang:0,protocol:0,just:0,tftproot:0,easi:0,handledat:0,dyn_file_func:0,except:0,add:0,input:0,save:0,match:0,tftperror:0,know:0,opc:0,bit:0,specif:0,server:0,"boolean":0,either:0,output:0,page:0,www:0,some:0,intern:0,librari:0,subclass:0,condit:0,host:0,oack:0,"throw":0,socket:0,ack:0,tftpstatesentwrq:0,manag:0,datagram:0,commit:0,block:0,own:0,encod:0,exceed:0,log:0,transfer:0,support:0,start:0,tftpstateexpectack:0,interfac:0,includ:0,"function":0,form:0,regard:0,tftppacketfactori:0,sethost:0,raddress:0,sendoack:0,match_opt:0,"default":0,tftppacketerr:0,creat:0,dure:0,repres:0,exist:0,decode_opt:0,check:0,when:0,refactor:0,cleanup:0,sock_timeout:0,you:0,tftpstate:0,returnsupportedopt:0,tftpboot:0,tftpserver:0,time:0,errorcod:0},titles:["Welcome to TFTPy&#8217;s documentation!"],modules:{"tftpy.TftpServer":0,tftpy:0,"tftpy.TftpShared":0,"tftpy.TftpPacketTypes":0,"tftpy.TftpStates":0,"tftpy.TftpClient":0,"tftpy.TftpPacketFactory":0},descrefs:{"tftpy.TftpPacketFactory.TftpPacketFactory":{parse:[0,0]},"tftpy.TftpShared":{tftpassert:[0,4],setLogLevel:[0,4],TftpException:[0,1],TftpErrors:[0,2]},"tftpy.TftpStates.TftpContextServer":{start:[0,0],end:[0,0]},"tftpy.TftpStates":{TftpContextClientUpload:[0,2],TftpMetrics:[0,2],TftpContextServer:[0,2],TftpState:[0,2],TftpContextClientDownload:[0,2],TftpStateServerStart:[0,2],TftpStateServerRecvRRQ:[0,2],TftpStateExpectACK:[0,2],TftpStateSentWRQ:[0,2],TftpStateSentRRQ:[0,2],TftpStateExpectDAT:[0,2],TftpContext:[0,2],TftpStateServerRecvWRQ:[0,2]},"tftpy.TftpPacketFactory":{TftpPacketFactory:[0,2]},"tftpy.TftpServer":{TftpServer:[0,2]},"tftpy.TftpPacketTypes.TftpPacket":{encode:[0,0],decode:[0,0]},"tftpy.TftpStates.TftpContext":{end:[0,0],checkTimeout:[0,0],sethost:[0,0],host:[0,3],gethost:[0,0],cycle:[0,0]},"tftpy.TftpStates.TftpContextClientDownload":{start:[0,0],end:[0,0]},"tftpy.TftpServer.TftpServer":{listen:[0,0]},"tftpy.TftpStates.TftpMetrics":{add_dup:[0,0]},"tftpy.TftpStates.TftpStateServerRecvRRQ":{handle:[0,0]},"tftpy.TftpClient":{TftpClient:[0,2]},"tftpy.TftpStates.TftpStateExpectDAT":{handle:[0,0]},"tftpy.TftpStates.TftpStateExpectACK":{handle:[0,0]},"tftpy.TftpStates.TftpStateSentRRQ":{handle:[0,0]},"tftpy.TftpStates.TftpState":{sendError:[0,0],handle:[0,0],handleOACK:[0,0],handleDat:[0,0],serverInitial:[0,0],returnSupportedOptions:[0,0],sendACK:[0,0],sendOACK:[0,0],sendDAT:[0,0]},"tftpy.TftpStates.TftpStateServerStart":{handle:[0,0]},"tftpy.TftpStates.TftpStateSentWRQ":{handle:[0,0]},"tftpy.TftpStates.TftpContextClientUpload":{end:[0,0]},"tftpy.TftpPacketTypes.TftpPacketERR":{decode:[0,0],encode:[0,0]},"tftpy.TftpPacketTypes.TftpPacketInitial":{encode:[0,0]},"tftpy.TftpClient.TftpClient":{download:[0,0],upload:[0,0]},"tftpy.TftpPacketTypes":{TftpPacketDAT:[0,2],TftpPacketWRQ:[0,2],TftpPacketERR:[0,2],TftpSession:[0,2],TftpPacketWithOptions:[0,2],TftpPacketOACK:[0,2],TftpPacketACK:[0,2],TftpPacketRRQ:[0,2],TftpPacketInitial:[0,2],TftpPacket:[0,2]},"tftpy.TftpPacketTypes.TftpPacketWithOptions":{decode_options:[0,0]},"tftpy.TftpStates.TftpStateServerRecvWRQ":{handle:[0,0]},"tftpy.TftpPacketTypes.TftpPacketDAT":{encode:[0,0],decode:[0,0]},"tftpy.TftpPacketTypes.TftpPacketOACK":{match_options:[0,0]}},filenames:["index"]})
\ No newline at end of file
+Search.setIndex({desctypes:{"0":"method","1":"exception","2":"class","3":"attribute","4":"function"},terms:{all:0,concept:0,chain:0,tftpclient:0,code:0,last_upd:0,inaddr_ani:0,disk:0,readabl:0,send:0,fatal:0,sent:0,string:0,fals:0,faq:0,tftpstateserverstart:0,util:0,tri:0,tftpshare:0,tftppacketwrq:0,tftpexcept:0,setloglevel:0,list:0,upload:0,blocknumb:0,sync:0,pass:0,download:0,port:0,rrq:0,index:0,compar:0,section:0,tftppacketiniti:0,access:0,"new":0,method:0,next_block:0,full:0,gener:0,here:0,address:0,path:0,sinc:0,valu:0,wait:0,search:0,serveriniti:0,amount:0,loop:0,permit:0,action:0,implement:0,tftppacketdat:0,via:0,modul:0,filenam:0,api:0,sendack:0,opcod:0,from:0,two:0,next:0,call:0,value1:0,msg:0,type:0,until:0,more:0,diamond:0,desir:0,tftpstateserverrecvrrq:0,indic:0,hold:0,must:0,none:0,valuen:0,setup:0,work:0,tftpsession:0,can:0,root:0,listenip:0,overrid:0,share:0,accept:0,alwai:0,end:0,goal:0,add_dup:0,write:0,instead:0,negoti:0,opt1:0,updat:0,after:0,mai:0,tftppacketrrq:0,data:0,alloc:0,optn:0,stdin:0,explicit:0,correspond:0,caus:0,perform:0,callabl:0,order:0,tftpy:0,over:0,through:0,dynam:0,paramet:0,tftppackettyp:0,better:0,wrq:0,main:0,them:0,"return":0,thei:0,handl:0,initi:0,dat:0,packethook:0,front:0,now:0,name:0,simpl:0,level:0,mode:0,timeout:0,each:0,found:0,mean:0,tftpcontextclientdownload:0,expect:0,out:0,variabl:0,network:0,content:0,suitabl:0,tftppacketack:0,tftpstateexpectdat:0,tftpcontextclientupload:0,standard:0,base:0,dictionari:0,put:0,org:0,"byte":0,unwant:0,tftppacketwithopt:0,first:0,oper:0,directli:0,onc:0,number:0,alreadi:0,done:0,tftppacket:0,size:0,differ:0,unknown:0,messag:0,transitori:0,illeg:0,conveni:0,listen:0,udp:0,option:0,copi:0,specifi:0,part:0,pars:0,than:0,serv:0,keyword:0,remot:0,tftpstateserverrecvwrq:0,cleaner:0,rfc1350:0,argument:0,raw:0,tftppacketoack:0,tabl:0,need:0,self:0,violat:0,note:0,also:0,take:0,which:0,notset:0,singl:0,unless:0,buffer:0,object:0,reach:0,"class":0,don:0,request:0,doe:0,getter:0,pkt:0,session:0,find:0,setter:0,current:0,onli:0,configur:0,should:0,dict:0,local:0,tftpassert:0,senddat:0,gethost:0,requir:0,resend:0,rfc:0,provid:0,common:0,contain:0,senderror:0,set:0,packet:0,see:0,result:0,respons:0,fail:0,tftpcontext:0,wire:0,hopefulli:0,someth:0,state:0,"import":0,parent:0,cycl:0,entir:0,popul:0,tftpmetric:0,handleoack:0,instanc:0,context:0,tftp:0,point:0,instanti:0,hyphen:0,arriv:0,dispatch:0,suppli:0,tftpstatesentrrq:0,throughout:0,quit:0,compos:0,been:0,destructor:0,interpret:0,dup:0,dure:0,ani:0,those:0,"case":0,ident:0,listenport:0,properti:0,defin:0,error:0,errmsg:0,pack:0,decode_opt:0,stdout:0,metric:0,itself:0,rport:0,welcom:0,receiv:0,make:0,same:0,binari:0,html:0,decod:0,document:0,complet:0,finish:0,http:0,tftpcontextserv:0,moment:0,rais:0,user:0,chang:0,ackd:0,appropri:0,off:0,checktimeout:0,inherit:0,client:0,thi:0,unchang:0,protocol:0,just:0,tftproot:0,easi:0,handledat:0,dyn_file_func:0,except:0,add:0,cleanup:0,input:0,save:0,match:0,read:0,tftperror:0,know:0,opc:0,bit:0,like:0,specif:0,server:0,"boolean":0,either:0,output:0,page:0,www:0,some:0,back:0,intern:0,librari:0,subclass:0,condit:0,run:0,host:0,oack:0,"throw":0,socket:0,ack:0,tftpstatesentwrq:0,manag:0,datagram:0,commit:0,block:0,own:0,encod:0,exceed:0,log:0,transfer:0,support:0,start:0,tftpstateexpectack:0,interfac:0,includ:0,"function":0,form:0,regard:0,tftppacketfactori:0,sethost:0,raddress:0,sendoack:0,match_opt:0,whether:0,tftppacketerr:0,creat:0,"abstract":0,repres:0,exist:0,file:0,check:0,when:0,refactor:0,"default":0,other:0,sock_timeout:0,you:0,tftpstate:0,returnsupportedopt:0,directori:0,tftpboot:0,tftpserver:0,time:0,errorcod:0},titles:["Welcome to TFTPy&#8217;s documentation!"],modules:{"tftpy.TftpServer":0,tftpy:0,"tftpy.TftpShared":0,"tftpy.TftpPacketTypes":0,"tftpy.TftpStates":0,"tftpy.TftpClient":0,"tftpy.TftpPacketFactory":0},descrefs:{"tftpy.TftpPacketFactory.TftpPacketFactory":{parse:[0,0]},"tftpy.TftpShared":{tftpassert:[0,4],setLogLevel:[0,4],TftpException:[0,1],TftpErrors:[0,2]},"tftpy.TftpStates.TftpContextServer":{start:[0,0],end:[0,0]},"tftpy.TftpStates":{TftpContextClientUpload:[0,2],TftpMetrics:[0,2],TftpContextServer:[0,2],TftpState:[0,2],TftpContextClientDownload:[0,2],TftpStateServerStart:[0,2],TftpStateServerRecvRRQ:[0,2],TftpStateExpectACK:[0,2],TftpStateSentWRQ:[0,2],TftpStateSentRRQ:[0,2],TftpStateExpectDAT:[0,2],TftpContext:[0,2],TftpStateServerRecvWRQ:[0,2]},"tftpy.TftpPacketFactory":{TftpPacketFactory:[0,2]},"tftpy.TftpServer":{TftpServer:[0,2]},"tftpy.TftpPacketTypes.TftpPacket":{encode:[0,0],decode:[0,0]},"tftpy.TftpStates.TftpContext":{end:[0,0],checkTimeout:[0,0],sethost:[0,0],host:[0,3],gethost:[0,0],cycle:[0,0]},"tftpy.TftpStates.TftpContextClientDownload":{start:[0,0],end:[0,0]},"tftpy.TftpServer.TftpServer":{listen:[0,0]},"tftpy.TftpStates.TftpMetrics":{add_dup:[0,0]},"tftpy.TftpStates.TftpStateServerRecvRRQ":{handle:[0,0]},"tftpy.TftpClient":{TftpClient:[0,2]},"tftpy.TftpStates.TftpStateExpectDAT":{handle:[0,0]},"tftpy.TftpStates.TftpStateExpectACK":{handle:[0,0]},"tftpy.TftpStates.TftpStateSentRRQ":{handle:[0,0]},"tftpy.TftpStates.TftpState":{sendError:[0,0],handle:[0,0],handleOACK:[0,0],handleDat:[0,0],serverInitial:[0,0],returnSupportedOptions:[0,0],sendACK:[0,0],sendOACK:[0,0],sendDAT:[0,0]},"tftpy.TftpStates.TftpStateServerStart":{handle:[0,0]},"tftpy.TftpStates.TftpStateSentWRQ":{handle:[0,0]},"tftpy.TftpStates.TftpContextClientUpload":{end:[0,0]},"tftpy.TftpPacketTypes.TftpPacketERR":{decode:[0,0],encode:[0,0]},"tftpy.TftpPacketTypes.TftpPacketInitial":{encode:[0,0]},"tftpy.TftpClient.TftpClient":{download:[0,0],upload:[0,0]},"tftpy.TftpPacketTypes":{TftpPacketDAT:[0,2],TftpPacketWRQ:[0,2],TftpPacketERR:[0,2],TftpSession:[0,2],TftpPacketWithOptions:[0,2],TftpPacketOACK:[0,2],TftpPacketACK:[0,2],TftpPacketRRQ:[0,2],TftpPacketInitial:[0,2],TftpPacket:[0,2]},"tftpy.TftpPacketTypes.TftpPacketWithOptions":{decode_options:[0,0]},"tftpy.TftpStates.TftpStateServerRecvWRQ":{handle:[0,0]},"tftpy.TftpPacketTypes.TftpPacketDAT":{encode:[0,0],decode:[0,0]},"tftpy.TftpPacketTypes.TftpPacketOACK":{match_options:[0,0]}},filenames:["index"]})
\ No newline at end of file
diff --git a/tftpy/TftpClient.py b/tftpy/TftpClient.py
index 2362535..5fbe733 100644
--- a/tftpy/TftpClient.py
+++ b/tftpy/TftpClient.py
@@ -1,4 +1,6 @@
-"""This module implements the TFTP Client functionality."""
+"""This module implements the TFTP Client functionality. Instantiate an
+instance of the client, and then use its upload or download method. Logging is
+performed via a standard logging object set in TftpShared."""
 
 import time, types
 from TftpShared import *
@@ -7,10 +9,10 @@ from TftpStates import TftpContextClientDownload, TftpContextClientUpload
 
 class TftpClient(TftpSession):
     """This class is an implementation of a tftp client. Once instantiated, a
-    download can be initiated via the download() method."""
+    download can be initiated via the download() method, or an upload via the
+    upload() method."""
+
     def __init__(self, host, port, options={}):
-        """This constructor returns an instance of TftpClient, taking the
-        remote host, the remote port, and the filename to fetch."""
         TftpSession.__init__(self)
         self.context = None
         self.host = host
@@ -68,7 +70,15 @@ class TftpClient(TftpSession):
         log.info("Received %d duplicate packets" % metrics.dupcount)
 
     def upload(self, filename, input, packethook=None, timeout=SOCK_TIMEOUT):
-        """Note: If input is a hyphen then stdin is used."""
+        """This method initiates a tftp upload to the configured remote host,
+        uploading the filename passed.  If a packethook is provided, it must
+        be a function that takes a single parameter, which will be a copy of
+        each DAT packet sent in the form of a TftpPacketDAT object. The
+        timeout parameter may be used to override the default SOCK_TIMEOUT
+        setting, which is the amount of time that the client will wait for a
+        DAT packet to be ACKd by the server.
+
+        Note: If output is a hyphen then stdout is used."""
         # Open the input file.
         # FIXME: As of the state machine, this is now broken. Need to
         # implement with new state machine.
diff --git a/tftpy/TftpPacketFactory.py b/tftpy/TftpPacketFactory.py
index fae52d3..d689185 100644
--- a/tftpy/TftpPacketFactory.py
+++ b/tftpy/TftpPacketFactory.py
@@ -1,3 +1,7 @@
+"""This module implements the TftpPacketFactory class, which can take a binary
+buffer, and return the appropriate TftpPacket object to represent it, via the
+parse() method."""
+
 from TftpShared import *
 from TftpPacketTypes import *
 
diff --git a/tftpy/TftpServer.py b/tftpy/TftpServer.py
index 589a1f3..f943b93 100644
--- a/tftpy/TftpServer.py
+++ b/tftpy/TftpServer.py
@@ -1,3 +1,8 @@
+"""This module implements the TFTP Server functionality. Instantiate an
+instance of the server, and then run the listen() method to listen for client
+requests. Logging is performed via a standard logging object set in
+TftpShared."""
+
 import socket, os, re, time, random
 import select
 from TftpShared import *
@@ -6,14 +11,14 @@ from TftpPacketFactory import *
 from TftpStates import *
 
 class TftpServer(TftpSession):
-    """This class implements a tftp server object."""
+    """This class implements a tftp server object. Run the listen() method to
+    listen for client requests.  It takes two optional arguments. tftproot is
+    the path to the tftproot directory to serve files from and/or write them
+    to. dyn_file_func is a callable that must return a file-like object to
+    read from during downloads. This permits the serving of dynamic
+    content."""
 
     def __init__(self, tftproot='/tftpboot', dyn_file_func=None):
-        """Class constructor. It takes two optional arguments. tftproot is
-        the path to the tftproot directory to serve files from and/or write
-        them to. dyn_file_func is a callable that must return a file-like
-        object to read from during downloads. This permits the serving of
-        dynamic content."""
         self.listenip = None
         self.listenport = None
         self.sock = None
diff --git a/tftpy/TftpShared.py b/tftpy/TftpShared.py
index c39be7d..69ade90 100644
--- a/tftpy/TftpShared.py
+++ b/tftpy/TftpShared.py
@@ -1,3 +1,5 @@
+"""This module holds all objects shared by all other modules in tftpy."""
+
 import logging
 
 LOG_LEVEL = logging.NOTSET
@@ -10,10 +12,6 @@ TIMEOUT_RETRIES = 5
 DEF_TFTP_PORT = 69
 
 # Initialize the logger.
-#logging.basicConfig(
-#    level=LOG_LEVEL,
-#    format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
-#    datefmt='%m-%d %H:%M:%S')
 logging.basicConfig()
 # The logger used by this library. Feel free to clobber it with your own, if you like, as
 # long as it conforms to Python's logging.
diff --git a/tftpy/TftpStates.py b/tftpy/TftpStates.py
index a53fc01..103dbc0 100644
--- a/tftpy/TftpStates.py
+++ b/tftpy/TftpStates.py
@@ -1,3 +1,14 @@
+"""This module implements all state handling during uploads and downloads, the
+main interface to which being the TftpContext base class and the TftpState
+base class. 
+
+The concept is simple. Each context object represents a single upload or
+download, and the state object in the context object represents the current
+state of that transfer. The state object has a handle() method that expects
+the next packet in the transfer, and returns a state object until the transfer
+is complete, at which point it returns None. That is, unless there is a fatal
+error, in which case a TftpException is returned instead."""
+
 from TftpShared import *
 from TftpPacketTypes import *
 from TftpPacketFactory import *
diff --git a/tftpy/__init__.py b/tftpy/__init__.py
index 94335fe..b1400df 100644
--- a/tftpy/__init__.py
+++ b/tftpy/__init__.py
@@ -1,7 +1,11 @@
-"""This library implements the tftp protocol, based on rfc 1350.
+"""
+This library implements the tftp protocol, based on rfc 1350.
 http://www.faqs.org/rfcs/rfc1350.html
 At the moment it implements only a client class, but will include a server,
 with support for variable block sizes.
+
+As a client of tftpy, this is the only module that you should need to import
+directly. The TftpClient and TftpServer classes can be reached through it.
 """
 
 import sys