sessions

module requests.sessions in requests

Description

requests.sessions
~~~~~~~~~~~~~~~~~

This module provides a Session object to manage and persist settings across
requests (cookies, auth, proxies).

Classes

builtins.object
    SessionRedirectMixin
        Session

Session

class Session(SessionRedirectMixin)
 |  A Requests session.
 |  
 |  Provides cookie persistence, connection-pooling, and configuration.
 |  
 |  Basic Usage::
 |  
 |    >>> import requests
 |    >>> s = requests.Session()
 |    >>> s.get('https://httpbin.org/get')
 |    <Response [200]>
 |  
 |  Or as a context manager::
 |  
 |    >>> with requests.Session() as s:
 |    ...     s.get('https://httpbin.org/get')
 |    <Response [200]>
 |  
 |  Method resolution order:
 |      Session
 |      SessionRedirectMixin
 |      builtins.object
 |  
 |  Methods defined here:
 |  
 |

Session.__enter__

 |  
 |  __enter__(self)
 |  
 |

Session.__exit__

 |  
 |  __exit__(self, *args)
 |  
 |

Session.__getstate__

 |  
 |  __getstate__(self)
 |  
 |

Session.__init__

 |  
 |  __init__(self)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |  
 |

Session.__setstate__

 |  
 |  __setstate__(self, state)
 |  
 |

Session.close

 |  
 |  close(self)
 |      Closes all adapters and as such the session
 |  
 |

Session.delete

 |  
 |  delete(self, url, **kwargs)
 |      Sends a DELETE request. Returns :class:`Response` object.
 |      
 |      :param url: URL for the new :class:`Request` object.
 |      :param \*\*kwargs: Optional arguments that ``request`` takes.
 |      :rtype: requests.Response
 |  
 |

Session.get

 |  
 |  get(self, url, **kwargs)
 |      Sends a GET request. Returns :class:`Response` object.
 |      
 |      :param url: URL for the new :class:`Request` object.
 |      :param \*\*kwargs: Optional arguments that ``request`` takes.
 |      :rtype: requests.Response
 |  
 |

Session.get_adapter

 |  
 |  get_adapter(self, url)
 |      Returns the appropriate connection adapter for the given URL.
 |      
 |      :rtype: requests.adapters.BaseAdapter
 |  
 |

Session.head

 |  
 |  head(self, url, **kwargs)
 |      Sends a HEAD request. Returns :class:`Response` object.
 |      
 |      :param url: URL for the new :class:`Request` object.
 |      :param \*\*kwargs: Optional arguments that ``request`` takes.
 |      :rtype: requests.Response
 |  
 |

Session.merge_environment_settings

 |  
 |  merge_environment_settings(self, url, proxies, stream, verify, cert)
 |      Check the environment and merge it with some settings.
 |      
 |      :rtype: dict
 |  
 |

Session.mount

 |  
 |  mount(self, prefix, adapter)
 |      Registers a connection adapter to a prefix.
 |      
 |      Adapters are sorted in descending order by prefix length.
 |  
 |

Session.options

 |  
 |  options(self, url, **kwargs)
 |      Sends a OPTIONS request. Returns :class:`Response` object.
 |      
 |      :param url: URL for the new :class:`Request` object.
 |      :param \*\*kwargs: Optional arguments that ``request`` takes.
 |      :rtype: requests.Response
 |  
 |

Session.patch

 |  
 |  patch(self, url, data=None, **kwargs)
 |      Sends a PATCH request. Returns :class:`Response` object.
 |      
 |      :param url: URL for the new :class:`Request` object.
 |      :param data: (optional) Dictionary, list of tuples, bytes, or file-like
 |          object to send in the body of the :class:`Request`.
 |      :param \*\*kwargs: Optional arguments that ``request`` takes.
 |      :rtype: requests.Response
 |  
 |

Session.post

 |  
 |  post(self, url, data=None, json=None, **kwargs)
 |      Sends a POST request. Returns :class:`Response` object.
 |      
 |      :param url: URL for the new :class:`Request` object.
 |      :param data: (optional) Dictionary, list of tuples, 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
 |  
 |

Session.prepare_request

 |  
 |  prepare_request(self, request)
 |      Constructs a :class:`PreparedRequest <PreparedRequest>` for
 |      transmission and returns it. The :class:`PreparedRequest` has settings
 |      merged from the :class:`Request <Request>` instance and those of the
 |      :class:`Session`.
 |      
 |      :param request: :class:`Request` instance to prepare with this
 |          session's settings.
 |      :rtype: requests.PreparedRequest
 |  
 |

Session.put

 |  
 |  put(self, url, data=None, **kwargs)
 |      Sends a PUT request. Returns :class:`Response` object.
 |      
 |      :param url: URL for the new :class:`Request` object.
 |      :param data: (optional) Dictionary, list of tuples, bytes, or file-like
 |          object to send in the body of the :class:`Request`.
 |      :param \*\*kwargs: Optional arguments that ``request`` takes.
 |      :rtype: requests.Response
 |  
 |

Session.request

 |  
 |  request(self, method, url, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None)
 |      Constructs a :class:`Request <Request>`, prepares it and sends it.
 |      Returns :class:`Response <Response>` object.
 |      
 |      :param method: method for the new :class:`Request` object.
 |      :param url: URL for the new :class:`Request` object.
 |      :param params: (optional) Dictionary or bytes to be sent in the query
 |          string for the :class:`Request`.
 |      :param data: (optional) Dictionary, list of tuples, 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 headers: (optional) Dictionary of HTTP Headers to send with the
 |          :class:`Request`.
 |      :param cookies: (optional) Dict or CookieJar object to send with the
 |          :class:`Request`.
 |      :param files: (optional) Dictionary of ``'filename': file-like-objects``
 |          for multipart encoding upload.
 |      :param auth: (optional) Auth tuple or callable to enable
 |          Basic/Digest/Custom HTTP Auth.
 |      :param timeout: (optional) How long to wait for the server to send
 |          data before giving up, as a float, or a :ref:`(connect timeout,
 |          read timeout) <timeouts>` tuple.
 |      :type timeout: float or tuple
 |      :param allow_redirects: (optional) Set to True by default.
 |      :type allow_redirects: bool
 |      :param proxies: (optional) Dictionary mapping protocol or protocol and
 |          hostname to the URL of the proxy.
 |      :param stream: (optional) whether to immediately download the response
 |          content. Defaults to ``False``.
 |      :param verify: (optional) Either a boolean, in which case it controls whether we verify
 |          the server's TLS certificate, or a string, in which case it must be a path
 |          to a CA bundle to use. Defaults to ``True``. When set to
 |          ``False``, requests will accept any TLS certificate presented by
 |          the server, and will ignore hostname mismatches and/or expired
 |          certificates, which will make your application vulnerable to
 |          man-in-the-middle (MitM) attacks. Setting verify to ``False``
 |          may be useful during local development or testing.
 |      :param cert: (optional) if String, path to ssl client cert file (.pem).
 |          If Tuple, ('cert', 'key') pair.
 |      :rtype: requests.Response
 |  
 |

Session.send

 |  
 |  send(self, request, **kwargs)
 |      Send a given PreparedRequest.
 |      
 |      :rtype: requests.Response
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  __attrs__ = ['headers', 'cookies', 'auth', 'proxies', 'hooks', 'params...
 |  
 |  ----------------------------------------------------------------------
 |  Methods inherited from SessionRedirectMixin:
 |  
 |

SessionRedirectMixin.get_redirect_target

 |  
 |  get_redirect_target(self, resp)
 |      Receives a Response. Returns a redirect URI or ``None``
 |  
 |

SessionRedirectMixin.rebuild_auth

 |  
 |  rebuild_auth(self, prepared_request, response)
 |      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.
 |  
 |

SessionRedirectMixin.rebuild_method

 |  
 |  rebuild_method(self, prepared_request, response)
 |      When being redirected we may want to change the method of the request
 |      based on certain specs or browser behavior.
 |  
 |

SessionRedirectMixin.rebuild_proxies

 |  
 |  rebuild_proxies(self, prepared_request, proxies)
 |      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
 |      redirect).
 |      
 |      This method also replaces the Proxy-Authorization header where
 |      necessary.
 |      
 |      :rtype: dict
 |  
 |

SessionRedirectMixin.resolve_redirects

 |  
 |  resolve_redirects(self, resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None, yield_requests=False, **adapter_kwargs)
 |      Receives a Response. Returns a generator of Responses or Requests.
 |  
 |

SessionRedirectMixin.should_strip_auth

 |  
 |  should_strip_auth(self, old_url, new_url)
 |      Decide whether Authorization header should be removed when redirecting
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from SessionRedirectMixin:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

SessionRedirectMixin

class SessionRedirectMixin(builtins.object)
 |  Methods defined here:
 |  
 |

SessionRedirectMixin.get_redirect_target

 |  
 |  get_redirect_target(self, resp)
 |      Receives a Response. Returns a redirect URI or ``None``
 |  
 |

SessionRedirectMixin.rebuild_auth

 |  
 |  rebuild_auth(self, prepared_request, response)
 |      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.
 |  
 |

SessionRedirectMixin.rebuild_method

 |  
 |  rebuild_method(self, prepared_request, response)
 |      When being redirected we may want to change the method of the request
 |      based on certain specs or browser behavior.
 |  
 |

SessionRedirectMixin.rebuild_proxies

 |  
 |  rebuild_proxies(self, prepared_request, proxies)
 |      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
 |      redirect).
 |      
 |      This method also replaces the Proxy-Authorization header where
 |      necessary.
 |      
 |      :rtype: dict
 |  
 |

SessionRedirectMixin.resolve_redirects

 |  
 |  resolve_redirects(self, resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None, yield_requests=False, **adapter_kwargs)
 |      Receives a Response. Returns a generator of Responses or Requests.
 |  
 |

SessionRedirectMixin.should_strip_auth

 |  
 |  should_strip_auth(self, old_url, new_url)
 |      Decide whether Authorization header should be removed when redirecting
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

Functions

merge_hooks

merge_hooks(request_hooks, session_hooks, dict_class=)
    Properly merges both requests and session hooks.
    
    This is necessary because when request_hooks == {'response': []}, the
    merge breaks Session hooks entirely.

merge_setting

merge_setting(request_setting, session_setting, dict_class=)
    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`

preferred_clock

preferred_clock = time(...)
    time() -> floating point number
    
    Return the current time in seconds since the Epoch.
    Fractions of a second may be present if the system clock provides them.

session

session()
    Returns a :class:`Session` for context-management.
    
    .. deprecated:: 1.0.0
    
        This method has been deprecated since version 1.0.0 and is only kept for
        backwards compatibility. New code should use :class:`~requests.sessions.Session`
        to create a session. This may be removed at a future date.
    
    :rtype: Session