Skip to content

Docs #105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lovelydinosaur merged 1 commit into from
Jun 24, 2025
Merged

Docs #105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 51 additions & 29 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,31 @@
<img width="350" height="208" src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/butterfly.png" alt='HTTPX'>
</p>

<p align="center"><em>HTTPX 1.0 — Design proposal.</em></p>
<p align="center"><em>HTTPX 1.0 — Prelease.</em></p>

---

*The following is a design proposal and is not yet fully functional. The work is well underway, tho be aware that some parts of the codebase are still under development.*
A complete HTTP toolkit for Python. Supporting both client & server, and available in either sync or async flavors.

---

A complete HTTP framework for Python.

*Installation...*

```shell
$ pip install git+https://github.com/encode/httpnext.git
<div class="tabs"><a onclick="httpx()" class="httpx">httpx</a> <a onclick="ahttpx()" class="ahttpx hidden">ahttpx</a></div>

```{ .shell .httpx }
$ pip install --pre httpx
```

```{ .shell .ahttpx .hidden }
$ pip install --pre ahttpx
```

*Making requests as a client...*

```python
<div class="tabs"><a onclick="httpx()" class="httpx">httpx</a> <a onclick="ahttpx()" class="ahttpx hidden">ahttpx</a></div>

```{ .python .httpx }
>>> r = httpx.get('https://www.example.org/')
>>> r
<Response [200 OK]>
Expand All @@ -32,34 +38,59 @@ $ pip install git+https://github.com/encode/httpnext.git
'<!doctype html>\n<html>\n<head>\n<title>Example Domain</title>...'
```

```{ .python .ahttpx .hidden }
>>> r = await ahttpx.get('https://www.example.org/')
>>> r
<Response [200 OK]>
>>> r.status_code
200
>>> r.headers['content-type']
'text/html; charset=UTF-8'
>>> r.text
'<!doctype html>\n<html>\n<head>\n<title>Example Domain</title>...'
```

*Serving responses as the server...*

```python
<div class="tabs"><a onclick="httpx()" class="httpx">httpx</a> <a onclick="ahttpx()" class="ahttpx hidden">ahttpx</a></div>

```{ .python .httpx }
>>> def hello_world(request):
... content = httpx.HTML('<html><body>hello, world.</body></html>')
... return httpx.Response(code=200, content=content)
...

>>> with httpx.serve_http(hello_world) as server:
... print(f"Serving on {server.url} (Press CTRL+C to quit)")
... server.wait()
... server.serve()
Serving on http://127.0.0.1:8080/ (Press CTRL+C to quit)
```

```{ .python .ahttpx .hidden }
>>> async def hello_world(request):
... content = httpx.HTML('<html><body>hello, world.</body></html>')
... return httpx.Response(code=200, content=content)

>>> async with httpx.serve_http(hello_world) as server:
... print(f"Serving on {server.url} (Press CTRL+C to quit)")
... await server.serve()
Serving on http://127.0.0.1:8080/ (Press CTRL+C to quit)
```

---

Features include...
Some things HTTPX supports...

* Available in either sync or async flavours.
* A comprehensive set of HTTP components, with immutability throughout.
* A low complexity stack, with no required dependencies.
* Type annotation throughout.
* Use it as an HTTP client, to interact with the web.
* Use it as an HTTP server, to create web APIs, applications, or websites.
* Use it as a general purpose toolkit, for working with URLs, query parameters & forms.
* Use it to build networking components, such as proxies.

Components provided by HTTPX are immutable by default, and provide tightly typed interfaces. The package has a light installation footprint, minimal stdlib imports, and no dependencies.

---

# Documentation

The httpx 1.0 [design proposal](https://www.encode.io/httpnext/) is now available.

* [Quickstart](docs/quickstart.md)
* [Clients](docs/clients.md)
* [Servers](docs/servers.md)
Expand All @@ -78,19 +109,10 @@ The httpx 1.0 [design proposal](https://www.encode.io/httpnext/) is now availabl

The design repository for this work is currently private. We are looking towards a development model that encourages a calm focused working environment, and are currently taking a little time to work through expectations & boundaries for contributions to the codebase.

---

# Background

If you've been working with 0.x versions of HTTPX you'll notice significant API differences.

Version 1.0 provides a much more tightly constrained API. It has a lighter installation footprint, far more obvious type annotations, and a lower overall complexity.

For example:
Getting to 1.0 has required reworking from the ground up, and presents a significantly sharper API than previous versions. Pin your dependencies. We are currently in prerelease mode.

* Client code [before](https://github.com/encode/httpx/blob/master/httpx/_client.py) and [after](https://github.com/encode/httpnext/blob/dev/src/httpx/_client.py).
* Response code [before](https://github.com/encode/httpx/blob/master/httpx/_models.py#L515) and [after](https://github.com/encode/httpnext/blob/dev/src/httpx/_response.py).
This work is made possible through [project sponsorships](https://github.com/sponsors/encode). Your support is greatly appreciated.

---

<p align="center"><i>This provisional design work is <a href="https://www.encode.io/httpnext/about/">not currently licensed</a> for reuse.</i><br/>&mdash; 🦋 &mdash;</p>
<p align="center"><i>This design work is <a href="https://www.encode.io/httpnext/about/">not yet licensed</a> for reuse.</i><br/>&mdash; 🦋 &mdash;</p>
55 changes: 53 additions & 2 deletions docs/templates/base.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
<!DOCTYPE html>
<!-- saved from url=(0016)https://dab.eco/ -->
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<meta name="viewport" content="width=device-width, initial-scale=1.0">
Expand All @@ -13,6 +12,30 @@
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>

<script>hljs.highlightAll();</script>
<script>
function httpx() {
const httpx = document.querySelectorAll('.httpx');
httpx.forEach(function(el) {
el.classList.remove('hidden');
});
const ahttpx = document.querySelectorAll('.ahttpx');
ahttpx.forEach(function(el) {
el.classList.add('hidden');
});
document.cookie = "selection=httpx; path=/;"
}
function ahttpx() {
const httpx = document.querySelectorAll('.httpx');
httpx.forEach(function(el) {
el.classList.add('hidden');
});
const ahttpx = document.querySelectorAll('.ahttpx');
ahttpx.forEach(function(el) {
el.classList.remove('hidden');
});
document.cookie = "selection=ahttpx; path=/;"
}
</script>
<style>
* {
margin: 0;
Expand Down Expand Up @@ -80,6 +103,28 @@
border-top: 1px solid #FF9300;
}

div.tabs {
font-size: small;
font-family: courier;
text-align: right;
border-bottom: 1px solid grey;
}

div.tabs a {
color: white;
text-decoration: none;
cursor: pointer;
}

div.tabs a.hidden {
color: grey;
text-decoration: none;
}

pre.hidden {
display: none;
}

span.link-prev {
float: left;
}
Expand Down Expand Up @@ -109,5 +154,11 @@
<main>
{{ content }}
</main>

<script>
document.addEventListener('DOMContentLoaded', function() {
if (document.cookie.match("selection=ahttpx")) {
ahttpx();
}
})
</script>
</body></html>