Enhanced Quickstart and Basic usage pages

docs/source/getting-started/quickstart.md

@@ -1,10 +1,12 @@
-# :zap: Quick Start
+# Quickstart
 
-This page will help you get up and running with wreq in minutes.
+This page covers the basics of making HTTP requests with wreq. By the end, you will be able to send requests, read responses, pass headers, work with JSON, and route traffic through a proxy.
 
 ---
 
-## Basic GET Request
+## Making a Request
+
+wreq supports both async and blocking usage. The async client is the default and recommended approach for most use cases.
 
 === "Async"
     ```python
@@ -13,61 +15,88 @@ This page will help you get up and running with wreq in minutes.
 
     async def main():
         client = Client()
-        resp = await client.get("https://httpbin.org/get")
-        print(resp.status_code)
-        print(await resp.text())
+        response = await client.get("https://httpbin.org/get")
+        print(response.status)
 
     asyncio.run(main())
     ```
+
 === "Blocking"
     ```python
     from wreq.blocking import Client
 
     client = Client()
-    resp = client.get("https://httpbin.org/get")
-    print(resp.status_code)
-    print(resp.text())
+    response = client.get("https://httpbin.org/get")
+    print(response.status_code)
     ```
 
+The same interface works for all standard HTTP methods:
+
+```python
+response = await client.post("https://httpbin.org/post")
+response = await client.put("https://httpbin.org/put")
+response = await client.delete("https://httpbin.org/delete")
+response = await client.head("https://httpbin.org/get")
+```
+
 ---
 
-## POST with JSON
+## Passing Parameters in URLs
+
+To append query parameters to a URL, pass a dictionary to the `params` argument:
 
 ```python
-import asyncio
-from wreq import Client
+params = {"search": "wreq", "page": "1"}
+response = await client.get("https://httpbin.org/get", params=params)
+print(response.url)
+# https://httpbin.org/get?search=wreq&page=1
+```
 
-async def main():
-    client = Client()
-    data = {"name": "John", "age": 30}
-    resp = await client.post("https://httpbin.org/post", json=data)
-    result = await resp.json()
-    print(result)
+---
+
+## Reading the Response
+
+### Status code
 
-asyncio.run(main())
+```python
+response = await client.get("https://httpbin.org/get")
+print(response.status_code)
+# 200
 ```
 
----
+### Text
+
+```python
+text = await response.text()
+print(text)
+```
 
-## Emulation
+### JSON
 
-Emulate different browsers to bypass detection:
+If the server returns a JSON body, parse it directly with `.json()`:
 
 ```python
-import asyncio
-from wreq import Client, Emulation
+response = await client.get("https://httpbin.org/json")
+data = await response.json()
+print(data)
+```
 
-async def main():
-    client = Client(emulation=Emulation.Safari26)
-    resp = await client.get("https://tls.peet.ws/api/all")
-    print(await resp.text())
+### Response headers
 
-asyncio.run(main())
+Response headers are available as a dictionary-like object:
+
+```python
+print(response.headers["content-type"])
+# application/json
 ```
 
 ---
 
-## Using Proxies
+## Sending Data
+
+### JSON body
+
+Pass a dictionary to the `json` argument and wreq will serialize it and set the correct `Content-Type` header automatically:
 
 The [Proxy](../guide/proxy.md) object defines how your HTTP client routes traffic through a proxy server.
 You create one using a named constructor that specifies the scope:
@@ -79,35 +108,87 @@ You create one using a named constructor that specifies the scope:
 Once created, you pass it to the `Client` and all requests will go through it automatically.
 
 ```python
-import asyncio
-from wreq import Client, Proxy
+payload = {"name": "John", "age": 30}
+response = await client.post("https://httpbin.org/post", json=payload)
+result = await response.json()
+print(result)
+```
+
+### Form-encoded data
 
-async def main():
-    client = Client(proxies=[Proxy.all("http://proxy.example.com:8080")])
-    resp = await client.get("https://httpbin.org/ip")
-    print(await resp.text())
+To send HTML form data, use the `data` argument instead:
 
-asyncio.run(main())
+```python
+form = {"username": "john", "password": "secret"}
+response = await client.post("https://httpbin.org/post", data=form)
 ```
 
 ---
 
 ## Custom Headers
 
+Pass a [HeaderMap](../api/header.md?h=HeaderMap#wreq.header.HeaderMap) to attach additional headers to a request:
+
 ```python
-import asyncio
-from wreq import Client
 from wreq.header import HeaderMap
 
-async def main():
-    client = Client()
-    headers = HeaderMap()
-    headers["User-Agent"] = "MyApp/1.0"
-    headers["Custom-Header"] = "value"
-    resp = await client.get("https://httpbin.org/headers", headers=headers)
-    print(await resp.text())
+headers = HeaderMap()
+headers["User-Agent"] = "MyApp/1.0"
+headers["Accept"] = "application/json"
+
+response = await client.get("https://httpbin.org/headers", headers=headers)
+print(await response.text())
+```
+
+---
+
+## Using Proxies
+
+The [Proxy](../guide/proxy.md) object controls how the client routes traffic. You create one using a named constructor that defines its scope:
+
+- `Proxy.all(url)` routes all traffic through the proxy.
+- `Proxy.http(url)` only intercepts plain HTTP requests.
+- `Proxy.https(url)` only intercepts HTTPS requests.
+
+Pass the proxy to the `Client` and every subsequent request will use it:
+
+```python
+from wreq import Client, Proxy
+
+client = Client(proxies=[Proxy.all("http://proxy.example.com:8080")])
+response = await client.get("https://httpbin.org/ip")
+print(await response.text())
+```
+
+---
+
+## Browser Emulation
+
+wreq can emulate the TLS fingerprint and headers of real browsers, which is useful when connecting to servers that inspect these signals. Pass an [Emulation](../guide/emulation.md) preset to the `Client`:
+
+```python
+from wreq import Client, Emulation
+
+client = Client(emulation=Emulation.Safari26)
+response = await client.get("https://tls.peet.ws/api/all")
+print(await response.text())
+```
+
+Available presets are listed in the [Emulation reference](../getting-started/introduction.md#behavior).
+
+---
+
+## Error Handling
+
+Check the status code manually, or call `raise_for_status()` to raise an exception on any 4xx or 5xx response:
+
+```python
+response = await client.get("https://httpbin.org/status/404")
 
-asyncio.run(main())
+try:
+    response.raise_for_status()
+except Exception as exc:
+    print(f"Request failed with status {response.status_code}")
 ```
 
 ---