Skip to content

Commit

Permalink
Merge branch 'master' into master
Browse files Browse the repository at this point in the history
  • Loading branch information
@tomchristie
tomchristie committed Sep 29, 2022
2 parents 9d4f3fe + 8152c4f commit 6b1078f
Show file tree
Hide file tree
Showing 26 changed files with 410 additions and 267 deletions.
4 changes: 0 additions & 4 deletions MANIFEST.in
View file

This file was deleted.

2 changes: 1 addition & 1 deletion README.md
View file
Expand Up @@ -103,7 +103,7 @@ Or, to include the optional HTTP/2 support, use:
$ pip install httpx[http2]
```

HTTPX requires Python 3.6+.
HTTPX requires Python 3.7+.

## Documentation

Expand Down
123 changes: 62 additions & 61 deletions README_chinese.md
View file
Expand Up @@ -2,7 +2,7 @@
<a href="https://www.python-httpx.org/"><img width="350" height="208" src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/butterfly.png" alt='HTTPX'></a>
</p>

<p align="center"><strong>HTTPX</strong> <em>- 适用于Python的次世代HTTP客户端 </em></p>
<p align="center"><strong>HTTPX</strong> <em>- 适用于 Python 的下一代 HTTP 客户端</em></p>

<p align="center">
<a href="https://github.com/encode/httpx/actions">
Expand All @@ -13,19 +13,17 @@
</a>
</p>

HTTPX是一个功能齐全的HTTP客户端python3库. 它集成了 **一个命令行客户端**, 支持 **HTTP/1.1 和 HTTP/2**, 而且提供了 **同步和异步API**.

**注意！**: *0.21版本包括对集成命令行的一些改进。最新版本与重新设计的 `http核心`. 都应该自动更新到所需的版本，如果您遇到任何问题，那么您应该确保您安装的版本为 `httpx0.21.*` 且 `httpcore0.14.*` . 请参考 [the CHANGELOG](https://github.com/encode/httpx/blob/master/CHANGELOG.md) 来获得更多细节.*
HTTPX 是适用于 Python3 的功能齐全的 HTTP 客户端。 它集成了 **一个命令行客户端**，同时支持 **HTTP/1.1 和 HTTP/2**，并提供了 **同步和异步 API**。

---

通过pip安装httpx:
通过 pip 安装 HTTPX：

```shell
$ pip install httpx
```

使用httpx:
使用 httpx：

```pycon
>>> import httpx
Expand All @@ -40,13 +38,13 @@ $ pip install httpx
'<!doctype html>\n<html>\n<head>\n<title>Example Domain</title>...'
```

或者使用命令行客户端.
或者使用命令行客户端。

```shell
$ pip install 'httpx[cli]' # 只安装集成的命令行功能
$ pip install 'httpx[cli]' # 命令行功能是可选的。
```

它现在允许我们直接从命令行使用HTTPX
它允许我们直接通过命令行来使用 HTTPX...

<p align="center">
<img width="700" src="docs/img/httpx-help.png" alt='httpx --help'>
Expand All @@ -60,85 +58,88 @@ $ pip install 'httpx[cli]' # 只安装集成的命令行功能

## 特性

HTTPX将并为您提供以下功能:

* 广泛的 [requests-compatible API](https://www.python-httpx.org/compatibility/).
* 内置的命令行客户端功能.
* HTTP/1.1 [和 HTTP/2 支持](https://www.python-httpx.org/http2/).
* 标准同步接口，也支持 [异步](https://www.python-httpx.org/async/).
* 能够直接向 [WSGI 应用发送请求](https://www.python-httpx.org/advanced/#calling-into-python-web-apps) 或向 [ASGI 应用发送请求](https://www.python-httpx.org/async/#calling-into-python-web-apps).
* 在任何地方设置详细的timeout.
* 全类型注释.
* 全部代码均通过测试.

加上这些应该具备的标准功能

* 域名与URL
* 保持活动状态
* 具有Cookie持久性的会话
* 浏览器风格的SSL验证
* 身份验证
* Elegant Key/Value Cookies
HTTPX 建立在成熟的 requests 可用性基础上，为您提供以下功能：

* 广泛的 [requests 兼容 API](https://www.python-httpx.org/compatibility/)。
* 内置的命令行客户端功能。
* HTTP/1.1 [和 HTTP/2 支持](https://www.python-httpx.org/http2/)。
* 标准同步接口，也支持 [异步](https://www.python-httpx.org/async/)。
* 能够直接向 [WSGI 应用发送请求](https://www.python-httpx.org/advanced/#calling-into-python-web-apps) 或向 [ASGI 应用发送请求](https://www.python-httpx.org/async/#calling-into-python-web-apps)。
* 每一处严格的超时控制。
* 完整的类型注解。
* 100% 测试。

加上这些应该具备的标准功能...

* 国际化域名与 URL
* Keep-Alive & 连接池
* Cookie 持久性会话
* 浏览器风格的 SSL 验证
* 基础或摘要身份验证
* 优雅的键值 Cookies
* 自动解压缩
* 内容自动解码
* Unicode Response Bodies
* Unicode 响应正文
* 分段文件上传
* 支持HTTP(S) 代理
* 支持设定timeout
* HTTP(S)代理支持
* 可配置的连接超时
* 流式下载
* 支持 .netrc
* 接收Chunked编码
* .netrc 支持
* 分块请求

## 安装

使用pip安装:
使用 pip 安装：

```shell
$ pip install httpx
```

安装HTTP/2支持:
或者，安装可选的 HTTP/2 支持：

```shell
$ pip install httpx[http2]
```

HTTPX 要求 Python 3.6版本或更高.
HTTPX 要求 Python 3.7+ 版本。

## 文档

项目文档现已就绪，请访问 [https://www.python-httpx.org/](https://www.python-httpx.org/) 来阅读！
项目文档现已就绪，请访问 [https://www.python-httpx.org/](https://www.python-httpx.org/) 来阅读。

想学习基础知识？请访问 [快速开始](https://www.python-httpx.org/quickstart/).
要浏览所有基础知识，请访问 [快速开始](https://www.python-httpx.org/quickstart/)。

想获得进阶帮助？ 请访问 [Advanced Usage](https://www.python-httpx.org/advanced/) 来获得答案, 不妨来看看 [异步支持](https://www.python-httpx.org/async/) 或者 [HTTP/2](https://www.python-httpx.org/http2/)
更高级的主题，可参阅 [高级用法](https://www.python-httpx.org/advanced/) 章节, [异步支持](https://www.python-httpx.org/async/) 或者 [HTTP/2](https://www.python-httpx.org/http2/) 章节。

[Developer Interface](https://www.python-httpx.org/api/) 提供了全面的API参考。
[Developer Interface](https://www.python-httpx.org/api/) 提供了全面的 API 参考。

要了解与HTTPX集成的工具, 请访问 [第三方包](https://www.python-httpx.org/third_party_packages/).
要了解与 HTTPX 集成的工具, 请访问 [第三方包](https://www.python-httpx.org/third_party_packages/)。

## 贡献

如果您想对本项目做出贡献，请访问 [贡献者指南](https://www.python-httpx.org/contributing/) 来了解注意事项
如果您想对本项目做出贡献，请访问 [贡献者指南](https://www.python-httpx.org/contributing/) 来了解如何开始。

## 依赖

HTTPX项目依赖于这些优秀的库:

* `httpcore` - The underlying transport implementation for `httpx`.
* `h11` - HTTP/1.1 support.
* `h2` - HTTP/2 support. *(Optional, with `httpx[http2]`)*
* `certifi` - SSL certificates.
* `rfc3986` - URL parsing & normalization.
* `idna` - Internationalized domain name support.
* `sniffio` - Async library autodetection.
* `rich` - Rich terminal support. *(Optional, with `httpx[cli]`)*
* `click` - Command line client support. *(Optional, with `httpx[cli]`)*
* `brotli` or `brotlicffi` - Decoding for "brotli" compressed responses. *(Optional, with `httpx[brotli]`)*

A huge amount of credit is due to `requests` for the API layout that
much of this work follows, as well as to `urllib3` for plenty of design
inspiration around the lower-level networking details.

<p align="center">&mdash; ⭐️ &mdash;</p>
<p align="center"><i>HTTPX 代码使用 <a href="https://github.com/encode/httpx/blob/master/LICENSE.md">BSD 开源协议</a>. 在英国布莱顿设计和构建。</i></p>
HTTPX 项目依赖于这些优秀的库：

* `httpcore` - `httpx` 基础传输接口实现。
* `h11` - HTTP/1.1 支持。
* `certifi` - SSL 证书。
* `rfc3986` - URL 解析与规范化。
* `idna` - 国际化域名支持。
* `sniffio` - 异步库自动检测。

以及这些可选的安装：

* `h2` - HTTP/2 支持。 *(可选的，通过 `httpx[http2]`)*
* `socksio` - SOCKS 代理支持。 *(可选的， 通过 `httpx[socks]`)*
* `rich` - 丰富的终端支持。 *(可选的，通过 `httpx[cli]`)*
* `click` - 命令行客户端支持。 *(可选的，通过 `httpx[cli]`)*
* `brotli` 或者 `brotlicffi` - 对 “brotli” 压缩响应的解码。*(可选的，通过 `httpx[brotli]`)*

这项工作的大量功劳都归功于参考了 `requests` 所遵循的 API 结构，以及 `urllib3` 中众多围绕底层网络细节的设计灵感。

---

<p align="center"><i>HTTPX 使用 <a href="https://github.com/encode/httpx/blob/master/LICENSE.md">BSD 开源协议</a> code。<br/>精心设计和制作。</i><br/>&mdash; 🦋 &mdash;</p>
4 changes: 2 additions & 2 deletions docs/advanced.md
View file
Expand Up @@ -1064,7 +1064,7 @@ When making requests to local servers, such as a development server running on `

If you do need to make HTTPS connections to a local server, for example to test an HTTPS-only service, you will need to create and use your own certificates. Here's one way to do it:

1. Use [trustme-cli](https://github.com/sethmlarson/trustme-cli/) to generate a pair of server key/cert files, and a client cert file.
1. Use [trustme](https://github.com/python-trio/trustme) to generate a pair of server key/cert files, and a client cert file.
1. Pass the server key/cert files when starting your local server. (This depends on the particular web server you're using. For example, [Uvicorn](https://www.uvicorn.org) provides the `--ssl-keyfile` and `--ssl-certfile` options.)
1. Tell HTTPX to use the certificates stored in `client.pem`:

Expand Down Expand Up @@ -1093,7 +1093,7 @@ class directly, and pass it to the client instance. One example is the
>>> client = httpx.Client(transport=transport)
```

Connection retries are also available via this interface.
Connection retries are also available via this interface. Requests will be retried the given number of times in case an `httpx.ConnectError` or an `httpx.ConnectTimeout` occurs, allowing smoother operation under flaky networks. If you need other forms of retry behaviors, such as handling read/write errors or reacting to `503 Service Unavailable`, consider general-purpose tools such as [tenacity](https://github.com/jd/tenacity).

```pycon
>>> import httpx
Expand Down
52 changes: 2 additions & 50 deletions docs/exceptions.md
View file
@@ -1,56 +1,8 @@
# Exceptions

## Request and Response exceptions

The most important exception classes in HTTPX are `RequestError` and `HTTPStatusError`.

The `RequestError` class is a superclass that encompasses any exception that occurs
while issuing an HTTP request. These exceptions include a `.request` attribute.

```python
try:
response = httpx.get("https://www.example.com/")
except httpx.RequestError as exc:
print(f"An error occurred while requesting {exc.request.url!r}.")
```

The `HTTPStatusError` class is raised by `response.raise_for_status()` on responses which are not a 2xx success code.
These exceptions include both a `.request` and a `.response` attribute.

```python
response = httpx.get("https://www.example.com/")
try:
response.raise_for_status()
except httpx.HTTPStatusError as exc:
print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
```

There is also a base class `HTTPError` that includes both of these categories, and can be used
to catch either failed requests, or 4xx and 5xx responses.

You can either use this base class to catch both categories...

```python
try:
response = httpx.get("https://www.example.com/")
response.raise_for_status()
except httpx.HTTPError as exc:
print(f"Error while requesting {exc.request.url!r}.")
```

Or handle each case explicitly...

```python
try:
response = httpx.get("https://www.example.com/")
response.raise_for_status()
except httpx.RequestError as exc:
print(f"An error occurred while requesting {exc.request.url!r}.")
except httpx.HTTPStatusError as exc:
print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
```
This page lists exceptions that may be raised when using HTTPX.

---
For an overview of how to work with HTTPX exceptions, see [Exceptions (Quickstart)](quickstart.md#exceptions).

## The exception hierarchy

Expand Down
2 changes: 1 addition & 1 deletion docs/http2.md
View file
Expand Up @@ -14,7 +14,7 @@ stream to handle multiple concurrent requests.
HTTP/2 also provides support for functionality such as response prioritization,
and server push.

For a comprehensive guide to HTTP/2 you may want to check out "[HTTP2 Explained](https://http2-explained.haxx.se/content/en/)".
For a comprehensive guide to HTTP/2 you may want to check out "[http2 explained](https://http2-explained.haxx.se/)".

## Enabling HTTP/2

Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
View file
Expand Up @@ -145,6 +145,6 @@ To include the optional brotli decoder support, use:
$ pip install httpx[brotli]
```

HTTPX requires Python 3.6+
HTTPX requires Python 3.7+

[sync-support]: https://github.com/encode/httpx/issues/572
54 changes: 54 additions & 0 deletions docs/quickstart.md
View file
Expand Up @@ -479,3 +479,57 @@ as above:
>>> httpx.get("https://example.com", auth=auth)
<Response [200 OK]>
```

## Exceptions

HTTPX will raise exceptions if an error occurs.

The most important exception classes in HTTPX are `RequestError` and `HTTPStatusError`.

The `RequestError` class is a superclass that encompasses any exception that occurs
while issuing an HTTP request. These exceptions include a `.request` attribute.

```python
try:
response = httpx.get("https://www.example.com/")
except httpx.RequestError as exc:
print(f"An error occurred while requesting {exc.request.url!r}.")
```

The `HTTPStatusError` class is raised by `response.raise_for_status()` on responses which are not a 2xx success code.
These exceptions include both a `.request` and a `.response` attribute.

```python
response = httpx.get("https://www.example.com/")
try:
response.raise_for_status()
except httpx.HTTPStatusError as exc:
print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
```

There is also a base class `HTTPError` that includes both of these categories, and can be used
to catch either failed requests, or 4xx and 5xx responses.

You can either use this base class to catch both categories...

```python
try:
response = httpx.get("https://www.example.com/")
response.raise_for_status()
except httpx.HTTPError as exc:
print(f"Error while requesting {exc.request.url!r}.")
```

Or handle each case explicitly...

```python
try:
response = httpx.get("https://www.example.com/")
response.raise_for_status()
except httpx.RequestError as exc:
print(f"An error occurred while requesting {exc.request.url!r}.")
except httpx.HTTPStatusError as exc:
print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
```

For a full list of available exceptions, see [Exceptions (API Reference)](exceptions.md).

0 comments on commit 6b1078f

Please sign in to comment.