README.rst

   1 Rainbow Stream
   2 --------------
   3
   4 .. image:: http://img.shields.io/pypi/l/rainbowstream.svg?style=flat-square
   5    :target: https://github.com/DTVD/rainbowstream/blob/master/LICENSE.txt
   6
   7 .. image:: http://img.shields.io/pypi/v/rainbowstream.svg?style=flat-square
   8    :target: https://pypi.python.org/pypi/rainbowstream
   9
  10 Terminal-based Twitter Client.  Real-time tweetstream, compose, search, favorite,
  11 and much more fun directly from terminal.
  12
  13 This package is built on the `Python Twitter Tools`_ and the `Twitter API`_, and runs
  14 on Python (2.7.x and 3.x).
  15
  16 Home page: https://github.com/orakaro/rainbowstream
  17
  18 Source code: https://github.com/DTVD/rainbowstream
  19
  20 Showcase
  21 --------
  22
  23 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/rs.gif
  24    :alt: gif
  25
  26 Installation
  27 ------------
  28
  29 The Quick Way
  30 ^^^^^^^^^^^^^
  31
  32 System Python (2.7.x or 3.x)
  33
  34 .. code:: bash
  35
  36     sudo pip install rainbowstream
  37     # Python 3 users: sudo pip3 install rainbowstream
  38
  39 The Recommended Way
  40 ^^^^^^^^^^^^^^^^^^^
  41
  42 `virtualenv`_
  43
  44 .. code:: bash
  45
  46     virtualenv venv
  47     # Python 3 users : use -p to specify your Python 3 location:
  48     # virtualenv -p /usr/bin/python3 venv
  49     source venv/bin/activate
  50     pip install rainbowstream
  51
  52 Troubleshooting
  53 ^^^^^^^^^^^^^^^
  54
  55 Some additional libraries may need to be installed on linux.
  56
  57 For Debian-based distros:
  58
  59 .. code:: bash
  60
  61     sudo apt-get install python-dev libjpeg-dev libfreetype6 libfreetype6-dev zlib1g-dev
  62
  63 For CentOS:
  64
  65 .. code:: bash
  66
  67     sudo yum install python-devel libjpeg-devel
  68
  69 Mac OSX Maverick with Xcode 5.1 has a well-known `clang unknown argument`_
  70 problem with the installation of the ``Pillow`` package—a dependency of this
  71 app.  Take a look at `Issue #10`_ and let me know if the workaround doesn't work
  72 for you.
  73
  74 .. code:: bash
  75
  76     export ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future
  77
  78 If *The Quick Way* doesn't work, then:
  79
  80 -  ``sudo pip uninstall rainbowstream``
  81 -  Use the *The Recommended Way*
  82 -  `Create an issue`_ and provide:
  83     - Your OS
  84     - Your Python version
  85
  86 Usage
  87 -----
  88
  89 The Stream
  90 ^^^^^^^^^^
  91
  92 Just type ``rainbowstream`` to see your stream.
  93
  94 You can now **display tweeted images directly on the terminal**!  Try it with:
  95
  96 .. code:: bash
  97
  98     rainbowstream -iot # Or rainbowstream --image-on-term
  99
 100 Set ``IMAGE_ON_TERM`` to ``True`` in your config to to enable above feature,
 101 change ``IMAGE_SHIFT`` to set image's margin (relative to your terminal's
 102 width), and ``IMAGE_MAX_HEIGHT`` to control max height of every image (see
 103 `Config Management`_).
 104
 105 You will be asked for authorization on Twitter the first time you run Rainbow
 106 Stream.  Just click the "Authorize access" button, paste PIN number to the
 107 terminal, and the rainbow will start.
 108
 109 You might want to use Rainbow Stream with an **HTTP/SOCKS proxy**.  Proxy
 110 settings are specified as follows:
 111
 112 .. code:: bash
 113
 114     rainbowstream --proxy-host localhost --proxy-port 1337 --proxy-type HTTP
 115     # or the short form:
 116     rainbowstream -ph localhost -pp 1337 -pt HTTP
 117
 118 Both ``--proxy-port`` and ``--proxy-type`` are optional.  The default proxy port
 119 is ``8080`` and the default proxy type is ``SOCKS5``.
 120
 121 Interactive Mode
 122 ^^^^^^^^^^^^^^^^
 123
 124 While your personal stream is continued, you are also ready to tweet, search,
 125 reply, retweet, etc. directly from your console.  Simply type ``h`` and hit the
 126 Enter key to see the help.
 127
 128 Input is in interactive mode.  It means that you can use the arrow keys to move
 129 up and down through the history, tab-autocomplete or double-tab to view
 130 available suggestions.  Input history from previous run is also available.
 131
 132 `Read the docs`_ for available commands.
 133
 134 Theme Customization
 135 ^^^^^^^^^^^^^^^^^^^
 136
 137 Rainbow Stream is shipped with some default themes.  You can switch themes with
 138 the ``theme`` command.  You can also customize themes as you please.
 139
 140 Theme screenshots:
 141
 142 - Monokai
 143
 144 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png
 145    :alt: monokai
 146
 147 - Solarized
 148
 149 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png
 150    :alt: solarized
 151
 152 - Tomorrow Night
 153
 154 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png
 155    :alt: tomorrownight
 156
 157 - Larapaste
 158
 159 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png
 160    :alt: larapaste
 161
 162 See `Theme Usage and Customization`_ for detailed information.
 163
 164
 165 Bug and Feature Requests
 166 ------------------------
 167
 168 Found a bug or a feature request?  Please `create an issue`_ or contact me at
 169 `@dtvd88`_.
 170
 171 Development
 172 -----------
 173
 174 If you want to build a runnable version yourself, follow these simple steps:
 175
 176 - `Create your own Twitter Application`_
 177 -  Get your Twitter application’s API key and secret
 178 - `Create your own Pocket Application`_ (platform: Web)
 179 -  Get your Pocket application’s key
 180 -  Fork this repo and ``git clone`` it
 181 -  Create a ``consumer.py`` file in the `rainbowstream`_ directory containing:
 182
 183    .. code:: python
 184
 185        # Consumer information
 186        CONSUMER_KEY = 'APIKey' # Your Twitter application's API key
 187        CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret
 188        PCKT_CONSUMER_KEY = 'PocketAPIKey' # Your Pocket application's API key
 189
 190 -  Use pip to install it locally
 191
 192    .. code:: bash
 193
 194        # cd to directory which contains setup.py (cloned directory)
 195        virtualenv venv # Python3 users: use -p to specify python3
 196        source venv/bin/activate
 197        pip install -e .
 198        which rainbowstream # /this-directory/venv/bin/rainbowstream
 199        # Remove ~/.rainbow_oauth if it exists
 200        rainbowstream # local version of rainbowstream
 201
 202
 203 Contributing
 204 ------------
 205
 206 I appreciate any help and support.  Feel free to `fork`_ and `create a pull
 207 request`_.  You will be listed as a contributor.
 208
 209 License
 210 -------
 211
 212 Rainbow Stream is released under an MIT License.  See LICENSE.txt for details.
 213
 214
 215 .. _Python Twitter Tools: http://mike.verdone.ca/twitter/
 216 .. _Twitter API: https://dev.twitter.com/docs/api/1.1
 217 .. _Create an issue: https://github.com/DTVD/rainbowstream/issues/new
 218 .. _@dtvd88: https://twitter.com/dtvd88
 219 .. _fork: https://github.com/DTVD/rainbowstream/fork
 220 .. _create a pull request: https://github.com/DTVD/rainbowstream/compare/
 221 .. _Read the docs: http://rainbowstream.readthedocs.org/en/latest/
 222 .. _config guide: https://github.com/DTVD/rainbowstream/blob/master/theme.md
 223 .. _Theme Usage and Customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md
 224 .. _Create your own Twitter Application: https://apps.twitter.com/app/new
 225 .. _Create your own Pocket Application: https://getpocket.com/developer/apps/new
 226 .. _rainbowstream: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream
 227 .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 228 .. _Config Management: http://rainbowstream.readthedocs.org/en/latest/#config-explanation
 229 .. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/
 230 .. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10