summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/_static/custom.css8
-rw-r--r--docs/_templates/hacks.html7
-rw-r--r--docs/_templates/sidebarintro.html19
-rw-r--r--docs/_templates/sidebarlogo.html17
-rw-r--r--docs/api.rst14
-rw-r--r--docs/community/out-there.rst2
-rw-r--r--docs/community/recommended.rst7
-rw-r--r--docs/community/release-process.rst17
-rw-r--r--docs/community/sponsors.rst96
-rw-r--r--docs/community/updates.rst1
-rw-r--r--docs/conf.py4
-rw-r--r--docs/dev/todo.rst3
-rw-r--r--docs/index.rst17
-rw-r--r--docs/user/advanced.rst61
-rw-r--r--docs/user/authentication.rst10
-rw-r--r--docs/user/quickstart.rst15
16 files changed, 214 insertions, 84 deletions
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index 3a8af312..54def686 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -1,3 +1,11 @@
+body > div.document > div.sphinxsidebar > div > form > table > tbody > tr:nth-child(2) > td > select {
+ width: 100%!important;
+}
+
+#python27 > a {
+ color: white;
+}
+
#carbonads {
display: block;
overflow: hidden;
diff --git a/docs/_templates/hacks.html b/docs/_templates/hacks.html
index 0d88a6ec..c3fe2d1e 100644
--- a/docs/_templates/hacks.html
+++ b/docs/_templates/hacks.html
@@ -1,7 +1,6 @@
<!-- Alabaster (krTheme++) Hacks -->
<aside id="python27">
- Python 3, the new best practice, is here to stay.
- Python 2 will retire in only <time></time> months!
+ <a href="https://www.kennethreitz.org/requests3"><strong>Requests 3.0</strong> development is underway, and your financial help is appreciated!</a>
</aside>
<!-- Python 2 Death Clock™ -->
@@ -20,14 +19,14 @@
}
</style>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.18.1/moment.min.js"></script>
+<!-- <script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.18.1/moment.min.js"></script>
<script>
var death = new Date('2020-04-12');
var diff = moment.duration(death - moment());
document.querySelector('#python27 time').innerText = (diff.years() * 12) + diff.months();
-</script>
+</script> -->
<!-- CSS Adjustments (I'm very picky.) -->
diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html
index 5b437d85..047e6524 100644
--- a/docs/_templates/sidebarintro.html
+++ b/docs/_templates/sidebarintro.html
@@ -5,7 +5,7 @@
</p>
<p>
- <iframe src="http://ghbtns.com/github-btn.html?user=requests&repo=requests&type=watch&count=true&size=large"
+ <iframe src="https://ghbtns.com/github-btn.html?user=requests&repo=requests&type=watch&count=true&size=large"
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>
@@ -13,24 +13,26 @@
Requests is an elegant and simple HTTP library for Python, built for
human beings.
</p>
+<p>Sponsored by <strong><a href="https://linode.com/">Linode</a></strong> and <a href="http://docs.python-requests.org/en/master/community/sponsors/#patron-sponsors">other wonderful organizations</a>.</p>
+
<script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=pythonrequestsorg" id="_carbonads_js"></script>
-<h3><a href="http://www.unixstickers.com/stickers/coding_stickers/requests-shaped-sticker">Stickers!</a></h3>
+<p><a href="http://www.unixstickers.com/stickers/coding_stickers/requests-shaped-sticker">Requests Stickers!</a></p>
<h3>Stay Informed</h3>
<p>Receive updates on new releases and upcoming projects.</p>
-<p><iframe src="http://ghbtns.com/github-btn.html?user=kennethreitz&type=follow&count=false"
+<p><iframe src="https://ghbtns.com/github-btn.html?user=kennethreitz&type=follow&count=false"
allowtransparency="true" frameborder="0" scrolling="0" width="200" height="20"></iframe></p>
<p><a href="https://twitter.com/kennethreitz" class="twitter-follow-button" data-show-count="false">Follow @kennethreitz</a> <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script></p>
-<p><a href="https://saythanks.io/to/kennethreitz">Say Thanks!</a></p>
<p><a href="http://tinyletter.com/kennethreitz">Join Mailing List</a>.</p>
<h3>Other Projects</h3>
<p>More <a href="http://kennethreitz.org/">Kenneth Reitz</a> projects:</p>
<ul>
- <li><a href="http://edmsynths.com/">edmsynths.com</a></li>
+ <li><a href="http://html.python-requests.org/">Requests-HTML</a></li>
+ <li><a href="http://howtopython.org/">howtopython.org</a></li>
<li><a href="http://pipenv.org/">pipenv</a></li>
<li><a href="http://pep8.org/">pep8.org</a></li>
<li><a href="http://httpbin.org/">httpbin.org</a></li>
@@ -48,9 +50,9 @@
<p></p>
- <li><a href="http://github.com/requests/requests">Requests @ GitHub</a></li>
- <li><a href="http://pypi.python.org/pypi/requests">Requests @ PyPI</a></li>
- <li><a href="http://github.com/requests/requests/issues">Issue Tracker</a></li>
+ <li><a href="https://github.com/requests/requests">Requests @ GitHub</a></li>
+ <li><a href="https://pypi.python.org/pypi/requests">Requests @ PyPI</a></li>
+ <li><a href="https://github.com/requests/requests/issues">Issue Tracker</a></li>
<li><a href="http://docs.python-requests.org/en/latest/community/updates/#software-updates">Release History</a></li>
</ul>
@@ -67,4 +69,3 @@
<li><a href="http://it.python-requests.org/">Italian</a></li>
<li><a href="http://es.python-requests.org/">Spanish</a></li>
</ul>
-
diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html
index b31c3477..1b7afbd8 100644
--- a/docs/_templates/sidebarlogo.html
+++ b/docs/_templates/sidebarlogo.html
@@ -4,28 +4,31 @@
</a>
</p>
<p>
-<iframe src="http://ghbtns.com/github-btn.html?user=requests&repo=requests&type=watch&count=true&size=large"
+<iframe src="https://ghbtns.com/github-btn.html?user=requests&repo=requests&type=watch&count=true&size=large"
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>
+
<p>
Requests is an elegant and simple HTTP library for Python, built for
human beings. You are currently looking at the documentation of the
development release.
</p>
-<h3><a href="http://www.unixstickers.com/stickers/coding_stickers/requests-shaped-sticker">Stickers!</a></h3>
+
+<p>Sponsored by <strong><a href="https://linode.com/">Linode</a></strong> and <a href="http://docs.python-requests.org/en/master/community/sponsors/#patron-sponsors">other wonderful organizations</a>.</p>
+
<h3>Stay Informed</h3>
<p>Receive updates on new releases and upcoming projects.</p>
+<p><a href="http://www.unixstickers.com/stickers/coding_stickers/requests-shaped-sticker">Requests Stickers!</a></p>
+
<p><a href="http://tinyletter.com/kennethreitz">Join Mailing List</a>.</p>
<hr/>
<script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=pythonrequestsorg" id="_carbonads_js"></script>
-<p>If you enjoy using this project, <a href="https://saythanks.io/to/kennethreitz">Say Thanks!</a></p>
-
-<p><iframe src="http://ghbtns.com/github-btn.html?user=kennethreitz&type=follow&count=false"
+<p><iframe src="https://ghbtns.com/github-btn.html?user=kennethreitz&type=follow&count=false"
allowtransparency="true" frameborder="0" scrolling="0" width="200" height="20"></iframe></p>
<p><a href="https://twitter.com/kennethreitz" class="twitter-follow-button" data-show-count="false">Follow @kennethreitz</a> <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script></p>
@@ -35,7 +38,8 @@
<p>More <a href="http://kennethreitz.org/">Kenneth Reitz</a> projects:</p>
<ul>
- <li><a href="http://edmsynths.com/">edmsynths.com</a></li>
+ <li><a href="http://html.python-requests.org/">Requests-HTML</a></li>
+ <li><a href="http://howtopython.org/">howtopython.org</a></li>
<li><a href="http://pipenv.org/">pipenv</a></li>
<li><a href="http://pep8.org/">pep8.org</a></li>
<li><a href="http://httpbin.org/">httpbin.org</a></li>
@@ -59,4 +63,3 @@
<li><a href="http://it.python-requests.org/">Italian</a></li>
<li><a href="http://es.python-requests.org/">Spanish</a></li>
</ul>
-
diff --git a/docs/api.rst b/docs/api.rst
index 5f258944..cecb0fe9 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -108,17 +108,7 @@ Status Code Lookup
.. autoclass:: requests.codes
-::
-
- >>> requests.codes['temporary_redirect']
- 307
-
- >>> requests.codes.teapot
- 418
-
- >>> requests.codes['\o/']
- 200
-
+.. automodule:: requests.status_codes
Migrating to 1.x
@@ -190,7 +180,7 @@ API Changes
logging.basicConfig() # you need to initialize logging, otherwise you will not see anything from requests
logging.getLogger().setLevel(logging.DEBUG)
- requests_log = logging.getLogger("requests.packages.urllib3")
+ requests_log = logging.getLogger("urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True
diff --git a/docs/community/out-there.rst b/docs/community/out-there.rst
index 5ce5f79f..63e70169 100644
--- a/docs/community/out-there.rst
+++ b/docs/community/out-there.rst
@@ -18,7 +18,7 @@ Articles & Talks
- `Python for the Web <http://gun.io/blog/python-for-the-web/>`_ teaches how to use Python to interact with the web, using Requests.
- `Daniel Greenfeld's Review of Requests <http://pydanny.blogspot.com/2011/05/python-http-requests-for-humans.html>`_
- `My 'Python for Humans' talk <http://python-for-humans.heroku.com>`_ ( `audio <http://codeconf.s3.amazonaws.com/2011/pycodeconf/talks/PyCodeConf2011%20-%20Kenneth%20Reitz.m4a>`_ )
-- `Issac Kelly's 'Consuming Web APIs' talk <http://issackelly.github.com/Consuming-Web-APIs-with-Python-Talk/slides/slides.html>`_
+- `Issac Kelly's 'Consuming Web APIs' talk <https://issackelly.github.com/Consuming-Web-APIs-with-Python-Talk/slides/slides.html>`_
- `Blog post about Requests via Yum <http://arunsag.wordpress.com/2011/08/17/new-package-python-requests-http-for-humans/>`_
- `Russian blog post introducing Requests <http://habrahabr.ru/blogs/python/126262/>`_
- `Sending JSON in Requests <http://www.coglib.com/~icordasc/blog/2014/11/sending-json-in-requests.html>`_
diff --git a/docs/community/recommended.rst b/docs/community/recommended.rst
index 0f652d54..8fcd47a4 100644
--- a/docs/community/recommended.rst
+++ b/docs/community/recommended.rst
@@ -15,7 +15,7 @@ Certifi CA Bundle
validating the trustworthiness of SSL certificates while verifying the
identity of TLS hosts. It has been extracted from the Requests project.
-.. _Certifi: http://certifi.io/en/latest/
+.. _Certifi: https://github.com/certifi/python-certifi
CacheControl
------------
@@ -34,7 +34,7 @@ but do not belong in Requests proper. This library is actively maintained
by members of the Requests core team, and reflects the functionality most
requested by users within the community.
-.. _Requests-Toolbelt: http://toolbelt.readthedocs.io/en/latest/index.html
+.. _Requests-Toolbelt: https://toolbelt.readthedocs.io/en/latest/index.html
Requests-Threads
@@ -62,6 +62,3 @@ Betamax
A VCR imitation designed only for Python-Requests.
.. _betamax: https://github.com/sigmavirus24/betamax
-
-
-
diff --git a/docs/community/release-process.rst b/docs/community/release-process.rst
index 2e317ceb..18f71168 100644
--- a/docs/community/release-process.rst
+++ b/docs/community/release-process.rst
@@ -19,19 +19,18 @@ Breaking changes are changes that break backwards compatibility with prior
versions. If the project were to change the ``text`` attribute on a
``Response`` object to a method, that would only happen in a Major release.
-Major releases may also include miscellaneous bug fixes and upgrades to
-vendored packages. The core developers of Requests are committed to providing
-a good user experience. This means we're also committed to preserving
-backwards compatibility as much as possible. Major releases will be infrequent
-and will need strong justifications before they are considered.
+Major releases may also include miscellaneous bug fixes. The core developers of
+Requests are committed to providing a good user experience. This means we're
+also committed to preserving backwards compatibility as much as possible. Major
+releases will be infrequent and will need strong justifications before they are
+considered.
Minor Releases
--------------
-A minor release will not include breaking changes but may include
-miscellaneous bug fixes and upgrades to vendored packages. If the previous
-version of Requests released was ``v10.2.7`` a minor release would be
-versioned as ``v10.3.0``.
+A minor release will not include breaking changes but may include miscellaneous
+bug fixes. If the previous version of Requests released was ``v10.2.7`` a minor
+release would be versioned as ``v10.3.0``.
Minor releases will be backwards compatible with releases that have the same
major version number. In other words, all versions that would start with
diff --git a/docs/community/sponsors.rst b/docs/community/sponsors.rst
new file mode 100644
index 00000000..f1e11efd
--- /dev/null
+++ b/docs/community/sponsors.rst
@@ -0,0 +1,96 @@
+Community Sponsors
+==================
+
+**tl;dr**: Requests development is currently `funded by the Python community <https://www.kennethreitz.org/requests3>`_, and
+some wonderful organizations that utilize the software in their businesses.
+
+
+-------------------
+
+
+Requests is one of the most heavily–utilized Python packages in the world.
+
+It is used by major corporations worldwide for all tasks, both small and large — from writing one–off scripts to orchestrating millions of dollars of critical infrastructure.
+
+It's even embedded within pip, that tool that you use to install packages and deploy with every day!
+
+After losing our primary open source maintainer (who was sponsored by a company to work on Requests, and other projects, full–time), we are seeking community financial contributions towards the development of Requests 3.0.
+
+Patron Sponsors
+----------------
+
+
+`Linode — SSD Cloud Hosting & Linux Servers <https://www.linode.com>`_
+//////////////////////////////////////////////////////////////////////
+
+Whether you’re just getting started or deploying a complex system, launching a Linode cloud server has never been easier. They offer the fastest hardware and network in the industry with scalable environments, and their 24x7 customer support team is always standing by to help with any questions.
+
+✨🍰✨
+//////
+
+----------------------------------
+
+This slot is reserved for ethical organizations willing to invest $10,000 or more in Requests per year.
+
+By becoming a patron–level sponsor, your organization will receive the following benefits:
+
+- Prominent placement on the Requests documentation sidebar (~11,000 uniques / day).
+- Honorable mention here, with logo.
+- Peace of mind knowing that the infrastructure you rely on is being actively maintained.
+
+Organizations that sign up will be listed in order — first come first serve!
+
+Major Sponsors
+--------------
+
+The following organizations have significantly contributed towards Requests' sustainability:
+
+`Slack — Bring your team together <https://slack.com>`_
+///////////////////////////////////////////////////////
+
+Slack was extremely kind to be the first organization to generously donate a large sum towards the `2018 Requests 3.0 fundraiser <https://www.kennethreitz.org/requests3>`_, surpassing our entire fundraising goal immediately! They are helping the world become a better place through connectiveness, and reducing the amount of email we all have
+to deal with on a daily basis.
+
+P.S. They're `hiring <https://slack.com/careers#openings>`_!
+
+
+`Twilio — Voice, SMS, and Video for Humans <https://www.twilio.com>`_
+/////////////////////////////////////////////////////////////////////
+
+Twilio was the second organization to generously donate a large sum towards the `2018 Requests 3.0 fundraiser <https://www.kennethreitz.org/requests3>`_, matching the donation of Slack! They are helping the world become a better place through interconnectivity,
+providing easy–to–use APIs, and empowering developers world-over to help humans communicate in meaningful and effictive ways.
+
+
+`Azure Cloud Developer Advocates <https://developer.microsoft.com/en-us/advocates/>`_
+/////////////////////////////////////////////////////////////////////////////////////
+
+Azure was the third organization to generously donate a large sum towards the `2018 Requests 3.0 fundraiser <https://www.kennethreitz.org/requests3>`_, matching the donation of Twilio! Awesome group of generous folks :)
+
+
+`Niteo — Web Systems Development <https://www.niteoweb.com>`_
+/////////////////////////////////////////////////////////////
+
+Niteo was the fourth company to generously donate towards the `2018 Requests 3.0 fundraiser <https://www.kennethreitz.org/requests3>`_. Niteo is a company employing tech enthusiasts from all over the world
+who love to build great stuff.
+
+
+`Heroku <https://heroku.com/python>`_
+/////////////////////////////////////
+
+Heroku has allowed Kenneth Reitz to work on some open source projects during work hours,
+including Requests (but mostly Pipenv), from time–to–time, so they are listed
+here as an honorable mention.
+
+----------------
+
+If your organization is interested in becoming either a sponsor or a patron, please `send us an email <mailto:me@kennethreitz.org>`_.
+
+
+Individual Sponsors
+-------------------
+
+Countless individuals, too many to list here, have individually contributed towards the sustainability of the Requests
+project over the years. Some, financially, others, with code. Contributions (from humans) of all kinds are greatly
+appreciated.
+
+✨🍰✨ \ No newline at end of file
diff --git a/docs/community/updates.rst b/docs/community/updates.rst
index f755a493..3b9a3097 100644
--- a/docs/community/updates.rst
+++ b/docs/community/updates.rst
@@ -29,4 +29,3 @@ Release and Version History
===========================
.. include:: ../../HISTORY.rst
-
diff --git a/docs/conf.py b/docs/conf.py
index 4bda98b0..c952fe79 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -58,7 +58,7 @@ master_doc = 'index'
# General information about the project.
project = u'Requests'
-copyright = u'MMXVII. A <a href="http://kennethreitz.com/pages/open-projects.html">Kenneth Reitz</a> Project'
+copyright = u'MMXVIII. A <a href="http://kennethreitz.com/pages/open-projects.html">Kenneth Reitz</a> Project'
author = u'Kenneth Reitz'
# The version info for the project you're documenting, acts as replacement for
@@ -376,4 +376,4 @@ epub_exclude_files = ['search.html']
# If false, no index is generated.
#epub_use_index = True
-intersphinx_mapping = {'urllib3': ('http://urllib3.readthedocs.io/en/latest', None)}
+intersphinx_mapping = {'urllib3': ('https://urllib3.readthedocs.io/en/latest', None)}
diff --git a/docs/dev/todo.rst b/docs/dev/todo.rst
index d960d305..b1a3f7eb 100644
--- a/docs/dev/todo.rst
+++ b/docs/dev/todo.rst
@@ -60,5 +60,4 @@ Requests currently supports the following versions of Python:
Google AppEngine is not officially supported although support is available
with the `Requests-Toolbelt`_.
-.. _Requests-Toolbelt: http://toolbelt.readthedocs.io/
-
+.. _Requests-Toolbelt: https://toolbelt.readthedocs.io/
diff --git a/docs/index.rst b/docs/index.rst
index 9ee0fc79..5ffe739c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -30,8 +30,8 @@ consumption.
.. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
—*Kenneth Reitz*
-
-
+
+
-------------------
**Behold, the power of Requests**::
@@ -59,12 +59,12 @@ are 100% automatic, thanks to `urllib3 <https://github.com/shazow/urllib3>`_.
User Testimonials
-----------------
-Twitter, Spotify, Microsoft, Amazon, Lyft, BuzzFeed, Reddit, The NSA, Her Majesty's Government, Google, Twilio, Runscope, Mozilla, Heroku,
+Nike, Twitter, Spotify, Microsoft, Amazon, Lyft, BuzzFeed, Reddit, The NSA, Her Majesty's Government, Google, Twilio, Runscope, Mozilla, Heroku,
PayPal, NPR, Obama for America, Transifex, Native Instruments, The Washington
Post, SoundCloud, Kippt, Sony, and Federal U.S.
Institutions that prefer to be unnamed claim to use Requests internally.
-**Armin Ronacher**—
+**Armin Ronacher**, creator of Flask—
*Requests is the perfect example how beautiful an API can be with the
right level of abstraction.*
@@ -74,14 +74,18 @@ Institutions that prefer to be unnamed claim to use Requests internally.
**Daniel Greenfeld**—
*Nuked a 1200 LOC spaghetti code library with 10 lines of code thanks to
- Kenneth Reitz's request library. Today has been AWESOME.*
+ Kenneth Reitz's Requests library. Today has been AWESOME.*
**Kenny Meyers**—
*Python HTTP: When in doubt, or when not in doubt, use Requests. Beautiful,
simple, Pythonic.*
Requests is one of the most downloaded Python packages of all time, pulling in
-over 13,000,000 downloads every month. All the cool kids are doing it!
+over 400,000 downloads **each day**. Join the party!
+
+If your organization uses Requests internally, consider `supporting the development of 3.0 <https://www.kennethreitz.org/requests3>`_. Your
+generosity will be greatly appreciated, and help drive the project forward
+into the future.
Beloved Features
----------------
@@ -133,6 +137,7 @@ Requests ecosystem and community.
.. toctree::
:maxdepth: 2
+ community/sponsors
community/recommended
community/faq
community/out-there
diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index 613df205..e5f7f297 100644
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -196,18 +196,18 @@ As a result an ``SSL: CERTIFICATE_VERIFY_FAILED`` is thrown.
You can get around this behaviour by explicity merging the environment settings into your session::
from requests import Request, Session
-
+
s = Session()
req = Request('GET', url)
-
+
prepped = s.prepare_request(req)
-
+
# Merge environment settings into session
settings = s.merge_environment_settings(prepped.url, None, None, None, None)
resp = s.send(prepped, **settings)
-
+
print(resp.status_code)
-
+
.. _verification:
SSL Cert Verification
@@ -274,20 +274,19 @@ If you specify a wrong path or an invalid cert, you'll get a SSLError::
CA Certificates
---------------
-By default, Requests bundles a set of root CAs that it trusts, sourced from the
-`Mozilla trust store`_. However, these are only updated once for each Requests
-version. This means that if you pin a Requests version your certificates can
-become extremely out of date.
+Requests uses certificates from the package `certifi`_. This allows for users
+to update their trusted certificates without changing the version of Requests.
-From Requests version 2.4.0 onwards, Requests will attempt to use certificates
-from `certifi`_ if it is present on the system. This allows for users to update
-their trusted certificates without having to change the code that runs on their
-system.
+Before version 2.16, Requests bundled a set of root CAs that it trusted,
+sourced from the `Mozilla trust store`_. The certificates were only updated
+once for each Requests version. When ``certifi`` was not installed, this led to
+extremely out-of-date certificate bundles when using significantly older
+versions of Requests.
For the sake of security we recommend upgrading certifi frequently!
.. _HTTP persistent connection: https://en.wikipedia.org/wiki/HTTP_persistent_connection
-.. _connection pooling: http://urllib3.readthedocs.io/en/latest/reference/index.html#module-urllib3.connectionpool
+.. _connection pooling: https://urllib3.readthedocs.io/en/latest/reference/index.html#module-urllib3.connectionpool
.. _certifi: http://certifi.io/
.. _Mozilla trust store: https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt
@@ -436,7 +435,7 @@ You can assign a hook function on a per-request basis by passing a
``{hook_name: callback_function}`` dictionary to the ``hooks`` request
parameter::
- hooks=dict(response=print_url)
+ hooks={'response': print_url}
That ``callback_function`` will receive a chunk of data as its first
argument.
@@ -452,12 +451,36 @@ If the callback function returns a value, it is assumed that it is to
replace the data that was passed in. If the function doesn't return
anything, nothing else is effected.
+::
+
+ def record_hook(r, *args, **kwargs):
+ r.hook_called = True
+ return r
+
Let's print some request method arguments at runtime::
- >>> requests.get('http://httpbin.org', hooks=dict(response=print_url))
+ >>> requests.get('http://httpbin.org', hooks={'response': print_url})
http://httpbin.org
<Response [200]>
+You can add multiple hooks to a single request. Let's call two hooks at once::
+
+ >>> r = requests.get('http://httpbin.org', hooks={'response': [print_url, record_hook]})
+ >>> r.hook_called
+ True
+
+You can also add hooks to a ``Session`` instance. Any hooks you add will then
+be called on every request made to the session. For example::
+
+ >>> s = requests.Session()
+ >>> s.hooks['response'].append(print_url)
+ >>> s.get('http://httpbin.org')
+ http://httpbin.org
+ <Response [200]>
+
+A ``Session`` can have multiple hooks, which will be called in the order
+they are added.
+
.. _custom-auth:
Custom Authentication
@@ -633,7 +656,7 @@ When you receive a response, Requests makes a guess at the encoding to
use for decoding the response when you access the :attr:`Response.text
<requests.Response.text>` attribute. Requests will first check for an
encoding in the HTTP header, and if none is present, will use `chardet
-<http://pypi.python.org/pypi/chardet>`_ to attempt to guess the encoding.
+<https://pypi.python.org/pypi/chardet>`_ to attempt to guess the encoding.
The only time Requests will not do this is if no explicit charset
is present in the HTTP headers **and** the ``Content-Type``
@@ -860,7 +883,7 @@ Link Headers
Many HTTP APIs feature Link headers. They make APIs more self describing and
discoverable.
-GitHub uses these for `pagination <http://developer.github.com/v3/#pagination>`_
+GitHub uses these for `pagination <https://developer.github.com/v3/#pagination>`_
in their API, for example::
>>> url = 'https://api.github.com/users/kennethreitz/repos?page=1&per_page=10'
@@ -927,9 +950,9 @@ passed-through to `urllib3`. We'll make a Transport Adapter that instructs the
library to use SSLv3::
import ssl
+ from urllib3.poolmanager import PoolManager
from requests.adapters import HTTPAdapter
- from requests.packages.urllib3.poolmanager import PoolManager
class Ssl3HttpAdapter(HTTPAdapter):
diff --git a/docs/user/authentication.rst b/docs/user/authentication.rst
index 8ffab504..411f79fd 100644
--- a/docs/user/authentication.rst
+++ b/docs/user/authentication.rst
@@ -136,11 +136,11 @@ Further examples can be found under the `Requests organization`_ and in the
.. _OAuth: http://oauth.net/
.. _requests_oauthlib: https://github.com/requests/requests-oauthlib
-.. _requests-oauthlib OAuth2 documentation: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html
-.. _Web Application Flow: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#web-application-flow
-.. _Mobile Application Flow: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#mobile-application-flow
-.. _Legacy Application Flow: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#legacy-application-flow
-.. _Backend Application Flow: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#backend-application-flow
+.. _requests-oauthlib OAuth2 documentation: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html
+.. _Web Application Flow: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#web-application-flow
+.. _Mobile Application Flow: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#mobile-application-flow
+.. _Legacy Application Flow: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#legacy-application-flow
+.. _Backend Application Flow: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#backend-application-flow
.. _Kerberos: https://github.com/requests/requests-kerberos
.. _NTLM: https://github.com/requests/requests-ntlm
.. _Requests organization: https://github.com/requests
diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst
index 109c3415..d393bf05 100644
--- a/docs/user/quickstart.rst
+++ b/docs/user/quickstart.rst
@@ -110,7 +110,7 @@ using, and change it, using the ``r.encoding`` property::
If you change the encoding, Requests will use the new value of ``r.encoding``
whenever you call ``r.text``. You might want to do this in any situation where
you can apply special logic to work out what the encoding of the content will
-be. For example, HTTP and XML have the ability to specify their encoding in
+be. For example, HTML and XML have the ability to specify their encoding in
their body. In situations like this, you should use ``r.content`` to find the
encoding, and then set ``r.encoding``. This will let you use ``r.text`` with
the correct encoding.
@@ -171,7 +171,7 @@ server, you can access ``r.raw``. If you want to do this, make sure you set
>>> r = requests.get('https://api.github.com/events', stream=True)
>>> r.raw
- <requests.packages.urllib3.response.HTTPResponse object at 0x101194810>
+ <urllib3.response.HTTPResponse object at 0x101194810>
>>> r.raw.read(10)
'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03'
@@ -189,6 +189,14 @@ download, the above is the preferred and recommended way to retrieve the
content. Note that ``chunk_size`` can be freely adjusted to a number that
may better fit your use cases.
+.. note::
+
+ An important note about using ``Response.iter_content`` versus ``Response.raw``.
+ ``Response.iter_content`` will automatically decode the ``gzip`` and ``deflate``
+ transfer-encodings. ``Response.raw`` is a raw stream of bytes -- it does not
+ transform the response content. If you really need access to the bytes as they
+ were returned, use ``Response.raw``.
+
Custom Headers
--------------
@@ -273,6 +281,9 @@ the ``json`` parameter (added in version 2.4.2) and it will be encoded automatic
>>> r = requests.post(url, json=payload)
+Note, the ``json`` parameter is ignored if either ``data`` or ``files`` is passed.
+
+Using the ``json`` parameter in the request will change the ``Content-Type`` in the header to ``application/json``.
POST a Multipart-Encoded File
-----------------------------
View Lorry Controller Status