{ "info": { "author": "Alejandro Ricoveri", "author_email": "alejandroricoveri@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Console", "License :: OSI Approved :: MIT License", "Natural Language :: English", "Operating System :: POSIX", "Operating System :: POSIX :: Linux", "Programming Language :: Python", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Topic :: Utilities" ], "description": "kaoru\n=====\n\n.. image:: https://badge.fury.io/py/kaoru.svg\n :target: http://badge.fury.io/py/kaoru\n\nA Telegram Bot as your personal IoT assistant\n---------------------------------------------------\n\n**kaoru** can be defined as a Telegram Bot whose roles are much alike\nto those related to IoT personal assistant.\n\nOK, I think I get the idea, but what is it good for?\n----------------------------------------------------\n\n**kaoru**'s purpose in life is to make your life a little bit easier by\nallowing you remote control of certain things on your host(s), the rationale\nbehind this is that there could be moments in which you would need to perform\nadministrative tasks on either your office or home laptop, things that you\nmaybe forgot to do, or things you could only do by getting in front of them.\nAn IoT-like approach would be ideal on this scenario, namely, talk to your\nmachines and tell them to do stuff for you while you're walking streets,\nor having a dinner with your friend, or when you're just too sleepy/lazy\nto get up from your couch/bed.\n\nFor the moment, **kaoru** is capable of:\n\n- Rebooting your host(s)\n- Shutting down your host(s)\n- Locking the screen on your host(s)\n- Send screen shots from your host(s)\n- Suspending your host(s) to either RAM or disk\n\nThings I feel tempted to implement:\n\n- Send alerts/warnings on certain things happening in your host(s)\n- Tell your host(s) to send you a file in their file system.\n- Perform a ``tail`` on a file and send messages as new content is appended to that file.\n\nWait, what?, bots are sort-of public domain, you know?\n------------------------------------------------------\n\nWhile that's true, the fact is that having your host running **kaoru**\nmeans that you have control over *her*, including (but not limited) to\ncontrol which people she's going to listen to, as explained in `Security <#security>`_.\n\nOK, I get it, how do I use this?, I just wanna get hands-on this \"thing\" ...\n----------------------------------------------------------------------------\n\nWell, the most essential thing you will need is to tell `@BotFather `_ to\nmake a new bot for you, as specified in `Telegram Bots Documentation `_\n\nOn the other hand, you gotta install **kaoru**, of course.\n\n.. code-block:: bash\n\n # First of all, you need to install\n pip3 install kaoru\n\nA Telegram Bot is a just a dummy client with no cell phone attached to it,\nyou need something to control this bot so it can become active, and that's when\n**kaoru** comes into play.\n\nMake sure you have properly set up your brand new Telegram Bot, `@BotFather `_\nshould have given you an **API access token** (a bunch of characters and numbers),\n**kaoru** needs this token in order for her to do her magic.\n\nMoreover, you can edit your `configuration file <#configuration-file>`_ from this point\n\n.. code-block:: bash\n\n $ vi /path/to/your/kaoru.conf\n\n**NOTE**: A configuration file is *not mandatory* for **kaoru** to run, she can do\nit using her defaults, however, you will need at least to set the API token\nthrough the environment variable ``TG_TOKEN``\n\n**Now you are done setting up kaoru, now is time to run it!**\n\n.. code-block:: bash\n\n $ kaoru --config /path/to/you/kaoru.conf\n\n kaoru [version] - https://github.com/axltxl/kaoru\n -------------------------------------------------\n --- Reading configuration file at: asd.conf\n (!) Strict mode has been enforced!\n (!) You will need to register my commands with my @BotFather\n (!) Ask him to /setcommands and after you\n (!) have mentioned me, you can paste the following:\n ---\n about - Information for nerds\n start - Start me up\n hello - See if I \"live\"\n help - Get list of available commands\n screenlock - See if I \"live\"\n screenshot - Get a screen shot from your host(s)\n dryrun - Toggle \"dry run\" mode\n cancel - Cancel any pending operation(s)\n reboot - Reboot your host(s)\n poweroff - Shut down your host(s)\n suspend - Suspend your host(s) to RAM\n hibernate - Suspend your host(s) to disk\n ---\n --- Waiting for updates ...\n\n**NOTE**: bear in mind that **you have to register kaoru's commands for your bot**\nwith the `@BotFather `_, **kaoru** will tell you how.\n\n**So, I have everything set up. What commands are available on this bot?**\n\nGood question indeed!, the following is the current set of commands\nsupported by **kaoru**, more are planned to come:\n\n\n- ``/hello`` A simple ping just to see if your bot is *alive*\n- ``/help`` How to use **kaoru**\n- ``/screenlock`` Lock screens on your host(s)\n- ``/screenshot`` Get a screen shot from your host(s)\n- ``/poweroff`` Tell your host(s) to shut down\n- ``/reboot`` Tell your host(s) to reboot\n- ``/cancel`` Cancel any pending operations\n- ``/dryrun`` don't do a thing, but pretend\n- ``/about`` information, mostly for nerds\n- ``/suspend`` Suspend your host(s) to RAM\n- ``/hibernate`` Suspend your host(s) to disk\n\n\nAre there any sort of requirements for kaoru in order to work properly?\n-----------------------------------------------------------------------\n\nYes indeed. For the moment, **kaoru** is only working under certain\nconditions. Hosts running **kaoru** must:\n\n\n- Be Linux-based at least (though conceptually speaking, ``*nix`` should be supported)\n- Have ``sudo``. Since commands like ``shutdown`` need to be run as ``root``.\n- Have either `scrot `_ or `imagemagick `_ installed (if you want ``/screenshot`` command to work)\n- Run kaoru on behalf on an user whose ``sudo`` privileges cover at least the execution of ``shutdown`` with no password requirement.\n- Have `pm-utils `_ installed on your system. This is necessary for ``/suspend`` and ``/hibernate`` to work properly.\n\nConfiguration file\n==================\n\n**kaoru** lists all sorts of configuration directives inside a YAML\nconfiguration file. These directives range from essentials like\na Telegram Bot API token to those related with blablabla. Please refer\nto the `example configuration file `_\nfor more details on how to configure **kaoru**.\n\n.. code-block:: yaml\n\n ---\n ############################\n # Example configuration file\n ############################\n\n # Telegram Bot API access token\n token: 1XXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXX\n\n # shutdown the host 2 minutes after a /poweroff command has been received\n poweroff_delay: 2\n\n # command to execute when a /screenlock command has been received\n screenlock_cmd: xscreensaver\n\n\n**NOTE**: Configuration files can be read by **kaoru** using the ``--config``\nargument, by default, **kaoru** will look up for a configuration file on\n``~/.config/kaoru/kaoru.conf``\n\n\nSecurity\n========\n\nBy default, **kaoru** runs openly, namely, it will listen to *any incoming\nupdates from any user* wanting to communicate with her, while this would allow you\nto quickly see her working, **it is inherently and by all means INSECURE!!!!**\n\nOnce you feel happy with your configuration, it is strongly advised\nthat you **enforce strict mode** on your configuration file, like so:\n\n.. code-block:: yaml\n\n ---\n # .. other options are behind\n\n # enforce strict mode\n strict: true\n\n # The following are the users who can talk\n # to kaoru. Requests coming from users outside\n # this list are simply IGNORED.\n masters:\n - \n - betty # your friend betty can also talk to kaoru\n\n\nOnce you're done, you can proceed to re-execute **kaoru**.\nWith ``strict`` directive set to ``true``, **kaoru** will only\nlisten and react to commands and messages coming from users set in ``masters``.\n\n\nOptions\n=======\n.. code-block:: bash\n\n kaoru [options]\n\n\n- ``--version`` show version number and exit\n- ``-i | --interactive`` enter CLI mode\n- ``-c FILE | --config FILE`` configuration file to use\n- ``-h | --help`` show a help message and exit\n- ``-d | --dry-run`` don't actually do anything\n- ``L NUM | --log-level NUM`` set logging output level\n- ``-l FILE | --log-file LOG_FILE`` set log file\n\n\nContributing\n============\n\nThere are many ways in which you can contribute to kaoru.\nCode patches are just one thing amongst others that you can submit to help the project.\nWe also welcome feedback, bug reports, feature requests, documentation improvements,\nadvertisement and testing.\n\nFeedback contributions\n----------------------\n\nThis is by far the easiest way to contribute something.\nIf you\u2019re using kaoru for your own benefit, don\u2019t hesitate sharing.\nFeel free to `submit issues and enhancement requests. `_\n\nCopyright and Licensing\n=======================\n\nCopyright (c) Alejandro Ricoveri\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included\nin all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.", "description_content_type": null, "docs_url": null, "download_url": "https://github.com/axltxl/kaoru/tarball/0.5.0", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/axltxl/kaoru", "keywords": "telegram,iot", "license": "MIT", "maintainer": null, "maintainer_email": null, "name": "kaoru", "package_url": "https://pypi.org/project/kaoru/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/kaoru/", "project_urls": { "Download": "https://github.com/axltxl/kaoru/tarball/0.5.0", "Homepage": "https://github.com/axltxl/kaoru" }, "release_url": "https://pypi.org/project/kaoru/0.5.0/", "requires_dist": null, "requires_python": null, "summary": "A Telegram Bot as your personal IoT assistant", "version": "0.5.0" }, "last_serial": 1878718, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "33fd491f40a1bc42f92d76ab9a1daa75", "sha256": "8b37cf5dfc5796be26dcde86c5812ee60e0057c5b945e6b0d468d8eff141ab35" }, "downloads": -1, "filename": "kaoru-0.1.0.tar.gz", "has_sig": false, "md5_digest": "33fd491f40a1bc42f92d76ab9a1daa75", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14729, "upload_time": "2015-12-21T16:15:20", "url": "https://files.pythonhosted.org/packages/d3/f7/8df887dbfe29dd60ec3cc492af6e47f760e95b8d61f5395f740d3267d7e3/kaoru-0.1.0.tar.gz" } ], "0.2.1": [ { "comment_text": "", "digests": { "md5": "b8dc6d5b4a352fcd5fe1fcd9ddaeb519", "sha256": "be2ef78710d1bf6291a257ae902a4725c72810dca517aa17bffc363bffc95d14" }, "downloads": -1, "filename": "kaoru-0.2.1.tar.gz", "has_sig": false, "md5_digest": "b8dc6d5b4a352fcd5fe1fcd9ddaeb519", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19200, "upload_time": "2015-12-22T00:19:23", "url": "https://files.pythonhosted.org/packages/6c/7a/d51670a389b92e16ea30adf62e95ca2028c92b86c093507cbb0d1b4fee1f/kaoru-0.2.1.tar.gz" } ], "0.3.0": [ { "comment_text": "", "digests": { "md5": "9d455998a4d456f2747b7e2d3402fe55", "sha256": "550acc81c3fa25cc3f297d0e7a8d3e7b53711a27af298c28767671ba5a1741a5" }, "downloads": -1, "filename": "kaoru-0.3.0.tar.gz", "has_sig": false, "md5_digest": "9d455998a4d456f2747b7e2d3402fe55", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 18936, "upload_time": "2015-12-22T20:20:55", "url": "https://files.pythonhosted.org/packages/de/06/f2a1897322bab49409f812b631cf3352a445e58188b43f0e4060ed1a8b9f/kaoru-0.3.0.tar.gz" } ], "0.3.1": [ { "comment_text": "", "digests": { "md5": "3a3af04e8b27ded7c2425a6f98cf1572", "sha256": "2831c26398e85ef268360ab87a9ed58e11ae0d5159feac21e2b1a72d04f3f193" }, "downloads": -1, "filename": "kaoru-0.3.1.tar.gz", "has_sig": false, "md5_digest": "3a3af04e8b27ded7c2425a6f98cf1572", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 21788, "upload_time": "2015-12-23T01:12:59", "url": "https://files.pythonhosted.org/packages/2e/c7/d8fe0765015e722660a062e427174e7a0a9bbc0ce15bb871d0b54cf4312c/kaoru-0.3.1.tar.gz" } ], "0.3.2": [ { "comment_text": "", "digests": { "md5": "e2dd94e7fb0b89981af313b7b6d1693e", "sha256": "5d72b58a895dc9cb2b12ebfa1d5ab79073bfb6f95b8f242ad88fe4d0cd724103" }, "downloads": -1, "filename": "kaoru-0.3.2.tar.gz", "has_sig": false, "md5_digest": "e2dd94e7fb0b89981af313b7b6d1693e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 21834, "upload_time": "2015-12-25T18:20:32", "url": "https://files.pythonhosted.org/packages/35/c1/e1f7115b94fab9f6cf938d563eda50dd824e0c2d8591716c5491b2cdf708/kaoru-0.3.2.tar.gz" } ], "0.4.0": [ { "comment_text": "", "digests": { "md5": "a145ef7db03c63a1fdad538104b00b71", "sha256": "c70150afb33f32210d4d14b1cdc70f818f0c39214f4dfeaec2bf0e0cb9fda99c" }, "downloads": -1, "filename": "kaoru-0.4.0.tar.gz", "has_sig": false, "md5_digest": "a145ef7db03c63a1fdad538104b00b71", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 22452, "upload_time": "2015-12-26T00:33:27", "url": "https://files.pythonhosted.org/packages/a7/58/b6959c18df84eb94a91ca747b4a1216a45262e85f0a0e9d76ee4407f79e1/kaoru-0.4.0.tar.gz" } ], "0.4.1": [ { "comment_text": "", "digests": { "md5": "654c630147e140ca5fb81a17cfb6a320", "sha256": "f1def9e8d1daaaa1a95d2beffad6ab7f0dc641016449873bceb66bd820a5d8b5" }, "downloads": -1, "filename": "kaoru-0.4.1.tar.gz", "has_sig": false, "md5_digest": "654c630147e140ca5fb81a17cfb6a320", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 22599, "upload_time": "2015-12-26T01:23:13", "url": "https://files.pythonhosted.org/packages/e1/5d/9362947ddc5a7d9a85875e97e148ef04d599b40a5448e72905c99c166d31/kaoru-0.4.1.tar.gz" } ], "0.5.0": [ { "comment_text": "", "digests": { "md5": "807a1e00853f93ecbca7c582fedb15ae", "sha256": "78d4863c867caa987c28c66d3b6c01550352101e5bf9e5d46c3a1eed89dfe645" }, "downloads": -1, "filename": "kaoru-0.5.0.tar.gz", "has_sig": false, "md5_digest": "807a1e00853f93ecbca7c582fedb15ae", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 23380, "upload_time": "2015-12-27T13:27:23", "url": "https://files.pythonhosted.org/packages/ba/81/3d1c5aa7949e26a75a3eabaf6c4694f31180bc98be3b6fce71593ffcaba6/kaoru-0.5.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "807a1e00853f93ecbca7c582fedb15ae", "sha256": "78d4863c867caa987c28c66d3b6c01550352101e5bf9e5d46c3a1eed89dfe645" }, "downloads": -1, "filename": "kaoru-0.5.0.tar.gz", "has_sig": false, "md5_digest": "807a1e00853f93ecbca7c582fedb15ae", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 23380, "upload_time": "2015-12-27T13:27:23", "url": "https://files.pythonhosted.org/packages/ba/81/3d1c5aa7949e26a75a3eabaf6c4694f31180bc98be3b6fce71593ffcaba6/kaoru-0.5.0.tar.gz" } ] }