py-wire http://www.sourceforge.net/projects/pywire/ =============================================================================== Table of Contents ================== 1 Introduction 2 License/Acknowledgments 3 Installation 4 Getting Started with the Library 5 More Advanced Use of the Library 6 Known Bugs 7 History 8 References 1 Introduction =============== py-wire is a pure Python library that implements the complete Wired protocol, both 1.0[1] and 1.1[2]. All available commands can be sent and all return types in the Wired RFCs are recognized. Both downloading and uploading files and entire directories are fully supported. If you have any problems using this library, please post a bug report on SourceForge. Likewise, questions about this library should be posted on the SourceForge messageboards. 2 Licenses/Acknowledgments ============================ py-wire is released under the MIT License, which gives you freedom to do pretty much anything you want with it as long as you include a copy of the license. Thanks to Axel Andersson for his design of the Wired protocol and server. Thanks to Trevor Perrin for his TLS Lite library, as well as the structure of this README. 3 Installation =============== Requirements: Python 2.3 or greater is required.[3] TLS Lite is requred, with 0.3.3 recommended.[4] I haven't used other versions, so I'm not sure if they work. Options: TLS Lite is a pure Python library, and the encryption that Wired uses is very processor intensive, so downloads and uploads will be very slow unless you have an additional library containing native encryption code, such as M2Crypto, cryptlib_py, or pycrypto (recommended). pycrypto is available in both source[5] and Windows binary format.[6] On Windows: Run the Windows installer. Anywhere else: Run 'setup.py install'. 4 Getting Started with the Library =================================== The library is designed to be fairly easy to use. The following three steps are necessary: 1) Import the library 2) Instantiate a new wire object 3) Connect to a server The Code that does this is: import wire test = wire.wire('wired.wbm') # Bookmark File test.connect() Alternatively, instead of passing a bookmark to the constructor, you can pass individual keyword arguments (see the .wbm file included in this distribution for which keyword arguments are accepted). You can pass both a bookmark and keyword arguments, and the keyword arguments will take precedence. After you have connected to the server, you can send any of the available commands to get information from the server, such as: test.getnews() test.download('/path/to/file/or/directory/on/server', '/local/path') test.upload('/local/file/or/directory/to/upload', '/server/path') To get a list of all available functions and related data structures: help(wire) 5 More Advanced Use of the Library =================================== If you plan on writing non-trivial applications with py-wire, you aren't going to just want to send commands. You'll also want to be able to process the servers response. For example, if you are writing a GUI library and you receive a private message, you are probably going to want to display that message somewhere on the screen where the user can see it. In order to do so, you need to create a callback function and pass it to the library. For example: 1 def showprivatemessage(wireconn, args): 2 # Include nice GUI code to print the message somewhere 3 4 import wire 5 test = wire.wire(host='127.0.0.1', callbacks = {305:showprivatemessage}) 6 test.connect() Some notes about the above process: Line 1: wireconn is the wire object that called this callback function args is a list of arguments that the server provided with its message. It's basically the server's response, less the first four characters (the response code), less the last character, and split by the ASCII field separator (0x1C) into a list of strings. In this case, args[0] is the id of the user who sent the message, and args[1] is the message itself. Line 5: callbacks are passed to the library as a dictionary with the key being an integer representing the server's response code, and the value being the function to call. There are some noninteger key callbacks that the library uses in certain circumstances, see help(wire) or the source code for more details. Also, note that server responses are handled in a separate thread. 6 Known Bugs ============= Doesn't support anonymous ciphers (not supported by TLS Lite) Not all exceptions are caught. If you find an uncaught exception, please post a description of the problem (including traceback if possible) on SourceForge. Not much documentation is currently available. The comments in the source code are probably your best bet. I'm happy to answer any questions on the SourceForge messageboard. If there is a need, I'll create more structured documentation at a later date. 7 History ========== 0.4 - 2004-09-26 - Major rewrite of the locking system, eliminating the need for explicit locking in most places - Make paths in bookmark (e.g. for queuefile) relative to the bookmark itself instead of the current directory - Don't save file or filelist caches in the queue file (pre-0.4 queue files should not be used without converting them first) - Signicant changes to user/group account and download/upload classes - Use simple dictionaries instead of classes for news posts and transfer information - Assign each wire a unique id - Change the default logging setup, with the option to log to a file as well 0.3.2 - 2004-09-12 - Upon disconnecting, add files in the server's queue back to the client queue - Make every possible attempt to associate a wirepath with every download, in order to ensure the size of every download can be determined - Minor utf8 encoding bugfix 0.3.1 - 2004-09-01 - Better designed queue processing and transfer functions - Fix infinite loop when trying to download the root directory - New functions to process the queues in new threads - Fix saving of queues that have functions - Use a single queue file instead of four separate files - Use container instead of attribute access for wireprivileges - Additional configuration options (loglevel, queuefile) - Fix return codes in some functions 0.3 - 2004-08-14 - Support Wired Protocol 1.1 (Wired RFC 2) - Keep track of server information (such as protocol version), and connection state - Keep track of users who left the server (or were banned or kicked) - Add wirechat class, now that chats have some attributes worth storing - Fix an UnboundLocalError in wire.gotclientleave 0.2.1 - 2004-08-02 - Break connect function into smaller components, allowing for callbacks for gotserverinfo, gotloginsucceeded, gotbanned, and gotloginfailed - Add anymessage callback as a catchall callback for any server message - Pass a flag to callbacks signifying whether the library had any problems with the server's message 0.2 - 2004-08-01 - Allow use of configuration file (with values overriden by keyword arguments) - Check that resumed download matches local file, instead of assuming it does - Save partial downloads as filename.wpf and only rename to filename if download is successful - Allow callables in upload and download queues - Add ability use given password hash instead of calculating one - Many stability improvements - Fix potential infinite loop when recurrent errors occur when uploading - Fix incomplete downloads when using savequeues inside downloadfinished or upload finished callbacks - Fix return codes on functions that send requests to server - Check that given chat, user, and account exist in related functions that send requests to the server 0.1 - 2004-07-26 - Initial public release 8 References ============= [1] http://www.zankasoftware.com/wired/rfc1.txt [2] http://www.zankasoftware.com/wired/rfc2.txt [3] http://www.python.org/ [4] http://trevp.net/tlslite/ [5] http://www.amk.ca/python/code/crypto.html [6] http://www.britishsteal.com/dist/