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