Bumped version 1.3.7
[rainbowstream.git] / README.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
20Showcase
21--------
22
23.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/rs.gif
24 :alt: gif
25
26Install
27-------
28
29The quick way
30^^^^^^^^^^^^^
31
32You 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
40The recommended way
41^^^^^^^^^^^^^^^^^^^
42
43Use `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
53Troubleshooting
54^^^^^^^^^^^^^^^
55
56If you use Linux, you might need to install some packages if you haven't already.
57For 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
63For CentOS:
64
65.. code:: bash
66
67 sudo yum install python-devel libjpeg-devel
68
69Besides, Mac OSX Maverick with Xcode 5.1 has a well-known `clang unknown argument`_ problem with
70the ``Pillow`` package installation - a dependency of this app.
71If 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
77If 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
86Usage
87-----
88
89The stream
90^^^^^^^^^^
91
92Just type
93
94.. code:: bash
95
96 rainbowstream
97
98and see your stream.
99
100I shipped a feature which can display **tweet's images directly on terminal**.
101You can try it with:
102
103.. code:: bash
104
105 rainbowstream -iot # Or rainbowstream --image-on-term
106
107You also can change the config key ``IMAGE_ON_TERM`` to ``True`` inside the app
108to enable above feature,
109change ``IMAGE_SHIFT`` to set image's margin (relative to your terminal's width)
110or ``IMAGE_MAX_HEIGHT`` to control max height of every image.
111(see `config management`_ section).
112
113In the first time you will be asked for authorization of Rainbow Stream
114app at Twitter. Just click the “Authorize access” button and paste PIN
115number to the terminal, the rainbow will start.
116
117You might want to use rainbowstream via an **HTTP/SOCKS proxy**. Proxy settings are
118provided 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
126Both ``--proxy-port`` and ``--proxy-type`` can be omitted. In this case default
127proxy port ``8080`` and default proxy type ``SOCKS5`` are used.
128
129The interactive mode
130^^^^^^^^^^^^^^^^^^^^
131
132While your personal stream is continued, you are also ready to tweet,
133search, reply, retweet… directly from console. Simply type “h” and hit
134the Enter key to see the help.
135
136Input is in interactive mode. It means that you can use arrow key to
137move up and down history, tab-autocomplete or 2 tab to view available
138suggestion. Input history from previous run is available as well.
139
140Available commands are listed in `Read The Docs`_.
141
142Theme customization
143^^^^^^^^^^^^^^^^^^^
144
145Rainbow Stream is shipped with some default themes.
146You can either change theme by ``theme`` command or create your favorite one.
147
148Theme’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
170For detail information, see `theme usage and customization`_.
171
172
173Bug and feature requests
174------------------------
175
176Found a bug or a feature request ?
177Please `create an issue`_ or contact me at `@dtvd88`_
178
179Development
180-----------
181
182If you want to build a runnable version yourself, follow these simple
183steps
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
213Contributing
214------------
215I appreciate any help and support. Feel free to `fork`_ and `create a pull request`_.
216You will be listed as contributor.
217
218License
219-------
220
221Rainbow Stream are released under an MIT License. See LICENSE.txt for
222details
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