From 542fbbc67fd07819551012295ff5468eb2714f62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ville=20Skytt=C3=A4?= Date: Tue, 9 Aug 2016 13:32:56 +0300 Subject: [PATCH] Document bunch of return types --- requests/adapters.py | 6 ++++ requests/auth.py | 9 +++++- requests/cookies.py | 10 ++++++- requests/sessions.py | 34 ++++++++++++++++++++--- requests/utils.py | 65 ++++++++++++++++++++++++++++++++++++++++---- 5 files changed, 113 insertions(+), 11 deletions(-) diff --git a/requests/adapters.py b/requests/adapters.py index 75c7901e..4a4c4e0e 100644 --- a/requests/adapters.py +++ b/requests/adapters.py @@ -168,6 +168,7 @@ class HTTPAdapter(BaseAdapter): :param proxy: The proxy to return a urllib3 ProxyManager for. :param proxy_kwargs: Extra keyword arguments used to configure the Proxy Manager. :returns: ProxyManager + :rtype: requests.packages.urllib3.ProxyManager """ if proxy in self.proxy_manager: manager = self.proxy_manager[proxy] @@ -244,6 +245,7 @@ class HTTPAdapter(BaseAdapter): :param req: The :class:`PreparedRequest ` used to generate the response. :param resp: The urllib3 response object. + :rtype: requests.Response """ response = Response() @@ -279,6 +281,7 @@ class HTTPAdapter(BaseAdapter): :param url: The URL to connect to. :param proxies: (optional) A Requests-style dictionary of proxies used on this request. + :rtype: requests.packages.urllib3.ConnectionPool """ proxy = select_proxy(url, proxies) @@ -316,6 +319,7 @@ class HTTPAdapter(BaseAdapter): :param request: The :class:`PreparedRequest ` being sent. :param proxies: A dictionary of schemes or schemes and hosts to proxy URLs. + :rtype: str """ proxy = select_proxy(request.url, proxies) scheme = urlparse(request.url).scheme @@ -357,6 +361,7 @@ class HTTPAdapter(BaseAdapter): :class:`HTTPAdapter `. :param proxies: The url of the proxy being used for this request. + :rtype: dict """ headers = {} username, password = get_auth_from_url(proxy) @@ -379,6 +384,7 @@ class HTTPAdapter(BaseAdapter): :param verify: (optional) Whether to verify SSL certificates. :param cert: (optional) Any user-provided SSL certificate to be trusted. :param proxies: (optional) The proxies dictionary to apply to the request. + :rtype: requests.Response """ conn = self.get_connection(request.url, proxies) diff --git a/requests/auth.py b/requests/auth.py index 4f09b911..49bcb24a 100644 --- a/requests/auth.py +++ b/requests/auth.py @@ -90,6 +90,9 @@ class HTTPDigestAuth(AuthBase): self._thread_local.num_401_calls = None def build_digest_header(self, method, url): + """ + :rtype: str + """ realm = self._thread_local.chal['realm'] nonce = self._thread_local.chal['nonce'] @@ -182,7 +185,11 @@ class HTTPDigestAuth(AuthBase): self._thread_local.num_401_calls = 1 def handle_401(self, r, **kwargs): - """Takes the given response and tries digest-auth, if needed.""" + """ + Takes the given response and tries digest-auth, if needed. + + :rtype: requests.Response + """ if self._thread_local.pos is not None: # Rewind the file position indicator of the body to where diff --git a/requests/cookies.py b/requests/cookies.py index a133684a..41a2fde1 100644 --- a/requests/cookies.py +++ b/requests/cookies.py @@ -134,7 +134,11 @@ def extract_cookies_to_jar(jar, request, response): def get_cookie_header(jar, request): - """Produce an appropriate Cookie header string to be sent with `request`, or None.""" + """ + Produce an appropriate Cookie header string to be sent with `request`, or None. + + :rtype: str + """ r = MockRequest(request) jar.add_cookie_header(r) return r.get_new_headers().get('Cookie') @@ -283,6 +287,8 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping): def multiple_domains(self): """Returns True if there are multiple domains in the jar. Returns False otherwise. + + :rtype: bool """ domains = [] for cookie in iter(self): @@ -295,6 +301,8 @@ class RequestsCookieJar(cookielib.CookieJar, collections.MutableMapping): """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. + + :rtype: dict """ dictionary = {} for cookie in iter(self): diff --git a/requests/sessions.py b/requests/sessions.py index d8b11fad..8d8d9105 100644 --- a/requests/sessions.py +++ b/requests/sessions.py @@ -214,6 +214,8 @@ class SessionRedirectMixin(object): This method also replaces the Proxy-Authorization header where necessary. + + :rtype: dict """ headers = prepared_request.headers url = prepared_request.url @@ -360,6 +362,7 @@ class Session(SessionRedirectMixin): :param request: :class:`Request` instance to prepare with this session's settings. + :rtype: requests.PreparedRequest """ cookies = request.cookies or {} @@ -477,6 +480,7 @@ class Session(SessionRedirectMixin): :param url: URL for the new :class:`Request` object. :param \*\*kwargs: Optional arguments that ``request`` takes. + :rtype: requests.Response """ kwargs.setdefault('allow_redirects', True) @@ -487,6 +491,7 @@ class Session(SessionRedirectMixin): :param url: URL for the new :class:`Request` object. :param \*\*kwargs: Optional arguments that ``request`` takes. + :rtype: requests.Response """ kwargs.setdefault('allow_redirects', True) @@ -497,6 +502,7 @@ class Session(SessionRedirectMixin): :param url: URL for the new :class:`Request` object. :param \*\*kwargs: Optional arguments that ``request`` takes. + :rtype: requests.Response """ kwargs.setdefault('allow_redirects', False) @@ -509,6 +515,7 @@ class Session(SessionRedirectMixin): :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`. :param json: (optional) json to send in the body of the :class:`Request`. :param \*\*kwargs: Optional arguments that ``request`` takes. + :rtype: requests.Response """ return self.request('POST', url, data=data, json=json, **kwargs) @@ -519,6 +526,7 @@ class Session(SessionRedirectMixin): :param url: URL for the new :class:`Request` object. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`. :param \*\*kwargs: Optional arguments that ``request`` takes. + :rtype: requests.Response """ return self.request('PUT', url, data=data, **kwargs) @@ -529,6 +537,7 @@ class Session(SessionRedirectMixin): :param url: URL for the new :class:`Request` object. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`. :param \*\*kwargs: Optional arguments that ``request`` takes. + :rtype: requests.Response """ return self.request('PATCH', url, data=data, **kwargs) @@ -538,12 +547,17 @@ class Session(SessionRedirectMixin): :param url: URL for the new :class:`Request` object. :param \*\*kwargs: Optional arguments that ``request`` takes. + :rtype: requests.Response """ return self.request('DELETE', url, **kwargs) def send(self, request, **kwargs): - """Send a given PreparedRequest.""" + """ + Send a given PreparedRequest. + + :rtype: requests.Response + """ # Set defaults that the hooks can utilize to ensure they always have # the correct parameters to reproduce the previous request. kwargs.setdefault('stream', self.stream) @@ -615,7 +629,11 @@ class Session(SessionRedirectMixin): return r def merge_environment_settings(self, url, proxies, stream, verify, cert): - """Check the environment and merge it with some settings.""" + """ + Check the environment and merge it with some settings. + + :rtype: dict + """ # Gather clues from the surrounding environment. if self.trust_env: # Set environment's proxies. @@ -639,7 +657,11 @@ class Session(SessionRedirectMixin): 'cert': cert} def get_adapter(self, url): - """Returns the appropriate connection adapter for the given URL.""" + """ + Returns the appropriate connection adapter for the given URL. + + :rtype: requests.adapters.BaseAdapter + """ for (prefix, adapter) in self.adapters.items(): if url.lower().startswith(prefix): @@ -680,6 +702,10 @@ class Session(SessionRedirectMixin): def session(): - """Returns a :class:`Session` for context-management.""" + """ + Returns a :class:`Session` for context-management. + + :rtype: Session + """ return Session() diff --git a/requests/utils.py b/requests/utils.py index 1c2a1648..e37b9109 100644 --- a/requests/utils.py +++ b/requests/utils.py @@ -164,6 +164,8 @@ def from_key_val_list(value): ValueError: need more than 1 value to unpack >>> from_key_val_list({'key': 'val'}) OrderedDict([('key', 'val')]) + + :rtype: OrderedDict """ if value is None: return None @@ -186,6 +188,8 @@ def to_key_val_list(value): [('key', 'val')] >>> to_key_val_list('string') ValueError: cannot encode objects that are not 2-tuples. + + :rtype: list """ if value is None: return None @@ -221,6 +225,7 @@ def parse_list_header(value): :param value: a string with a list header. :return: :class:`list` + :rtype: list """ result = [] for item in _parse_list_header(value): @@ -251,6 +256,7 @@ def parse_dict_header(value): :param value: a string with a dict header. :return: :class:`dict` + :rtype: dict """ result = {} for item in _parse_list_header(value): @@ -271,6 +277,7 @@ def unquote_header_value(value, is_filename=False): using for quoting. :param value: the header value to unquote. + :rtype: str """ if value and value[0] == value[-1] == '"': # this is not the real unquoting, but fixing this so that the @@ -293,6 +300,7 @@ def dict_from_cookiejar(cj): """Returns a key/value dictionary from a CookieJar. :param cj: CookieJar object to extract cookies from. + :rtype: dict """ cookie_dict = {} @@ -308,6 +316,7 @@ def add_dict_to_cookiejar(cj, cookie_dict): :param cj: CookieJar to insert cookies into. :param cookie_dict: Dict of key/values to insert into CookieJar. + :rtype: CookieJar """ cj2 = cookiejar_from_dict(cookie_dict) @@ -339,6 +348,7 @@ def get_encoding_from_headers(headers): """Returns encodings from given HTTP Header Dict. :param headers: dictionary to extract encoding from. + :rtype: str """ content_type = headers.get('content-type') @@ -399,6 +409,8 @@ def get_unicode_from_response(r): 1. charset from content-type 2. fall back and replace all unicode characters + + :rtype: str """ warnings.warn(( 'In requests 3.0, get_unicode_from_response will be removed. For ' @@ -433,6 +445,8 @@ UNRESERVED_SET = frozenset( def unquote_unreserved(uri): """Un-escape any percent-escape sequences in a URI that are unreserved characters. This leaves all reserved, illegal and non-ASCII bytes encoded. + + :rtype: str """ parts = uri.split('%') for i in range(1, len(parts)): @@ -457,6 +471,8 @@ def requote_uri(uri): This function passes the given URI through an unquote/quote cycle to ensure that it is fully and consistently quoted. + + :rtype: str """ safe_with_percent = "!#$%&'()*+,/:;=?@[]~" safe_without_percent = "!#$&'()*+,/:;=?@[]~" @@ -477,6 +493,8 @@ def address_in_network(ip, net): 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 + + :rtype: bool """ ipaddr = struct.unpack('=L', socket.inet_aton(ip))[0] netaddr, bits = net.split('/') @@ -489,12 +507,17 @@ def dotted_netmask(mask): """Converts mask from /xx format to xxx.xxx.xxx.xxx Example: if mask is 24 function returns 255.255.255.0 + + :rtype: str """ bits = 0xffffffff ^ (1 << 32 - mask) - 1 return socket.inet_ntoa(struct.pack('>I', bits)) def is_ipv4_address(string_ip): + """ + :rtype: bool + """ try: socket.inet_aton(string_ip) except socket.error: @@ -503,7 +526,11 @@ def is_ipv4_address(string_ip): def is_valid_cidr(string_network): - """Very simple check of the cidr format in no_proxy variable""" + """ + Very simple check of the cidr format in no_proxy variable. + + :rtype: bool + """ if string_network.count('/') == 1: try: mask = int(string_network.split('/')[1]) @@ -523,7 +550,11 @@ 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. + + :rtype: bool + """ 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 @@ -573,7 +604,11 @@ def should_bypass_proxies(url): def get_environ_proxies(url): - """Return a dict of environment proxies.""" + """ + Return a dict of environment proxies. + + :rtype: dict + """ if should_bypass_proxies(url): return {} else: @@ -607,11 +642,18 @@ def select_proxy(url, proxies): def default_user_agent(name="python-requests"): - """Return a string representing the default user agent.""" + """ + Return a string representing the default user agent. + + :rtype: str + """ return '%s/%s' % (name, __version__) def default_headers(): + """ + :rtype: requests.structures.CaseInsensitiveDict + """ return CaseInsensitiveDict({ 'User-Agent': default_user_agent(), 'Accept-Encoding': ', '.join(('gzip', 'deflate')), @@ -624,6 +666,8 @@ def parse_header_links(value): """Return a dict of parsed link headers proxies. i.e. Link: ; rel=front; type="image/jpeg",; rel=back;type="image/jpeg" + + :rtype: list """ links = [] @@ -658,6 +702,9 @@ _null3 = _null * 3 def guess_json_utf(data): + """ + :rtype: str + """ # JSON always starts with two ASCII characters, so detection is as # easy as counting the nulls and from their location and count # determine the encoding. Also detect a BOM, if present. @@ -689,6 +736,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. + + :rtype: str """ scheme, netloc, path, params, query, fragment = urlparse(url, new_scheme) @@ -704,6 +753,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. + + :rtype: (str,str) """ parsed = urlparse(url) @@ -757,7 +808,11 @@ 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. + + :rtype: str + """ scheme, netloc, path, params, query, fragment = urlparse(url) # see func:`prepend_scheme_if_needed`