open file with encoding (python 2/3 supported)
[rainbowstream.git] / README.rst
CommitLineData
3108149e 1Rainbow Stream\r
2--------------\r
3\r
d7fbaba9
O
4.. image:: http://img.shields.io/pypi/dm/rainbowstream.svg?style=flat\r
5 :target: https://pypi.python.org/pypi/rainbowstream\r
3216f3f4 6\r
d7fbaba9
O
7.. image:: http://img.shields.io/pypi/v/rainbowstream.svg?style=flat\r
8 :target: https://pypi.python.org/pypi/rainbowstream\r
c96321cc 9\r
3108149e 10Terminal-based Twitter Client. Realtime tweetstream, compose, search ,\r
11favorite … and much more fun directly from terminal.\r
12\r
091aaddc 13This package is built on the top of `Python Twitter Tool`_ and `Twitter API`_, \r
687567eb 14can run on Python 2.7.x and 3.x .\r
091aaddc 15\r
3108149e 16\r
456019d6 17Showcase\r
b13c6a0d 18--------\r
456019d6 19\r
bd48f980 20.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/rs.gif\r
99087831 21 :alt: gif\r
997c0570 22\r
3108149e 23Install\r
24-------\r
25\r
3ac213c1 26Prerequisite\r
60a59e8b
TS
27^^^^^^^^^^^^\r
28\r
3ac213c1
O
29If you use Linux, you might need to install the ``python-dev`` and ``libsqlite3-dev`` packages if you haven't already. \r
30For debian-based distros, these can be installed with \r
60a59e8b 31\r
3ac213c1
O
32.. code:: bash\r
33\r
34 sudo apt-get install python-dev libsqlite3-dev\r
35\r
36Besides, Mac OSX Maverick with Xcode 5.1 has a well-known `clang unknown argument`_ problem with \r
37the ``Pillow`` package installation - a dependency of this app.\r
38If you are in this case, I recommend take a look at `Issue #10`_ and let me know if the workaround doesn't work for you.\r
60a59e8b 39\r
45e6bb0d
O
40The quick way\r
41^^^^^^^^^^^^^\r
42\r
8e004f8d 43You will need Python and pip (2.7.x or 3.x).\r
3108149e 44\r
45.. code:: bash\r
46\r
fd9cd791 47 sudo pip install rainbowstream\r
8e004f8d 48 # Python 3 users: sudo pip3 install rainbowstream\r
b84845b9 49\r
b84845b9 50\r
45e6bb0d
O
51The recommended way\r
52^^^^^^^^^^^^^^^^^^^\r
53\r
54Use `virtualenv`_\r
fd9cd791
O
55\r
56.. code:: bash\r
57\r
b84845b9 58 virtualenv venv\r
45e6bb0d
O
59 # Python 3 users : use -p to specify your Python 3 localtion as below\r
60 # virtualenv -p /usr/bin/python3 venv\r
61 source venv/bin/activate\r
3108149e 62 pip install rainbowstream\r
63\r
45e6bb0d 64\r
3108149e 65Usage\r
66-----\r
67\r
68The stream\r
69^^^^^^^^^^\r
70\r
71Just type\r
72\r
73.. code:: bash\r
74\r
9f37426f 75 rainbowstream\r
3108149e 76\r
77and see your stream.\r
78\r
3216f3f4
O
79I shipped a feature which can display **tweet's images directly on terminal**.\r
80You can try it with:\r
4373c17c
O
81\r
82.. code:: bash\r
83\r
9f37426f 84 rainbowstream -iot # Or rainbowstream --image-on-term\r
4373c17c 85\r
89d0f21f
O
86You also can change the config key ``IMAGE_ON_TERM`` to ``True`` inside the app \r
87to enable above feature (see `config management`_ section).\r
88\r
3108149e 89In the first time you will be asked for authorization of Rainbow Stream\r
90app at Twitter. Just click the “Authorize access” button and paste PIN\r
3216f3f4 91number to the terminal, the rainbow will start.\r
3108149e 92\r
93The interactive mode\r
9348f8ed 94^^^^^^^^^^^^^^^^^^^^\r
3108149e 95\r
96While your personal stream is continued, you are also ready to tweet,\r
97search, reply, retweet… directly from console. Simply type “h” and hit\r
f5677fb1 98the Enter key to see the help.\r
3108149e 99\r
100Input is in interactive mode. It means that you can use arrow key to\r
101move up and down history, tab-autocomplete or 2 tab to view available\r
f5677fb1 102suggestion. Input history from previous run is available as well.\r
3108149e 103\r
b913cd75 104Available commands are listed in `Read The Docs`_.\r
3108149e 105\r
b913cd75 106Theme customization\r
9348f8ed 107^^^^^^^^^^^^^^^^^^^\r
b913cd75 108\r
06302419 109Rainbow Stream is shipped with some default themes.\r
b913cd75
O
110You can either change theme by ``theme`` command or create your favorite one.\r
111\r
547283bf 112Theme’s screenshot:\r
19d6c002 113\r
06302419
O
114- Monokai\r
115\r
547283bf
O
116.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png\r
117 :alt: monokai\r
19d6c002 118\r
06302419
O
119- Solarized\r
120\r
547283bf
O
121.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png\r
122 :alt: solarized\r
123\r
98258022
O
124- Tomorrow Night\r
125\r
126.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png\r
127 :alt: tomorrownight\r
128\r
129- Larapaste\r
130\r
131.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png\r
132 :alt: larapaste\r
133\r
b913cd75 134For detaile information, see `theme usage and customization`_.\r
3108149e 135\r
9348f8ed 136\r
050c4214 137Bug and feature requests\r
36e1924e 138------------------------\r
3108149e 139\r
b84845b9 140Found a bug or a feature request ?\r
3216f3f4 141Please `create an issue`_ or contact me at `@dtvd88`_\r
3108149e 142\r
2d341029
O
143Development\r
144-----------\r
145\r
146If you want to build a runnable version yourself, follow these simple\r
147steps\r
148\r
149- `Create your own Twitter Application`_\r
150- Get your Twitter application’s API key and secret\r
a80d4179 151- Fork this repo and clone in your system.\r
b145ada0 152- Create a file ``consumer.py`` in `rainbowstream`_ folder with\r
2d341029
O
153 following content\r
154\r
155 .. code:: python\r
156\r
157 # Consumer information\r
158 CONSUMER_KEY = 'APIKey' # Your Twitter application's API key\r
159 CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret\r
160\r
161- Use pip to install in local\r
162\r
163 .. code:: bash\r
164\r
a80d4179 165 # cd to directory which contains setup.py (cloned directory)\r
2d341029
O
166 virtualenv venv # Python3 users: use -p to specify python3\r
167 source venv/bin/activate\r
168 pip install -e .\r
a80d4179
O
169 which rainbowstream # /this-directory/venv/bin/rainbowstream\r
170 pip list | grep rainbowstream # rainbowstream (0.x.x, /this-directory)\r
171 # Remove ~/.rainbow_oauth if exists\r
2d341029
O
172 rainbowstream # local version of rainbowstream\r
173\r
174\r
050c4214 175Contributing\r
36e1924e 176------------\r
050c4214
O
177I appreciate any help and support. Feel free to `fork`_ and `create a pull request`_.\r
178You will be listed as contributor.\r
179\r
3108149e 180License\r
181-------\r
182\r
183Rainbow Stream are released under an MIT License. See LICENSE.txt for\r
184details\r
185\r
186\r
187.. _Python Twitter Tool: http://mike.verdone.ca/twitter/\r
bade45d4 188.. _Twitter API: https://dev.twitter.com/docs/api/1.1\r
3108149e 189.. _create an issue: https://github.com/DTVD/rainbowstream/issues/new\r
3216f3f4 190.. _@dtvd88: https://twitter.com/dtvd88\r
050c4214
O
191.. _fork: https://github.com/DTVD/rainbowstream/fork\r
192.. _create a pull request: https://github.com/DTVD/rainbowstream/compare/\r
670e8049 193.. _Read The Docs: http://rainbowstream.readthedocs.org/en/latest/\r
b52327dc 194.. _config guide: https://github.com/DTVD/rainbowstream/blob/master/theme.md\r
b913cd75 195.. _theme usage and customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md\r
2d341029 196.. _Create your own Twitter Application: https://apps.twitter.com/app/new\r
b145ada0 197.. _rainbowstream: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream\r
45e6bb0d 198.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/\r
89d0f21f 199.. _config management: http://rainbowstream.readthedocs.org/en/latest/#the-interactive-mode\r
3ac213c1
O
200.. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/\r
201.. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10\r