1  from __future__ import annotations
   2  
   3  import typing
   4  from contextlib import contextmanager
   5  
   6  from ._client import Client
   7  from ._config import DEFAULT_TIMEOUT_CONFIG
   8  from ._models import Response
   9  from ._types import (
  10      AuthTypes,
  11      CookieTypes,
  12      HeaderTypes,
  13      ProxyTypes,
  14      QueryParamTypes,
  15      RequestContent,
  16      RequestData,
  17      RequestFiles,
  18      TimeoutTypes,
  19  )
  20  from ._urls import URL
  21  
  22  if typing.TYPE_CHECKING:
  23      import ssl  # pragma: no cover
  24  
  25  
  26  __all__ = [
  27      "delete",
  28      "get",
  29      "head",
  30      "options",
  31      "patch",
  32      "post",
  33      "put",
  34      "request",
  35      "stream",
  36  ]
  37  
  38  
  39  def request(
  40      method: str,
  41      url: URL | str,
  42      *,
  43      params: QueryParamTypes | None = None,
  44      content: RequestContent | None = None,
  45      data: RequestData | None = None,
  46      files: RequestFiles | None = None,
  47      json: typing.Any | None = None,
  48      headers: HeaderTypes | None = None,
  49      cookies: CookieTypes | None = None,
  50      auth: AuthTypes | None = None,
  51      proxy: ProxyTypes | None = None,
  52      timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
  53      follow_redirects: bool = False,
  54      verify: ssl.SSLContext | str | bool = True,
  55      trust_env: bool = True,
  56  ) -> Response:
  57      """
  58      Sends an HTTP request.
  59  
  60      **Parameters:**
  61  
  62      * **method** - HTTP method for the new `Request` object: `GET`, `OPTIONS`,
  63      `HEAD`, `POST`, `PUT`, `PATCH`, or `DELETE`.
  64      * **url** - URL for the new `Request` object.
  65      * **params** - *(optional)* Query parameters to include in the URL, as a
  66      string, dictionary, or sequence of two-tuples.
  67      * **content** - *(optional)* Binary content to include in the body of the
  68      request, as bytes or a byte iterator.
  69      * **data** - *(optional)* Form data to include in the body of the request,
  70      as a dictionary.
  71      * **files** - *(optional)* A dictionary of upload files to include in the
  72      body of the request.
  73      * **json** - *(optional)* A JSON serializable object to include in the body
  74      of the request.
  75      * **headers** - *(optional)* Dictionary of HTTP headers to include in the
  76      request.
  77      * **cookies** - *(optional)* Dictionary of Cookie items to include in the
  78      request.
  79      * **auth** - *(optional)* An authentication class to use when sending the
  80      request.
  81      * **proxy** - *(optional)* A proxy URL where all the traffic should be routed.
  82      * **timeout** - *(optional)* The timeout configuration to use when sending
  83      the request.
  84      * **follow_redirects** - *(optional)* Enables or disables HTTP redirects.
  85      * **verify** - *(optional)* Either `True` to use an SSL context with the
  86      default CA bundle, `False` to disable verification, or an instance of
  87      `ssl.SSLContext` to use a custom context.
  88      * **trust_env** - *(optional)* Enables or disables usage of environment
  89      variables for configuration.
  90  
  91      **Returns:** `Response`
  92  
  93      Usage:
  94  
  95      ```
  96      >>> import httpx
  97      >>> response = httpx.request('GET', 'https://httpbin.org/get')
  98      >>> response
  99      <Response [200 OK]>
 100      ```
 101      """
 102      with Client(
 103          cookies=cookies,
 104          proxy=proxy,
 105          verify=verify,
 106          timeout=timeout,
 107          trust_env=trust_env,
 108      ) as client:
 109          return client.request(
 110              method=method,
 111              url=url,
 112              content=content,
 113              data=data,
 114              files=files,
 115              json=json,
 116              params=params,
 117              headers=headers,
 118              auth=auth,
 119              follow_redirects=follow_redirects,
 120          )
 121  
 122  
 123  @contextmanager
 124  def stream(
 125      method: str,
 126      url: URL | str,
 127      *,
 128      params: QueryParamTypes | None = None,
 129      content: RequestContent | None = None,
 130      data: RequestData | None = None,
 131      files: RequestFiles | None = None,
 132      json: typing.Any | None = None,
 133      headers: HeaderTypes | None = None,
 134      cookies: CookieTypes | None = None,
 135      auth: AuthTypes | None = None,
 136      proxy: ProxyTypes | None = None,
 137      timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
 138      follow_redirects: bool = False,
 139      verify: ssl.SSLContext | str | bool = True,
 140      trust_env: bool = True,
 141  ) -> typing.Iterator[Response]:
 142      """
 143      Alternative to `httpx.request()` that streams the response body
 144      instead of loading it into memory at once.
 145  
 146      **Parameters**: See `httpx.request`.
 147  
 148      See also: [Streaming Responses][0]
 149  
 150      [0]: /quickstart#streaming-responses
 151      """
 152      with Client(
 153          cookies=cookies,
 154          proxy=proxy,
 155          verify=verify,
 156          timeout=timeout,
 157          trust_env=trust_env,
 158      ) as client:
 159          with client.stream(
 160              method=method,
 161              url=url,
 162              content=content,
 163              data=data,
 164              files=files,
 165              json=json,
 166              params=params,
 167              headers=headers,
 168              auth=auth,
 169              follow_redirects=follow_redirects,
 170          ) as response:
 171              yield response
 172  
 173  
 174  def get(
 175      url: URL | str,
 176      *,
 177      params: QueryParamTypes | None = None,
 178      headers: HeaderTypes | None = None,
 179      cookies: CookieTypes | None = None,
 180      auth: AuthTypes | None = None,
 181      proxy: ProxyTypes | None = None,
 182      follow_redirects: bool = False,
 183      verify: ssl.SSLContext | str | bool = True,
 184      timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
 185      trust_env: bool = True,
 186  ) -> Response:
 187      """
 188      Sends a `GET` request.
 189  
 190      **Parameters**: See `httpx.request`.
 191  
 192      Note that the `data`, `files`, `json` and `content` parameters are not available
 193      on this function, as `GET` requests should not include a request body.
 194      """
 195      return request(
 196          "GET",
 197          url,
 198          params=params,
 199          headers=headers,
 200          cookies=cookies,
 201          auth=auth,
 202          proxy=proxy,
 203          follow_redirects=follow_redirects,
 204          verify=verify,
 205          timeout=timeout,
 206          trust_env=trust_env,
 207      )
 208  
 209  
 210  def options(
 211      url: URL | str,
 212      *,
 213      params: QueryParamTypes | None = None,
 214      headers: HeaderTypes | None = None,
 215      cookies: CookieTypes | None = None,
 216      auth: AuthTypes | None = None,
 217      proxy: ProxyTypes | None = None,
 218      follow_redirects: bool = False,
 219      verify: ssl.SSLContext | str | bool = True,
 220      timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
 221      trust_env: bool = True,
 222  ) -> Response:
 223      """
 224      Sends an `OPTIONS` request.
 225  
 226      **Parameters**: See `httpx.request`.
 227  
 228      Note that the `data`, `files`, `json` and `content` parameters are not available
 229      on this function, as `OPTIONS` requests should not include a request body.
 230      """
 231      return request(
 232          "OPTIONS",
 233          url,
 234          params=params,
 235          headers=headers,
 236          cookies=cookies,
 237          auth=auth,
 238          proxy=proxy,
 239          follow_redirects=follow_redirects,
 240          verify=verify,
 241          timeout=timeout,
 242          trust_env=trust_env,
 243      )
 244  
 245  
 246  def head(
 247      url: URL | str,
 248      *,
 249      params: QueryParamTypes | None = None,
 250      headers: HeaderTypes | None = None,
 251      cookies: CookieTypes | None = None,
 252      auth: AuthTypes | None = None,
 253      proxy: ProxyTypes | None = None,
 254      follow_redirects: bool = False,
 255      verify: ssl.SSLContext | str | bool = True,
 256      timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
 257      trust_env: bool = True,
 258  ) -> Response:
 259      """
 260      Sends a `HEAD` request.
 261  
 262      **Parameters**: See `httpx.request`.
 263  
 264      Note that the `data`, `files`, `json` and `content` parameters are not available
 265      on this function, as `HEAD` requests should not include a request body.
 266      """
 267      return request(
 268          "HEAD",
 269          url,
 270          params=params,
 271          headers=headers,
 272          cookies=cookies,
 273          auth=auth,
 274          proxy=proxy,
 275          follow_redirects=follow_redirects,
 276          verify=verify,
 277          timeout=timeout,
 278          trust_env=trust_env,
 279      )
 280  
 281  
 282  def post(
 283      url: URL | str,
 284      *,
 285      content: RequestContent | None = None,
 286      data: RequestData | None = None,
 287      files: RequestFiles | None = None,
 288      json: typing.Any | None = None,
 289      params: QueryParamTypes | None = None,
 290      headers: HeaderTypes | None = None,
 291      cookies: CookieTypes | None = None,
 292      auth: AuthTypes | None = None,
 293      proxy: ProxyTypes | None = None,
 294      follow_redirects: bool = False,
 295      verify: ssl.SSLContext | str | bool = True,
 296      timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
 297      trust_env: bool = True,
 298  ) -> Response:
 299      """
 300      Sends a `POST` request.
 301  
 302      **Parameters**: See `httpx.request`.
 303      """
 304      return request(
 305          "POST",
 306          url,
 307          content=content,
 308          data=data,
 309          files=files,
 310          json=json,
 311          params=params,
 312          headers=headers,
 313          cookies=cookies,
 314          auth=auth,
 315          proxy=proxy,
 316          follow_redirects=follow_redirects,
 317          verify=verify,
 318          timeout=timeout,
 319          trust_env=trust_env,
 320      )
 321  
 322  
 323  def put(
 324      url: URL | str,
 325      *,
 326      content: RequestContent | None = None,
 327      data: RequestData | None = None,
 328      files: RequestFiles | None = None,
 329      json: typing.Any | None = None,
 330      params: QueryParamTypes | None = None,
 331      headers: HeaderTypes | None = None,
 332      cookies: CookieTypes | None = None,
 333      auth: AuthTypes | None = None,
 334      proxy: ProxyTypes | None = None,
 335      follow_redirects: bool = False,
 336      verify: ssl.SSLContext | str | bool = True,
 337      timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
 338      trust_env: bool = True,
 339  ) -> Response:
 340      """
 341      Sends a `PUT` request.
 342  
 343      **Parameters**: See `httpx.request`.
 344      """
 345      return request(
 346          "PUT",
 347          url,
 348          content=content,
 349          data=data,
 350          files=files,
 351          json=json,
 352          params=params,
 353          headers=headers,
 354          cookies=cookies,
 355          auth=auth,
 356          proxy=proxy,
 357          follow_redirects=follow_redirects,
 358          verify=verify,
 359          timeout=timeout,
 360          trust_env=trust_env,
 361      )
 362  
 363  
 364  def patch(
 365      url: URL | str,
 366      *,
 367      content: RequestContent | None = None,
 368      data: RequestData | None = None,
 369      files: RequestFiles | None = None,
 370      json: typing.Any | None = None,
 371      params: QueryParamTypes | None = None,
 372      headers: HeaderTypes | None = None,
 373      cookies: CookieTypes | None = None,
 374      auth: AuthTypes | None = None,
 375      proxy: ProxyTypes | None = None,
 376      follow_redirects: bool = False,
 377      verify: ssl.SSLContext | str | bool = True,
 378      timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
 379      trust_env: bool = True,
 380  ) -> Response:
 381      """
 382      Sends a `PATCH` request.
 383  
 384      **Parameters**: See `httpx.request`.
 385      """
 386      return request(
 387          "PATCH",
 388          url,
 389          content=content,
 390          data=data,
 391          files=files,
 392          json=json,
 393          params=params,
 394          headers=headers,
 395          cookies=cookies,
 396          auth=auth,
 397          proxy=proxy,
 398          follow_redirects=follow_redirects,
 399          verify=verify,
 400          timeout=timeout,
 401          trust_env=trust_env,
 402      )
 403  
 404  
 405  def delete(
 406      url: URL | str,
 407      *,
 408      params: QueryParamTypes | None = None,
 409      headers: HeaderTypes | None = None,
 410      cookies: CookieTypes | None = None,
 411      auth: AuthTypes | None = None,
 412      proxy: ProxyTypes | None = None,
 413      follow_redirects: bool = False,
 414      timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
 415      verify: ssl.SSLContext | str | bool = True,
 416      trust_env: bool = True,
 417  ) -> Response:
 418      """
 419      Sends a `DELETE` request.
 420  
 421      **Parameters**: See `httpx.request`.
 422  
 423      Note that the `data`, `files`, `json` and `content` parameters are not available
 424      on this function, as `DELETE` requests should not include a request body.
 425      """
 426      return request(
 427          "DELETE",
 428          url,
 429          params=params,
 430          headers=headers,
 431          cookies=cookies,
 432          auth=auth,
 433          proxy=proxy,
 434          follow_redirects=follow_redirects,
 435          verify=verify,
 436          timeout=timeout,
 437          trust_env=trust_env,
 438      )
 439