{ "info": { "author": "Brendan W. McAdams", "author_email": "bwmcadams@evilmonkeylabs.com", "bugtrack_url": null, "classifiers": [], "description": "===============\nSocketTornad.IO\n===============\n\nRelease 0.1.3\n^^^^^^^^^^^^^\n\nContributors\n------------\n- Brendan W. McAdams bwmcadams@evilmonkeylabs.com\n- `Matt Swanson `_\n\n\nLicense\n-------\n Copyright (c) 2010, Brendan W. McAdams & Novus Partners, Inc. \n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n\n\n\n\nImplementation of the `Socket.IO `_ Websocket\nemulation protocol in Python on top of the non-blocking\n`Tornado Web Framework `_. Socket.IO is\na JavaScript library for providing full emulation of Websockets for\nbrowsers which don't support it. While the client-side programmer\ncodes as if they have a constantly open bi-directional\ncommunication channel, Socket.IO will (if the browser doesn't\nsupport Websockets) use several fallback protocols to provide the\nbehavior. These fallback protocols require a negotiation between\nthe client and server to determine an agreeable protocol; the\n`reference implementation `_\nof the server is done in Node.JS which was less than agreeable to\nour needs. There are also implementations in Ruby Rack and Go but\nwe rejected those for simlar reasons to Node.JS.\n\nThis version is designed for making\n`Pythonistas `_\nhappy.\n\nImplementing SocketTornad.IO\n----------------------------\n\nAs a user your only major requirement is to subclass\n``tornad_io.socket_io.SocketIOHandler``. This base class provides\nTornado Handler logic for the entire Socket.IO protocol - it\nautomatically responds to protocol handshakes and notifies you of\nthree events, represented by Python methods on your class:\n\n\n1. ``on_open``: Called when a Socket.IO handshake completes\n successfully and a client is brought online. Gets a copy of the\n ``*args`` and ``**kwargs`` from the request... can be used for you\n as a user to do further authentication of the connection. By way of\n example, we lookup certain authorization information once a\n connection finishes and decide if we'll allow the connection to\n continue.\n **This is not a required method - you need not implement it if you don't care about it.**\n2. ``on_close``: Called when a Socket.IO connection is fully\n closed. Passes no arguments, but lets you do any cleanup of\n database handles, etc.\n **This is not a required method - you need not implement it if you don't care about it.**\n3. ``on_message``: The main method. This is invoked whenever the\n browser client sends a message. It is automatically decoded, and\n any JSON will be passed as a fully parsed Python object. This\n method receives a single argument of ``message`` which contains the\n parsed message. You can respond with the ``self.send`` method (see\n below)\n\nYou can send messages to the client by use of the ``self.send``\nmethod. This takes a single argument of ``message`` and transmits\nit to the client. If you pass a string it will be pased \"as is\" to\nthe browser; if you want to send JSON you should pass a ``dict``\nin, which will be JSON encoded and marked as JSON in the Socket.IO\nwire format. An Object is also acceptable as long as *simplejson*\nis able to encode it to JSON.\n\nThere *is* fallback code for the JSON import - if you don't have\n``simplejson`` installed it will import the ``json`` module (based\non ``simplejson``) which has been included with Python since 2.6\ninstead (thanks to `swanson `_ for the\npatch). However, the version of ``json`` which ships with Python\nlacks built in support for encoding ``decimal.Decimal`` objects,\nwhich is why we prefer (as specified in ``setup.py``)\n``simplejson >= 2.1``. If you do not have an appropriate version of\n``simplejson`` installed and try to send an object or ``dict``\ncontaining ``decimal.Decimal`` instances to the client, you may\nencounter errors.\n\nFor those of you who know Tornado already, do *not* call the\n``self.write`` method unless you want things to act weird.\n``self.write`` still (in the current iteration) sends raw data to\nthe client - but Socket.IO uses a wire format which requires\ncertain encoding. Anything you pass via ``self.write`` will likely\nnot be understood by the client.\n\nThis is an example handler:\n\n::\n\n class EchoHandler(SocketIOHandler):\n def on_open(self, *args, **kwargs):\n logging.info(\"Socket.IO Client connected with protocol '%s' {session id: '%s'}\" % (self.protocol, self.session.id))\n logging.info(\"Extra Data for Open: '%s'\" % (kwargs.get('extra', None)))\n \n def on_message(self, message):\n logging.info(\"[echo] %s\" % message)\n self.send(\"[echo] %s\" % message)\n \n def on_close(self):\n logging.info(\"Closing Socket.IO Client for protocol '%s'\" % (self.protocol))\n\nThis handler is meant to be simple: It merely echoes back any\nmessage it receives to the client. Were you to test this in your\nbrowser your console will reflect back what you send:\n\n::\n\n > socket.send(\"OMG! Ponies!\")\n [echo] OMG! Ponies!\n\n(In this case I have my test page set to print any messages to\n``console.log()``.)\n\nUseful properties\n-----------------\n\nEvery subclass of ``SocketIOHandler`` has a few useful properties\nattached to it:\n\n\n- ``protocol``: This is a string containing the name of the\n protocol currently being used to communicate with the client.\n- ``session``: This is a `Beaker `_\n Session object which can be used to track information about the\n connection in question. We use it internally to direct output to\n the right place in polling. Feel free to save your own data - just\n make sure to call ``self.session.save()`` if you modify it or your\n changes will be lost.\n\nConfiguring SocketTornad.IO\n---------------------------\n\nRoutes (e.g. how clients access you)\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIt is necessary in Tornado set up your 'resources' (known in some\nframeworks as 'routes') which define what paths are valid and what\ncontrollers handle the request. Because the paths Socket.IO uses to\nnegotiate the connection and speak (esp. in the fallback protocols)\nare hairy, we have instead created a ClassMethod on\n``SocketIOHandler`` which allows you to easily get the correct\nroute for your service:\n\n::\n\n echoRoute = EchoHandler.routes(\"echoTest\", \"(?P123)(?P.*)\", extraSep='/')\n\nThis returns the data structure which Tornado expects to configure\nitself, with all requests for '/echoTest' pointed at the\nEchoHandler class. For the curious, the structure returned looks\nlike this:\n\n::\n\n ('/(?PechoTest)/(?P(?P123)(?P.*))/(?P(websocket|xhr-multipart|htmlfile|jsonp-polling|flashsocket|xhr-polling))/?(?P[0-9a-zA-Z]*?)/?((?P\\\\d*?)|(?P\\\\w*?))/?(?P\\\\d*?)', )\n\nHence the ``routes`` classmethod to easily configure with...\n``resource`` can be any valid string, including, if necessary, a\nRegular Expression. Any requests beginning with your ``resource``\nparameter will be routed to ``EchoHandler`` for processing. The\nadditional cruft in there are regular expressions to handle the\nmyriad of extra path information Socket.IO ships to find a valid\nprotocol.\n\nWe also accept two additional optional parameters to configure\nroutes (only the ``resource`` parameter is required).\n\n\n- ``extraRE`` is an optional string containing a regular\n expression for 'extra' information to capture on the URL. In my\n case, I have a PHP process pass an authenticated secure token to\n the Tornado process on each request to help identify and authorize\n a user. I pass this as part of the Socket.IO ``resource`` - while\n my Tornado resource is configured as 'echoTest', I want to capture\n and separate the additional secure token. By setting up an\n ``extraRE`` SocketTornad.IO will automatically save the extra data\n in ``**kwargs['extra']`` - specifically accessible in ``on_open``\n for further authentication. You *MAY* put capture groups inside\n ``extraRE`` - if you name them they are available from ``on_open``\n in ``**kwargs``, otherwise they will be in unnamed buckets inside\n of ``*args*``.\n\n- ``extraSep`` indicates a character to separate the 'base'\n ``resource`` and ``extraRE`` with. By default there is none - they\n are expected to run together. I typically set ``extraSep`` to a '/'\n character.\n\n\nAfter that you simply need to pass the configured route to\nTornado:\n\n::\n\n application = tornado.web.Application([\n echoRoute\n ])\n\nService Settings (ports, etc)\n-----------------------------\n\nYou can configure the service very easily by passing arguments into\nthe Tornado application object. There are currently 4 user\nconfigurable properties:\n\n\n- **enabled\\_protocols**: This is a ``list`` of the Socket.IO\n protocols the server will respond to requests for. Clients try them\n one by one until the server and client both find one they both\n support. The possibilities are:\n- *websocket*: Standard HTML5 Spec Websockets. Our implementation\n uses the one built into Tornado with a slight tweak to message\n receipt to enable decoding of the special Socket.IO wire encoding\n format. (Works in Chrome and any other browser with native\n Websocket support)\n- *flashsocket*: HTML5 Websockets emulated in Flash for older\n browsers like Firefox. *EXACTLY* the same implementation wise to\n *websocket*, but starts up a Flash policy server which is necessary\n for Flash sockets to work. (Tested in IE8, and Firefox 3)\n- *xhr-multipart*: XMLHTTPRequest (AJAX) Multipart messaging.\n Opens and long polls a GET request to send from server to client,\n client sends a POST to send client to server. Uses multipart &\n chunking to send a continuous stream of messages down the same open\n GET channel. Best option after *websocket*/*flashsocket*. (Tested\n in IE8, Firefox 3 and Chrome)\n- *xhr-polling*: XMLHTTPRequest (AJAX) Long Polling. Client polls\n on a GET until a message is available, closes the GET after getting\n a message and then opens a new one until a message is available.\n (Tested in IE8, Firefox 3 - does NOT work with Chrome at all)\n- *jsonp-polling*: Identical protocol to *xhr-polling* but pushes\n Javascript script data via JSONp. (Tested in IE8, Firefox 3 - does\n NOT work with Chrome at all)\n- *htmlfile*: Appears to be for much older IE browsers w/o proper\n AJAX support, creates an AJAX HTMLFile control and does some iframe\n nastiness. I haven't found a browser that properly supports this so\n if you test it let me know ... Copied implementation from reference\n Node code.\n\nThe default setting is to enable *ALL* protocols, i.e.:\n\n::\n\n ['websocket', 'flashsocket', 'xhr-multipart', 'xhr-polling', 'jsonp-polling', 'htmlfile']\n\n\n- **socket\\_io\\_port**: The port for the Socket IO Server to\n listen on.\n *This configuration setting is ignored unless you explicitly use the ``SocketIOServer`` class to start Tornado (See below).*\n- **flash\\_policy\\_file** A fully qualified path to a Flash Policy\n XML File. A default permissive one is included in this distribution\n as ``flashpolicy.xml``; by default the Flash service looks for\n ``flashpolicy.xml`` in the same directory as the current execution.\n *This configuration setting is ignored unless you explicitly use the ``SocketIOServer`` class to start Tornado (See below).*\n- **flash\\_policy\\_port** The port for the Flash policy server to\n listen on. This defaults to port **843** - Flash absolutely\n *will not* connect to any other port so if you change this, make\n sure you setup a portmap on the frontend. Without a valid policy\n service Flash fallback sockets will not work.\n *This configuration setting is ignored unless you explicitly use the ``SocketIOServer`` class to start Tornado (See below).*\n\nConfiguring these settings is done by passing them to the\n``tornado.web.Application`` constructor as kwargs:\n\n::\n\n application = tornado.web.Application([\n echoRoute \n ], enabled_protocols=['websocket', 'flashsocket', 'xhr-multipart', 'xhr-polling'],\n flash_policy_port=8043, flash_policy_file='/etc/lighttpd/flashpolicy.xml', socket_io_port=8888)\n\nStarting Up\n-----------\n\nBest Way: SocketIOServer\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe SocketTornad.IO distribution contains a modified version of the\nTornado ``HTTPServer`` class designed to automatically read the\nnecessary configuration settings and start everything up. If\n``flashsocket`` is enabled it will start the Flash Policy server,\nand it starts the Socket.IO Service for you (as opposed to you\nstarting it up manually).\n\nAssuming you set the configuration options on your ``Application``\ninstance (or are happy with the defaults) you need merely\ninstantiate a ``tornad_io.SocketIOServer``:\n\n::\n\n if __name__ == \"__main__\":\n socketio_server = SocketIOServer(application)\n\nStarting Manually\n^^^^^^^^^^^^^^^^^\n\nIf you'd like more control over how you start everything up you can\nstart things manually, similar to the\n`Tornado Docs `_. This\nrequires booting the IOLoop yourself:\n\n::\n\n if __name__ == \"__main__\":\n flash_policy = tornad_io.websocket.flash.FlashPolicyServer(port=8043, policy_file=\"/etc/lighttpd/flashpolicy.xml\")\n http_server = tornado.httpserver.HTTPServer(application)\n http_server.listen(8888)\n tornado.ioloop.IOLoop.instance().start()\n\nExamples\n--------\n\nChatroom Example\n^^^^^^^^^^^^^^^^\n\nThere is a chatroom example application contributed by\n`swanson `_. It is in the\n``examples/chatroom`` directory. For instructions, please see its\n`README `_.", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://github.com/SocketTornadIO/SocketTornad.IO", "keywords": null, "license": "Copyright (c) 2010, Brendan W. McAdams & Novus Partners, Inc. \n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.", "maintainer": null, "maintainer_email": null, "name": "SocketTornad.IO", "package_url": "https://pypi.org/project/SocketTornad.IO/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/SocketTornad.IO/", "project_urls": { "Download": "UNKNOWN", "Homepage": "http://github.com/SocketTornadIO/SocketTornad.IO" }, "release_url": "https://pypi.org/project/SocketTornad.IO/0.1.3/", "requires_dist": null, "requires_python": null, "summary": "Python implementation of the Socket.IO protocol for the Tornado webserver/framework.", "version": "0.1.3" }, "last_serial": 785688, "releases": { "0.1.0": [], "0.1.1": [ { "comment_text": "", "digests": { "md5": "cfe0ff74d28a5d811070f03a8a48b1c9", "sha256": "85bce4303a56e8e2b7270020acd7a785f051d979cf79cda80661e3fe38f46770" }, "downloads": -1, "filename": "SocketTornad.IO-0.1.1.tar.gz", "has_sig": false, "md5_digest": "cfe0ff74d28a5d811070f03a8a48b1c9", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13413, "upload_time": "2010-10-04T18:34:45", "url": "https://files.pythonhosted.org/packages/ae/39/4ea3222e9ffeb120319b5a249ed26f71f444a11a5937fffe7425f11e5a13/SocketTornad.IO-0.1.1.tar.gz" } ], "0.1.2": [ { "comment_text": "", "digests": { "md5": "9d2792a18c0a7ce8b3c0e60c169025a8", "sha256": "c7fed6c4f387a55074a7779a0b98be8c139bfc12a2700ec331553f8fc868c521" }, "downloads": -1, "filename": "SocketTornad.IO-0.1.2.tar.gz", "has_sig": false, "md5_digest": "9d2792a18c0a7ce8b3c0e60c169025a8", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9346, "upload_time": "2010-10-04T22:12:28", "url": "https://files.pythonhosted.org/packages/a3/3b/29045035ba4df99b3390276c83746c993e3a57ac0da07970537e4a366914/SocketTornad.IO-0.1.2.tar.gz" } ], "0.1.3": [ { "comment_text": "", "digests": { "md5": "f11af0c58cae60f3b34cb4f9dfcb5e88", "sha256": "49e2226882beedf4366ee15b99fb1114594872ca18a614341b5b04122bfdd629" }, "downloads": -1, "filename": "SocketTornad.IO-0.1.3.tar.gz", "has_sig": false, "md5_digest": "f11af0c58cae60f3b34cb4f9dfcb5e88", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19890, "upload_time": "2010-10-14T21:52:18", "url": "https://files.pythonhosted.org/packages/12/39/e28687ab1239d41850b74be26f27e4c3754b223bb08d33595500ec413b25/SocketTornad.IO-0.1.3.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "f11af0c58cae60f3b34cb4f9dfcb5e88", "sha256": "49e2226882beedf4366ee15b99fb1114594872ca18a614341b5b04122bfdd629" }, "downloads": -1, "filename": "SocketTornad.IO-0.1.3.tar.gz", "has_sig": false, "md5_digest": "f11af0c58cae60f3b34cb4f9dfcb5e88", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19890, "upload_time": "2010-10-14T21:52:18", "url": "https://files.pythonhosted.org/packages/12/39/e28687ab1239d41850b74be26f27e4c3754b223bb08d33595500ec413b25/SocketTornad.IO-0.1.3.tar.gz" } ] }