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 The interactive mode
 109 ^^^^^^^^^^^^^^^^^^^^
 110
 111 While your personal stream is continued, you are also ready to tweet,
 112 search, reply, retweet… directly from console. Simply type “h” and hit
 113 the Enter key to see the help.
 114
 115 Input is in interactive mode. It means that you can use arrow key to
 116 move up and down history, tab-autocomplete or 2 tab to view available
 117 suggestion. Input history from previous run is available as well.
 118
 119 Available commands are listed in `Read The Docs`_.
 120
 121 Theme customization
 122 ^^^^^^^^^^^^^^^^^^^
 123
 124 Rainbow Stream is shipped with some default themes.
 125 You can either change theme by ``theme`` command or create your favorite one.
 126
 127 Theme’s screenshot:
 128
 129 - Monokai
 130
 131 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png
 132    :alt: monokai
 133
 134 - Solarized
 135
 136 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png
 137    :alt: solarized
 138
 139 - Tomorrow Night
 140
 141 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png
 142    :alt: tomorrownight
 143
 144 - Larapaste
 145
 146 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png
 147    :alt: larapaste
 148
 149 For detaile information, see `theme usage and customization`_.
 150
 151
 152 Bug and feature requests
 153 ------------------------
 154
 155 Found a bug or a feature request ?
 156 Please `create an issue`_ or contact me at `@dtvd88`_
 157
 158 Development
 159 -----------
 160
 161 If you want to build a runnable version yourself, follow these simple
 162 steps
 163
 164 -  `Create your own Twitter Application`_
 165 -  Get your Twitter application’s API key and secret
 166 -  Fork this repo and clone in your system.
 167 -  Create a file ``consumer.py`` in `rainbowstream`_ folder with
 168    following content
 169
 170    .. code:: python
 171
 172        # Consumer information
 173        CONSUMER_KEY = 'APIKey' # Your Twitter application's API key
 174        CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret
 175
 176 -  Use pip to install in local
 177
 178    .. code:: bash
 179
 180        # cd to directory which contains setup.py (cloned directory)
 181        virtualenv venv # Python3 users: use -p to specify python3
 182        source venv/bin/activate
 183        pip install -e .
 184        which rainbowstream # /this-directory/venv/bin/rainbowstream
 185        pip list | grep rainbowstream # rainbowstream (0.x.x, /this-directory)
 186        # Remove ~/.rainbow_oauth if exists
 187        rainbowstream # local version of rainbowstream
 188
 189
 190 Contributing
 191 ------------
 192 I appreciate any help and support. Feel free to `fork`_ and `create a pull request`_.
 193 You will be listed as contributor.
 194
 195 License
 196 -------
 197
 198 Rainbow Stream are released under an MIT License. See LICENSE.txt for
 199 details
 200
 201
 202 .. _Python Twitter Tool: http://mike.verdone.ca/twitter/
 203 .. _Twitter API: https://dev.twitter.com/docs/api/1.1
 204 .. _create an issue: https://github.com/DTVD/rainbowstream/issues/new
 205 .. _@dtvd88: https://twitter.com/dtvd88
 206 .. _fork: https://github.com/DTVD/rainbowstream/fork
 207 .. _create a pull request: https://github.com/DTVD/rainbowstream/compare/
 208 .. _Read The Docs: http://rainbowstream.readthedocs.org/en/latest/
 209 .. _config guide: https://github.com/DTVD/rainbowstream/blob/master/theme.md
 210 .. _theme usage and customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md
 211 .. _Create your own Twitter Application: https://apps.twitter.com/app/new
 212 .. _rainbowstream: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream
 213 .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 214 .. _config management: http://rainbowstream.readthedocs.org/en/latest/#config-explanation
 215 .. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/
 216 .. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10