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