Fix bug can not quote in Python 2, Fix #195
[rainbowstream.git] / README.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 Showcase
21 --------
22
23 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/rs.gif
24    :alt: gif
25
26 Install
27 -------
28
29 The quick way
30 ^^^^^^^^^^^^^
31
32 You will need Python and pip (2.7.x or 3.x).
33
34 .. code:: bash
35
36     sudo pip install rainbowstream
37     # Python 3 users: sudo pip3 install rainbowstream
38
39
40 The recommended way
41 ^^^^^^^^^^^^^^^^^^^
42
43 Use `virtualenv`_
44
45 .. code:: bash
46
47     virtualenv venv
48     # Python 3 users : use -p to specify your Python 3 location as below
49     # virtualenv -p /usr/bin/python3 venv
50     source venv/bin/activate
51     pip install rainbowstream
52
53 Troubleshooting
54 ^^^^^^^^^^^^^^^
55
56 If you use Linux, you might need to install some packages if you haven't already.
57 For debian-based distros, these can be installed with
58
59 .. code:: bash
60
61     sudo apt-get install python-dev libjpeg-dev libfreetype6 libfreetype6-dev zlib1g-dev
62
63 For CentOS:
64
65 .. code:: bash
66
67     sudo yum install python-devel libjpeg-devel
68
69 Besides, Mac OSX Maverick with Xcode 5.1 has a well-known `clang unknown argument`_ problem with
70 the ``Pillow`` package installation - a dependency of this app.
71 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.
72
73 .. code:: bash
74
75     export ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future
76
77 If installation in *the quick way* doesn't work:
78
79 -  ``sudo pip uninstall rainbowstream``
80 -  use the *virtualenv way* above
81 -  `create an issue`_ and provide:
82
83   + Your OS
84   + Your Python version
85
86 Usage
87 -----
88
89 The stream
90 ^^^^^^^^^^
91
92 Just type
93
94 .. code:: bash
95
96     rainbowstream
97
98 and see your stream.
99
100 I shipped a feature which can display **tweet's images directly on terminal**.
101 You can try it with:
102
103 .. code:: bash
104
105     rainbowstream -iot # Or rainbowstream --image-on-term
106
107 You also can change the config key ``IMAGE_ON_TERM`` to ``True`` inside the app
108 to enable above feature,
109 change ``IMAGE_SHIFT`` to set image's margin (relative to your terminal's width)
110 or ``IMAGE_MAX_HEIGHT`` to control max height of every image.
111 (see `config management`_ section).
112
113 In the first time you will be asked for authorization of Rainbow Stream
114 app at Twitter. Just click the “Authorize access” button and paste PIN
115 number to the terminal, the rainbow will start.
116
117 You might want to use rainbowstream via an **HTTP/SOCKS proxy**. Proxy settings are
118 provided as follows:
119
120 .. code:: bash
121
122     rainbowstream --proxy-host localhost --proxy-port 1337 --proxy-type HTTP
123     # or using the short form:
124     rainbowstream -ph localhost -pp 1337 -pt HTTP
125
126 Both ``--proxy-port`` and ``--proxy-type`` can be omitted. In this case default
127 proxy port ``8080`` and default proxy type ``SOCKS5`` are used.
128
129 The interactive mode
130 ^^^^^^^^^^^^^^^^^^^^
131
132 While your personal stream is continued, you are also ready to tweet,
133 search, reply, retweet… directly from console. Simply type “h” and hit
134 the Enter key to see the help.
135
136 Input is in interactive mode. It means that you can use arrow key to
137 move up and down history, tab-autocomplete or 2 tab to view available
138 suggestion. Input history from previous run is available as well.
139
140 Available commands are listed in `Read The Docs`_.
141
142 Theme customization
143 ^^^^^^^^^^^^^^^^^^^
144
145 Rainbow Stream is shipped with some default themes.
146 You can either change theme by ``theme`` command or create your favorite one.
147
148 Theme’s screenshot:
149
150 - Monokai
151
152 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png
153    :alt: monokai
154
155 - Solarized
156
157 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png
158    :alt: solarized
159
160 - Tomorrow Night
161
162 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png
163    :alt: tomorrownight
164
165 - Larapaste
166
167 .. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png
168    :alt: larapaste
169
170 For detail information, see `theme usage and customization`_.
171
172
173 Bug and feature requests
174 ------------------------
175
176 Found a bug or a feature request ?
177 Please `create an issue`_ or contact me at `@dtvd88`_
178
179 Development
180 -----------
181
182 If you want to build a runnable version yourself, follow these simple
183 steps
184
185 - `Create your own Twitter Application`_
186 -  Get your Twitter application’s API key and secret
187 - `Create your own Pocket Application`_ (platform: Web)
188 -  Get your Pocket application’s key
189 -  Fork this repo and clone in your system.
190 -  Create a file ``consumer.py`` in `rainbowstream`_ folder with
191    following content
192
193    .. code:: python
194
195        # Consumer information
196        CONSUMER_KEY = 'APIKey' # Your Twitter application's API key
197        CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret
198        PCKT_CONSUMER_KEY = 'PocketAPIKey' # Your Pocket application's API key
199
200 -  Use pip to install in local
201
202    .. code:: bash
203
204        # cd to directory which contains setup.py (cloned directory)
205        virtualenv venv # Python3 users: use -p to specify python3
206        source venv/bin/activate
207        pip install -e .
208        which rainbowstream # /this-directory/venv/bin/rainbowstream
209        # Remove ~/.rainbow_oauth if exists
210        rainbowstream # local version of rainbowstream
211
212
213 Contributing
214 ------------
215 I appreciate any help and support. Feel free to `fork`_ and `create a pull request`_.
216 You will be listed as contributor.
217
218 License
219 -------
220
221 Rainbow Stream are released under an MIT License. See LICENSE.txt for
222 details
223
224
225 .. _python twitter tool: http://mike.verdone.ca/twitter/
226 .. _Twitter API: https://dev.twitter.com/docs/api/1.1
227 .. _create an issue: https://github.com/DTVD/rainbowstream/issues/new
228 .. _@dtvd88: https://twitter.com/dtvd88
229 .. _fork: https://github.com/DTVD/rainbowstream/fork
230 .. _create a pull request: https://github.com/DTVD/rainbowstream/compare/
231 .. _Read The Docs: http://rainbowstream.readthedocs.org/en/latest/
232 .. _config guide: https://github.com/DTVD/rainbowstream/blob/master/theme.md
233 .. _theme usage and customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md
234 .. _Create your own Twitter Application: https://apps.twitter.com/app/new
235 .. _Create your own Pocket Application: https://getpocket.com/developer/apps/new
236 .. _rainbowstream: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream
237 .. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
238 .. _config management: http://rainbowstream.readthedocs.org/en/latest/#config-explanation
239 .. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/
240 .. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10