Skip to content

Commit 69efa44

Browse files
lovelydinosaurlovelydinosaur
authored
Docs (#105)
1 parent d501e70 commit 69efa44

File tree

2 files changed

+104
-31
lines changed

2 files changed

+104
-31
lines changed

‎docs/index.md‎

Lines changed: 51 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,31 @@
22
<img width="350" height="208" src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/butterfly.png" alt='HTTPX'>
33
</p>
44

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

77
---
88

9-
*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.*
9+
A complete HTTP toolkit for Python. Supporting both client & server, and available in either sync or async flavors.
1010

1111
---
1212

13-
A complete HTTP framework for Python.
14-
1513
*Installation...*
1614

17-
```shell
18-
$ pip install git+https://github.com/encode/httpnext.git
15+
<div class="tabs"><a onclick="httpx()" class="httpx">httpx</a> <a onclick="ahttpx()" class="ahttpx hidden">ahttpx</a></div>
16+
17+
```{ .shell .httpx }
18+
$ pip install --pre httpx
19+
```
20+
21+
```{ .shell .ahttpx .hidden }
22+
$ pip install --pre ahttpx
1923
```
2024

2125
*Making requests as a client...*
2226

23-
```python
27+
<div class="tabs"><a onclick="httpx()" class="httpx">httpx</a> <a onclick="ahttpx()" class="ahttpx hidden">ahttpx</a></div>
28+
29+
```{ .python .httpx }
2430
>>> r = httpx.get('https://www.example.org/')
2531
>>> r
2632
<Response [200 OK]>
@@ -32,34 +38,59 @@ $ pip install git+https://github.com/encode/httpnext.git
3238
'<!doctype html>\n<html>\n<head>\n<title>Example Domain</title>...'
3339
```
3440

41+
```{ .python .ahttpx .hidden }
42+
>>> r = await ahttpx.get('https://www.example.org/')
43+
>>> r
44+
<Response [200 OK]>
45+
>>> r.status_code
46+
200
47+
>>> r.headers['content-type']
48+
'text/html; charset=UTF-8'
49+
>>> r.text
50+
'<!doctype html>\n<html>\n<head>\n<title>Example Domain</title>...'
51+
```
52+
3553
*Serving responses as the server...*
3654

37-
```python
55+
<div class="tabs"><a onclick="httpx()" class="httpx">httpx</a> <a onclick="ahttpx()" class="ahttpx hidden">ahttpx</a></div>
56+
57+
```{ .python .httpx }
3858
>>> def hello_world(request):
3959
... content = httpx.HTML('<html><body>hello, world.</body></html>')
4060
... return httpx.Response(code=200, content=content)
41-
...
61+
4262
>>> with httpx.serve_http(hello_world) as server:
4363
... print(f"Serving on {server.url} (Press CTRL+C to quit)")
44-
... server.wait()
64+
... server.serve()
65+
Serving on http://127.0.0.1:8080/ (Press CTRL+C to quit)
66+
```
67+
68+
```{ .python .ahttpx .hidden }
69+
>>> async def hello_world(request):
70+
... content = httpx.HTML('<html><body>hello, world.</body></html>')
71+
... return httpx.Response(code=200, content=content)
72+
73+
>>> async with httpx.serve_http(hello_world) as server:
74+
... print(f"Serving on {server.url} (Press CTRL+C to quit)")
75+
... await server.serve()
4576
Serving on http://127.0.0.1:8080/ (Press CTRL+C to quit)
4677
```
4778

4879
---
4980

50-
Features include...
81+
Some things HTTPX supports...
5182

52-
* Available in either sync or async flavours.
53-
* A comprehensive set of HTTP components, with immutability throughout.
54-
* A low complexity stack, with no required dependencies.
55-
* Type annotation throughout.
83+
* Use it as an HTTP client, to interact with the web.
84+
* Use it as an HTTP server, to create web APIs, applications, or websites.
85+
* Use it as a general purpose toolkit, for working with URLs, query parameters & forms.
86+
* Use it to build networking components, such as proxies.
87+
88+
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.
5689

5790
---
5891

5992
# Documentation
6093

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

79110
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.
80111

81-
---
82-
83-
# Background
84-
85-
If you've been working with 0.x versions of HTTPX you'll notice significant API differences.
86-
87-
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.
88-
89-
For example:
112+
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.
90113

91-
* 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).
92-
* 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).
114+
This work is made possible through [project sponsorships](https://github.com/sponsors/encode). Your support is greatly appreciated.
93115

94116
---
95117

96-
<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>
118+
<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>

‎docs/templates/base.html‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
<!DOCTYPE html>
2-
<!-- saved from url=(0016)https://dab.eco/ -->
32
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
43

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

1514
<script>hljs.highlightAll();</script>
15+
<script>
16+
function httpx() {
17+
const httpx = document.querySelectorAll('.httpx');
18+
httpx.forEach(function(el) {
19+
el.classList.remove('hidden');
20+
});
21+
const ahttpx = document.querySelectorAll('.ahttpx');
22+
ahttpx.forEach(function(el) {
23+
el.classList.add('hidden');
24+
});
25+
document.cookie = "selection=httpx; path=/;"
26+
}
27+
function ahttpx() {
28+
const httpx = document.querySelectorAll('.httpx');
29+
httpx.forEach(function(el) {
30+
el.classList.add('hidden');
31+
});
32+
const ahttpx = document.querySelectorAll('.ahttpx');
33+
ahttpx.forEach(function(el) {
34+
el.classList.remove('hidden');
35+
});
36+
document.cookie = "selection=ahttpx; path=/;"
37+
}
38+
</script>
1639
<style>
1740
* {
1841
margin: 0;
@@ -80,6 +103,28 @@
80103
border-top: 1px solid #FF9300;
81104
}
82105

106+
div.tabs {
107+
font-size: small;
108+
font-family: courier;
109+
text-align: right;
110+
border-bottom: 1px solid grey;
111+
}
112+
113+
div.tabs a {
114+
color: white;
115+
text-decoration: none;
116+
cursor: pointer;
117+
}
118+
119+
div.tabs a.hidden {
120+
color: grey;
121+
text-decoration: none;
122+
}
123+
124+
pre.hidden {
125+
display: none;
126+
}
127+
83128
span.link-prev {
84129
float: left;
85130
}
@@ -109,5 +154,11 @@
109154
<main>
110155
{{ content }}
111156
</main>
112-
157+
<script>
158+
document.addEventListener('DOMContentLoaded', function() {
159+
if (document.cookie.match("selection=ahttpx")) {
160+
ahttpx();
161+
}
162+
})
163+
</script>
113164
</body></html>

0 commit comments

Comments
 (0)