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