1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
.. _contributor-guide:
Contributor Guide
=================
This document is for developers who want to contribute code to this project.
Any contributions are welcome and greatly appreciated!
This project follows the common conventions of a Python/GitHub project. So if
you're already an experienced Python/GitHub user, it should be straightforward
for you to set up your development environment and send patches. Generally, the
steps include:
1. Fork and clone the repo
2. Create a virtualenv for this project
3. Install dependent packages with ``pip install -e .``
4. Install test dependent packages with ``pip install -r requirements-test.txt``
5. Make your changes to the code
6. Run tests with ``pytest`` and ``tox``
7. Commit and push your changes
8. Send a pull request
9. Wait to be reviewed and get merged!
If you're not familiar with any of the above steps, read the following
instructions.
Forking
-------
Fork_ is like copying someone else's project to your account, so you can start
your own independent development without interfering with the original one.
To fork HTTP Prompt, just click the **Fork** button on HTTP Prompt's GitHub
project page. Then you clone your fork to your local computer::
$ cd ~/Projects
$ git clone git@github.com:{YOUR_USERNAME}/http-prompt.git
Read `Forking Projects`_ on GitHub to learn more.
Working with virtualenv
-----------------------
*virtualenv* is the de facto standard tool when developing a Python project.
Instead of polluting your system-wide Python installation with different Python
projects, virtualenv creates an isolated Python environment exclusively for a
Python project.
There are several tools you can use for managing virtualenvs. In this guide,
we'll show you how to use pyenv_ and pyenv-virtualenv_, which is one of the
most popular virtualenv management tools.
Make sure you have installed pyenv_ and pyenv-virtualenv_ first.
HTTP Prompt should work on Python 3.6 and newer. You can use any
of these Python versions as your development environment, but using the latest
version (3.6.x) is probably the best. You can install the latest Python with
pyenv::
$ pyenv install 3.6.0
This will install Python 3.6.0 in ``~/.pyenv/versions/3.6.0`` directory. To
create a virtualenv for HTTP Prompt, do::
$ pyenv virtualenv 3.6.0 http-prompt
The command means: create a virtualenv named "http-prompt" based on Python
3.6.0. The virtualenv can be found at ``~/.pyenv/versions/3.6.0/envs/http-prompt``.
To activate the virtualenv, do::
$ pyenv activate http-prompt
This will switch your Python environment from the system-wide Python to the
virtualenv's (named "http-prompt") Python.
To go back to the system-wide Python, you have to deactivate the virtualenv::
$ pyenv deactivate
Refer to pyenv_ and pyenv-virtualenv_ if anything else is unclear.
Installing Dependent Packages
-----------------------------
The dependent packages should be installed on a virtualenv, so make sure you
activate your virtualenv first. If not, do::
$ pyenv activate http-prompt
It is also recommended to use the latest version of pip. You can upgrade it
with::
$ pip install -U pip
Install HTTP Prompt with its dependent packages::
$ cd ~/Projects/http-prompt
$ pip install -e .
``pip install -e .`` means install the ``http-prompt`` package in editable mode
(or developer mode). This allows you to edit code directly in
``~/Projects/http-prompt`` without reinstalling the package. Without the ``-e``
option, the package will be installed to Python's ``site-packages`` directory,
which is not convenient for developing.
Installing Test Dependent Packages
----------------------------------
Test requirements are placed in a separate file named ``requirements-test.txt``.
To install them, do::
$ cd ~/Projects/http-prompt
$ pip install -r requirements-test.txt
Making Your Changes
-------------------
Code Style
~~~~~~~~~~
Always lint your code with Flake8_. You can set it up in your code editor or
simply use ``flake8`` in the command line.
`The Hitchhiker’s Guide to Python`_ provides the best Python coding practices.
We recommend anyone who wants to write good Python code to read it.
Adding Features
~~~~~~~~~~~~~~~
Before you add a new feature, make sure you create an issue making a proposal
first, because you don't want to waste your time on something that the
community don't agree upon.
Python Compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
HTTP Prompt is compatible with Python 3.6+.
Documentation
~~~~~~~~~~~~~
Documentation is written in Sphinx_. To build documentation, you need to
install Sphinx_ first::
$ pip install sphinx
To build and view documentation in HTML, do::
$ cd ~/Projects/http-prompt/docs
$ make html
$ open _build/html/index.html
Running Tests
-------------
Single Python Version
~~~~~~~~~~~~~~~~~~~~~
Make sure your virtualenv is activated. To run tests, do::
$ cd ~/Projects/http-prompt
$ pytest
``pytest`` runs the tests with your virtualenv's Python version. This is good
for fast testing. To test the code against multiple Python versions, you use
Tox_.
Multiple Python Versions
~~~~~~~~~~~~~~~~~~~~~~~~
All the commands in this section should **NOT** be run in a virtualenv.
Deactivate it first if you're in a virtualenv::
$ pyenv deactivate
Make sure you have installed all the Python versions we're targeting. If not,
do::
$ pyenv install 3.6.0
$ pyenv install 3.7.0
$ pyenv install 3.8.0
To use Tox_ with pyenv_, you have to instruct pyenv to use multiple Python
versions for the project::
$ cd ~/Projects/http-prompt
$ pyenv local 3.6.0 3.7.0 3.8.0
This will generate a ``.python-version`` in the project directory::
$ cat ~/Projects/http-prompt/.python-version
3.6.0
3.7.0
3.8.0
This tells pyenv_ to choose a Python version based on the above order. In this
case, 3.6.0 is the first choice, so any Python executables (such as ``python``
and ``pip``) will be automatically mapped to the ones in
``~/.pyenv/versions/3.8.0/bin``.
We want to run ``tox`` using on Python 3.8.0. Make sure you have installed
Tox_::
$ pip install tox
To run tests, execute ``tox``::
$ cd ~/Projects/http-prompt
$ tox
Tox_ will install the test Python environments in the ``.tox/`` directory in
the project directory, and run the test code against all the Python versions
listed above.
Code Review
-----------
Once you made changes and all the tests pass, push your modified code to your
GitHub account. Submit a pull request (PR) on GitHub for the maintainers to
review. If the patch is good, The maintainers will merge it to the master
branch and ship the new code in the next release. If the patch needs
improvements, we'll give you feedback so you can modify accordingly and
resubmit it to the PR.
.. _Flake8: http://flake8.pycqa.org/en/latest/index.html
.. _Fork: https://en.wikipedia.org/wiki/Fork_(software_development)
.. _Forking Projects: https://guides.github.com/activities/forking/
.. _pyenv-virtualenv: https://github.com/yyuu/pyenv-virtualenv
.. _pyenv: https://github.com/yyuu/pyenv
.. _Sphinx: http://www.sphinx-doc.org/
.. _The Hitchhiker’s Guide to Python: http://docs.python-guide.org/en/latest/
.. _Tox: https://tox.readthedocs.io/en/latest/
|
