Bumped version 1.5.2
[rainbowstream.git] / docs / index.rst
1 Rainbow Stream
2 --------------
3
4 .. image:: http://img.shields.io/pypi/l/rainbowstream.svg?style=flat-square
5    :target: https://github.com/DTVD/rainbowstream/blob/master/LICENSE.txt
6
7 .. image:: http://img.shields.io/pypi/v/rainbowstream.svg?style=flat-square
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 Home page : http://www.rainbowstream.org/
17
18 Source code : https://github.com/DTVD/rainbowstream
19
20 Install
21 -------
22
23 The quick way
24 ^^^^^^^^^^^^^
25
26 You will need Python and pip (2.7.x or 3.x).
27
28 .. code:: bash
29
30     sudo pip install rainbowstream
31     # Python 3 users: sudo pip3 install rainbowstream
32
33 The recommended way
34 ^^^^^^^^^^^^^^^^^^^
35
36 Use `virtualenv`_
37
38 .. code:: bash
39
40     virtualenv venv
41     # Python 3 users : use -p to specify your Python 3 localtion as below
42     # virtualenv -p /usr/bin/python3 venv
43     source venv/bin/activate
44     pip install rainbowstream
45
46 Troubleshooting
47 ^^^^^^^^^^^^^^^
48
49 If you use Linux, you might need to install some packages if you haven't already.
50 For debian-based distros, these can be installed with
51
52 .. code:: bash
53
54     sudo apt-get install python-dev libjpeg libjpeg-dev libfreetype6 libfreetype6-dev zlib1g-dev
55
56 Besides, Mac OSX Maverick with Xcode 5.1 has a well-known `clang unknown argument`_ problem with
57 the ``Pillow`` package installation - a dependency of this app.
58 If you are in this case, I recommend taking a look at `Issue #10`_ and let me know if this workaround doesn't work for you.
59
60 .. code:: bash
61
62     export ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future
63
64 If installation in *the quick way* doesn't work:
65
66 -  ``sudo pip uninstall rainbowstream``
67 -  use the *virtualenv way* above
68 -  `create an issue`_ and provide:
69
70   + Your OS
71   + Your Python version
72
73 Usage
74 -----
75
76 The stream
77 ^^^^^^^^^^
78
79 Just type
80
81 .. code:: bash
82
83     rainbowstream
84
85 and see your stream.
86
87 I shipped a feature which can display **tweet's images directly on terminal**.
88 You can try it with:
89
90 .. code:: bash
91
92     rainbowstream -iot # Or rainbowstream --image-on-term
93
94 You also can change the config key ``IMAGE_ON_TERM`` to ``True`` inside the app
95 to enable above feature,
96 change ``IMAGE_SHIFT`` to set image's margin (relative to your terminal's width)
97 or ``IMAGE_MAX_HEIGHT`` to control max height of every image.
98 (see `config management`_ section).
99
100 In the first time you will be asked for authorization of Rainbow Stream
101 app at Twitter. Just click the “Authorize access” button and paste PIN
102 number to the terminal, the rainbow will start.
103
104 You might want to use rainbowstream via an **HTTP/SOCKS proxy**. Proxy settings are
105 provided as follows:
106
107 .. code:: bash
108
109     rainbowstream --proxy-host localhost --proxy-port 1337 --proxy-type HTTP
110     # or using the short form:
111     rainbowstream -ph localhost -pp 1337 -pt HTTP
112
113 Both ``--proxy-port`` and ``--proxy-type`` can be omitted. In this case default
114 proxy port ``8080`` and default proxy type ``SOCKS5`` are used.
115
116 If you would like to specify an alternate location for storing the OAuth credential files for both twitter and pocket you can do so with the ``--twitter-auth`` and ``--pocket-auth`` settings. This is also useful if you wish to have multiple accounts for rainbowstream. Specify a location as follows:
117
118 .. code:: bash
119
120     rainbowstream --twitter-auth /path/to/twitter_oauth
121     # or using the short form:
122     rainbowstream -ta /path/to/twitter_oauth
123
124 If the oauth file doesn't exist at the location you specified then a new one will be created and you'll be required to autenticate with Twitter again.
125
126 The interactive mode
127 ^^^^^^^^^^^^^^^^^^^^
128
129 While your personal stream is continued, you are also ready to tweet,
130 search, reply, retweet… directly from console. Simply type “h” and hit
131 the Enter key to see the help.
132
133 Input is in interactive mode. It means that you can use arrow key to
134 move up and down history, tab-autocomplete or 2 tab to view available
135 suggestion. Input history from previous run is available as well.
136
137 Here is full list of supported command:
138
139 **Explore Commands**
140
141 -  ``trend`` will show global trending topics. ``trend US`` will show trends in United States while ``trend JP Tokyo`` will show trends in Tokyo/Japan.
142
143 -  ``home`` will show your timeline. ``home 10`` will print exactly 10 tweets.
144
145 -  ``me`` will show your latest tweets. ``me 2`` will show your last 2 tweets.
146
147 -  ``notification`` will show your notification from the time you started RainbowStream.
148
149 -  ``mentions`` will show mentions timeline. ``mentions 7`` will show 7 mention tweets.
150
151 -  ``whois @dtvd88`` will show profile of @dtvd88.
152
153 -  ``view @mdo`` will show @mdo ’s timeline. ``view @dmo 9`` will print exactly 9 tweets.
154
155 -  ``s noah`` will search the word *‘noah’*. Result will come back with highlight. Search can be performed with or without hashtag.
156
157 **Tweet Commands**
158
159 -  ``t the rainbow is god's promise to noah`` will tweet exactly *‘the rainbow is god’s promise to noah’*.
160
161 -  ``rt 12`` will retweet the tweet with *[id=12]*. You can see id of each tweet beside the time.
162
163 -  ``quote 12`` will quote the tweet with *[id=12]*. If no extra text is added, the quote will be cancelled.
164
165 -  ``allrt 12 20`` will list 20 newest retweets of the tweet with *[id=12]*. If the number of retweets is not specified, 5 newest retweets will be listed instead.
166
167 -  ``conversation 12`` will show the chain of replies prior to the tweet with *[id=12]*.
168
169 -  ``rep 12 Really`` will reply *‘Really’* to the owner of the tweet with *[id=12]*.
170
171 -  ``repall 12 Really`` will reply *‘Really’* to all people in the tweet with *[id=12]*.
172
173 -  ``fav 12`` will favorite the tweet with *[id=12]*.
174
175 -  ``ufav 12`` will unfavorite tweet with *[id=12]*.
176
177 -  ``share 12`` will copy link to tweet with *[id=12]* to your clipboard if you are on a Mac, or display it directly if you are on Linux.
178
179 -  ``del 12`` will delete tweet with *[id=12]*.
180
181 -  ``show image 12`` will show the image in tweet with *[id=12]* in your OS’s image viewer.
182
183 -  ``open 12`` will open url in tweet with *[id=12]* in your OS’s default browser.
184
185 -  ``pt 12`` will add tweet with *[id=12]* in your Pocket list.
186
187 **Direct Messages Commands**
188
189 -  ``inbox`` will show inbox messages. ``inbox 7`` will show newest 7 messages.
190
191 -  ``thread 2`` will show full thread with [id=2].
192
193 -  ``mes @dtvd88 hi`` will send a ``hi`` message to @dtvd88.
194
195 -  ``trash 5`` will remove message with *[message\_id=5]*
196
197 **Friends and followers Commands**
198
199 -  ``ls fl`` will list all your followers (people who are following you).
200
201 -  ``ls fr`` will list all your friends (people who you are following).
202
203 -  ``fl @dtvd88`` will follow @dtvd88.
204
205 -  ``ufl @dtvd88`` will unfollow @dtvd88.
206
207 -  ``mute @dtvd88`` will mute @dtvd88.
208
209 -  ``unmute @dtvd88`` will unmute @dtvd88.
210
211 -  ``muting`` will list muting users.
212
213 -  ``block @dtvd88`` will block @dtvd88.
214
215 -  ``unblock @dtvd88`` will unblock @dtvd88.
216
217 -  ``report @dtvd88`` will report @dtvd88 as a spam account.
218
219 **Twitter list**
220
221 -  ``list`` will show all lists you are belong to.
222
223 -  ``list home`` will show timeline of list. You will be asked for list's name.
224
225 -  ``list all_mem`` will show list's all members.
226
227 -  ``list all_sub`` will show list's all subscribers.
228
229 -  ``list add`` will add specific person to a list owned by you.
230
231 -  ``list rm`` will remove specific person from a list owned by you.
232
233 -  ``list sub`` will subscribe you to a specific list.
234
235 -  ``list unsub`` will unsubscribe you from a specific list.
236
237 -  ``list own`` will show all list owned by you.
238
239 -  ``list new`` will create a new list.
240
241 -  ``list update`` will update a list owned by you.
242
243 -  ``list del`` will delete a list owned by you.
244
245 **Switching Stream Commands**
246
247 -  ``switch public #AKB48`` will switch current stream to public stream and track keyword ``AKB48``
248
249 -  ``switch public #AKB48 -f`` will do exactly as above but will ask you to provide 2 list:
250
251    ``Only nicks`` decide what nicks will be include only.
252
253    ``Ignore nicks``\ decide what nicks will be exclude.
254
255 -  ``switch mine`` will switch current stream to personal stream. ``-f`` will work as well.
256
257 -  ``switch list`` will switch to a Twitter list's stream. You will be asked for list name.
258
259 **Smart shell**
260
261 - Put anything to terminal, the app will try to eval and display result as a python interactive shell.
262
263   + ``142857*2`` or ``101**3`` like a calculator.
264   + Even ``cal`` will show the calendar for current month.
265   + Put ``order_rainbow('anything')`` or ``random_rainbow('wahahaha')`` will make more fun :)
266
267 **Config Management**
268
269 -  ``theme`` will list available themes.
270
271   + ``theme monokai`` will apply *monokai* theme immediately.
272   + Changed theme will be remember as the next time's default theme.
273
274 -  ``config`` will list all config key.
275
276   + ``config ASCII_ART`` will output current value of *ASCII_ART* config key.
277   + ``config TREND_MAX default`` will output default value of *TREND_MAX* config key.
278   + ``config CUSTOM_CONFIG drop`` will drop *CUSTOM_CONFIG* config key.
279   + ``config IMAGE_ON_TERM = true`` will set value of *IMAGE_ON_TERM* config key to *True*.
280
281 **Screening Commands**
282
283 -  ``h`` will show the help.
284
285 -  ``p`` will pause the stream.
286
287 -  ``r`` will unpause the stream.
288
289 -  ``c`` will clear the screen.
290
291 -  ``v`` will show version info.
292
293 -  ``q`` will quit.
294
295 Theme customization
296 ^^^^^^^^^^^^^^^^^^^
297
298 Rainbow Stream is shipped with some default themes.
299 You can either change theme by ``theme`` command or create your favorite one.
300
301 Theme’s screenshot:
302
303 - Monokai
304
305 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png
306    :alt: monokai
307
308 - Solarized
309
310 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png
311    :alt: solarized
312
313 - Tomorrow Night
314
315 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png
316    :alt: tomorrownight
317
318 - Larapaste
319
320 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png
321    :alt: larapaste
322
323 For detaile information, see `theme usage and customization`_.
324
325 Config explanation
326 ^^^^^^^^^^^^^^^^^^
327
328 Rainbow Stream has a custom config file located at ``~/.rainbow_config.json`` which will be loaded **after** its `default config`_. You are free to change anything on your custom config. If you mess up the JSON format the app will still work but you'll need to overwrite your custom config with the `default config`_ to solve format problems.
329
330 If you would like to specify a different location for your custom config you can set the ``RAINBOW_CONFIG`` environment variable to the location of your custom config.
331
332 You also can view or set a new value of every config key with the ``config`` command (See **Interactive mode** section above).
333
334 -  ``HEARTBEAT_TIMEOUT``: after this timeout (count by minutes), the stream will automatically hangup.
335
336 -  ``IMAGE_ON_TERM``: display tweet's image directly on terminal.
337
338 -  ``IMAGE_RESIZE_TO_FIT``: display tweet's image fit inside terminal view (width and height).
339
340 -  ``THEME``: current theme.
341
342 -  ``ASCII_ART``: diplay your twitter name by ascii art at stream begin or not.
343
344 -  ``HIDE_PROMPT``: hide prompt after receiving a tweet or not.
345
346 -  ``PREFIX``: display formated string of prompt.
347
348     + ``#me``: Your username with '@', only available in personal stream.
349     + ``#place``: List name, only available in list stream.
350     + ``#owner``: Owner of list name, only available in list stream.
351     + ``#keyword``: Keyword, only available on public stream.
352
353 -  ``SEARCH_TYPE``: search type in 'search' command ('mixed','recent','popular').
354
355 -  ``SEARCH_MAX_RECORD``: max tweets can display on 'search' command.
356
357 -  ``HOME_TWEET_NUM``: default tweets to display on 'home' command.
358
359 -  ``RETWEETS_SHOW_NUM``: default tweets to display on 'allrt' command.
360
361 -  ``CONVERSATION_MAX``: max tweet in a 'conversation' thread.
362
363 -  ``QUOTE_FORMAT``: format when quote a tweet
364
365     + ``#comment``: Your own comment about the tweet
366     + ``#owner``: owner's username *without* '@'
367     + ``#tweet``: original tweet
368     + ``#tid``: the tweet id on Twitter
369
370 -  ``THREAD_META_LEFT``: format for meta information of messages from partner which is display in the left of screen.
371
372 -  ``THREAD_META_RIGHT``: format for meta information of messages from you which is display in the right of screen.
373
374 -  ``THREAD_MIN_WIDTH``: minimum width of a message frame.
375
376 -  ``NOTIFY_FORMAT``: format of a notification.
377
378 -  ``MESSAGES_DISPLAY``: default messages to display on 'inbox' or 'sent' command.
379
380 -  ``TREND_MAX``: default trends to display on 'trend' command.
381
382 -  ``LIST_MAX``: default tweets to display on 'list home' command.
383
384 -  ``ONLY_LIST``: filter list on 'switch' command. Eg: ["@fat","mdo"]
385
386 -  ``IGNORE_LIST``: ignore list on 'switch' command. Eg: ["@fat"]
387
388 -  ``HISTORY_FILENAME``: name of file which stores input history.
389
390 -  ``IMAGE_SHIFT``: left and right margin of image in '-iot'/'--image-on-term' mode.
391
392 -  ``IMAGE_MAX_HEIGHT``: max height of image in '-iot'/'--image-on-term' mode.
393
394 -  ``STREAM_DELAY``: seconds to wait before displaying another tweet, will drop all tweets while waiting. This value can be used to slow down the stream.
395
396 -  ``USER_DOMAIN``: user URL of Twitter Streaming API.
397
398 -  ``PUBLIC_DOMAIN``: public URL of Twitter Streaming API.
399
400 -  ``SITE_DOMAIN``: site URL of Twitter Streaming API.
401
402 -  ``FORMAT``: display format for tweet and message.
403
404   + ``CLOCK_FORMAT``: time format, see `Python's strftime format`_.
405   + ``DISPLAY``: decide how tweet will be printed.
406
407     + ``#name``: Twitter's name
408     + ``#nick``: Twitter's screen name
409     + ``#clock``: Datetime
410     + ``#rt_count``: retweets count
411     + ``#fa_count``: favorites count
412     + ``#id``: ID
413     + ``#fav``: favorited symbol
414     + ``#fav``: favorited symbol
415     + ``#tweet``: Tweet's content
416     + ``#sender_name``: Message's sender name
417     + ``#sender_nick``: Message's sender screen name
418     + ``#to``: '>>>' symbol
419     + ``#recipient_name``: Message's recipient name
420     + ``#recipient_nick``: Message's recipient screen name
421
422 - ``POCKET_SUPPORT`` : enable Pocket support.
423
424 In every format, you can use unicode characters like ``\u2665``.
425 Mac users also can use emoji characters as well (Ex: ``::zap::``).
426 See `Emoji cheatsheet`_ for details.
427
428 Development
429 -----------
430
431 If you want to build a runnable version yourself, follow these simple
432 steps
433
434 -  `Create your own Twitter Application`_
435 -  Get your Twitter application’s API key and secret
436 -  Fork github's repo and clone in your system.
437 -  Create a file ``consumer.py`` in `rainbowstream`_ folder with
438    following content
439
440    .. code:: python
441
442        # Consumer information
443        CONSUMER_KEY = 'APIKey' # Your Twitter application's API key
444        CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret
445        PCKT_CONSUMER_KEY = 'PocketAPIKey' # Your Pocket application's API key
446
447 -  Use pip to install in local
448
449    .. code:: bash
450
451        # cd to directory which contains setup.py (cloned directory)
452        virtualenv venv # Python3 users: use -p to specify python3
453        source venv/bin/activate
454        pip install -e .
455        which rainbowstream # /this-directory/venv/bin/rainbowstream
456        # Remove ~/.rainbow_oauth if exists
457        rainbowstream # local version of rainbowstream
458
459 .. _Python Twitter Tool: http://mike.verdone.ca/twitter/
460 .. _Twitter API: https://dev.twitter.com/docs/api/1.1
461 .. _Create your own Twitter Application: https://apps.twitter.com/app/new
462 .. _Create your own Pocket Application: https://getpocket.com/developer/apps/new
463 .. _rainbowstream: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream
464 .. _Python Twitter Tool: http://mike.verdone.ca/twitter/
465 .. _Twitter API: https://dev.twitter.com/docs/api/1.1
466 .. _theme usage and customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md
467 .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
468 .. _config management: http://rainbowstream.readthedocs.org/en/latest/#config-explanation
469 .. _Python's strftime format: https://docs.python.org/2/library/time.html#time.strftime
470 .. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/
471 .. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10
472 .. _default config: https://github.com/DTVD/rainbowstream/blob/master/rainbowstream/colorset/config
473 .. _Emoji cheatsheet: http://www.emoji-cheat-sheet.com/