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