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 The interactive mode
 117 ^^^^^^^^^^^^^^^^^^^^
 118
 119 While your personal stream is continued, you are also ready to tweet,
 120 search, reply, retweet… directly from console. Simply type “h” and hit
 121 the Enter key to see the help.
 122
 123 Input is in interactive mode. It means that you can use arrow key to
 124 move up and down history, tab-autocomplete or 2 tab to view available
 125 suggestion. Input history from previous run is available as well.
 126
 127 Here 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 **Direct Messages Commands**
 176
 177 -  ``inbox`` will show inbox messages. ``inbox 7`` will show newest 7 messages.
 178
 179 -  ``thread 2`` will show full thread with [id=2].
 180
 181 -  ``mes @dtvd88 hi`` will send a ``hi`` message to @dtvd88.
 182
 183 -  ``trash 5`` will remove message with *[message\_id=5]*
 184
 185 **Friends and followers Commands**
 186
 187 -  ``ls fl`` will list all your followers (people who are following you).
 188
 189 -  ``ls fr`` will list all your friends (people who you are following).
 190
 191 -  ``fl @dtvd88`` will follow @dtvd88.
 192
 193 -  ``ufl @dtvd88`` will unfollow @dtvd88.
 194
 195 -  ``mute @dtvd88`` will mute @dtvd88.
 196
 197 -  ``unmute @dtvd88`` will unmute @dtvd88.
 198
 199 -  ``muting`` will list muting users.
 200
 201 -  ``block @dtvd88`` will block @dtvd88.
 202
 203 -  ``unblock @dtvd88`` will unblock @dtvd88.
 204
 205 -  ``report @dtvd88`` will report @dtvd88 as a spam account.
 206
 207 **Twitter list**
 208
 209 -  ``list`` will show all lists you are belong to.
 210
 211 -  ``list home`` will show timeline of list. You will be asked for list's name.
 212
 213 -  ``list all_mem`` will show list's all members.
 214
 215 -  ``list all_sub`` will show list's all subscribers.
 216
 217 -  ``list add`` will add specific person to a list owned by you.
 218
 219 -  ``list rm`` will remove specific person from a list owned by you.
 220
 221 -  ``list sub`` will subscribe you to a specific list.
 222
 223 -  ``list unsub`` will unsubscribe you from a specific list.
 224
 225 -  ``list own`` will show all list owned by you.
 226
 227 -  ``list new`` will create a new list.
 228
 229 -  ``list update`` will update a list owned by you.
 230
 231 -  ``list del`` will delete a list owned by you.
 232
 233 **Switching Stream Commands**
 234
 235 -  ``switch public #AKB48`` will switch current stream to public stream and track keyword ``AKB48``
 236
 237 -  ``switch public #AKB48 -f`` will do exactly as above but will ask you to provide 2 list:
 238
 239    ``Only nicks`` decide what nicks will be include only.
 240
 241    ``Ignore nicks``\ decide what nicks will be exclude.
 242
 243 -  ``switch mine`` will switch current stream to personal stream. ``-f`` will work as well.
 244
 245 -  ``switch list`` will switch to a Twitter list's stream. You will be asked for list name.
 246
 247 **Smart shell**
 248
 249 - Put anything to terminal, the app will try to eval and display result as a python interactive shell.
 250
 251   + ``142857*2`` or ``101**3`` like a calculator.
 252   + Even ``cal`` will show the calendar for current month.
 253   + Put ``order_rainbow('anything')`` or ``random_rainbow('wahahaha')`` will make more fun :)
 254
 255 **Config Management**
 256
 257 -  ``theme`` will list available themes.
 258
 259   + ``theme monokai`` will apply *monokai* theme immediately.
 260   + Changed theme will be remember as the next time's default theme.
 261
 262 -  ``config`` will list all config key.
 263
 264   + ``config ASCII_ART`` will output current value of *ASCII_ART* config key.
 265   + ``config TREND_MAX default`` will output default value of *TREND_MAX* config key.
 266   + ``config CUSTOM_CONFIG drop`` will drop *CUSTOM_CONFIG* config key.
 267   + ``config IMAGE_ON_TERM = true`` will set value of *IMAGE_ON_TERM* config key to *True*.
 268
 269 **Screening Commands**
 270
 271 -  ``h`` will show the help.
 272
 273 -  ``p`` will pause the stream.
 274
 275 -  ``r`` will unpause the stream.
 276
 277 -  ``c`` will clear the screen.
 278
 279 -  ``v`` will show version info.
 280
 281 -  ``q`` will quit.
 282
 283 Theme customization
 284 ^^^^^^^^^^^^^^^^^^^
 285
 286 Rainbow Stream is shipped with some default themes.
 287 You can either change theme by ``theme`` command or create your favorite one.
 288
 289 Theme’s screenshot:
 290
 291 - Monokai
 292
 293 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png
 294    :alt: monokai
 295
 296 - Solarized
 297
 298 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png
 299    :alt: solarized
 300
 301 - Tomorrow Night
 302
 303 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png
 304    :alt: tomorrownight
 305
 306 - Larapaste
 307
 308 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png
 309    :alt: larapaste
 310
 311 For detaile information, see `theme usage and customization`_.
 312
 313 Config explanation
 314 ^^^^^^^^^^^^^^^^^^
 315
 316 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, 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.
 317
 318 You also can view or set a new value of every config key by ``config`` command (See **Interactive mode** section above).
 319
 320 -  ``HEARTBEAT_TIMEOUT``: after this timeout (count by minutes), the stream will automatically hangup.
 321
 322 -  ``IMAGE_ON_TERM``: display tweet's image directly on terminal.
 323
 324 -  ``IMAGE_RESIZE_TO_FIT``: display tweet's image fit inside terminal view (width and height).
 325
 326 -  ``THEME``: current theme.
 327
 328 -  ``ASCII_ART``: diplay your twitter name by ascii art at stream begin or not.
 329
 330 -  ``HIDE_PROMPT``: hide prompt after receiving a tweet or not.
 331
 332 -  ``PREFIX``: display formated string of prompt.
 333
 334     + ``#me``: Your username with '@', only available in personal stream.
 335     + ``#place``: List name, only available in list stream.
 336     + ``#owner``: Owner of list name, only available in list stream.
 337     + ``#keyword``: Keyword, only available on public stream.
 338
 339 -  ``SEARCH_TYPE``: search type in 'search' command ('mixed','recent','popular').
 340
 341 -  ``SEARCH_MAX_RECORD``: max tweets can display on 'search' command.
 342
 343 -  ``HOME_TWEET_NUM``: default tweets to display on 'home' command.
 344
 345 -  ``RETWEETS_SHOW_NUM``: default tweets to display on 'allrt' command.
 346
 347 -  ``CONVERSATION_MAX``: max tweet in a 'conversation' thread.
 348
 349 -  ``QUOTE_FORMAT``: format when quote a tweet
 350
 351     + ``#comment``: Your own comment about the tweet
 352     + ``#owner``: owner's username with '@'
 353     + ``#tweet``: original tweet
 354
 355 -  ``THREAD_META_LEFT``: format for meta information of messages from partner which is display in the left of screen.
 356
 357 -  ``THREAD_META_RIGHT``: format for meta information of messages from you which is display in the right of screen.
 358
 359 -  ``THREAD_MIN_WIDTH``: minimum width of a message frame.
 360
 361 -  ``NOTIFY_FORMAT``: format of a notification.
 362
 363 -  ``MESSAGES_DISPLAY``: default messages to display on 'inbox' or 'sent' command.
 364
 365 -  ``TREND_MAX``: default trends to display on 'trend' command.
 366
 367 -  ``LIST_MAX``: default tweets to display on 'list home' command.
 368
 369 -  ``ONLY_LIST``: filter list on 'switch' command. Eg: ["@fat","mdo"]
 370
 371 -  ``IGNORE_LIST``: ignore list on 'switch' command. Eg: ["@fat"]
 372
 373 -  ``HISTORY_FILENAME``: name of file which stores input history.
 374
 375 -  ``IMAGE_SHIFT``: left and right margin of image in '-iot'/'--image-on-term' mode.
 376
 377 -  ``IMAGE_MAX_HEIGHT``: max height of image in '-iot'/'--image-on-term' mode.
 378
 379 -  ``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.
 380
 381 -  ``USER_DOMAIN``: user URL of Twitter Streaming API.
 382
 383 -  ``PUBLIC_DOMAIN``: public URL of Twitter Streaming API.
 384
 385 -  ``SITE_DOMAIN``: site URL of Twitter Streaming API.
 386
 387 -  ``FORMAT``: display format for tweet and message.
 388
 389   + ``CLOCK_FORMAT``: time format, see `Python's strftime format`_.
 390   + ``DISPLAY``: decide how tweet will be printed.
 391
 392     + ``#name``: Twitter's name
 393     + ``#nick``: Twitter's screen name
 394     + ``#clock``: Datetime
 395     + ``#rt_count``: retweets count
 396     + ``#fa_count``: favorites count
 397     + ``#id``: ID
 398     + ``#fav``: favorited symbol
 399     + ``#fav``: favorited symbol
 400     + ``#tweet``: Tweet's content
 401     + ``#sender_name``: Message's sender name
 402     + ``#sender_nick``: Message's sender screen name
 403     + ``#to``: '>>>' symbol
 404     + ``#recipient_name``: Message's recipient name
 405     + ``#recipient_nick``: Message's recipient screen name
 406
 407 In every format, you can use unicode characters like ``\u2665``.
 408 Mac users also can use emoji characters as well (Ex: ``::zap::``).
 409 See `Emoji cheatsheet`_ for details.
 410
 411 Development
 412 -----------
 413
 414 If you want to build a runnable version yourself, follow these simple
 415 steps
 416
 417 -  `Create your own Twitter Application`_
 418 -  Get your Twitter application’s API key and secret
 419 -  Fork github's repo and clone in your system.
 420 -  Create a file ``consumer.py`` in ```rainbowstream```_ folder with
 421    following content
 422
 423    .. code:: python
 424
 425        # Consumer information
 426        CONSUMER_KEY = 'APIKey' # Your Twitter application's API key
 427        CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret
 428
 429 -  Use pip to install in local
 430
 431    .. code:: bash
 432
 433        # cd to directory which contains setup.py (cloned directory)
 434        virtualenv venv # Python3 users: use -p to specify python3
 435        source venv/bin/activate
 436        pip install -e .
 437        which rainbowstream # /this-directory/venv/bin/rainbowstream
 438        # Remove ~/.rainbow_oauth if exists
 439        rainbowstream # local version of rainbowstream
 440
 441 .. _Create your own Twitter Application: https://apps.twitter.com/app/new
 442 .. _``rainbowstream``: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream
 443 .. _Python Twitter Tool: http://mike.verdone.ca/twitter/
 444 .. _Twitter API: https://dev.twitter.com/docs/api/1.1
 445 .. _theme usage and customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md
 446 .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 447 .. _config management: http://rainbowstream.readthedocs.org/en/latest/#config-explanation
 448 .. _Python's strftime format: https://docs.python.org/2/library/time.html#time.strftime
 449 .. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/
 450 .. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10
 451 .. _default config: https://github.com/DTVD/rainbowstream/blob/master/rainbowstream/colorset/config
 452 .. _Emoji cheatsheet: http://www.emoji-cheat-sheet.com/