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 The quick way
  27 ^^^^^^^^^^^^^
  28
  29 You will need Python and pip (2.7.x or 3.x).
  30
  31 .. code:: bash
  32
  33     sudo pip install rainbowstream
  34     # Python 3 users: sudo pip3 install rainbowstream
  35
  36
  37 The recommended way
  38 ^^^^^^^^^^^^^^^^^^^
  39
  40 Use `virtualenv`_
  41
  42 .. code:: bash
  43
  44     virtualenv venv
  45     # Python 3 users : use -p to specify your Python 3 localtion as below
  46     # virtualenv -p /usr/bin/python3 venv
  47     source venv/bin/activate
  48     pip install rainbowstream
  49
  50 Troubleshooting
  51 ^^^^^^^^^^^^^^^
  52
  53 If you use Linux, you might need to install some packages if you haven't already.
  54 For debian-based distros, these can be installed with
  55
  56 .. code:: bash
  57
  58     sudo apt-get install python-dev libjpeg libjpeg-dev libfreetype6 libfreetype6-dev zlib1g-dev
  59
  60 Besides, Mac OSX Maverick with Xcode 5.1 has a well-known `clang unknown argument`_ problem with
  61 the ``Pillow`` package installation - a dependency of this app.
  62 If you are in this case, I recommend taking a look at `Issue #10`_ and let me know if this workaround doesn't work for you.
  63
  64 .. code:: bash
  65
  66     export ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future
  67
  68 If installation in *the quick way* doesn't work:
  69
  70 -  ``sudo pip uninstall rainbowstream``
  71 -  use the *virtualenv way* above
  72 -  `create an issue`_ and provide:
  73
  74   + Your OS
  75   + Your Python version
  76
  77 Usage
  78 -----
  79
  80 The stream
  81 ^^^^^^^^^^
  82
  83 Just type
  84
  85 .. code:: bash
  86
  87     rainbowstream
  88
  89 and see your stream.
  90
  91 I shipped a feature which can display **tweet's images directly on terminal**.
  92 You can try it with:
  93
  94 .. code:: bash
  95
  96     rainbowstream -iot # Or rainbowstream --image-on-term
  97
  98 You also can change the config key ``IMAGE_ON_TERM`` to ``True`` inside the app
  99 to enable above feature,
 100 change ``IMAGE_SHIFT`` to set image's margin (relative to your terminal's width)
 101 or ``IMAGE_MAX_HEIGHT`` to control max height of every image.
 102 (see `config management`_ section).
 103
 104 In the first time you will be asked for authorization of Rainbow Stream
 105 app at Twitter. Just click the “Authorize access” button and paste PIN
 106 number to the terminal, the rainbow will start.
 107
 108 You might want to use rainbowstream via an **HTTP/SOCKS proxy**. Proxy settings are
 109 provided as follows:
 110
 111 .. code:: bash
 112
 113     rainbowstream --proxy-host localhost --proxy-port 1337 --proxy-type HTTP
 114     # or using the short form:
 115     rainbowstream -ph localhost -pp 1337 -pt HTTP
 116
 117 Both ``--proxy-port`` and ``--proxy-type`` can be omitted. In this case default
 118 proxy port ``8080`` and default proxy type ``SOCKS5`` are used.
 119
 120 The interactive mode
 121 ^^^^^^^^^^^^^^^^^^^^
 122
 123 While your personal stream is continued, you are also ready to tweet,
 124 search, reply, retweet… directly from console. Simply type “h” and hit
 125 the Enter key to see the help.
 126
 127 Input is in interactive mode. It means that you can use arrow key to
 128 move up and down history, tab-autocomplete or 2 tab to view available
 129 suggestion. Input history from previous run is available as well.
 130
 131 Available commands are listed in `Read The Docs`_.
 132
 133 Theme customization
 134 ^^^^^^^^^^^^^^^^^^^
 135
 136 Rainbow Stream is shipped with some default themes.
 137 You can either change theme by ``theme`` command or create your favorite one.
 138
 139 Theme’s screenshot:
 140
 141 - Monokai
 142
 143 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png
 144    :alt: monokai
 145
 146 - Solarized
 147
 148 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png
 149    :alt: solarized
 150
 151 - Tomorrow Night
 152
 153 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png
 154    :alt: tomorrownight
 155
 156 - Larapaste
 157
 158 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png
 159    :alt: larapaste
 160
 161 For detaile information, see `theme usage and customization`_.
 162
 163
 164 Bug and feature requests
 165 ------------------------
 166
 167 Found a bug or a feature request ?
 168 Please `create an issue`_ or contact me at `@dtvd88`_
 169
 170 Development
 171 -----------
 172
 173 If you want to build a runnable version yourself, follow these simple
 174 steps
 175
 176 -  `Create your own Twitter Application`_
 177 -  Get your Twitter application’s API key and secret
 178 -  Fork this repo and clone in your system.
 179 -  Create a file ``consumer.py`` in `rainbowstream`_ folder with
 180    following content
 181
 182    .. code:: python
 183
 184        # Consumer information
 185        CONSUMER_KEY = 'APIKey' # Your Twitter application's API key
 186        CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret
 187
 188 -  Use pip to install in local
 189
 190    .. code:: bash
 191
 192        # cd to directory which contains setup.py (cloned directory)
 193        virtualenv venv # Python3 users: use -p to specify python3
 194        source venv/bin/activate
 195        pip install -e .
 196        which rainbowstream # /this-directory/venv/bin/rainbowstream
 197        # Remove ~/.rainbow_oauth if exists
 198        rainbowstream # local version of rainbowstream
 199
 200
 201 Contributing
 202 ------------
 203 I appreciate any help and support. Feel free to `fork`_ and `create a pull request`_.
 204 You will be listed as contributor.
 205
 206 License
 207 -------
 208
 209 Rainbow Stream are released under an MIT License. See LICENSE.txt for
 210 details
 211
 212
 213 .. _Python Twitter Tool: http://mike.verdone.ca/twitter/
 214 .. _Twitter API: https://dev.twitter.com/docs/api/1.1
 215 .. _create an issue: https://github.com/DTVD/rainbowstream/issues/new
 216 .. _@dtvd88: https://twitter.com/dtvd88
 217 .. _fork: https://github.com/DTVD/rainbowstream/fork
 218 .. _create a pull request: https://github.com/DTVD/rainbowstream/compare/
 219 .. _Read The Docs: http://rainbowstream.readthedocs.org/en/latest/
 220 .. _config guide: https://github.com/DTVD/rainbowstream/blob/master/theme.md
 221 .. _theme usage and customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md
 222 .. _Create your own Twitter Application: https://apps.twitter.com/app/new
 223 .. _rainbowstream: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream
 224 .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 225 .. _config management: http://rainbowstream.readthedocs.org/en/latest/#config-explanation
 226 .. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/
 227 .. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10