Bumped version 1.5.2
[rainbowstream.git] / README.rst
... / ...
CommitLineData
1A Note about Twitter API Change
2-------------------------------
3
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 :)
5
6If you are interested in detail: https://github.com/orakaro/rainbowstream/issues/271
7
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
17Terminal-based Twitter Client. Real-time tweetstream, compose, search, favorite,
18and much more fun directly from terminal.
19
20This package is built on the `Python Twitter Tools`_ and the `Twitter API`_, and runs
21on Python (2.7.x and 3.x).
22
23Home page: https://github.com/orakaro/rainbowstream
24
25Source code: https://github.com/orakaro/rainbowstream
26
27Showcase
28--------
29
30.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/rs.gif
31 :alt: gif
32
33Installation
34------------
35
36The Quick Way
37^^^^^^^^^^^^^
38
39System Python (2.7.x or 3.x)
40
41.. code:: bash
42
43 sudo pip install rainbowstream
44 # Python 3 users: sudo pip3 install rainbowstream
45
46The Recommended Way
47^^^^^^^^^^^^^^^^^^^
48
49`virtualenv`_
50
51.. code:: bash
52
53 virtualenv venv
54 # Python 3 users : use -p to specify your Python 3 location:
55 # virtualenv -p /usr/bin/python3 venv
56 source venv/bin/activate
57 pip install rainbowstream
58
59Troubleshooting
60^^^^^^^^^^^^^^^
61
62Some additional libraries may need to be installed on linux.
63
64For Debian-based distros:
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
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.
80
81.. code:: bash
82
83 export ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future
84
85If *The Quick Way* doesn't work, then:
86
87- ``sudo pip uninstall rainbowstream``
88- Use the *The Recommended Way*
89- `Create an issue`_ and provide:
90 - Your OS
91 - Your Python version
92
93Usage
94-----
95
96The Stream
97^^^^^^^^^^
98
99Just type ``rainbowstream`` to see your stream.
100
101You can now **display tweeted images directly on the terminal**! Try it with:
102
103.. code:: bash
104
105 rainbowstream -iot # Or rainbowstream --image-on-term
106
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`_).
111
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.
115
116You might want to use Rainbow Stream with an **HTTP/SOCKS proxy**. Proxy
117settings are specified as follows:
118
119.. code:: bash
120
121 rainbowstream --proxy-host localhost --proxy-port 1337 --proxy-type HTTP
122 # or the short form:
123 rainbowstream -ph localhost -pp 1337 -pt HTTP
124
125Both ``--proxy-port`` and ``--proxy-type`` are optional. The default proxy port
126is ``8080`` and the default proxy type is ``SOCKS5``.
127
128Interactive Mode
129^^^^^^^^^^^^^^^^
130
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.
134
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.
138
139`Read the docs`_ for available commands.
140
141Theme Customization
142^^^^^^^^^^^^^^^^^^^
143
144Rainbow Stream is shipped with some default themes. You can switch themes with
145the ``theme`` command. You can also customize themes as you please.
146
147Theme screenshots:
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
169See `Theme Usage and Customization`_ for detailed information.
170
171
172Bug and Feature Requests
173------------------------
174
175Found a bug or a feature request? Please `create an issue`_ or contact me at
176`@dtvd88`_.
177
178Development
179-----------
180
181If you want to build a runnable version yourself, follow these simple steps:
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
187- Fork this repo and ``git clone`` it
188- Create a ``consumer.py`` file in the `rainbowstream`_ directory containing:
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
197- Use pip to install it locally
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
206 # Remove ~/.rainbow_oauth if it exists
207 rainbowstream # local version of rainbowstream
208
209
210Contributing
211------------
212
213I appreciate any help and support. Feel free to `fork`_ and `create a pull
214request`_. You will be listed as a contributor.
215
216License
217-------
218
219Rainbow Stream is released under an MIT License. See LICENSE.txt for details.
220
221
222.. _Python Twitter Tools: http://mike.verdone.ca/twitter/
223.. _Twitter API: https://dev.twitter.com/docs/api/1.1
224.. _Create an issue: https://github.com/DTVD/rainbowstream/issues/new
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/
228.. _Read the docs: http://rainbowstream.readthedocs.org/en/latest/
229.. _config guide: https://github.com/DTVD/rainbowstream/blob/master/theme.md
230.. _Theme Usage and Customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md
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/
235.. _Config Management: http://rainbowstream.readthedocs.org/en/latest/#config-explanation
236.. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/
237.. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10