{
    "info": {
        "author": "Ian Epperson",
        "author_email": "ian@epperson.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Environment :: Other Environment",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Topic :: Communications",
            "Topic :: Communications :: BBS",
            "Topic :: Software Development :: Libraries :: Python Modules",
            "Topic :: System :: Shells",
            "Topic :: Terminals",
            "Topic :: Terminals :: Telnet"
        ],
        "description": "telnetsrvlib\n============\n\nTelnet server using gevent or threading.\n\nCopied from http://pytelnetsrvlib.sourceforge.net/\nand modified to support gevent, better input handling, clean asynchronous messages and much more.\nLicensed under the LGPL, as per the SourceForge notes.\n\nThis library allows you to easily create a Telnet server, powered by your Python code.\nThe library negotiates with a Telnet client, parses commands, provides an automated \nhelp command, optionally provides login queries, then allows you to define your own\ncommands.\n\nYou use the library to create your own handler, then pass that handler to a StreamServer\nor TCPServer to perform the actual connection tasks.\n\nThis library includes two flavors of the server handler, one uses separate threads,\nthe other uses greenlets (green pseudo-threads) via gevent.\n\nThe threaded version uses a separate thread to process the input buffer and\nsemaphores reading and writing.  The provided test server only handles a single\nconnection at a time.\n\nThe green version moves the input buffer processing into a greenlet to allow \ncooperative multi-processing.  This results in significantly less memory usage\nand nearly no idle processing.  The provided test server handles a large number of connections.\n\n\nInstall\n-------\n\ntelnetsrv is available through the Cheeseshop.  You can use easy_install or pip to perform the installation.\n\n:: \n\n easy_install telnetsrv\n\nor\n\n::\n\n pip install telnetsrv\n\nNote that there are no dependancies defined, but if you want to use the green version, you must also install gevent.\n\nTo Use\n------\n\nImport the ``TelnetHandler`` base class and ``command`` function decorator from either the green class or threaded class, \nthen subclass ``TelnetHandler`` to add your own commands which are methods decorated with ``@command``.  \n\nThreaded\n++++++++\n\n.. code:: python\n\n from telnetsrv.threaded import TelnetHandler, command\n class MyHandler(TelnetHandler):\n    ...\n\nGreen\n+++++\n\n.. code:: python\n\n from telnetsrv.green import TelnetHandler, command\n class MyHandler(TelnetHandler):\n    ...\n\nAdding Commands\n---------------\n\nCommands can be defined by using the ``command`` function decorator.\n\n.. code:: python\n\n  @command('echo')\n  def command_echo(self, params):\n     ...\n\nOld Style\n+++++++++\n\nCommands can also be defined by prefixing any method with \"cmd\".  For example, \nthis also creates an ``echo`` command:\n\n.. code:: python\n\n  def cmdECHO(self, params):\n     ...\n\n*This method is less flexible and may not be supported in future versions.*\n\nCommand Parameters\n++++++++++++++++++\n\nAny command parameters will be passed to this function automatically.  The parameters are\ncontained in a list.  The user input is parsed similar to the way Bash parses text: space delimited,\nquoted parameters are kept together and default behavior can be modified with the ``\\`` character.  \nIf you need to access the raw text input, inspect the self.input.raw variable.\n\n::\n\n   Telnet Server> echo 1  \"2    3\"\n\n.. code:: python\n\n  params == ['1', '2    3']\n  self.input.raw == 'echo 1 \"2    3\"\\n'\n\n::\n\n    Telnet Server> echo 1 \\\n    ... 2 \"3\n    ... 4\"  \"5\\\n    ... 6\"\n    \n.. code:: python\n\n  params == ['1', '2', '3\\n4', '56']\n\n::\n\n    Telnet Server> echo 1\\ 2\n    \n.. code:: python\n\n  params == ['1 2']\n\nCommand Help Text\n+++++++++++++++++\n\nThe command's docstring is used for generating the console help information, and must be formatted\nwith at least 3 lines:\n\n- Line 0:  Command parameter(s) if any. (Can be blank line)\n- Line 1:  Short descriptive text. (Mandatory)\n- Line 2+: Long descriptive text. (Can be blank line)\n\nIf there is no line 2, line 1 will be used for the long description as well.\n\n.. code:: python\n\n   @command('echo')\n   def command_echo(self, params):\n       '''<text to echo>\n       Echo text back to the console.\n       This command simply echos the provided text\n       back to the console.\n       '''\n       pass\n\n\n::\n\n    Telnet Server> help\n    ? [<command>] - Display help\n    BYE - Exit the command shell\n    ECHO <text to echo> - Echo text back to the console.\n    ...\n\n\n    Telnet Server> help echo\n    ECHO <text to echo>\n\n    This command simply echos the provided text\n    back to the console.\n    Telnet Server>\n\n\nCommand Aliases\n+++++++++++++++\n\nTo create an alias for the new command, set the method's name to a list:\n\n.. code:: python\n\n  @command(['echo', 'copy'])\n  def command_echo(self, params):\n     ...\n\nThe decorator may be stacked, which adds each list to the aliases:\n\n.. code:: python\n\n  @command('echo')\n  @command(['copy', 'repeat'])\n  @command('ditto')\n  def command_echo(self, params):\n     ...\n\n\n\nHidden Commands\n+++++++++++++++\n\nTo hide the command (and any alias for that command) from the help text output, pass in hidden=True to the decorator:\n\n.. code:: python\n\n  @command('echo', hidden=True)\n  def command_echo(self, params):\n     ...\n\nThe command will not show when the user invokes ``help`` by itself, but the detailed help text will show if\nthe user invokes ``help echo``.\n\nWhen stacking decorators, any one of the stack may define the hidden parameter to hide the command.\n\nConsole Information\n-------------------\n\nThese will be provided for inspection.\n\n``TERM``\n  String ID describing the currently connected terminal\n  \n``username``\n  Set after authentication succeeds, name of the logged in user.\n  If no authentication was requested, will be ``None``.\n  \n``history``\n  List containing the command history.  This can be manipulated directly.\n  \n\n.. code:: python\n\n    @command('info')\n    def command_info(self, params):\n        '''\n        Provides some information about the current terminal.\n        '''\n        self.writeresponse( \"Username: %s, terminal type: %s\" % (self.username, self.TERM) )\n        self.writeresponse( \"Command history:\" )\n        for c in self.history:\n            self.writeresponse(\"  %r\" % c)\n\n\nConsole Communication\n---------------------\n\nSend Text to the Client\n+++++++++++++++++++++++\n \nLower level functions:\n\n``self.writeline( TEXT )``\n\n``self.write( TEXT )``\n\nHigher level functions:\n\n``self.writemessage( TEXT )`` - for clean, asynchronous writing.  Any interrupted input is rebuilt.\n\n``self.writeresponse( TEXT )`` - to emit a line of expected output\n\n``self.writeerror( TEXT )`` - to emit error messages\n\nThe writemessage method is intended to send messages to the console without\ninterrupting any current input.  If the user has entered text at the prompt, \nthe prompt and text will be seamlessly regenerated following the message.  \nIt is ideal for asynchronous messages that aren't generated from the direct user input.\n\nReceive Text from the Client\n++++++++++++++++++++++++++++\n\n``self.readline( prompt=TEXT )``\n\nSetting the prompt is important to recreate the user input following a ``writemessage``\ninterruption.\n\nWhen requesting sensative information from the user (such as requesting a password) the input should\nnot be shown nor should it have access to or be written to the command history.  ``readline`` accepts\ntwo optional parameters to control this, ``echo`` and ``user_history``.\n\n``self.readline( prompt=TEXT, echo=False, use_history=False )``\n\n\nHandler Options\n---------------\n\nOverride these class members to change the handler's behavior.\n\n``logging``\n  Default: pass\n\n``PROMPT``\n  Default: ``\"Telnet Server> \"``\n    \n``CONTINUE_PROMPT``\n  Default: ``\"... \"``\n     \n``WELCOME``\n  Displayed after a successful connection, after the username/password is accepted, if configured.\n  \n  Default: ``\"You have connected to the telnet server.\"``\n\n``session_start(self)``\n  Called after the ``WELCOME`` text is displayed.\n  \n  Default:  pass\n    \n``session_end(self)``\n  Called after the console is disconnected.\n  \n  Default:  pass\n  \n``authCallback(self, username, password)`` \n  Reference to authentication function. If\n  this is not defined, no username or password is requested. Should\n  raise an exception if authentication fails\n  \n  Default: None\n\n``authNeedUser`` \n  Should a username be requested?\n  \n  Default: ``False``\n\n``authNeedPass``\n  Should a password be requested?\n  \n  Default: ``False``\n\n\nHandler Display Modification\n----------------------------\n\nIf you want to change how the output is displayed, override one or all of the\nwrite classes.  Make sure you call back to the base class when doing so.\nThis is a good way to provide color to your console by using ANSI color commands.\nSee http://en.wikipedia.org/wiki/ANSI_escape_code\n\n- writemessage( TEXT ) \n- writeresponse( TEXT ) \n- writeerror( TEXT ) \n\n.. code:: python\n\n    def writeerror(self, text):\n        '''Write errors in red'''\n        TelnetHandler.writeerror(self, \"\\x1b[91m%s\\x1b[0m\" % text )\n\nServing the Handler\n-------------------\n\nNow you have a shiny new handler class, but it doesn't serve itself - it must be called\nfrom an appropriate server.  The server will create an instance of the TelnetHandler class\nfor each new connection.  The handler class will work with either a gevent StreamServer instance\n(for the green version) or with a SocketServer.TCPServer instance (for the threaded version).\n\nThreaded\n++++++++\n\n.. code:: python\n\n import SocketServer\n class TelnetServer(SocketServer.TCPServer):\n     allow_reuse_address = True\n    \n server = TelnetServer((\"0.0.0.0\", 8023), MyHandler)\n server.serve_forever()\n\nGreen\n+++++\n\nThe TelnetHandler class includes a streamserver_handle class method to translate the \nrequired fields from a StreamServer, allowing use with the gevent StreamServer (and possibly\nothers).\n\n.. code:: python\n\n import gevent.server\n server = gevent.server.StreamServer((\"\", 8023), MyHandler.streamserver_handle)\n server.server_forever()\n\n\nShort Example\n-------------\n\n.. code:: python\n\n import gevent, gevent.server\n from telnetsrv.green import TelnetHandler, command\n \n class MyTelnetHandler(TelnetHandler):\n     WELCOME = \"Welcome to my server.\"\n     \n     @command(['echo', 'copy', 'repeat'])\n     def command_echo(self, params):\n         '''<text to echo>\n         Echo text back to the console.\n         \n         '''\n         self.writeresponse( ' '.join(params) )\n \n     @command('timer')\n     def command_timer(self, params):\n         '''<time> <message>\n         In <time> seconds, display <message>.\n         Send a message after a delay.\n         <time> is in seconds.\n         If <message> is more than one word, quotes are required.\n         example: \n         > TIMER 5 \"hello world!\"\n         '''\n         try:\n             timestr, message = params[:2]\n             time = int(timestr)\n         except ValueError:\n             self.writeerror( \"Need both a time and a message\" )\n             return\n         self.writeresponse(\"Waiting %d seconds...\", time)\n         gevent.spawn_later(time, self.writemessage, message)\n \n \n server = gevent.server.StreamServer((\"\", 8023), MyTelnetHandler.streamserver_handle)\n server.serve_forever()\n\n\nSSH\n---\n\nIf the paramiko library is installed, the TelnetHanlder can be used via an SSH server for significantly\nimproved security.  ``paramiko_ssh`` contains ``SSHHandler`` and ``getRsaKeyFile`` to make setting\nup the server trivial.  Since the authentication is done prior to invoking the TelnetHandler,\nany ``authCallback`` defined in the TelnetHandler is ignored.\n\nGreen\n+++++\n\nIf using the green version of the TelnetHandler, you must use Gevent's monkey patch_all prior to\nimporting from ``paramiko_ssh``.\n\n.. code:: python\n\n    from gevent import monkey; monkey.patch_all()\n    from telnetsrv.paramiko_ssh import SSHHandler, getRsaKeyFile\n\n\nOperation Overview\n++++++++++++++++++\n\nThe SocketServer/StreamServer sets up the socket then passes that to an SSHHandler class which \nauthenticates then starts the SSH transport.  Within the SSH transport, the client requests a PTY channel\n(and possibly other channel types, which are denied) and the SSHHandler sets up a TelnetHandler class \nas the PTY for the channel.  If the client never requests a PTY channel, the transport will disconnect\nafter a timeout.\n\nSSH Host Key\n++++++++++++\n\nTo thwart man-in-the-middle attacks, every SSH server provides an RSA key as a unique fingerprint.  This unique key\nshould never change, and should be stored in a local file or a database.  The ``getRsaKeyFile`` makes this\neasy by reading the given key file if it exists, or creating the key if it does not.  The result should be\nread once and set in the class definition.\n\nEasy way:\n\n``host_key = getRsaKeyFile( FILENAME )``\n  If the FILENAME can be read, the RSA key is read in and returned as an RSAKey object.  \n  If the file can't be read, it generates a new RSA key and stores it in that file.\n\nLong way:\n\n.. code:: python\n\n   from paramiko_ssh import RSAKey\n   \n   # Make a new key - should only be done once per server during setup\n   new_key = RSAKey.generate(1024)\n   save_to_my_database( 'server_fingerprint',  str(new_key) )\n   \n   ...\n   \n   host_key = RSAKey( data=get_from_my_database('server_fingerprint') )\n   \n\nSSH Authentication\n++++++++++++++++++\n\nUsers can authenticate with just a username, a username/publickey or a username/password.  Up to three callbacks\ncan be defined, and if all three are defined, all three will be tried before denying the authentication attempt.\nAn SSH client will always provide a username.  If no ``authCallbackXX`` is defined, the SSH authentication will be\nset to \"none\" and any username will be able to log in.\n\n``authCallbackUsername(self, username)``\n  Reference to username-only authentication function.  Define this function to permit specific usernames\n  to log in without any futher authentication.  Raise any exception to deny this authentication attempt.\n  \n  If defined, this is always tried first.\n  \n  Default: None\n\n``authCallbackKey(self, username, key)``\n  Reference to username/key authentication function.  If this is defined,\n  users can log in the SSH client automatically with a key.  Raise any exception to deny this authentication attempt.\n  \n  Default: None\n  \n``authCallback(self, username, password)`` \n  Reference to username/password authentication function. If\n  this is defined, a password is requested. Raise any exception to deny this authentication attempt.\n  \n  If defined, this is always tried last.\n  \n  Default: None\n\n  \nSSHHandler uses Paramiko's ServerInterface as one of its base classes.  If you are familiar with Paramiko, feel free\nto instead override the authentication callbacks as needed.\n\n\nShort SSH Example\n+++++++++++++++++\n\n.. code:: python\n\n from gevent import monkey; monkey.patch_all()\n import gevent.server\n from telnetsrv.paramiko_ssh import SSHHandler, getRsaKeyFile\n from telnetsrv.green import TelnetHandler, command\n \n class MyTelnetHandler(TelnetHandler):\n     WELCOME = \"Welcome to my server.\"\n     \n     @command(['echo', 'copy', 'repeat'])\n     def command_echo(self, params):\n         '''<text to echo>\n         Echo text back to the console.\n         \n         '''\n         self.writeresponse( ' '.join(params) ) \n \n class MySSHHandler(SSHHandler):\n     # Set the unique host key\n     host_key = getRsaKeyFile('server_fingerprint.key') \n     \n     # Instruct this SSH handler to use MyTelnetHandler for any PTY connections\n     telnet_handler = MyTelnetHandler\n     \n     def authCallbackUsername(self, username):\n         # These users do not require a password\n         if username not in ['john', 'eric', 'terry', 'graham']:\n            raise RuntimeError('Not a Python!')\n \n     def authCallback(self, username, password):\n         # Super secret password:\n         if password != 'concord':\n            raise RuntimeError('Wrong password!')\n \n # Start a telnet server for just the localhost on port 8023.  (Will not request any authentication.)\n telnetserver = gevent.server.StreamServer(('127.0.0.1', 8023), MyTelnetHandler.streamserver_handle)\n telnetserver.start()\n \n # Start an SSH server for any local or remote host on port 8022\n sshserver = gevent.server.StreamServer((\"\", 8022), MySSHHandler.streamserver_handle)\n sshserver.serve_forever()\n\n\nLonger Example\n--------------\n\nSee https://github.com/ianepperson/telnetsrvlib/blob/master/test.py",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/ianepperson/telnetsrvlib",
        "keywords": "gevent,telnet,server",
        "license": "UNKNOWN",
        "maintainer": null,
        "maintainer_email": null,
        "name": "telnetsrv",
        "package_url": "https://pypi.org/project/telnetsrv/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/telnetsrv/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "https://github.com/ianepperson/telnetsrvlib"
        },
        "release_url": "https://pypi.org/project/telnetsrv/0.4/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "Telnet server handler library",
        "version": "0.4"
    },
    "last_serial": 800423,
    "releases": {
        "0.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c7cadc5125e854286b556e950d098cfb",
                    "sha256": "c48de36eea9075cc3cc04ca6197e98bb2b2d9c9982d32376351b1432e8b7b83e"
                },
                "downloads": -1,
                "filename": "telnetsrv-0.3.tar.gz",
                "has_sig": false,
                "md5_digest": "c7cadc5125e854286b556e950d098cfb",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15324,
                "upload_time": "2012-11-25T06:27:41",
                "url": "https://files.pythonhosted.org/packages/78/f6/feda4bf7bbfc68470748aaf797a6f3c89b5c419182985680c950ba9a68e3/telnetsrv-0.3.tar.gz"
            }
        ],
        "0.3.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "9ea5c5b842937075d2ee3c12a860c344",
                    "sha256": "b215a15fdb59fc7fdf9f2a5d7f1be484f8a0befb8fed44050913f7f37aeeccfd"
                },
                "downloads": -1,
                "filename": "telnetsrv-0.3.1.tar.gz",
                "has_sig": false,
                "md5_digest": "9ea5c5b842937075d2ee3c12a860c344",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17811,
                "upload_time": "2012-11-25T06:36:23",
                "url": "https://files.pythonhosted.org/packages/d7/61/12b3a3e3a9f9440fc866e9d2bed3f64461862e92207f94ff46c1fcbb04ea/telnetsrv-0.3.1.tar.gz"
            }
        ],
        "0.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "eb59ce5a765c4f9acb85f60342ae0be9",
                    "sha256": "195fa7acdeba7bb46a1a320c0afd66e23b5d7ab8810393468a05936113d84799"
                },
                "downloads": -1,
                "filename": "telnetsrv-0.4.tar.gz",
                "has_sig": false,
                "md5_digest": "eb59ce5a765c4f9acb85f60342ae0be9",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 22940,
                "upload_time": "2012-12-02T05:58:24",
                "url": "https://files.pythonhosted.org/packages/d2/ad/be6cc443a85d412077e1e4a12da8dba14113fedff0f79ae110e69ec0bd3d/telnetsrv-0.4.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "eb59ce5a765c4f9acb85f60342ae0be9",
                "sha256": "195fa7acdeba7bb46a1a320c0afd66e23b5d7ab8810393468a05936113d84799"
            },
            "downloads": -1,
            "filename": "telnetsrv-0.4.tar.gz",
            "has_sig": false,
            "md5_digest": "eb59ce5a765c4f9acb85f60342ae0be9",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 22940,
            "upload_time": "2012-12-02T05:58:24",
            "url": "https://files.pythonhosted.org/packages/d2/ad/be6cc443a85d412077e1e4a12da8dba14113fedff0f79ae110e69ec0bd3d/telnetsrv-0.4.tar.gz"
        }
    ]
}