kennethreitz/requests
1
0
Fork 0
mirror of https://github.com/kennethreitz/requests.git synced 2026-06-05 22:50:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3429 from nateprewitt/docstring_cleanup

Browse Source 
Docstring cleanup
This commit is contained in:
Kenneth Reitz
2016-07-20 18:38:38 -04:00
committed by GitHub
parent 4285bac3fd b7809acb47
commit fb01456061
22 changed files with 130 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
requests/__init__.py
-1
View File
@@ -38,7 +38,6 @@ is at <http://python-requests.org>.
:copyright: (c) 2016 by Kenneth Reitz.
:license: Apache 2.0, see LICENSE for more details.
"""
__title__ = 'requests'
requests/api.py
-1
View File
@@ -8,7 +8,6 @@ This module implements the Requests API.
:copyright: (c) 2012 by Kenneth Reitz.
:license: Apache2, see LICENSE for more details.
"""
from . import sessions
requests/certs.py
+2 -2
View File
@@ -2,8 +2,8 @@
# -*- coding: utf-8 -*-
"""
certs.py
~~~~~~~~
requests.certs
~~~~~~~~~~~~~~
This module returns the preferred default CA certificate bundle.
requests/compat.py
+5 -1
View File
@@ -1,7 +1,11 @@
# -*- coding: utf-8 -*-
"""
pythoncompat
requests.compat
~~~~~~~~~~~~~~~
This module handles import compatibility issues between Python 2 and
Python 3.
"""
from .packages import chardet
requests/cookies.py
+65 -27
View File
@@ -1,6 +1,9 @@
# -*- coding: utf-8 -*-
"""
requests.cookies
~~~~~~~~~~~~~~~~
Compatibility code to be able to use `cookielib.CookieJar` with requests.
requests.utils imports from here, so be careful with imports.
@@ -158,7 +161,8 @@ def remove_cookie_by_name(cookiejar, name, domain=None, path=None):
class CookieConflictError(RuntimeError):
"""There are two cookies that meet the criteria specified in the cookie jar.
Use .get and .set and include domain and path args in order to be more specific."""
Use .get and .set and include domain and path args in order to be more specific.
"""
class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping):
@@ -184,7 +188,8 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping):
order to resolve naming collisions from using one cookie jar over
multiple domains.
.. warning:: operation is O(n), not O(1)."""
.. warning:: operation is O(n), not O(1).
"""
try:
return self._find_no_duplicates(name, domain, path)
except KeyError:
@@ -193,7 +198,8 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping):
def set(self, name, value, **kwargs):
"""Dict-like set() that also supports optional domain and path args in
order to resolve naming collisions from using one cookie jar over
multiple domains."""
multiple domains.
"""
# support client code that unsets cookies by assignment of a None value:
if value is None:
remove_cookie_by_name(self, name, domain=kwargs.get('domain'), path=kwargs.get('path'))
@@ -208,37 +214,54 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping):
def iterkeys(self):
"""Dict-like iterkeys() that returns an iterator of names of cookies
from the jar. See itervalues() and iteritems()."""
from the jar.
.. seealso:: itervalues() and iteritems().
"""
for cookie in iter(self):
yield cookie.name
def keys(self):
"""Dict-like keys() that returns a list of names of cookies from the
jar. See values() and items()."""
jar.
.. seealso:: values() and items().
"""
return list(self.iterkeys())
def itervalues(self):
"""Dict-like itervalues() that returns an iterator of values of cookies
from the jar. See iterkeys() and iteritems()."""
from the jar.
.. seealso:: iterkeys() and iteritems().
"""
for cookie in iter(self):
yield cookie.value
def values(self):
"""Dict-like values() that returns a list of values of cookies from the
jar. See keys() and items()."""
jar.
.. seealso:: keys() and items().
"""
return list(self.itervalues())
def iteritems(self):
"""Dict-like iteritems() that returns an iterator of name-value tuples
from the jar. See iterkeys() and itervalues()."""
from the jar.
.. seealso:: iterkeys() and itervalues().
"""
for cookie in iter(self):
yield cookie.name, cookie.value
def items(self):
"""Dict-like items() that returns a list of name-value tuples from the
jar. See keys() and values(). Allows client-code to call
``dict(RequestsCookieJar)`` and get a vanilla python dict of key value
pairs."""
jar. Allows client-code to call ``dict(RequestsCookieJar)`` and get a
vanilla python dict of key value pairs.
.. seealso:: keys() and values().
"""
return list(self.iteritems())
def list_domains(self):
@@ -259,7 +282,8 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping):
def multiple_domains(self):
"""Returns True if there are multiple domains in the jar.
Returns False otherwise."""
Returns False otherwise.
"""
domains = []
for cookie in iter(self):
if cookie.domain is not None and cookie.domain in domains:
@@ -270,7 +294,8 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping):
def get_dict(self, domain=None, path=None):
"""Takes as an argument an optional domain and path and returns a plain
old Python dict of name-value pairs of cookies that meet the
requirements."""
requirements.
"""
dictionary = {}
for cookie in iter(self):
if (domain is None or cookie.domain == domain) and (path is None
@@ -289,20 +314,21 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping):
exception if there are more than one cookie with name. In that case,
use the more explicit get() method instead.
.. warning:: operation is O(n), not O(1)."""
.. warning:: operation is O(n), not O(1).
"""
return self._find_no_duplicates(name)
def __setitem__(self, name, value):
"""Dict-like __setitem__ for compatibility with client code. Throws
exception if there is already a cookie of that name in the jar. In that
case, use the more explicit set() method instead."""
case, use the more explicit set() method instead.
"""
self.set(name, value)
def __delitem__(self, name):
"""Deletes a cookie given a name. Wraps ``cookielib.CookieJar``'s
``remove_cookie_by_name()``."""
``remove_cookie_by_name()``.
"""
remove_cookie_by_name(self, name)
def set_cookie(self, cookie, *args, **kwargs):
@@ -319,11 +345,17 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping):
super(RequestsCookieJar, self).update(other)
def _find(self, name, domain=None, path=None):
"""Requests uses this method internally to get cookie values. Takes as
args name and optional domain and path. Returns a cookie.value. If
there are conflicting cookies, _find arbitrarily chooses one. See
_find_no_duplicates if you want an exception thrown if there are
conflicting cookies."""
"""Requests uses this method internally to get cookie values.
If there are conflicting cookies, _find arbitrarily chooses one.
See _find_no_duplicates if you want an exception thrown if there are
conflicting cookies.
:param name: a string containing name of cookie
:param domain: (optional) string containing domain of cookie
:param path: (optional) string containing path of cookie
:return: cookie.value
"""
for cookie in iter(self):
if cookie.name == name:
if domain is None or cookie.domain == domain:
@@ -334,10 +366,16 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping):
def _find_no_duplicates(self, name, domain=None, path=None):
"""Both ``__get_item__`` and ``get`` call this function: it's never
used elsewhere in Requests. Takes as args name and optional domain and
path. Returns a cookie.value. Throws KeyError if cookie is not found
and CookieConflictError if there are multiple cookies that match name
and optionally domain and path."""
used elsewhere in Requests.
:param name: a string containing name of cookie
:param domain: (optional) string containing domain of cookie
:param path: (optional) string containing path of cookie
:raises KeyError: if cookie is not found
:raises CookieConflictError: if there are multiple cookies
that match name and optionally domain and path
:return: cookie.value
"""
toReturn = None
for cookie in iter(self):
if cookie.name == name:
requests/exceptions.py
+4 -8
View File
@@ -5,19 +5,17 @@ requests.exceptions
~~~~~~~~~~~~~~~~~~~
This module contains the set of Requests' exceptions.
"""
from .packages.urllib3.exceptions import HTTPError as BaseHTTPError
class RequestException(IOError):
"""There was an ambiguous exception that occurred while handling your
request."""
request.
"""
def __init__(self, *args, **kwargs):
"""
Initialize RequestException with `request` and `response` objects.
"""
"""Initialize RequestException with `request` and `response` objects."""
response = kwargs.pop('response', None)
self.response = response
self.request = kwargs.pop('request', None)
@@ -112,7 +110,5 @@ class RequestsWarning(Warning):
class FileModeWarning(RequestsWarning, DeprecationWarning):
"""
A file was opened in text mode, but Requests determined its binary length.
"""
"""A file was opened in text mode, but Requests determined its binary length."""
pass
requests/hooks.py
-1
View File
@@ -10,7 +10,6 @@ Available hooks:
``response``:
The response generated from a Request.
"""
HOOKS = ['response']
requests/models.py
+2 -5
View File
@@ -108,7 +108,6 @@ class RequestEncodingMixin(object):
if parameters are supplied as a dict.
The tuples may be 2-tuples (filename, fileobj), 3-tuples (filename, fileobj, contentype)
or 4-tuples (filename, fileobj, contentype, custom_headers).
"""
if (not files):
raise ValueError("Files must be provided.")
@@ -207,7 +206,6 @@ class Request(RequestHooksMixin):
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> req.prepare()
<PreparedRequest [GET]>
"""
def __init__(self, method=None, url=None, headers=None, files=None,
@@ -271,7 +269,6 @@ class PreparedRequest(RequestEncodingMixin, RequestHooksMixin):
>>> s = requests.Session()
>>> s.send(r)
<Response [200]>
"""
def __init__(self):
@@ -517,8 +514,8 @@ class PreparedRequest(RequestEncodingMixin, RequestHooksMixin):
can only be called once for the life of the
:class:`PreparedRequest <PreparedRequest>` object. Any subsequent calls
to ``prepare_cookies`` will have no actual effect, unless the "Cookie"
header is removed beforehand."""
header is removed beforehand.
"""
if isinstance(cookies, cookielib.CookieJar):
self._cookies = cookies
else:
requests/sessions.py
+7 -12
View File
@@ -6,7 +6,6 @@ requests.session
This module provides a Session object to manage and persist settings across
requests (cookies, auth, proxies).
"""
import os
from collections import Mapping
@@ -40,9 +39,8 @@ REDIRECT_CACHE_SIZE = 1000
def merge_setting(request_setting, session_setting, dict_class=OrderedDict):
"""
Determines appropriate setting for a given request, taking into account the
explicit setting on that request, and the setting in the session. If a
"""Determines appropriate setting for a given request, taking into account
the explicit setting on that request, and the setting in the session. If a
setting is a dictionary, they will be merged together using `dict_class`
"""
@@ -72,8 +70,7 @@ def merge_setting(request_setting, session_setting, dict_class=OrderedDict):
def merge_hooks(request_hooks, session_hooks, dict_class=OrderedDict):
"""
Properly merges both requests and session hooks.
"""Properly merges both requests and session hooks.
This is necessary because when request_hooks == {'response': []}, the
merge breaks Session hooks entirely.
@@ -185,8 +182,7 @@ class SessionRedirectMixin(object):
yield resp
def rebuild_auth(self, prepared_request, response):
"""
When being redirected we may want to strip authentication from the
"""When being redirected we may want to strip authentication from the
request to avoid leaking credentials. This method intelligently removes
and reapplies authentication where possible to avoid credential loss.
"""
@@ -210,8 +206,7 @@ class SessionRedirectMixin(object):
return
def rebuild_proxies(self, prepared_request, proxies):
"""
This method re-evaluates the proxy configuration by considering the
"""This method re-evaluates the proxy configuration by considering the
environment variables. If we are redirected to a URL covered by
NO_PROXY, we strip the proxy configuration. Otherwise, we set missing
proxy keys for this URL (in case they were stripped by a previous
@@ -661,8 +656,8 @@ class Session(SessionRedirectMixin):
def mount(self, prefix, adapter):
"""Registers a connection adapter to a prefix.
Adapters are sorted in descending order by key length."""
Adapters are sorted in descending order by key length.
"""
self.adapters[prefix] = adapter
keys_to_move = [k for k in self.adapters if len(k) < len(prefix)]
requests/structures.py
+1 -4
View File
@@ -5,7 +5,6 @@ requests.structures
~~~~~~~~~~~~~~~~~~~
Data structures that power Requests.
"""
import collections
@@ -14,8 +13,7 @@ from .compat import OrderedDict
class CaseInsensitiveDict(collections.MutableMapping):
"""
A case-insensitive ``dict``-like object.
"""A case-insensitive ``dict``-like object.
Implements all methods and operations of
``collections.MutableMapping`` as well as dict's ``copy``. Also
@@ -39,7 +37,6 @@ class CaseInsensitiveDict(collections.MutableMapping):
If the constructor, ``.update``, or equality comparison
operations are given keys that have equal ``.lower()``s, the
behavior is undefined.
"""
def __init__(self, data=None, **kwargs):
requests/utils.py
+14 -20
View File
@@ -6,7 +6,6 @@ requests.utils
This module provides utility functions that are used within Requests
that are also useful for external consumption.
"""
import cgi
@@ -400,7 +399,6 @@ def get_unicode_from_response(r):
1. charset from content-type
2. fall back and replace all unicode characters
"""
warnings.warn((
'In requests 3.0, get_unicode_from_response will be removed. For '
@@ -475,8 +473,8 @@ def requote_uri(uri):
def address_in_network(ip, net):
"""
This function allows you to check if on IP belongs to a network subnet
"""This function allows you to check if on IP belongs to a network subnet
Example: returns True if ip = 192.168.1.1 and net = 192.168.1.0/24
returns False if ip = 192.168.1.1 and net = 192.168.100.0/24
"""
@@ -488,8 +486,8 @@ def address_in_network(ip, net):
def dotted_netmask(mask):
"""
Converts mask from /xx format to xxx.xxx.xxx.xxx
"""Converts mask from /xx format to xxx.xxx.xxx.xxx
Example: if mask is 24 function returns 255.255.255.0
"""
bits = 0xffffffff ^ (1 << 32 - mask) - 1
@@ -525,9 +523,7 @@ def is_valid_cidr(string_network):
def should_bypass_proxies(url):
"""
Returns whether we should bypass proxies or not.
"""
"""Returns whether we should bypass proxies or not."""
get_proxy = lambda k: os.environ.get(k) or os.environ.get(k.upper())
# First check whether no_proxy is defined. If it is, check that the URL
@@ -628,7 +624,6 @@ def parse_header_links(value):
"""Return a dict of parsed link headers proxies.
i.e. Link: <http:/.../front.jpeg>; rel=front; type="image/jpeg",<http://.../back.jpeg>; rel=back;type="image/jpeg"
"""
links = []
@@ -693,7 +688,8 @@ def guess_json_utf(data):
def prepend_scheme_if_needed(url, new_scheme):
"""Given a URL that may or may not have a scheme, prepend the given scheme.
Does not replace a present scheme with the one provided as an argument."""
Does not replace a present scheme with the one provided as an argument.
"""
scheme, netloc, path, params, query, fragment = urlparse(url, new_scheme)
# urlparse is a finicky beast, and sometimes decides that there isn't a
@@ -707,7 +703,8 @@ def prepend_scheme_if_needed(url, new_scheme):
def get_auth_from_url(url):
"""Given a url with authentication components, extract them into a tuple of
username,password."""
username,password.
"""
parsed = urlparse(url)
try:
@@ -719,10 +716,9 @@ def get_auth_from_url(url):
def to_native_string(string, encoding='ascii'):
"""
Given a string object, regardless of type, returns a representation of that
string in the native string type, encoding and decoding where necessary.
This assumes ASCII unless told otherwise.
"""Given a string object, regardless of type, returns a representation of
that string in the native string type, encoding and decoding where
necessary. This assumes ASCII unless told otherwise.
"""
if isinstance(string, builtin_str):
out = string
@@ -740,7 +736,7 @@ _CLEAN_HEADER_REGEX_BYTE = re.compile(b'^\\S[^\\r\\n]*$|^$')
_CLEAN_HEADER_REGEX_STR = re.compile(r'^\S[^\r\n]*$|^$')
def check_header_validity(header):
"""Verifies that header value is a string which doesn't contain
"""Verifies that header value is a string which doesn't contain
leading whitespace or return characters. This prevents unintended
header injection.
@@ -761,9 +757,7 @@ def check_header_validity(header):
def urldefragauth(url):
"""
Given a url remove the fragment and the authentication part
"""
"""Given a url remove the fragment and the authentication part"""
scheme, netloc, path, params, query, fragment = urlparse(url)
# see func:`prepend_scheme_if_needed`
tests/__init__.py
+1 -1
View File
@@ -1,4 +1,4 @@
# coding: utf-8
# -*- coding: utf-8 -*-
"""Requests test package initialisation."""
tests/compat.py
+2 -1
View File
@@ -1,4 +1,5 @@
# coding: utf-8
# -*- coding: utf-8 -*-
from requests.compat import is_py3
tests/conftest.py
+2 -1
View File
@@ -1,4 +1,5 @@
# coding: utf-8
# -*- coding: utf-8 -*-
import pytest
from requests.compat import urljoin
tests/test_hooks.py
+2 -1
View File
@@ -1,4 +1,5 @@
# coding: utf-8
# -*- coding: utf-8 -*-
import pytest
from requests import hooks
tests/test_lowlevel.py
+2
View File
@@ -1,3 +1,5 @@
# -*- coding: utf-8 -*-
import os
import pytest
import threading
tests/test_requests.py
+3 -6
View File
@@ -955,8 +955,7 @@ class TestRequests:
io.close()
def test_response_decode_unicode(self):
"""
When called with decode_unicode, Response.iter_content should always
"""When called with decode_unicode, Response.iter_content should always
return unicode.
"""
r = requests.Response()
@@ -1047,9 +1046,7 @@ class TestRequests:
assert r.status_code == 200
def test_fixes_1329(self, httpbin):
"""
Ensure that header updates are done case-insensitively.
"""
"""Ensure that header updates are done case-insensitively."""
s = requests.Session()
s.headers.update({'ACCEPT': 'BOGUS'})
s.headers.update({'accept': 'application/json'})
@@ -1578,7 +1575,7 @@ class TestTimeout:
assert error_text in str(e)
def test_none_timeout(self, httpbin):
""" Check that you can set None as a valid timeout value.
"""Check that you can set None as a valid timeout value.
To actually test this behavior, we'd want to check that setting the
timeout to None actually lets the request block past the system default
tests/test_structures.py
+4 -7
View File
@@ -1,4 +1,5 @@
# coding: utf-8
# -*- coding: utf-8 -*-
import pytest
from requests.structures import CaseInsensitiveDict, LookupDict
@@ -8,9 +9,7 @@ class TestCaseInsensitiveDict:
@pytest.fixture(autouse=True)
def setup(self):
"""
CaseInsensitiveDict instance with "Accept" header.
"""
"""CaseInsensitiveDict instance with "Accept" header."""
self.case_insensitive_dict = CaseInsensitiveDict()
self.case_insensitive_dict['Accept'] = 'application/json'
@@ -54,9 +53,7 @@ class TestLookupDict:
@pytest.fixture(autouse=True)
def setup(self):
"""
LookupDict instance with "bad_gateway" attribute.
"""
"""LookupDict instance with "bad_gateway" attribute."""
self.lookup_dict = LookupDict('test')
self.lookup_dict.bad_gateway = 502
tests/test_testserver.py
+2
View File
@@ -1,3 +1,5 @@
# -*- coding: utf-8 -*-
import threading
import socket
import time
tests/test_utils.py
+8 -9
View File
@@ -1,4 +1,5 @@
# coding: utf-8
# -*- coding: utf-8 -*-
from io import BytesIO
import pytest
@@ -40,9 +41,7 @@ class TestSuperLen:
@pytest.mark.parametrize('error', [IOError, OSError])
def test_super_len_handles_files_raising_weird_errors_in_tell(self, error):
"""
If tell() raises errors, assume the cursor is at position zero.
"""
"""If tell() raises errors, assume the cursor is at position zero."""
class BoomFile(object):
def __len__(self):
return 5
@@ -104,7 +103,8 @@ class TestUnquoteHeaderValue:
class TestGetEnvironProxies:
"""Ensures that IP addresses are correctly matches with ranges
in no_proxy variable."""
in no_proxy variable.
"""
@pytest.fixture(autouse=True, params=['no_proxy', 'NO_PROXY'])
def no_proxy(self, request, monkeypatch):
@@ -288,8 +288,7 @@ def test_get_auth_from_url(url, auth):
),
))
def test_requote_uri_with_unquoted_percents(uri, expected):
"""See: https://github.com/kennethreitz/requests/issues/2356
"""
"""See: https://github.com/kennethreitz/requests/issues/2356"""
assert requote_uri(uri) == expected
@@ -460,8 +459,8 @@ def test_urldefragauth(url, expected):
('http://google.com:5000/v1.0/', False),
))
def test_should_bypass_proxies(url, expected, monkeypatch):
"""
Tests for function should_bypass_proxies to check if proxy can be bypassed or not
"""Tests for function should_bypass_proxies to check if proxy
can be bypassed or not
"""
monkeypatch.setenv('no_proxy', '192.168.0.0/24,127.0.0.1,localhost.localdomain,172.16.1.1')
monkeypatch.setenv('NO_PROXY', '192.168.0.0/24,127.0.0.1,localhost.localdomain,172.16.1.1')
tests/testserver/server.py
+2
View File
@@ -1,3 +1,5 @@
# -*- coding: utf-8 -*-
import threading
import socket
import select
tests/utils.py
+2
View File
@@ -1,3 +1,5 @@
# -*- coding: utf-8 -*-
import contextlib
import os