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
|
Contributing
============
urllib3 is a community-maintained project and we happily accept contributions.
If you wish to add a new feature or fix a bug:
#. `Check for open issues <https://github.com/urllib3/urllib3/issues>`_ or open
a fresh issue to start a discussion around a feature idea or a bug. There is
a *Contributor Friendly* tag for issues that should be ideal for people who
are not very familiar with the codebase yet.
#. Fork the `urllib3 repository on Github <https://github.com/urllib3/urllib3>`_
to start making your changes.
#. Write a test which shows that the bug was fixed or that the feature works
as expected.
#. Format your changes with black using command `$ nox -rs blacken` and lint your
changes using command `nox -rs lint`.
#. Send a pull request and bug the maintainer until it gets merged and published.
:) Make sure to add yourself to ``CONTRIBUTORS.txt``.
Setting up your development environment
---------------------------------------
In order to setup the development environment all that you need is
`nox <https://nox.thea.codes/en/stable/index.html>`_ installed in your machine::
$ pip install --user --upgrade nox
Running the tests
-----------------
We use some external dependencies, multiple interpreters and code coverage
analysis while running test suite. Our ``noxfile.py`` handles much of this for
you::
$ nox --reuse-existing-virtualenvs --sessions test-2.7 test-3.7
[ Nox will create virtualenv if needed, install the specified dependencies, and run the commands in order.]
nox > Running session test-2.7
.......
.......
nox > Session test-2.7 was successful.
.......
.......
nox > Running session test-3.7
.......
.......
nox > Session test-3.7 was successful.
There is also a nox command for running all of our tests and multiple python
versions.::
$ nox --reuse-existing-virtualenvs --sessions test
Note that code coverage less than 100% is regarded as a failing run. Some
platform-specific tests are skipped unless run in that platform. To make sure
the code works in all of urllib3's supported platforms, you can run our ``tox``
suite::
$ nox --reuse-existing-virtualenvs --sessions test
[ Nox will create virtualenv if needed, install the specified dependencies, and run the commands in order.]
.......
.......
nox > Session test-2.7 was successful.
nox > Session test-3.4 was successful.
nox > Session test-3.5 was successful.
nox > Session test-3.6 was successful.
nox > Session test-3.7 was successful.
nox > Session test-3.8 was successful.
nox > Session test-pypy was successful.
Our test suite `runs continuously on Travis CI
<https://travis-ci.org/urllib3/urllib3>`_ with every pull request.
To run specific tests or quickly re-run without nox recreating the env, do the following::
$ nox --reuse-existing-virtualenvs --sessions test-3.8 -- pyTestArgument1 pyTestArgument2 pyTestArgumentN
[ Nox will create virtualenv, install the specified dependencies, and run the commands in order.]
nox > Running session test-3.8
nox > Re-using existing virtual environment at .nox/test-3-8.
.......
.......
nox > Session test-3.8 was successful.
After the ``--`` indicator, any arguments will be passed to pytest.
To specify an exact test case the following syntax also works:
``test/dir/module_name.py::TestClassName::test_method_name``
(eg.: ``test/with_dummyserver/test_https.py::TestHTTPS::test_simple``).
The following argument is another valid example to pass to pytest: ``-k test_methode_name``.
These are useful when developing new test cases and there is no point
re-running the entire test suite every iteration. It is also possible to
further parameterize pytest for local testing.
For all valid arguments, check `the pytest documentation
<https://docs.pytest.org/en/stable/usage.html#stopping-after-the-first-or-n-failures>`_.
Releases
--------
A release candidate can be created by any contributor by creating a branch
named ``release-x.x`` where ``x.x`` is the version of the proposed release.
- Update ``CHANGES.rst`` and ``urllib3/__init__.py`` with the proper version number
and commit the changes to ``release-x.x``.
- Open a pull request to merge the ``release-x.x`` branch into the ``master`` branch.
- Integration tests are run against the release candidate on Travis. From here on all
the steps below will be handled by a maintainer so unless you receive review comments
you are done here.
- Once the pull request is squash merged into master the merging maintainer
will tag the merge commit with the version number:
- ``git tag -a 1.24.1 [commit sha]``
- ``git push origin master --tags``
- After the commit is tagged Travis will build the tagged commit and upload the sdist and wheel
to PyPI and create a draft release on GitHub for the tag. The merging maintainer will
ensure that the PyPI sdist and wheel are properly uploaded.
- The merging maintainer will mark the draft release on GitHub as an approved release.
Sponsorship
-----------
.. |tideliftlogo| image:: https://nedbatchelder.com/pix/Tidelift_Logos_RGB_Tidelift_Shorthand_On-White_small.png
:width: 75
:alt: Tidelift
.. list-table::
:widths: 10 100
* - |tideliftlogo|
- Professional support for urllib3 is available as part of the `Tidelift
Subscription`_. Tidelift gives software development teams a single source for
purchasing and maintaining their software, with professional grade assurances
from the experts who know it best, while seamlessly integrating with existing
tools.
.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs
Please consider sponsoring urllib3 development, especially if your company
benefits from this library.
Your contribution will go towards adding new features to urllib3 and making
sure all functionality continues to meet our high quality standards.
We also welcome sponsorship in the form of time. We greatly appreciate companies
who encourage employees to contribute on an ongoing basis during their work hours.
Please let us know and we'll be glad to add you to our sponsors list!
A grant for contiguous full-time development has the biggest impact for
progress. Periods of 3 to 10 days allow a contributor to tackle substantial
complex issues which are otherwise left to linger until somebody can't afford
to not fix them.
Contact `@theacodes <https://github.com/theacodes>`_ or `@shazow <https://github.com/shazow>`_
to arrange a grant for a core contributor.
Huge thanks to all the companies and individuals who financially contributed to
the development of urllib3. Please send a PR if you've donated and would like
to be listed.
* `GOVCERT.LU <https://govcert.lu/>`_ (October 23, 2018)
* `Stripe <https://stripe.com/>`_ (June 23, 2014)
.. * [Company] ([date])
|
