Unlokc request version
[rainbowstream.git] / README.rst
1 A Note about Twitter API Change
2 -------------------------------
3
4 Heads-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
6 If you are interested in detail: https://github.com/orakaro/rainbowstream/issues/271
7
8 Rainbow 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
17 Terminal-based Twitter Client.  Real-time tweetstream, compose, search, favorite,
18 and much more fun directly from terminal.
19
20 This package is built on the `Python Twitter Tools`_ and the `Twitter API`_, and runs
21 on Python (2.7.x and 3.x).
22
23 Home page: https://github.com/orakaro/rainbowstream
24
25 Source code: https://github.com/DTVD/rainbowstream
26
27 Showcase
28 --------
29
30 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/rs.gif
31    :alt: gif
32
33 Installation
34 ------------
35
36 The Quick Way
37 ^^^^^^^^^^^^^
38
39 System 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
46 The 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
59 Troubleshooting
60 ^^^^^^^^^^^^^^^
61
62 Some additional libraries may need to be installed on linux.
63
64 For Debian-based distros:
65
66 .. code:: bash
67
68     sudo apt-get install python-dev libjpeg-dev libfreetype6 libfreetype6-dev zlib1g-dev
69
70 For CentOS:
71
72 .. code:: bash
73
74     sudo yum install python-devel libjpeg-devel
75
76 Mac OSX Maverick with Xcode 5.1 has a well-known `clang unknown argument`_
77 problem with the installation of the ``Pillow`` package—a dependency of this
78 app.  Take a look at `Issue #10`_ and let me know if the workaround doesn't work
79 for you.
80
81 .. code:: bash
82
83     export ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future
84
85 If *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
93 Usage
94 -----
95
96 The Stream
97 ^^^^^^^^^^
98
99 Just type ``rainbowstream`` to see your stream.
100
101 You 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
107 Set ``IMAGE_ON_TERM`` to ``True`` in your config to to enable above feature,
108 change ``IMAGE_SHIFT`` to set image's margin (relative to your terminal's
109 width), and ``IMAGE_MAX_HEIGHT`` to control max height of every image (see
110 `Config Management`_).
111
112 You will be asked for authorization on Twitter the first time you run Rainbow
113 Stream.  Just click the "Authorize access" button, paste PIN number to the
114 terminal, and the rainbow will start.
115
116 You might want to use Rainbow Stream with an **HTTP/SOCKS proxy**.  Proxy
117 settings 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
125 Both ``--proxy-port`` and ``--proxy-type`` are optional.  The default proxy port
126 is ``8080`` and the default proxy type is ``SOCKS5``.
127
128 Interactive Mode
129 ^^^^^^^^^^^^^^^^
130
131 While your personal stream is continued, you are also ready to tweet, search,
132 reply, retweet, etc. directly from your console.  Simply type ``h`` and hit the
133 Enter key to see the help.
134
135 Input is in interactive mode.  It means that you can use the arrow keys to move
136 up and down through the history, tab-autocomplete or double-tab to view
137 available suggestions.  Input history from previous run is also available.
138
139 `Read the docs`_ for available commands.
140
141 Theme Customization
142 ^^^^^^^^^^^^^^^^^^^
143
144 Rainbow Stream is shipped with some default themes.  You can switch themes with
145 the ``theme`` command.  You can also customize themes as you please.
146
147 Theme 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
169 See `Theme Usage and Customization`_ for detailed information.
170
171
172 Bug and Feature Requests
173 ------------------------
174
175 Found a bug or a feature request?  Please `create an issue`_ or contact me at
176 `@dtvd88`_.
177
178 Development
179 -----------
180
181 If 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
210 Contributing
211 ------------
212
213 I appreciate any help and support.  Feel free to `fork`_ and `create a pull
214 request`_.  You will be listed as a contributor.
215
216 License
217 -------
218
219 Rainbow 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