README.rst 2.3 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586
  1. Whistler Bot
  2. ============
  3. Whistler Bot is an XMPP bot written in python using SleekXMPP_, which is
  4. a requirement. The bot is designed to handle some commands, and it is easy to
  5. extend.
  6. .. image:: https://img.shields.io/pypi/v/whistler.svg
  7. :target: https://crate.io/packages/whistler/
  8. :alt: Latest PyPI version
  9. .. image:: https://img.shields.io/pypi/dm/whistler.svg
  10. :target: https://crate.io/packages/whistler/
  11. :alt: Number of PyPI downloads
  12. Simple usage:
  13. .. code-block:: bash
  14. $ whistler myconfig.conf
  15. Create bot programmatically:
  16. .. code-block:: python
  17. from whistler.bot import WhistlerBot
  18. bot = WhistlerBot( "myjid@myserver.com", "mypassword" )
  19. bot.start()
  20. .. _SleekXMPP: https://github.com/fritzy/SleekXMPP
  21. Extending bot
  22. -------------
  23. You can extend the bot functionalities, just see for example the code of the
  24. whistler console script. In short you can add commands creating a new class
  25. from WhistlerBot, and define new functions in the form ``cmd_<command>`` plus the
  26. command name, for example, to handle the command *ping*.
  27. .. code-block:: python
  28. from whistler.bot import WhistlerBot
  29. class MyBot(WhistlerBot):
  30. def cmd_ping(self, msg, args):
  31. return "pong"
  32. Example chat
  33. ------------
  34. .. image:: doc/source/_static/whistler_screenshot.png
  35. :align: left
  36. :alt: An example of chat with Whistler
  37. Whistler allows to send private commands in usual jabber (and of course
  38. GTalk and Google Hangouts) chat.
  39. Also public commands are available, prefixed them with "!" (exclamation mark),
  40. as also reply to a direct mention in the form "whistler:" or "whistler,", where
  41. "whistler" is the nickname of the bot in the MUC::
  42. (Me) whistler: uptime
  43. (whistler) 17:33:01 up 2 days, ...
  44. Currently Whistler support a number of features, including tweet from
  45. command, shorting url action and so on...
  46. You can see the mixins_ directory to see a number of examples for whistler
  47. and how easy is to extend.
  48. .. _mixins: https://github.com/ajdiaz/whistler/tree/master/whistler/mixins
  49. Contributions
  50. -------------
  51. Any new mixin or functionality is welcome to Whistler. If you has been
  52. developed new one or want new feature, please `send me a message` or a `pull
  53. request`_.
  54. .. _`send me a message`: mailto:ajdiaz@connectical.com
  55. .. _`pull request`: https://github.com/ajdiaz/whistler/pulls