395class Session(SessionRedirectMixin):

396 """A Requests session.

397

398 Provides cookie persistence, connection-pooling, and configuration.

399

400 Basic Usage::

401

402 >>> import requests

403 >>> s = requests.Session()

404 >>> s.get('https://httpbin.org/get')

405 <Response [200]>

406

407 Or as a context manager::

408

409 >>> with requests.Session() as s:

410 ... s.get('https://httpbin.org/get')

411 <Response [200]>

412 """

413

414 headers: CaseInsensitiveDict[str]

415 auth: _t.AuthType

416 proxies: dict[str, str]

417 hooks: dict[str, list[_t.HookType]]

418 params: MutableMapping[str, Any]

419 stream: bool

420 verify: _t.VerifyType

421 cert: _t.CertType

422 max_redirects: int

423 trust_env: bool

424 cookies: RequestsCookieJar

425 adapters: MutableMapping[str, BaseAdapter]

426

427 __attrs__: list[str] = [

428 "headers",

429 "cookies",

430 "auth",

431 "proxies",

432 "hooks",

433 "params",

434 "verify",

435 "cert",

436 "adapters",

437 "stream",

438 "trust_env",

439 "max_redirects",

440 ]

441

442 def __init__(self) -> None:

443 #: A case-insensitive dictionary of headers to be sent on each

444 #: :class:`Request <Request>` sent from this

445 #: :class:`Session <Session>`.

446 self.headers = default_headers()

447

448 #: Default Authentication tuple or object to attach to

449 #: :class:`Request <Request>`.

450 self.auth = None

451

452 #: Dictionary mapping protocol or protocol and host to the URL of the proxy

453 #: (e.g. {'http': 'foo.bar:3128', 'http://host.name': 'foo.bar:4012'}) to

454 #: be used on each :class:`Request <Request>`.

455 self.proxies = {}

456

457 #: Event-handling hooks.

458 self.hooks = default_hooks()

459

460 #: Dictionary of querystring data to attach to each

461 #: :class:`Request <Request>`. The dictionary values may be lists for

462 #: representing multivalued query parameters.

463 self.params = {}

464

465 #: Stream response content default.

466 self.stream = False

467

468 #: SSL Verification default.

469 #: Defaults to `True`, requiring requests to verify the TLS certificate at the

470 #: remote end.

471 #: If verify is set to `False`, requests will accept any TLS certificate

472 #: presented by the server, and will ignore hostname mismatches and/or

473 #: expired certificates, which will make your application vulnerable to

474 #: man-in-the-middle (MitM) attacks.

475 #: Only set this to `False` for testing.

476 #: If verify is set to a string, it must be the path to a CA bundle file

477 #: that will be used to verify the TLS certificate.

478 self.verify = True

479

480 #: SSL client certificate default, if String, path to ssl client

481 #: cert file (.pem). If Tuple, ('cert', 'key') pair.

482 self.cert = None

483

484 #: Maximum number of redirects allowed. If the request exceeds this

485 #: limit, a :class:`TooManyRedirects` exception is raised.

486 #: This defaults to requests.models.DEFAULT_REDIRECT_LIMIT, which is

487 #: 30.

488 self.max_redirects = DEFAULT_REDIRECT_LIMIT

489

490 #: Trust environment settings for proxy configuration, default

491 #: authentication and similar.

492 self.trust_env = True

493

494 #: A CookieJar containing all currently outstanding cookies set on this

495 #: session. By default it is a

496 #: :class:`RequestsCookieJar <requests.cookies.RequestsCookieJar>`, but

497 #: may be any other ``cookielib.CookieJar`` compatible object.

498 self.cookies = cookiejar_from_dict({})

499

500 # Default connection adapters.

501 self.adapters = OrderedDict()

502 self.mount("https://", HTTPAdapter())

503 self.mount("http://", HTTPAdapter())

504

505 def __enter__(self) -> Self:

506 return self

507

508 def __exit__(self, *args: Any) -> None:

509 self.close()

510

511 def prepare_request(self, request: Request) -> PreparedRequest:

512 """Constructs a :class:`PreparedRequest <PreparedRequest>` for

513 transmission and returns it. The :class:`PreparedRequest` has settings

514 merged from the :class:`Request <Request>` instance and those of the

515 :class:`Session`.

516

517 :param request: :class:`Request` instance to prepare with this

518 session's settings.

519 :rtype: requests.PreparedRequest

520 """

521 url = cast("_t.UriType", request.url)

522 method = cast(str, request.method)

523

524 cookies = request.cookies or {}

525

526 # Bootstrap CookieJar.

527 if not isinstance(cookies, cookielib.CookieJar):

528 cookies = cookiejar_from_dict(cookies)

529

530 # Merge with session cookies

531 merged_cookies = merge_cookies(

532 merge_cookies(RequestsCookieJar(), self.cookies), cookies

533 )

534

535 # Set environment's basic authentication if not explicitly set.

536 auth = request.auth

537 if self.trust_env and not auth and not self.auth:

538 auth = get_netrc_auth(url)

539

540 p = PreparedRequest()

541 p.prepare(

542 method=method.upper(),

543 url=url,

544 files=request.files,

545 data=request.data,

546 json=request.json,

547 headers=merge_setting(

548 request.headers, self.headers, dict_class=CaseInsensitiveDict

549 ),

550 params=merge_setting(request.params, self.params),

551 auth=merge_setting(auth, self.auth),

552 cookies=merged_cookies,

553 hooks=merge_hooks(request.hooks, self.hooks),

554 )

555 return p

556

557 def request(

558 self,

559 method: str,

560 url: _t.UriType,

561 params: _t.ParamsType = None,

562 data: _t.DataType = None,

563 headers: _t.HeadersType = None,

564 cookies: RequestsCookieJar | CookieJar | dict[str, str] | None = None,

565 files: _t.FilesType = None,

566 auth: _t.AuthType = None,

567 timeout: _t.TimeoutType = None,

568 allow_redirects: bool = True,

569 proxies: dict[str, str] | None = None,

570 hooks: _t.HooksInputType | None = None,

571 stream: bool | None = None,

572 verify: _t.VerifyType | None = None,

573 cert: _t.CertType = None,

574 json: _t.JsonType = None,

575 ) -> Response:

576 """Constructs a :class:`Request <Request>`, prepares it and sends it.

577 Returns :class:`Response <Response>` object.

578

579 :param method: method for the new :class:`Request` object.

580 :param url: URL for the new :class:`Request` object.

581 :param params: (optional) Dictionary or bytes to be sent in the query

582 string for the :class:`Request`.

583 :param data: (optional) Dictionary, list of tuples, bytes, or file-like

584 object to send in the body of the :class:`Request`.

585 :param json: (optional) json to send in the body of the

586 :class:`Request`.

587 :param headers: (optional) Dictionary of HTTP Headers to send with the

588 :class:`Request`.

589 :param cookies: (optional) Dict or CookieJar object to send with the

590 :class:`Request`.

591 :param files: (optional) Dictionary of ``'filename': file-like-objects``

592 for multipart encoding upload.

593 :param auth: (optional) Auth tuple or callable to enable

594 Basic/Digest/Custom HTTP Auth.

595 :param timeout: (optional) How many seconds to wait for the server to send

596 data before giving up, as a float, or a :ref:`(connect timeout,

597 read timeout) <timeouts>` tuple.

598 :type timeout: float or tuple

599 :param allow_redirects: (optional) Set to True by default.

600 :type allow_redirects: bool

601 :param proxies: (optional) Dictionary mapping protocol or protocol and

602 hostname to the URL of the proxy.

603 :param hooks: (optional) Dictionary mapping hook name to one event or

604 list of events, event must be callable.

605 :param stream: (optional) whether to immediately download the response

606 content. Defaults to ``False``.

607 :param verify: (optional) Either a boolean, in which case it controls whether we verify

608 the server's TLS certificate, or a string, in which case it must be a path

609 to a CA bundle to use. Defaults to ``True``. When set to

610 ``False``, requests will accept any TLS certificate presented by

611 the server, and will ignore hostname mismatches and/or expired

612 certificates, which will make your application vulnerable to

613 man-in-the-middle (MitM) attacks. Setting verify to ``False``

614 may be useful during local development or testing.

615 :param cert: (optional) if String, path to ssl client cert file (.pem).

616 If Tuple, ('cert', 'key') pair.

617 :rtype: requests.Response

618 """

619 if isinstance(url, bytes):

620 url = url.decode("utf-8")

621

622 # Create the Request.

623 req = Request(

624 method=method.upper(),

625 url=url,

626 headers=headers,

627 files=files,

628 data=data or {},

629 json=json,

630 params=params or {},

631 auth=auth,

632 cookies=cookies,

633 hooks=hooks,

634 )

635 prep = self.prepare_request(req)

636

637 assert _is_prepared(prep)

638

639 proxies = proxies or {}

640

641 settings = self.merge_environment_settings(

642 prep.url, proxies, stream, verify, cert

643 )

644

645 # Send the request.

646 send_kwargs = {

647 "timeout": timeout,

648 "allow_redirects": allow_redirects,

649 }

650 send_kwargs.update(settings)

651 resp = self.send(prep, **send_kwargs)

652

653 return resp

654

655 def get(

656 self,

657 url: _t.UriType,

658 params: _t.ParamsType = None,

659 **kwargs: Unpack[_t.GetKwargs],

660 ) -> Response:

661 r"""Sends a GET request. Returns :class:`Response` object.

662

663 :param url: URL for the new :class:`Request` object.

664 :param params: (optional) Dictionary, list of tuples or bytes to send

665 in the query string for the :class:`Request`.

666 :param \*\*kwargs: Optional arguments that ``request`` takes.

667 :rtype: requests.Response

668 """

669

670 kwargs.setdefault("allow_redirects", True)

671 return self.request("GET", url, params=params, **kwargs)

672

673 def options(self, url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response:

674 r"""Sends a OPTIONS request. Returns :class:`Response` object.

675

676 :param url: URL for the new :class:`Request` object.

677 :param \*\*kwargs: Optional arguments that ``request`` takes.

678 :rtype: requests.Response

679 """

680

681 kwargs.setdefault("allow_redirects", True)

682 return self.request("OPTIONS", url, **kwargs)

683

684 def head(self, url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response:

685 r"""Sends a HEAD request. Returns :class:`Response` object.

686

687 :param url: URL for the new :class:`Request` object.

688 :param \*\*kwargs: Optional arguments that ``request`` takes.

689 :rtype: requests.Response

690 """

691

692 kwargs.setdefault("allow_redirects", False)

693 return self.request("HEAD", url, **kwargs)

694

695 def post(

696 self,

697 url: _t.UriType,

698 data: _t.DataType = None,

699 json: _t.JsonType = None,

700 **kwargs: Unpack[_t.PostKwargs],

701 ) -> Response:

702 r"""Sends a POST request. Returns :class:`Response` object.

703

704 :param url: URL for the new :class:`Request` object.

705 :param data: (optional) Dictionary, list of tuples, bytes, or file-like

706 object to send in the body of the :class:`Request`.

707 :param json: (optional) json to send in the body of the :class:`Request`.

708 :param \*\*kwargs: Optional arguments that ``request`` takes.

709 :rtype: requests.Response

710 """

711

712 return self.request("POST", url, data=data, json=json, **kwargs)

713

714 def put(

715 self, url: _t.UriType, data: _t.DataType = None, **kwargs: Unpack[_t.DataKwargs]

716 ) -> Response:

717 r"""Sends a PUT request. Returns :class:`Response` object.

718

719 :param url: URL for the new :class:`Request` object.

720 :param data: (optional) Dictionary, list of tuples, bytes, or file-like

721 object to send in the body of the :class:`Request`.

722 :param \*\*kwargs: Optional arguments that ``request`` takes.

723 :rtype: requests.Response

724 """

725

726 return self.request("PUT", url, data=data, **kwargs)

727

728 def patch(

729 self, url: _t.UriType, data: _t.DataType = None, **kwargs: Unpack[_t.DataKwargs]

730 ) -> Response:

731 r"""Sends a PATCH request. Returns :class:`Response` object.

732

733 :param url: URL for the new :class:`Request` object.

734 :param data: (optional) Dictionary, list of tuples, bytes, or file-like

735 object to send in the body of the :class:`Request`.

736 :param \*\*kwargs: Optional arguments that ``request`` takes.

737 :rtype: requests.Response

738 """

739

740 return self.request("PATCH", url, data=data, **kwargs)

741

742 def delete(self, url: _t.UriType, **kwargs: Unpack[_t.RequestKwargs]) -> Response:

743 r"""Sends a DELETE request. Returns :class:`Response` object.

744

745 :param url: URL for the new :class:`Request` object.

746 :param \*\*kwargs: Optional arguments that ``request`` takes.

747 :rtype: requests.Response

748 """

749

750 return self.request("DELETE", url, **kwargs)

751

752 def send(self, request: PreparedRequest, **kwargs: Any) -> Response:

753 """Send a given PreparedRequest.

754

755 :rtype: requests.Response

756 """

757 # Set defaults that the hooks can utilize to ensure they always have

758 # the correct parameters to reproduce the previous request.

759 kwargs.setdefault("stream", self.stream)

760 kwargs.setdefault("verify", self.verify)

761 kwargs.setdefault("cert", self.cert)

762 if "proxies" not in kwargs:

763 kwargs["proxies"] = resolve_proxies(request, self.proxies, self.trust_env)

764

765 # It's possible that users might accidentally send a Request object.

766 # Guard against that specific failure case.

767 if isinstance(request, Request):

768 raise ValueError("You can only send PreparedRequests.")

769

770 assert _is_prepared(request)

771

772 # Set up variables needed for resolve_redirects and dispatching of hooks

773 allow_redirects = kwargs.pop("allow_redirects", True)

774 stream = kwargs.get("stream")

775 hooks = request.hooks

776

777 # Get the appropriate adapter to use

778 adapter = self.get_adapter(url=request.url)

779

780 # Start time (approximately) of the request

781 start = preferred_clock()

782

783 # Send the request

784 r = adapter.send(request, **kwargs)

785

786 # Total elapsed time of the request (approximately)

787 elapsed = preferred_clock() - start

788 r.elapsed = timedelta(seconds=elapsed)

789

790 # Response manipulation hooks

791 r = dispatch_hook("response", hooks, r, **kwargs)

792

793 # Persist cookies

794 if r.history: