From: Florimond Manca Date: Thu, 21 Jul 2022 06:43:18 +0000 (+0200) Subject: Rework docs structure (#2308) X-Git-Tag: 0.23.1~46 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3a82176f1fb3c9b441dcc019655306e64e035f17;p=thirdparty%2Fhttpx.git Rework docs structure (#2308) --- diff --git a/docs/exceptions.md b/docs/exceptions.md index d96e23ab..151c6e46 100644 --- a/docs/exceptions.md +++ b/docs/exceptions.md @@ -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 diff --git a/docs/quickstart.md b/docs/quickstart.md index e8923f02..fc0b0584 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -479,3 +479,57 @@ as above: >>> httpx.get("https://example.com", auth=auth) ``` + +## 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). diff --git a/mkdocs.yml b/mkdocs.yml index 4bcc4d75..2a1d8e77 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,8 @@ site_url: https://www.python-httpx.org/ theme: name: 'material' + features: + - navigation.sections repo_name: encode/httpx repo_url: https://github.com/encode/httpx/ @@ -11,18 +13,22 @@ edit_uri: "" nav: - Introduction: 'index.md' - - QuickStart: 'quickstart.md' - - Advanced Usage: 'advanced.md' - - Async Support: 'async.md' - - HTTP/2 Support: 'http2.md' - - Environment Variables: 'environment_variables.md' - - Requests Compatibility: 'compatibility.md' - - Developer Interface: 'api.md' - - Exceptions: 'exceptions.md' - - Troubleshooting: 'troubleshooting.md' - - Third Party Packages: 'third_party_packages.md' - - Contributing: 'contributing.md' - - Code of Conduct: 'code_of_conduct.md' + - Usage: + - QuickStart: 'quickstart.md' + - Advanced Usage: 'advanced.md' + - Guides: + - Async Support: 'async.md' + - HTTP/2 Support: 'http2.md' + - Requests Compatibility: 'compatibility.md' + - Troubleshooting: 'troubleshooting.md' + - API Reference: + - Developer Interface: 'api.md' + - Exceptions: 'exceptions.md' + - Environment Variables: 'environment_variables.md' + - Community: + - Third Party Packages: 'third_party_packages.md' + - Contributing: 'contributing.md' + - Code of Conduct: 'code_of_conduct.md' markdown_extensions: - admonition