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