From 476938ab8d6722e76d0311cde8230f1ed524a01e Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 7 Feb 2016 03:43:15 -0500 Subject: [PATCH 01/61] Delete setup.cfg --- setup.cfg | 2 -- 1 file changed, 2 deletions(-) delete mode 100644 setup.cfg diff --git a/setup.cfg b/setup.cfg deleted file mode 100644 index 5e409001..00000000 --- a/setup.cfg +++ /dev/null @@ -1,2 +0,0 @@ -[wheel] -universal = 1 From 2fa5fa6ac5e008f918d8bd6e4a0c253f63780f55 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 7 Feb 2016 03:43:35 -0500 Subject: [PATCH 02/61] Update Makefile --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 60b5e000..ff014fae 100644 --- a/Makefile +++ b/Makefile @@ -28,7 +28,7 @@ chardet: publish: python setup.py register python setup.py sdist upload - python setup.py bdist_wheel upload + python setup.py bdist_wheel upload --universal docs-init: From a3ded28c5728775d3509649bd9ee981efe8f5b0b Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 7 Feb 2016 03:45:31 -0500 Subject: [PATCH 03/61] Update Makefile --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index ff014fae..be5fecf2 100644 --- a/Makefile +++ b/Makefile @@ -29,6 +29,7 @@ publish: python setup.py register python setup.py sdist upload python setup.py bdist_wheel upload --universal + rm -fr dist .egg docs-init: From 283491f8b6a4204427f91a3327cbe6840f73e253 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 7 Feb 2016 10:58:30 -0500 Subject: [PATCH 04/61] Update Makefile --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index be5fecf2..b31be6fb 100644 --- a/Makefile +++ b/Makefile @@ -28,7 +28,7 @@ chardet: publish: python setup.py register python setup.py sdist upload - python setup.py bdist_wheel upload --universal + python setup.py bdist_wheel --universal upload rm -fr dist .egg From 169b7edcc3c732dc949cfed377cbecda797b94ac Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 7 Feb 2016 11:51:23 -0500 Subject: [PATCH 05/61] Update README.rst --- README.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/README.rst b/README.rst index 80f2edf7..9fe548d2 100644 --- a/README.rst +++ b/README.rst @@ -74,6 +74,7 @@ To install Requests, simply: .. code-block:: bash $ pip install requests + ✨🍰✨ Satisfaction, guaranteed. From 057722af23edf3f69bf7bdfed7c6c32cbe1ce2e7 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Wed, 10 Feb 2016 21:07:22 -0500 Subject: [PATCH 06/61] Update Makefile --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index b31be6fb..a8289712 100644 --- a/Makefile +++ b/Makefile @@ -29,7 +29,7 @@ publish: python setup.py register python setup.py sdist upload python setup.py bdist_wheel --universal upload - rm -fr dist .egg + rm -fr build dist .egg requests.egg-info docs-init: From b0704b86de4f207c11b72c1ea4046be95af5f9e5 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Thu, 18 Feb 2016 14:16:50 -0500 Subject: [PATCH 07/61] years --- requests/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requests/__init__.py b/requests/__init__.py index bd5b5b97..1218d432 100644 --- a/requests/__init__.py +++ b/requests/__init__.py @@ -46,7 +46,7 @@ __version__ = '2.9.1' __build__ = 0x020901 __author__ = 'Kenneth Reitz' __license__ = 'Apache 2.0' -__copyright__ = 'Copyright 2015 Kenneth Reitz' +__copyright__ = 'Copyright 2016 Kenneth Reitz' # Attempt to enable urllib3's SNI support, if possible try: From 9f33a0cd3c5106d4cc1b114f3ad57af45ab31daf Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Thu, 18 Feb 2016 20:40:46 -0500 Subject: [PATCH 08/61] refactor API documentation --- docs/api.rst | 109 ++++++++++++++++++++++++--------------------------- 1 file changed, 51 insertions(+), 58 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index b257f5ca..f3bc2107 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -25,9 +25,30 @@ They all return an instance of the :class:`Response ` object. .. autofunction:: patch .. autofunction:: delete +Exceptions +---------- + +.. autoexception:: requests.RequestException +.. autoexception:: requests.ConnectionError +.. autoexception:: requests.HTTPError +.. autoexception:: requests.URLRequired +.. autoexception:: requests.TooManyRedirects +.. autoexception:: requests.ConnectTimeout +.. autoexception:: requests.ReadTimeout +.. autoexception:: requests.Timeout + + +Request Sessions +---------------- + +.. _sessionapi: + +.. autoclass:: Session + :inherited-members: + Lower-Level Classes -~~~~~~~~~~~~~~~~~~~ +------------------- .. autoclass:: requests.Request :inherited-members: @@ -35,10 +56,11 @@ Lower-Level Classes .. autoclass:: Response :inherited-members: -Request Sessions ----------------- -.. autoclass:: Session +Lower-Lower-Level Classes +------------------------- + +.. autoclass:: requests.PreparedRequest :inherited-members: .. autoclass:: requests.adapters.HTTPAdapter @@ -52,21 +74,35 @@ Authentication .. autoclass:: requests.auth.HTTPProxyAuth .. autoclass:: requests.auth.HTTPDigestAuth -Exceptions -~~~~~~~~~~ -.. autoexception:: requests.exceptions.RequestException -.. autoexception:: requests.exceptions.ConnectionError -.. autoexception:: requests.exceptions.HTTPError -.. autoexception:: requests.exceptions.URLRequired -.. autoexception:: requests.exceptions.TooManyRedirects -.. autoexception:: requests.exceptions.ConnectTimeout -.. autoexception:: requests.exceptions.ReadTimeout -.. autoexception:: requests.exceptions.Timeout + +Encodings +--------- + +.. autofunction:: requests.utils.get_encodings_from_content +.. autofunction:: requests.utils.get_encoding_from_headers +.. autofunction:: requests.utils.get_unicode_from_response + + +.. _api-cookies: + +Cookies +------- + +.. autofunction:: requests.utils.dict_from_cookiejar +.. autofunction:: requests.utils.cookiejar_from_dict +.. autofunction:: requests.utils.add_dict_to_cookiejar + +.. autoclass:: requests.cookies.RequestsCookieJar + :inherited-members: + +.. autoclass:: requests.cookies.CookieConflictError + :inherited-members: + Status Code Lookup -~~~~~~~~~~~~~~~~~~ +------------------ .. autofunction:: requests.codes @@ -81,49 +117,6 @@ Status Code Lookup >>> requests.codes['\o/'] 200 -.. _api-cookies: - -Cookies -~~~~~~~ - -.. autofunction:: requests.utils.dict_from_cookiejar -.. autofunction:: requests.utils.cookiejar_from_dict -.. autofunction:: requests.utils.add_dict_to_cookiejar - -.. autoclass:: requests.cookies.RequestsCookieJar - :inherited-members: - -.. autoclass:: requests.cookies.CookieConflictError - :inherited-members: - - -Encodings -~~~~~~~~~ - -.. autofunction:: requests.utils.get_encodings_from_content -.. autofunction:: requests.utils.get_encoding_from_headers -.. autofunction:: requests.utils.get_unicode_from_response - - -Classes -~~~~~~~ - -.. autoclass:: requests.Response - :inherited-members: - -.. autoclass:: requests.Request - :inherited-members: - -.. autoclass:: requests.PreparedRequest - :inherited-members: - -.. _sessionapi: - -.. autoclass:: requests.Session - :inherited-members: - -.. autoclass:: requests.adapters.HTTPAdapter - :inherited-members: Migrating to 1.x From c1c393122d4975b166fa58fc5f62e4e789904e76 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Thu, 18 Feb 2016 20:40:59 -0500 Subject: [PATCH 09/61] change up marketing, update js/css --- docs/_templates/layout.html | 61 +++++++++---------------------- docs/_templates/sidebarintro.html | 39 ++++++++++---------- docs/_templates/sidebarlogo.html | 11 +++--- 3 files changed, 42 insertions(+), 69 deletions(-) diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index 3f435497..b53db050 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -11,6 +11,7 @@ {% endblock %} @@ -23,64 +24,36 @@ Fork me on GitHub - - - - - + (function() { + window._pa = window._pa || {}; + _pa.productId = "requests-docs"; + var pa = document.createElement('script'); pa.type = 'text/javascript'; pa.async = true; + pa.src = ('https:' == document.location.protocol ? 'https:' : 'http:') + "//tag.perfectaudience.com/serve/5226171f87bc6890da0000a0.js"; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(pa, s); + })(); + {%- endblock %} diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index d2cbfe9d..38661e00 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -14,29 +14,15 @@ human beings.

- -

- Buy Requests Pro -

- - -

Get Updates

+

Stay Informed

Receive updates on new releases and upcoming projects.

-

Subscribe to Newsletter

+

+

-

Translations

- +

Join Mailing List.

Useful Links

+ + +

Translations

+ + + diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html index 928cd2fd..5fcfae19 100644 --- a/docs/_templates/sidebarlogo.html +++ b/docs/_templates/sidebarlogo.html @@ -14,13 +14,12 @@ development release.

-

- Buy Requests Pro -

- -

Get Updates

+

Stay Informed

Receive updates on new releases and upcoming projects.

-

Subscribe to Newsletter

+

Join Mailing List.

+

+

\ No newline at end of file From f6252c2203dc3f9152056955266cce7050bc8e85 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Thu, 18 Feb 2016 20:59:01 -0500 Subject: [PATCH 10/61] improved installation instructions --- docs/user/install.rst | 28 ++++++++++------------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/docs/user/install.rst b/docs/user/install.rst index 5f0ef9c4..b14ee310 100644 --- a/docs/user/install.rst +++ b/docs/user/install.rst @@ -7,20 +7,16 @@ This part of the documentation covers the installation of Requests. The first step to using any software package is getting it properly installed. -Distribute & Pip ----------------- +Pip Install +----------- -Installing Requests is simple with `pip `_, just run -this in your terminal:: +To install Requests, simply run this simple command in your terminal of choice:: $ pip install requests -or, with `easy_install `_:: - - $ easy_install requests - -But, you really `shouldn't do that `_. - +If you don't have `pip `_ installed (tisk tisk!), +`this Python installation guide `_ +can guide you through the process. Get the Code ------------ @@ -32,16 +28,12 @@ You can either clone the public repository:: $ git clone git://github.com/kennethreitz/requests.git -Download the `tarball `_:: +Or, download the `tarball `_:: $ curl -OL https://github.com/kennethreitz/requests/tarball/master + # optionally, zipball is also available (for Windows users). -Or, download the `zipball `_:: - - $ curl -OL https://github.com/kennethreitz/requests/zipball/master - - -Once you have a copy of the source, you can embed it in your Python package, -or install it into your site-packages easily:: +Once you have a copy of the source, you can embed it in your own Python +package, or install it into your site-packages easily:: $ python setup.py install From 47fa07dcd844663e7062713f510dd34fdf231b2d Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Thu, 18 Feb 2016 23:57:30 -0500 Subject: [PATCH 11/61] update requirements workflow --- requirements-to-freeze.txt | 3 +++ requirements.txt | 20 ++++++++++++++------ 2 files changed, 17 insertions(+), 6 deletions(-) create mode 100644 requirements-to-freeze.txt diff --git a/requirements-to-freeze.txt b/requirements-to-freeze.txt new file mode 100644 index 00000000..7dc46a32 --- /dev/null +++ b/requirements-to-freeze.txt @@ -0,0 +1,3 @@ +pytest +pytest-cov +pytest-httpbin \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index ad5da761..f41e8aa1 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,14 @@ -py==1.4.30 -pytest==2.8.1 -pytest-cov==2.1.0 -pytest-httpbin==0.0.7 -httpbin==0.4.0 -wheel +coverage==4.0.3 +decorator==4.0.9 +Flask==0.10.1 +httpbin==0.4.1 +itsdangerous==0.24 +Jinja2==2.8 +MarkupSafe==0.23 +py==1.4.31 +pytest==2.8.7 +pytest-cov==2.2.1 +pytest-httpbin==0.2.0 +six==1.10.0 +Werkzeug==0.11.4 +wheel==0.29.0 From 45992769b2a4adcb4859da73417e8da92e4ae967 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Thu, 18 Feb 2016 23:58:47 -0500 Subject: [PATCH 12/61] +sphinx --- requirements-to-freeze.txt | 3 ++- requirements.txt | 8 ++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/requirements-to-freeze.txt b/requirements-to-freeze.txt index 7dc46a32..e8b9e354 100644 --- a/requirements-to-freeze.txt +++ b/requirements-to-freeze.txt @@ -1,3 +1,4 @@ pytest pytest-cov -pytest-httpbin \ No newline at end of file +pytest-httpbin +sphinx \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index f41e8aa1..3d29de0c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,14 +1,22 @@ +alabaster==0.7.7 +Babel==2.2.0 coverage==4.0.3 decorator==4.0.9 +docutils==0.12 Flask==0.10.1 httpbin==0.4.1 itsdangerous==0.24 Jinja2==2.8 MarkupSafe==0.23 py==1.4.31 +Pygments==2.1.1 pytest==2.8.7 pytest-cov==2.2.1 pytest-httpbin==0.2.0 +pytz==2015.7 six==1.10.0 +snowballstemmer==1.2.1 +Sphinx==1.3.5 +sphinx-rtd-theme==0.1.9 Werkzeug==0.11.4 wheel==0.29.0 From e98d71de135fceff1ce08fc52adb78f239e2c3c0 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 00:56:14 -0500 Subject: [PATCH 13/61] docs cleanup --- docs/Makefile | 71 ++++++- docs/make.bat | 453 ++++++++++++++++++++++++----------------- docs/requirements.txt | 2 - docs/user/advanced.rst | 5 +- 4 files changed, 333 insertions(+), 198 deletions(-) delete mode 100644 docs/requirements.txt diff --git a/docs/Makefile b/docs/Makefile index 946ba445..08a2acf6 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,6 +7,11 @@ SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter @@ -14,8 +19,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - +.PHONY: help help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @@ -25,53 +29,66 @@ help: @echo " json to make JSON files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" @echo " text to make text files" @echo " man to make manual pages" @echo " texinfo to make Texinfo files" @echo " info to make Texinfo files and run them through makeinfo" @echo " gettext to make PO message catalogs" @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" +.PHONY: clean clean: - -rm -rf $(BUILDDIR)/* + rm -rf $(BUILDDIR)/* +.PHONY: html html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +.PHONY: dirhtml dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." +.PHONY: singlehtml singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." +.PHONY: pickle pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." +.PHONY: json json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." +.PHONY: htmlhelp htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." +.PHONY: qthelp qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @@ -81,6 +98,16 @@ qthelp: @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Requests.qhc" +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @@ -90,11 +117,13 @@ devhelp: @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Requests" @echo "# devhelp" +.PHONY: epub epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." +.PHONY: latex latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @@ -102,22 +131,33 @@ latex: @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." +.PHONY: latexpdf latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf + $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." +.PHONY: man man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." +.PHONY: texinfo texinfo: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo @@ -125,29 +165,52 @@ texinfo: @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." +.PHONY: info info: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." +.PHONY: gettext gettext: $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." +.PHONY: changes changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." +.PHONY: linkcheck linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." +.PHONY: doctest doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/make.bat b/docs/make.bat index 4441160c..9eaf9b88 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,190 +1,263 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -set I18NSPHINXOPTS=%SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Requests.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Requests.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + echo. coverage to run coverage check of the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 1>NUL 2>NUL +if errorlevel 9009 goto sphinx_python +goto sphinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +:sphinx_ok + + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Requests.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Requests.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "coverage" ( + %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage + if errorlevel 1 exit /b 1 + echo. + echo.Testing of coverage in the sources finished, look at the ^ +results in %BUILDDIR%/coverage/python.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index bf596036..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -alabaster==0.7.3 -Sphinx==1.1.3 diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 9c31950d..d3bf3cf4 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -356,11 +356,11 @@ POST Multiple Multipart-Encoded Files ------------------------------------- You can send multiple files in one request. For example, suppose you want to -upload image files to an HTML form with a multiple file field 'images': +upload image files to an HTML form with a multiple file field 'images':: -To do that, just set files to a list of tuples of (form_field_name, file_info): +To do that, just set files to a list of tuples of ``(form_field_name, file_info)``: >>> url = 'http://httpbin.org/post' >>> multiple_files = [('images', ('foo.png', open('foo.png', 'rb'), 'image/png')), @@ -519,6 +519,7 @@ You can also configure proxies by setting the environment variables $ export HTTP_PROXY="http://10.10.1.10:3128" $ export HTTPS_PROXY="http://10.10.1.10:1080" + $ python >>> import requests >>> requests.get("http://example.org") From dbefff68214b9a65d53a6f13fc1f1e49d6c7c91f Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 01:23:31 -0500 Subject: [PATCH 14/61] sphinx is now working properly on RTD (grrrR) --- docs/MANIFEST.in | 1 - docs/_templates/hacks.html | 23 ++++ docs/_templates/layout.html | 59 ---------- docs/conf.py | 215 ++++++++++++++++++++++++++++-------- 4 files changed, 192 insertions(+), 106 deletions(-) delete mode 100644 docs/MANIFEST.in create mode 100644 docs/_templates/hacks.html delete mode 100644 docs/_templates/layout.html diff --git a/docs/MANIFEST.in b/docs/MANIFEST.in deleted file mode 100644 index fb1021bf..00000000 --- a/docs/MANIFEST.in +++ /dev/null @@ -1 +0,0 @@ -include HISTORY.rst README.rst LICENSE \ No newline at end of file diff --git a/docs/_templates/hacks.html b/docs/_templates/hacks.html new file mode 100644 index 00000000..b18e73d0 --- /dev/null +++ b/docs/_templates/hacks.html @@ -0,0 +1,23 @@ + + + + + + + diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html deleted file mode 100644 index b53db050..00000000 --- a/docs/_templates/layout.html +++ /dev/null @@ -1,59 +0,0 @@ -{%- extends "basic/layout.html" %} -{%- block extrahead %} - - {{ super() }} - - {% if theme_touch_icon %} - - {% endif %} - - - - - -{% endblock %} -{%- block relbar2 %}{% endblock %} -{%- block footer %} -
- © Copyright {{ copyright }}. -
- - Fork me on GitHub - - - - - - - - -{%- endblock %} diff --git a/docs/conf.py b/docs/conf.py index a84469db..00e4261c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,9 +1,10 @@ # -*- coding: utf-8 -*- # # Requests documentation build configuration file, created by -# sphinx-quickstart on Sun Feb 13 23:54:25 2011. +# sphinx-quickstart on Fri Feb 19 00:05:47 2016. # -# This file is execfile()d with the current directory set to its containing dir. +# This file is execfile()d with the current directory set to its +# containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. @@ -11,34 +12,43 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import sys +import os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# Insert Requests' path into the system. sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('_themes')) + import requests from requests import __version__ -import alabaster -# -- General configuration ----------------------------------------------------- +# -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', - 'alabaster' + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix of source filenames. +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The encoding of source files. @@ -50,6 +60,7 @@ master_doc = 'index' # General information about the project. project = u'Requests' copyright = u'2016. A Kenneth Reitz Project' +author = u'Kenneth Reitz' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -58,11 +69,14 @@ copyright = u'2016. A tag referring to it. The value of this option must be the @@ -181,23 +208,45 @@ html_show_sphinx = False # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + # Output file base name for HTML help builder. htmlhelp_basename = 'Requestsdoc' +# -- Options for LaTeX output --------------------------------------------- -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). latex_documents = [ - ('index', 'Requests.tex', u'Requests Documentation', - u'Kenneth Reitz', 'manual'), + (master_doc, 'Requests.tex', u'Requests Documentation', + u'Kenneth Reitz', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -214,9 +263,6 @@ latex_documents = [ # If true, show URL addresses after external links. #latex_show_urls = False -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - # Documents to append as an appendix to all manuals. #latex_appendices = [] @@ -224,33 +270,110 @@ latex_documents = [ #latex_domain_indices = True -# -- Options for manual page output -------------------------------------------- +# -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'requests', u'Requests Documentation', - [u'Kenneth Reitz'], 1) + (master_doc, 'requests', u'Requests Documentation', + [author], 1) ] # If true, show URL addresses after external links. #man_show_urls = False -# -- Options for Texinfo output ------------------------------------------------ + +# -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'Requests', u'Requests Documentation', u'Kenneth Reitz', - 'Requests', 'One line description of project.', 'Miscellaneous'), + (master_doc, 'Requests', u'Requests Documentation', + author, 'Requests', 'One line description of project.', + 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. -texinfo_appendices = [] +#texinfo_appendices = [] -sys.path.append(os.path.abspath('_themes')) -html_theme_path =[alabaster.get_path()] -html_theme = 'alabaster' +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not +# optimized for small screen space, using the same theme for HTML and epub +# output is usually not wise. This defaults to 'epub', a theme designed to save +# visual space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files that should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True intersphinx_mapping = {'urllib3': ('http://urllib3.readthedocs.org/en/latest', None)} From 60b591eaac1836998550f555cd6d28a2c87b4f84 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 01:47:54 -0500 Subject: [PATCH 15/61] docs: widen things up --- docs/_templates/hacks.html | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/_templates/hacks.html b/docs/_templates/hacks.html index b18e73d0..997f8b23 100644 --- a/docs/_templates/hacks.html +++ b/docs/_templates/hacks.html @@ -2,8 +2,21 @@ @@ -21,3 +34,7 @@ s.parentNode.insertBefore(t, s); })(); + + + + \ No newline at end of file From f422ace07e92d79308f2e72897126971c37a3414 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 01:52:59 -0500 Subject: [PATCH 16/61] clean up codeblock styles --- docs/_templates/hacks.html | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/_templates/hacks.html b/docs/_templates/hacks.html index 997f8b23..4763b26b 100644 --- a/docs/_templates/hacks.html +++ b/docs/_templates/hacks.html @@ -12,11 +12,15 @@ /* Make the document a little wider, less code is cut-off. */ div.document {width: 1008px;} + /* Much-improved spacing around code blocks. */ + div.highlight pre {padding: 11px 14px;} + /* Remain Responsive! */ @media screen and (max-width: 1008px) { div.sphinxsidebar {display: none;} div.document {width: 100%!important;} } + From f4f863f168d6e2c660cd73d158aaf330ba9070da Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 02:06:33 -0500 Subject: [PATCH 17/61] cleanup advanced.rst single-quoted strings, yo! --- docs/user/advanced.rst | 47 ++++++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index d3bf3cf4..79ba227b 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -24,7 +24,7 @@ Let's persist some cookies across requests:: s = requests.Session() s.get('http://httpbin.org/cookies/set/sessioncookie/123456789') - r = s.get("http://httpbin.org/cookies") + r = s.get('http://httpbin.org/cookies') print(r.text) # '{"cookies": {"sessioncookie": "123456789"}}' @@ -50,6 +50,7 @@ requests, even if using a session. This example will only send the cookies with the first request, but not the second:: s = requests.Session() + r = s.get('http://httpbin.org/cookies', cookies={'from-my': 'browser'}) print(r.text) # '{"cookies": {"from-my": "browser"}}' @@ -129,14 +130,15 @@ request. The simple recipe for this is the following:: from requests import Request, Session s = Session() - req = Request('GET', url, - data=data, - headers=header - ) + + req = Request('POST', url, data=data, headers=headers) prepped = req.prepare() # do something with prepped.body + prepped.body = 'No, I want exactly this as the body.' + # do something with prepped.headers + del prepped.headers['Content-Type'] resp = s.send(prepped, stream=stream, @@ -491,7 +493,9 @@ set ``stream`` to ``True`` and iterate over the response with lines = r.iter_lines() # Save the first line for later or just skip it + first_line = next(lines) + for line in lines: print(line) @@ -506,11 +510,11 @@ If you need to use a proxy, you can configure individual requests with the import requests proxies = { - "http": "http://10.10.1.10:3128", - "https": "http://10.10.1.10:1080", + 'http': 'http://10.10.1.10:3128', + 'https': 'http://10.10.1.10:1080', } - requests.get("http://example.org", proxies=proxies) + requests.get('http://example.org', proxies=proxies) You can also configure proxies by setting the environment variables ``HTTP_PROXY`` and ``HTTPS_PROXY``. @@ -522,12 +526,12 @@ You can also configure proxies by setting the environment variables $ python >>> import requests - >>> requests.get("http://example.org") + >>> requests.get('http://example.org') To use HTTP Basic Auth with your proxy, use the `http://user:password@host/` syntax:: proxies = { - "http": "http://user:pass@10.10.1.10:3128/", + 'http': 'http://user:pass@10.10.1.10:3128/', } To give a proxy for a specific scheme and host, use the @@ -537,7 +541,7 @@ any request to the given scheme and exact hostname. :: proxies = { - "http://10.20.1.128": "http://10.10.1.10:5323", + 'http://10.20.1.128': 'http://10.10.1.10:5323', } Note that proxy URLs must include the scheme. @@ -603,10 +607,13 @@ So, GitHub returns JSON. That's great, we can use the :meth:`r.json :: >>> commit_data = r.json() + >>> print(commit_data.keys()) [u'committer', u'author', u'url', u'tree', u'sha', u'parents', u'message'] + >>> print(commit_data[u'committer']) {u'date': u'2012-05-10T11:10:50-07:00', u'email': u'me@kennethreitz.com', u'name': u'Kenneth Reitz'} + >>> print(commit_data[u'message']) makin' history @@ -646,9 +653,12 @@ already exists, we will use it as an example. Let's start by getting it. >>> r = requests.get('https://api.github.com/repos/kennethreitz/requests/issues/482') >>> r.status_code 200 + >>> issue = json.loads(r.text) + >>> print(issue[u'title']) Feature any http verb in docs + >>> print(issue[u'comments']) 3 @@ -659,9 +669,12 @@ Cool, we have three comments. Let's take a look at the last of them. >>> r = requests.get(r.url + u'/comments') >>> r.status_code 200 + >>> comments = r.json() + >>> print(comments[0].keys()) [u'body', u'url', u'created_at', u'updated_at', u'user', u'id'] + >>> print(comments[2][u'body']) Probably in the "advanced" section @@ -681,6 +694,7 @@ is to POST to the thread. Let's do it. >>> body = json.dumps({u"body": u"Sounds great! I'll get right on it!"}) >>> url = u"https://api.github.com/repos/kennethreitz/requests/issues/482/comments" + >>> r = requests.post(url=url, data=body) >>> r.status_code 404 @@ -693,9 +707,11 @@ the very common Basic Auth. >>> from requests.auth import HTTPBasicAuth >>> auth = HTTPBasicAuth('fake@example.com', 'not_a_real_password') + >>> r = requests.post(url=url, data=body, auth=auth) >>> r.status_code 201 + >>> content = r.json() >>> print(content[u'body']) Sounds great! I'll get right on it. @@ -709,8 +725,10 @@ that. >>> print(content[u"id"]) 5804413 + >>> body = json.dumps({u"body": u"Sounds great! I'll get right on it once I feed my cat."}) >>> url = u"https://api.github.com/repos/kennethreitz/requests/issues/comments/5804413" + >>> r = requests.patch(url=url, data=body, auth=auth) >>> r.status_code 200 @@ -831,10 +849,9 @@ SSLv3: """"Transport adapter" that allows us to use SSLv3.""" def init_poolmanager(self, connections, maxsize, block=False): - self.poolmanager = PoolManager(num_pools=connections, - maxsize=maxsize, - block=block, - ssl_version=ssl.PROTOCOL_SSLv3) + self.poolmanager = PoolManager( + num_pools=connections, maxsize=maxsize, + block=block, ssl_version=ssl.PROTOCOL_SSLv3) .. _`described here`: http://www.kennethreitz.org/essays/the-future-of-python-http .. _`urllib3`: https://github.com/shazow/urllib3 From bf8c8312ddece928b2549104b5864600df368904 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 02:12:15 -0500 Subject: [PATCH 18/61] cleanup quickstart --- docs/user/quickstart.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index 10037fe6..d31f224e 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -37,15 +37,15 @@ get all the information we need from this object. Requests' simple API means that all forms of HTTP request are as obvious. For example, this is how you make an HTTP POST request:: - >>> r = requests.post("http://httpbin.org/post", data = {"key":"value"}) + >>> r = requests.post('http://httpbin.org/post', data = {'key':'value'}) Nice, right? What about the other HTTP request types: PUT, DELETE, HEAD and OPTIONS? These are all just as simple:: - >>> r = requests.put("http://httpbin.org/put", data = {"key":"value"}) - >>> r = requests.delete("http://httpbin.org/delete") - >>> r = requests.head("http://httpbin.org/get") - >>> r = requests.options("http://httpbin.org/get") + >>> r = requests.put('http://httpbin.org/put', data = {'key':'value'}) + >>> r = requests.delete('http://httpbin.org/delete') + >>> r = requests.head('http://httpbin.org/get') + >>> r = requests.options('http://httpbin.org/get') That's all well and good, but it's also only the start of what Requests can do. @@ -63,7 +63,7 @@ Requests allows you to provide these arguments as a dictionary, using the following code:: >>> payload = {'key1': 'value1', 'key2': 'value2'} - >>> r = requests.get("http://httpbin.org/get", params=payload) + >>> r = requests.get('http://httpbin.org/get', params=payload) You can see that the URL has been correctly encoded by printing the URL:: @@ -76,7 +76,8 @@ URL's query string. You can also pass a list of items as a value:: >>> payload = {'key1': 'value1', 'key2': ['value2', 'value3']} - >>> r = requests.get("http://httpbin.org/get", params=payload) + + >>> r = requests.get('http://httpbin.org/get', params=payload) >>> print(r.url) http://httpbin.org/get?key1=value1&key2=value2&key2=value3 @@ -87,6 +88,7 @@ We can read the content of the server's response. Consider the GitHub timeline again:: >>> import requests + >>> r = requests.get('https://api.github.com/events') >>> r.text u'[{"repository":{"open_issues":0,"url":"https://github.com/... @@ -131,6 +133,7 @@ use the following code:: >>> from PIL import Image >>> from StringIO import StringIO + >>> i = Image.open(StringIO(r.content)) @@ -140,6 +143,7 @@ JSON Response Content There's also a builtin JSON decoder, in case you're dealing with JSON data:: >>> import requests + >>> r = requests.get('https://api.github.com/events') >>> r.json() [{u'repository': {u'open_issues': 0, u'url': 'https://github.com/... @@ -163,8 +167,10 @@ server, you can access ``r.raw``. If you want to do this, make sure you set ``stream=True`` in your initial request. Once you do, you can do this:: >>> r = requests.get('https://api.github.com/events', stream=True) + >>> r.raw + >>> r.raw.read(10) '\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03' @@ -189,7 +195,6 @@ If you'd like to add HTTP headers to a request, simply pass in a ``dict`` to the For example, we didn't specify our user-agent in the previous example:: - >>> import json >>> url = 'https://api.github.com/some/endpoint' >>> headers = {'user-agent': 'my-app/0.0.1'} @@ -215,6 +220,7 @@ To do this, simply pass a dictionary to the ``data`` argument. Your dictionary of data will automatically be form-encoded when the request is made:: >>> payload = {'key1': 'value1', 'key2': 'value2'} + >>> r = requests.post("http://httpbin.org/post", data=payload) >>> print(r.text) { @@ -232,6 +238,7 @@ you pass in a ``string`` instead of a ``dict``, that data will be posted directl For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data:: >>> import json + >>> url = 'https://api.github.com/some/endpoint' >>> payload = {'some': 'data'} @@ -426,10 +433,13 @@ response. For example, GitHub redirects all HTTP requests to HTTPS:: >>> r = requests.get('http://github.com') + >>> r.url 'https://github.com/' + >>> r.status_code 200 + >>> r.history [] @@ -438,16 +448,20 @@ If you're using GET, OPTIONS, POST, PUT, PATCH or DELETE, you can disable redirection handling with the ``allow_redirects`` parameter:: >>> r = requests.get('http://github.com', allow_redirects=False) + >>> r.status_code 301 + >>> r.history [] If you're using HEAD, you can enable redirection as well:: >>> r = requests.head('http://github.com', allow_redirects=True) + >>> r.url 'https://github.com/' + >>> r.history [] From f4445b3d4f320f66142cf5aa0656fe62a6c0df3e Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 02:40:14 -0500 Subject: [PATCH 19/61] improve advanced.rst --- docs/user/advanced.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 79ba227b..cc99b679 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -167,15 +167,15 @@ applied, replace the call to :meth:`Request.prepare() from requests import Request, Session s = Session() - req = Request('GET', url, - data=data - headers=headers - ) + req = Request('GET', url, data=data, headers=headers) prepped = s.prepare_request(req) # do something with prepped.body + prepped.body = 'Seriously, send exactly these bytes.' + # do something with prepped.headers + prepped.headers['Keep-Dead'] = 'parrot' resp = s.send(prepped, stream=stream, @@ -362,11 +362,12 @@ upload image files to an HTML form with a multiple file field 'images':: -To do that, just set files to a list of tuples of ``(form_field_name, file_info)``: +To do that, just set files to a list of tuples of ``(form_field_name, file_info)``:: >>> url = 'http://httpbin.org/post' - >>> multiple_files = [('images', ('foo.png', open('foo.png', 'rb'), 'image/png')), - ('images', ('bar.png', open('bar.png', 'rb'), 'image/png'))] + >>> multiple_files = [ + ('images', ('foo.png', open('foo.png', 'rb'), 'image/png')), + ('images', ('bar.png', open('bar.png', 'rb'), 'image/png'))] >>> r = requests.post(url, files=multiple_files) >>> r.text { From f8af499700b58cf550205c463ad4b163a784892b Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 02:45:07 -0500 Subject: [PATCH 20/61] improve further advanced.rst --- docs/user/advanced.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index cc99b679..ddd6edf6 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -531,9 +531,7 @@ You can also configure proxies by setting the environment variables To use HTTP Basic Auth with your proxy, use the `http://user:password@host/` syntax:: - proxies = { - 'http': 'http://user:pass@10.10.1.10:3128/', - } + proxies = {'http': 'http://user:pass@10.10.1.10:3128/'} To give a proxy for a specific scheme and host, use the `scheme://hostname` form for the key. This will match for @@ -541,9 +539,7 @@ any request to the given scheme and exact hostname. :: - proxies = { - 'http://10.20.1.128': 'http://10.10.1.10:5323', - } + proxies = {'http://10.20.1.128': 'http://10.10.1.10:5323'} Note that proxy URLs must include the scheme. From f63106005b3050b5a99833ec47b78667dc4766b2 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 02:59:05 -0500 Subject: [PATCH 21/61] better codeblocks on mobile --- docs/_templates/hacks.html | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/_templates/hacks.html b/docs/_templates/hacks.html index 4763b26b..ba032452 100644 --- a/docs/_templates/hacks.html +++ b/docs/_templates/hacks.html @@ -19,6 +19,9 @@ @media screen and (max-width: 1008px) { div.sphinxsidebar {display: none;} div.document {width: 100%!important;} + + /* Have code blocks escape the document right-margin. */ + div.highlight pre {margin-right: -30px;} } From 688a00c38643f55df41f8337b063ba1944f33ca6 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 03:47:12 -0500 Subject: [PATCH 22/61] improve contributions section --- docs/dev/contributing.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 075d042a..f619e569 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -22,12 +22,8 @@ contributors. .. _Ian Cordasco: http://www.coglib.com/~icordasc/ .. _Cory Benfield: https://lukasa.co.uk/about - -All Contributions ------------------ - Be Cordial -~~~~~~~~~~ +---------- **Be cordial or be on your way.** @@ -41,7 +37,7 @@ everyone involved is treated with respect. .. _early-feedback: Get Early Feedback -~~~~~~~~~~~~~~~~~~ +------------------ If you are contributing, do not feel the need to sit on your contribution until it is perfectly polished and complete. It helps everyone involved for you to @@ -51,7 +47,7 @@ getting that contribution accepted, and can save you from putting a lot of work into a contribution that is not suitable for the project. Contribution Suitability -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ The project maintainer has the last word on whether or not a contribution is suitable for Requests. All contributions will be considered, but from time @@ -116,6 +112,9 @@ When contributing documentation, please attempt to follow the style of the documentation files. This means a soft-limit of 79 characters wide in your text files and a semi-formal prose style. +When presenting Python code, use single-quoted strings (``'hello'`` instead of +``"hello"``). + .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Sphinx: http://sphinx-doc.org/index.html From d3bd9f30a6acec62cafee067e82f7cb1cd775701 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 04:09:03 -0500 Subject: [PATCH 23/61] contributing --- docs/dev/contributing.rst | 45 +++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index f619e569..7aa763cd 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -3,33 +3,38 @@ Contributor's Guide =================== -If you're reading this you're probably interested in contributing to -Requests. First, We'd like to say: thank you! Open source projects -live-and-die based on the support they receive from others, and the fact that -you're even considering supporting Requests is very generous of -you. +If you're reading this, you're probably interested in contributing to Requests. +Thank you very much! Open source projects live-and-die based on the support +they receive from others, and the fact that you're even considering +contributing to the Requests project is *very* generous of you. -This document lays out guidelines and advice for contributing to Requests. -If you're thinking of contributing, start by reading this thoroughly and -getting a feel for how contributing to the project works. If you have any +This document lays out guidelines and advice for contributing to this project. +If you're thinking of contributing, please start by reading this document and +getting a feel for how contributing to this project works. If you have any questions, feel free to reach out to either `Ian Cordasco`_ or `Cory Benfield`_, the primary maintainers. +.. _Ian Cordasco: http://www.coglib.com/~icordasc/ +.. _Cory Benfield: https://lukasa.co.uk/about + +If you have non-technical feedback, philisophical ponderings, crazy ideas, or +other general thoughts about Requests or its position within the Python +ecosystem, the BDFL, `Kenneth Reitz`_, would love to hear from you. + The guide is split into sections based on the type of contribution you're thinking of making, with a section that covers general guidelines for all contributors. -.. _Ian Cordasco: http://www.coglib.com/~icordasc/ -.. _Cory Benfield: https://lukasa.co.uk/about +.. _Kenneth Reitz: mailto:me@kennethreitz.org Be Cordial ---------- -**Be cordial or be on your way.** + **Be cordial or be on your way**. *—Kenneth Reitz* Requests has one very important rule governing all forms of contribution, including reporting bugs or requesting features. This golden rule is -`be cordial or be on your way`_. **All contributions are welcome**, as long as +"`be cordial or be on your way`_". **All contributions are welcome**, as long as everyone involved is treated with respect. .. _be cordial or be on your way: http://kennethreitz.org/be-cordial-or-be-on-your-way/ @@ -108,9 +113,9 @@ the ``docs/`` directory of the codebase. They're written in `reStructuredText`_, and use `Sphinx`_ to generate the full suite of documentation. -When contributing documentation, please attempt to follow the style of the +When contributing documentation, please do your best to follow the style of the documentation files. This means a soft-limit of 79 characters wide in your text -files and a semi-formal prose style. +files and a semi-formal, yet friendly and approachable, prose style. When presenting Python code, use single-quoted strings (``'hello'`` instead of ``"hello"``). @@ -135,10 +140,14 @@ of other contributors, and should be avoided as much as possible. Feature Requests ---------------- -Requests is in a perpetual feature freeze. The maintainers believe that -requests contains every major feature currently required by the vast majority -of users. +Requests is in a perpetual feature freeze, only the BDFL can add or approve of +new features. The maintainers believe that Requests is a feature-complete +peice of software at this time. + +One of the most important skills to have while maintaining a largely-used +open source project is learning the ability to say "no" to suggested changes, +while keeping an open ear and mind. If you believe there is a feature missing, feel free to raise a feature request, but please do be aware that the overwhelming likelihood is that your -feature request will not be accepted. +feature request will not be accepted. \ No newline at end of file From 886f92324a4a030676fca440d33f34631c27acd9 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 04:10:37 -0500 Subject: [PATCH 24/61] contributing --- docs/dev/contributing.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 7aa763cd..ceedda33 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -34,7 +34,9 @@ Be Cordial Requests has one very important rule governing all forms of contribution, including reporting bugs or requesting features. This golden rule is -"`be cordial or be on your way`_". **All contributions are welcome**, as long as +"`be cordial or be on your way`_". + +**All contributions are welcome**, as long as everyone involved is treated with respect. .. _be cordial or be on your way: http://kennethreitz.org/be-cordial-or-be-on-your-way/ From 2cb052aa950a20744778af802acff240830505f3 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 04:11:41 -0500 Subject: [PATCH 25/61] sp --- docs/dev/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index ceedda33..094b7b19 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -17,7 +17,7 @@ the primary maintainers. .. _Ian Cordasco: http://www.coglib.com/~icordasc/ .. _Cory Benfield: https://lukasa.co.uk/about -If you have non-technical feedback, philisophical ponderings, crazy ideas, or +If you have non-technical feedback, philosophical ponderings, crazy ideas, or other general thoughts about Requests or its position within the Python ecosystem, the BDFL, `Kenneth Reitz`_, would love to hear from you. From 5d0ffd85cef1f85124ab38a9207f9d4d734910cf Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 04:30:06 -0500 Subject: [PATCH 26/61] style guide --- docs/dev/contributing.rst | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 094b7b19..585497bb 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -68,8 +68,8 @@ accepted. Code Contributions ------------------ -Steps -~~~~~ +Steps for Submitting Code +~~~~~~~~~~~~~~~~~~~~~~~~~ When contributing code, you'll want to follow this checklist: @@ -107,6 +107,30 @@ asking for help. Please also check the :ref:`early-feedback` section. +Code Style +~~~~~~~~~~ + +The Requests codebase uses the `PEP8`_ code style. + +In addition to the standards outlined in PEP8, we have a few guidelines: + +- Line-length can exceed 79 characters, to 100, when convenient. +- Line-length can exceed 100 characters, when doing otherwise would be *terribly* inconvenient. +- Always use single-quoted strings (e.g. ``'#flatearth'``), unless a single-quote occurs within the string. + +Additionally, one of the few style recommendations PEP8 makes for +`line continuations`_ lacks all sense of taste, and is not to be found within +the Requests codebase:: + + # Aligned with opening delimiter. + foo = long_function_name(var_one, var_two, + var_three, var_four) + +Just don't. Ever. + +.. _PEP8: https://www.python.org/dev/peps/pep-0008/ +.. _line continuations: https://www.python.org/dev/peps/pep-0008/#indentation + Documentation Contributions --------------------------- From 90ddeca70d7846e6a5b99a9c1fe1a2666b5ca47c Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 04:42:54 -0500 Subject: [PATCH 27/61] updated style guide --- docs/dev/contributing.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 585497bb..1c43cea7 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -126,7 +126,21 @@ the Requests codebase:: foo = long_function_name(var_one, var_two, var_three, var_four) -Just don't. Ever. +No. + +Docstrings are to follow the following syntaxes:: + + def the_earth_is_flat(): + """There is no curve! Also, human cloning centers.""" + +:: + + def well_documented_utility(): + """Lorem ipsum dolor sit amet, consectetur adipiscing elit, + sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris + nisi ut aliquip ex ea commodo consequat. + """ .. _PEP8: https://www.python.org/dev/peps/pep-0008/ .. _line continuations: https://www.python.org/dev/peps/pep-0008/#indentation From ee024423a5d586b2e2cfe773cc5c47a8dcf1db99 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 04:44:11 -0500 Subject: [PATCH 28/61] more pleasant wording about strong opinion --- docs/dev/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 1c43cea7..e4209366 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -126,7 +126,7 @@ the Requests codebase:: foo = long_function_name(var_one, var_two, var_three, var_four) -No. +No. Just don't. Please. Docstrings are to follow the following syntaxes:: From 29b191b5ea66f7d8e4f9a5db2cc6e0aec9c0d884 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 04:48:47 -0500 Subject: [PATCH 29/61] --- docs/dev/contributing.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index e4209366..85e443b2 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -142,6 +142,8 @@ Docstrings are to follow the following syntaxes:: nisi ut aliquip ex ea commodo consequat. """ +Thanks for helping to make the world a better place! + .. _PEP8: https://www.python.org/dev/peps/pep-0008/ .. _line continuations: https://www.python.org/dev/peps/pep-0008/#indentation From 8dc5f68bc1d9d28b79478f495be445ba048e8081 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 04:50:55 -0500 Subject: [PATCH 30/61] sp --- docs/dev/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 85e443b2..feb7e741 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -184,7 +184,7 @@ Feature Requests Requests is in a perpetual feature freeze, only the BDFL can add or approve of new features. The maintainers believe that Requests is a feature-complete -peice of software at this time. +piece of software at this time. One of the most important skills to have while maintaining a largely-used open source project is learning the ability to say "no" to suggested changes, From 1cf1699e37139daa37913e989c91fa130a2472fe Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 04:56:25 -0500 Subject: [PATCH 31/61] what's docstrung --- docs/dev/contributing.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index feb7e741..41159fb9 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -142,6 +142,9 @@ Docstrings are to follow the following syntaxes:: nisi ut aliquip ex ea commodo consequat. """ +All functions, methods, and classes are to contain docstrings. Object data +model methods (e.g. ``__repr__``) are usually an exception to this rule. + Thanks for helping to make the world a better place! .. _PEP8: https://www.python.org/dev/peps/pep-0008/ From f653b9ac58ad74441e118538619979edcf6749a5 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 05:03:04 -0500 Subject: [PATCH 32/61] sentences --- docs/dev/contributing.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 41159fb9..0c17c3b3 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -56,13 +56,14 @@ into a contribution that is not suitable for the project. Contribution Suitability ------------------------ -The project maintainer has the last word on whether or not a contribution is -suitable for Requests. All contributions will be considered, but from time -to time contributions will be rejected because they do not suit the project. +Our project maintainers have the last word on whether or not a contribution is +suitable for Requests. All contributions will be considered carefully, but from +time to time, contributions will be rejected because they do not suit the +current goals or needs of the project. -If your contribution is rejected, don't despair! So long as you followed these -guidelines, you'll have a much better chance of getting your next contribution -accepted. +If your contribution is rejected, don't despair! As long as you followed these +guidelines, you will have a much better chance of getting your next +contribution accepted. Code Contributions From b70136cf52e8dfd5a950fecfe2aee820dc7926ef Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 05:38:33 -0500 Subject: [PATCH 33/61] completely (docs) --- docs/dev/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 0c17c3b3..82b4a45c 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -119,8 +119,8 @@ In addition to the standards outlined in PEP8, we have a few guidelines: - Line-length can exceed 100 characters, when doing otherwise would be *terribly* inconvenient. - Always use single-quoted strings (e.g. ``'#flatearth'``), unless a single-quote occurs within the string. -Additionally, one of the few style recommendations PEP8 makes for -`line continuations`_ lacks all sense of taste, and is not to be found within +Additionally, one of the styles that PEP8 recommends for `line continuations`_ +completely lacks all sense of taste, and is not to be permitted within the Requests codebase:: # Aligned with opening delimiter. From 14a83339a74929eae193fbbefd3668cfa8943780 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 05:41:17 -0500 Subject: [PATCH 34/61] words (docs) --- docs/dev/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 82b4a45c..f17af82c 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -144,7 +144,7 @@ Docstrings are to follow the following syntaxes:: """ All functions, methods, and classes are to contain docstrings. Object data -model methods (e.g. ``__repr__``) are usually an exception to this rule. +model methods (e.g. ``__repr__``) are typically the exception to this rule. Thanks for helping to make the world a better place! From d8bf59dde4bd47f07ef88a4161b4a652b06c7599 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 05:45:55 -0500 Subject: [PATCH 35/61] namedrop --- docs/dev/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index f17af82c..1f692621 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -108,8 +108,8 @@ asking for help. Please also check the :ref:`early-feedback` section. -Code Style -~~~~~~~~~~ +Kenneth Reitz's Code Style +~~~~~~~~~~~~~~~~~~~~~~~~~~ The Requests codebase uses the `PEP8`_ code style. From 1b1f4ac77d778eb730790890ce764e5127758e02 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 06:08:38 -0500 Subject: [PATCH 36/61] cheat code --- docs/_static/konami.js | 116 +++++++++++++++++++++++++++++++++++++ docs/_templates/hacks.html | 9 ++- docs/index.rst | 9 ++- 3 files changed, 130 insertions(+), 4 deletions(-) create mode 100644 docs/_static/konami.js diff --git a/docs/_static/konami.js b/docs/_static/konami.js new file mode 100644 index 00000000..d72cf9df --- /dev/null +++ b/docs/_static/konami.js @@ -0,0 +1,116 @@ +/* + * Konami-JS ~ + * :: Now with support for touch events and multiple instances for + * :: those situations that call for multiple easter eggs! + * Code: http://konami-js.googlecode.com/ + * Examples: http://www.snaptortoise.com/konami-js + * Copyright (c) 2009 George Mandis (georgemandis.com, snaptortoise.com) + * Version: 1.4.2 (9/2/2013) + * Licensed under the MIT License (http://opensource.org/licenses/MIT) + * Tested in: Safari 4+, Google Chrome 4+, Firefox 3+, IE7+, Mobile Safari 2.2.1 and Dolphin Browser + */ + +var Konami = function (callback) { + var konami = { + addEvent: function (obj, type, fn, ref_obj) { + if (obj.addEventListener) + obj.addEventListener(type, fn, false); + else if (obj.attachEvent) { + // IE + obj["e" + type + fn] = fn; + obj[type + fn] = function () { + obj["e" + type + fn](window.event, ref_obj); + }; + obj.attachEvent("on" + type, obj[type + fn]); + } + }, + input: "", + pattern: "38384040373937396665", + load: function (link) { + this.addEvent(document, "keydown", function (e, ref_obj) { + if (ref_obj) konami = ref_obj; // IE + konami.input += e ? e.keyCode : event.keyCode; + if (konami.input.length > konami.pattern.length) + konami.input = konami.input.substr((konami.input.length - konami.pattern.length)); + if (konami.input == konami.pattern) { + konami.code(link); + konami.input = ""; + e.preventDefault(); + return false; + } + }, this); + this.iphone.load(link); + }, + code: function (link) { + window.location = link + }, + iphone: { + start_x: 0, + start_y: 0, + stop_x: 0, + stop_y: 0, + tapTolerance: 8, + capture: false, + orig_keys: "", + keys: ["UP", "UP", "DOWN", "DOWN", "LEFT", "RIGHT", "LEFT", "RIGHT", "TAP", "TAP"], + code: function (link) { + konami.code(link); + }, + touchCapture: function(evt) { + konami.iphone.start_x = evt.changedTouches[0].pageX; + konami.iphone.start_y = evt.changedTouches[0].pageY; + konami.iphone.capture = true; + }, + load: function (link) { + this.orig_keys = this.keys; + konami.addEvent(document, "touchmove", function (e) { + if (e.touches.length == 1 && konami.iphone.capture == true) { + var touch = e.touches[0]; + konami.iphone.stop_x = touch.pageX; + konami.iphone.stop_y = touch.pageY; + konami.iphone.check_direction(); + } + }); + konami.addEvent(document, "touchend", function (evt) { + konami.touchCapture(evt); + konami.iphone.check_direction(link); + }, false); + konami.addEvent(document, "touchstart", function (evt) { + konami.touchCapture(evt); + }); + }, + check_direction: function (link) { + var x_magnitude = Math.abs(this.start_x - this.stop_x); + var y_magnitude = Math.abs(this.start_y - this.stop_y); + var hasMoved = (x_magnitude > this.tapTolerance || y_magnitude > this.tapTolerance); + var result; + if (this.capture === true && hasMoved) { + this.capture = false; + var x = ((this.start_x - this.stop_x) < 0) ? "RIGHT" : "LEFT"; + var y = ((this.start_y - this.stop_y) < 0) ? "DOWN" : "UP"; + var result = (x_magnitude > y_magnitude) ? x : y; + } + else if (this.capture === false && !hasMoved) { + result = (this.tap == true) ? "TAP" : result; + result = "TAP"; + } + if (result) { + if (result == this.keys[0]) this.keys = this.keys.slice(1, this.keys.length); + else this.keys = this.orig_keys; + } + if (this.keys.length == 0) { + this.keys = this.orig_keys; + this.code(link); + } + } + } + } + + typeof callback === "string" && konami.load(callback); + if (typeof callback === "function") { + konami.code = callback; + konami.load(); + } + + return konami; +}; diff --git a/docs/_templates/hacks.html b/docs/_templates/hacks.html index ba032452..ca9865d6 100644 --- a/docs/_templates/hacks.html +++ b/docs/_templates/hacks.html @@ -44,4 +44,11 @@ - \ No newline at end of file + + + + + + \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 0df56107..75983c37 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -124,8 +124,8 @@ Requests ecosystem and community. community/updates community/release-process -API Documentation ------------------ +API Documentation / Guide +------------------------- If you are looking for information on a specific function, class or method, this part of the documentation is for you. @@ -143,9 +143,12 @@ If you want to contribute to the project, this part of the documentation is for you. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 dev/contributing dev/philosophy dev/todo dev/authors + +There are no more guides. You are now guideless. +Good luck. From ca303cda0a4664bf925ba2eecdd4c5abf1987443 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 06:14:51 -0500 Subject: [PATCH 37/61] letters --- docs/index.rst | 2 +- docs/user/install.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 75983c37..cc4d4510 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -143,7 +143,7 @@ If you want to contribute to the project, this part of the documentation is for you. .. toctree:: - :maxdepth: 2 + :maxdepth: 3 dev/contributing dev/philosophy diff --git a/docs/user/install.rst b/docs/user/install.rst index b14ee310..c3f0084e 100644 --- a/docs/user/install.rst +++ b/docs/user/install.rst @@ -7,8 +7,8 @@ This part of the documentation covers the installation of Requests. The first step to using any software package is getting it properly installed. -Pip Install ------------ +Pip Install Requests +-------------------- To install Requests, simply run this simple command in your terminal of choice:: @@ -18,8 +18,8 @@ If you don't have `pip `_ installed (tisk tisk!), `this Python installation guide `_ can guide you through the process. -Get the Code ------------- +Get the Source Code +------------------- Requests is actively developed on GitHub, where the code is `always available `_. From a7b5e3191d1b121e452e83798287209d12ade7ee Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 08:51:36 -0500 Subject: [PATCH 38/61] pass go, yay $200 --- docs/dev/contributing.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 1f692621..24f4b9f7 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -133,6 +133,7 @@ Docstrings are to follow the following syntaxes:: def the_earth_is_flat(): """There is no curve! Also, human cloning centers.""" + pass :: @@ -142,6 +143,7 @@ Docstrings are to follow the following syntaxes:: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. """ + pass All functions, methods, and classes are to contain docstrings. Object data model methods (e.g. ``__repr__``) are typically the exception to this rule. From fc1e9b46a197b8412fa3fdb7d2bcb5e0f62f68a5 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 09:08:29 -0500 Subject: [PATCH 39/61] lyrics, er, docstrings --- docs/dev/contributing.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 24f4b9f7..302d1bd6 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -132,16 +132,20 @@ No. Just don't. Please. Docstrings are to follow the following syntaxes:: def the_earth_is_flat(): - """There is no curve! Also, human cloning centers.""" + """NASA divided up the seas into thirty-three degrees.""" pass :: - def well_documented_utility(): - """Lorem ipsum dolor sit amet, consectetur adipiscing elit, - sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. - Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris - nisi ut aliquip ex ea commodo consequat. + def fibonacci_spiral_tool(): + """With my feet upon the ground I lose myself / between the sounds and open + wide to suck it in. / I feel it move across my skin. / I'm reaching up and + reaching out. / I'm reaching for the random or whatever will bewilder me. / + Whatever will bewilder me. /And following our will and wind we may just go + where no one's been. / We'll ride the spiral to the end and may just go + where no one's been. + + Spiral out. Keep going... """ pass From b366ef039cf2d9cafaaeed063d44ebef2d7f801c Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 09:11:09 -0500 Subject: [PATCH 40/61] improved presentation of style guide --- docs/dev/contributing.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index 302d1bd6..fb6eb874 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -138,12 +138,13 @@ Docstrings are to follow the following syntaxes:: :: def fibonacci_spiral_tool(): - """With my feet upon the ground I lose myself / between the sounds and open - wide to suck it in. / I feel it move across my skin. / I'm reaching up and - reaching out. / I'm reaching for the random or whatever will bewilder me. / - Whatever will bewilder me. /And following our will and wind we may just go - where no one's been. / We'll ride the spiral to the end and may just go - where no one's been. + """With my feet upon the ground I lose myself / between the sounds + and open wide to suck it in. / I feel it move across my skin. / I'm + reaching up and reaching out. / I'm reaching for the random or + whatever will bewilder me. / Whatever will bewilder me. / And + following our will and wind we may just go where no one's been. / + We'll ride the spiral to the end and may just go where no one's + been. Spiral out. Keep going... """ From 75096a167cd6c3293223995d9207ceb96f254fd6 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 19 Feb 2016 09:26:21 -0500 Subject: [PATCH 41/61] transcendental meditation --- docs/dev/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst index fb6eb874..4b98a945 100644 --- a/docs/dev/contributing.rst +++ b/docs/dev/contributing.rst @@ -108,8 +108,8 @@ asking for help. Please also check the :ref:`early-feedback` section. -Kenneth Reitz's Code Style -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Kenneth Reitz's Code Style™ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Requests codebase uses the `PEP8`_ code style. From 41c26ce1f54278954575df015d861b4dd5cb8894 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 21 Feb 2016 20:32:36 -0500 Subject: [PATCH 42/61] improvements to index --- docs/index.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index cc4d4510..5eb643e1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,8 +38,8 @@ URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling are 100% automatic, powered by `urllib3 `_, which is embedded within Requests. -Testimonials ------------- +User Testimonials +----------------- Her Majesty's Government, Amazon, Google, Twilio, Runscope, Mozilla, Heroku, PayPal, NPR, Obama for America, Transifex, Native Instruments, The Washington @@ -65,8 +65,8 @@ Institutions that prefer to be unnamed claim to use Requests internally. Requests is one of the most downloaded Python packages of all time, pulling in over 7,000,000 downloads every month. All the cool kids are doing it! -Feature Support ---------------- +Supported Features +------------------ Requests is ready for today's web. @@ -90,8 +90,8 @@ Requests is ready for today's web. Requests supports Python 2.6 — 3.5, and runs great on PyPy. -User Guide ----------- +The User Guide +-------------- This part of the documentation, which is mostly prose, begins with some background information about Requests, then focuses on step-by-step @@ -107,8 +107,8 @@ instructions for getting the most out of Requests. user/authentication -Community Guide ------------------ +The Community Guide +------------------- This part of the documentation, which is mostly prose, details the Requests ecosystem and community. @@ -124,10 +124,10 @@ Requests ecosystem and community. community/updates community/release-process -API Documentation / Guide -------------------------- +The API Documentation / Guide +----------------------------- -If you are looking for information on a specific function, class or method, +If you are looking for information on a specific function, class, or method, this part of the documentation is for you. .. toctree:: @@ -136,8 +136,8 @@ this part of the documentation is for you. api -Contributor Guide ------------------ +The Contributor Guide +--------------------- If you want to contribute to the project, this part of the documentation is for you. From 5f06b8196e8a652101b32fdffcd0d10e8b961fd2 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 21 Feb 2016 20:32:42 -0500 Subject: [PATCH 43/61] updated sidebars --- docs/_templates/sidebarintro.html | 15 ++++++++++++++- docs/_templates/sidebarlogo.html | 16 ++++++++++++++-- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index 38661e00..69ef6685 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -14,7 +14,7 @@ human beings.

-

Stay Informed

+

Get Updates

Receive updates on new releases and upcoming projects.

-

\ No newline at end of file +

+ +

Other Projects

+ +

MoreKenneth Reitz projects:

+ \ No newline at end of file From e47e80b92f354efe5db7049b40f9cadc4ea7566e Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 21 Feb 2016 20:34:15 -0500 Subject: [PATCH 44/61] &bsp; --- docs/_templates/sidebarlogo.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html index c05ab3e7..7bcd4735 100644 --- a/docs/_templates/sidebarlogo.html +++ b/docs/_templates/sidebarlogo.html @@ -26,7 +26,7 @@

Other Projects

-

MoreKenneth Reitz projects:

+

More Kenneth Reitz projects:

  • pep8.org
  • The Python Guide
    • From f2ec732ce8bd339187cc01f3c5290d4fc19ed0d1 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 21 Feb 2016 20:45:45 -0500 Subject: [PATCH 45/61] stay informed --- docs/_templates/sidebarintro.html | 2 +- docs/_templates/sidebarlogo.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index 69ef6685..3fa77a1d 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -14,7 +14,7 @@ human beings.

    -

    Get Updates

    +

    Stay Informed

    Receive updates on new releases and upcoming projects.