Unlokc request version
[rainbowstream.git] / README.rst
CommitLineData
8a7554f1 1A Note about Twitter API Change
c89363f2 2-------------------------------
8a7554f1 3
c4e48381 4Heads-up! As Twitter **discontinues supporting** Stream API, RainbowStream's stream function has been stopped working for a long time. But here is a good new, from version 1.5.0 we **switched to a Polling Strategy** that using the `home` command to check for every 90 seconds. Notes that rate limit for `home` command itself is 15 times per 15 minutes, so don't abuse it too much to leave space for the polling stream :)
8a7554f1 5
c89363f2 6If you are interested in detail: https://github.com/orakaro/rainbowstream/issues/271
8a7554f1 7
4f025227
O
8Rainbow Stream
9--------------
10
11.. image:: http://img.shields.io/pypi/l/rainbowstream.svg?style=flat-square
12 :target: https://github.com/DTVD/rainbowstream/blob/master/LICENSE.txt
13
14.. image:: http://img.shields.io/pypi/v/rainbowstream.svg?style=flat-square
15 :target: https://pypi.python.org/pypi/rainbowstream
16
4e9c5124 17Terminal-based Twitter Client. Real-time tweetstream, compose, search, favorite,
18and much more fun directly from terminal.
4f025227 19
4e9c5124 20This package is built on the `Python Twitter Tools`_ and the `Twitter API`_, and runs
21on Python (2.7.x and 3.x).
4f025227 22
012dd457 23Home page: https://github.com/orakaro/rainbowstream
4f025227 24
4e9c5124 25Source code: https://github.com/DTVD/rainbowstream
4f025227
O
26
27Showcase
28--------
29
30.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/rs.gif
31 :alt: gif
32
4e9c5124 33Installation
34------------
4f025227 35
4e9c5124 36The Quick Way
4f025227
O
37^^^^^^^^^^^^^
38
4e9c5124 39System Python (2.7.x or 3.x)
4f025227
O
40
41.. code:: bash
42
43 sudo pip install rainbowstream
44 # Python 3 users: sudo pip3 install rainbowstream
45
4e9c5124 46The Recommended Way
4f025227
O
47^^^^^^^^^^^^^^^^^^^
48
4e9c5124 49`virtualenv`_
4f025227
O
50
51.. code:: bash
52
53 virtualenv venv
4e9c5124 54 # Python 3 users : use -p to specify your Python 3 location:
4f025227
O
55 # virtualenv -p /usr/bin/python3 venv
56 source venv/bin/activate
57 pip install rainbowstream
58
59Troubleshooting
60^^^^^^^^^^^^^^^
61
4e9c5124 62Some additional libraries may need to be installed on linux.
63
64For Debian-based distros:
4f025227
O
65
66.. code:: bash
67
68 sudo apt-get install python-dev libjpeg-dev libfreetype6 libfreetype6-dev zlib1g-dev
69
70For CentOS:
71
72.. code:: bash
73
74 sudo yum install python-devel libjpeg-devel
75
4e9c5124 76Mac OSX Maverick with Xcode 5.1 has a well-known `clang unknown argument`_
77problem with the installation of the ``Pillow`` package—a dependency of this
78app. Take a look at `Issue #10`_ and let me know if the workaround doesn't work
79for you.
4f025227
O
80
81.. code:: bash
82
83 export ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future
84
4e9c5124 85If *The Quick Way* doesn't work, then:
4f025227
O
86
87- ``sudo pip uninstall rainbowstream``
4e9c5124 88- Use the *The Recommended Way*
89- `Create an issue`_ and provide:
90 - Your OS
91 - Your Python version
4f025227
O
92
93Usage
94-----
95
4e9c5124 96The Stream
4f025227
O
97^^^^^^^^^^
98
4e9c5124 99Just type ``rainbowstream`` to see your stream.
4f025227 100
4e9c5124 101You can now **display tweeted images directly on the terminal**! Try it with:
4f025227
O
102
103.. code:: bash
104
105 rainbowstream -iot # Or rainbowstream --image-on-term
106
4e9c5124 107Set ``IMAGE_ON_TERM`` to ``True`` in your config to to enable above feature,
108change ``IMAGE_SHIFT`` to set image's margin (relative to your terminal's
109width), and ``IMAGE_MAX_HEIGHT`` to control max height of every image (see
110`Config Management`_).
4f025227 111
4e9c5124 112You will be asked for authorization on Twitter the first time you run Rainbow
113Stream. Just click the "Authorize access" button, paste PIN number to the
114terminal, and the rainbow will start.
4f025227 115
4e9c5124 116You might want to use Rainbow Stream with an **HTTP/SOCKS proxy**. Proxy
117settings are specified as follows:
4f025227
O
118
119.. code:: bash
120
121 rainbowstream --proxy-host localhost --proxy-port 1337 --proxy-type HTTP
4e9c5124 122 # or the short form:
4f025227
O
123 rainbowstream -ph localhost -pp 1337 -pt HTTP
124
4e9c5124 125Both ``--proxy-port`` and ``--proxy-type`` are optional. The default proxy port
126is ``8080`` and the default proxy type is ``SOCKS5``.
4f025227 127
4e9c5124 128Interactive Mode
129^^^^^^^^^^^^^^^^
4f025227 130
4e9c5124 131While your personal stream is continued, you are also ready to tweet, search,
132reply, retweet, etc. directly from your console. Simply type ``h`` and hit the
133Enter key to see the help.
4f025227 134
4e9c5124 135Input is in interactive mode. It means that you can use the arrow keys to move
136up and down through the history, tab-autocomplete or double-tab to view
137available suggestions. Input history from previous run is also available.
4f025227 138
4e9c5124 139`Read the docs`_ for available commands.
4f025227 140
4e9c5124 141Theme Customization
4f025227
O
142^^^^^^^^^^^^^^^^^^^
143
4e9c5124 144Rainbow Stream is shipped with some default themes. You can switch themes with
145the ``theme`` command. You can also customize themes as you please.
4f025227 146
4e9c5124 147Theme screenshots:
4f025227
O
148
149- Monokai
150
151.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png
152 :alt: monokai
153
154- Solarized
155
156.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png
157 :alt: solarized
158
159- Tomorrow Night
160
161.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png
162 :alt: tomorrownight
163
164- Larapaste
165
166.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png
167 :alt: larapaste
168
4e9c5124 169See `Theme Usage and Customization`_ for detailed information.
4f025227
O
170
171
4e9c5124 172Bug and Feature Requests
4f025227
O
173------------------------
174
4e9c5124 175Found a bug or a feature request? Please `create an issue`_ or contact me at
176`@dtvd88`_.
4f025227
O
177
178Development
179-----------
180
4e9c5124 181If you want to build a runnable version yourself, follow these simple steps:
4f025227
O
182
183- `Create your own Twitter Application`_
184- Get your Twitter application’s API key and secret
185- `Create your own Pocket Application`_ (platform: Web)
186- Get your Pocket application’s key
4e9c5124 187- Fork this repo and ``git clone`` it
188- Create a ``consumer.py`` file in the `rainbowstream`_ directory containing:
4f025227
O
189
190 .. code:: python
191
192 # Consumer information
193 CONSUMER_KEY = 'APIKey' # Your Twitter application's API key
194 CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret
195 PCKT_CONSUMER_KEY = 'PocketAPIKey' # Your Pocket application's API key
196
4e9c5124 197- Use pip to install it locally
4f025227
O
198
199 .. code:: bash
200
201 # cd to directory which contains setup.py (cloned directory)
202 virtualenv venv # Python3 users: use -p to specify python3
203 source venv/bin/activate
204 pip install -e .
205 which rainbowstream # /this-directory/venv/bin/rainbowstream
4e9c5124 206 # Remove ~/.rainbow_oauth if it exists
4f025227
O
207 rainbowstream # local version of rainbowstream
208
209
210Contributing
211------------
4e9c5124 212
213I appreciate any help and support. Feel free to `fork`_ and `create a pull
214request`_. You will be listed as a contributor.
4f025227
O
215
216License
217-------
218
4e9c5124 219Rainbow Stream is released under an MIT License. See LICENSE.txt for details.
4f025227
O
220
221
4e9c5124 222.. _Python Twitter Tools: http://mike.verdone.ca/twitter/
4f025227 223.. _Twitter API: https://dev.twitter.com/docs/api/1.1
4e9c5124 224.. _Create an issue: https://github.com/DTVD/rainbowstream/issues/new
4f025227
O
225.. _@dtvd88: https://twitter.com/dtvd88
226.. _fork: https://github.com/DTVD/rainbowstream/fork
227.. _create a pull request: https://github.com/DTVD/rainbowstream/compare/
4e9c5124 228.. _Read the docs: http://rainbowstream.readthedocs.org/en/latest/
4f025227 229.. _config guide: https://github.com/DTVD/rainbowstream/blob/master/theme.md
4e9c5124 230.. _Theme Usage and Customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md
4f025227
O
231.. _Create your own Twitter Application: https://apps.twitter.com/app/new
232.. _Create your own Pocket Application: https://getpocket.com/developer/apps/new
233.. _rainbowstream: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream
234.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
4e9c5124 235.. _Config Management: http://rainbowstream.readthedocs.org/en/latest/#config-explanation
4f025227
O
236.. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/
237.. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10