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