README.rst

   1 Rainbow Stream
   2 --------------
   3
   4 .. image:: http://img.shields.io/pypi/dm/rainbowstream.svg?style=flat
   5    :target: https://pypi.python.org/pypi/rainbowstream
   6
   7 .. image:: http://img.shields.io/pypi/v/rainbowstream.svg?style=flat
   8    :target: https://pypi.python.org/pypi/rainbowstream
   9
  10 Terminal-based Twitter Client. Realtime tweetstream, compose, search ,
  11 favorite … and much more fun directly from terminal.
  12
  13 This package is built on the top of `Python Twitter Tool`_ and `Twitter API`_,
  14 can run on Python 2.7.x and 3.x .
  15
  16
  17 Showcase
  18 --------
  19
  20 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/rs.gif
  21    :alt: gif
  22
  23 Install
  24 -------
  25
  26 Requirements
  27 ^^^^^^^^^^^^
  28
  29 If you use Linux, you might need to install the ``python-dev`` and
  30 ``libsqlite3-dev`` packages if you haven't already. For debian-based distros,
  31 these can be installed with ``sudo apt-get install python-dev libsqlite3-dev``.
  32
  33
  34 The quick way
  35 ^^^^^^^^^^^^^
  36
  37 You will need Python and pip (2.7.x or 3.x).
  38
  39 .. code:: bash
  40
  41     sudo pip install rainbowstream
  42     # Python 3 users: sudo pip3 install rainbowstream
  43
  44
  45 The recommended way
  46 ^^^^^^^^^^^^^^^^^^^
  47
  48 Use `virtualenv`_
  49
  50 .. code:: bash
  51
  52     virtualenv venv
  53     # Python 3 users : use -p to specify your Python 3 localtion as below
  54     # virtualenv -p /usr/bin/python3 venv
  55     source venv/bin/activate
  56     pip install rainbowstream
  57
  58
  59 Usage
  60 -----
  61
  62 The stream
  63 ^^^^^^^^^^
  64
  65 Just type
  66
  67 .. code:: bash
  68
  69     rainbowstream
  70
  71 and see your stream.
  72
  73 I shipped a feature which can display **tweet's images directly on terminal**.
  74 You can try it with:
  75
  76 .. code:: bash
  77
  78     rainbowstream -iot # Or rainbowstream --image-on-term
  79
  80 You also can change the config key ``IMAGE_ON_TERM`` to ``True`` inside the app
  81 to enable above feature (see `config management`_ section).
  82
  83 In the first time you will be asked for authorization of Rainbow Stream
  84 app at Twitter. Just click the “Authorize access” button and paste PIN
  85 number to the terminal, the rainbow will start.
  86
  87 The interactive mode
  88 --------------------
  89
  90 While your personal stream is continued, you are also ready to tweet,
  91 search, reply, retweet… directly from console. Simply type “h” and hit
  92 the Enter key to see the help.
  93
  94 Input is in interactive mode. It means that you can use arrow key to
  95 move up and down history, tab-autocomplete or 2 tab to view available
  96 suggestion. Input history from previous run is available as well.
  97
  98 Available commands are listed in `Read The Docs`_.
  99
 100 Theme customization
 101 -------------------
 102
 103 Rainbow Stream is shipped with some default themes.
 104 You can either change theme by ``theme`` command or create your favorite one.
 105
 106 Theme’s screenshot:
 107
 108 - Monokai
 109
 110 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png
 111    :alt: monokai
 112
 113 - Solarized
 114
 115 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png
 116    :alt: solarized
 117
 118 - Tomorrow Night
 119
 120 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png
 121    :alt: tomorrownight
 122
 123 - Larapaste
 124
 125 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png
 126    :alt: larapaste
 127
 128
 129 For detaile information, see `theme usage and customization`_.
 130
 131 Bug and feature requests
 132 ------------------------
 133
 134 Found a bug or a feature request ?
 135 Please `create an issue`_ or contact me at `@dtvd88`_
 136
 137 Development
 138 -----------
 139
 140 If you want to build a runnable version yourself, follow these simple
 141 steps
 142
 143 -  `Create your own Twitter Application`_
 144 -  Get your Twitter application’s API key and secret
 145 -  Fork this repo and clone in your system.
 146 -  Create a file ``consumer.py`` in `rainbowstream`_ folder with
 147    following content
 148
 149    .. code:: python
 150
 151        # Consumer information
 152        CONSUMER_KEY = 'APIKey' # Your Twitter application's API key
 153        CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret
 154
 155 -  Use pip to install in local
 156
 157    .. code:: bash
 158
 159        # cd to directory which contains setup.py (cloned directory)
 160        virtualenv venv # Python3 users: use -p to specify python3
 161        source venv/bin/activate
 162        pip install -e .
 163        which rainbowstream # /this-directory/venv/bin/rainbowstream
 164        pip list | grep rainbowstream # rainbowstream (0.x.x, /this-directory)
 165        # Remove ~/.rainbow_oauth if exists
 166        rainbowstream # local version of rainbowstream
 167
 168
 169 Contributing
 170 ------------
 171 I appreciate any help and support. Feel free to `fork`_ and `create a pull request`_.
 172 You will be listed as contributor.
 173
 174 License
 175 -------
 176
 177 Rainbow Stream are released under an MIT License. See LICENSE.txt for
 178 details
 179
 180
 181 .. _Python Twitter Tool: http://mike.verdone.ca/twitter/
 182 .. _Twitter API: https://dev.twitter.com/docs/api/1.1
 183 .. _create an issue: https://github.com/DTVD/rainbowstream/issues/new
 184 .. _@dtvd88: https://twitter.com/dtvd88
 185 .. _fork: https://github.com/DTVD/rainbowstream/fork
 186 .. _create a pull request: https://github.com/DTVD/rainbowstream/compare/
 187 .. _Read The Docs: http://rainbowstream.readthedocs.org/en/latest/
 188 .. _config guide: https://github.com/DTVD/rainbowstream/blob/master/theme.md
 189 .. _theme usage and customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md
 190 .. _Create your own Twitter Application: https://apps.twitter.com/app/new
 191 .. _rainbowstream: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream
 192 .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 193 .. _config management: http://rainbowstream.readthedocs.org/en/latest/#the-interactive-mode