docs: add example of Modify (redefine) response only to particular endpoint (#37)

* Add example of redefining particular endpoint

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* docs(CHANGELOG): update `CHANGELOG.md`

* docs: move inline code snippets in the documentation to separate files

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: WSH032 <614337162@qq.com>
Co-authored-by: Sean Wang <126865849+WSH032@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -23,6 +23,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- [#37](https://github.com/WSH032/fastapi-proxy-lib/pull/37) - docs: add example of `Modify (redefine) response only to particular endpoint`. Thanks [@pavelsr](https://github.com/pavelsr)!
+
 ### Changed
 
 - [#30](https://github.com/WSH032/fastapi-proxy-lib/pull/30) - fix(internal): use `websocket` in favor of `websocket_route`. Thanks [@WSH032](https://github.com/WSH032)!

docs/Usage/Advanced.md

@@ -30,27 +30,7 @@ See <https://www.python-httpx.org/advanced/#customizing-authentication>
 You can refer following example to implement a simple authentication:
 
 ```python
-import httpx
-from fastapi_proxy_lib.fastapi.app import reverse_http_app
-
-
-class MyCustomAuth(httpx.Auth):
-    # ref: https://www.python-httpx.org/advanced/#customizing-authentication
-
-    def __init__(self, token: str):
-        self.token = token
-
-    def auth_flow(self, request: httpx.Request):
-        # Send the request, with a custom `X-Authentication` header.
-        request.headers["X-Authentication"] = self.token
-        yield request
-
-
-app = reverse_http_app(
-    client=httpx.AsyncClient(auth=MyCustomAuth("bearer_token")),
-    base_url="http://www.httpbin.org/",
-)
-
+--8<-- "docs_src/advanced/modify-request.py"
 ```
 
 visit `/headers` to see the result which contains `"X-Authentication": "bearer_token"` header.
@@ -64,57 +44,24 @@ See [issue#15](https://github.com/WSH032/fastapi-proxy-lib/issues/15)
 You can refer following example to modify the response:
 
 ```python
-from contextlib import asynccontextmanager
-from typing import AsyncIterable, AsyncIterator, Union
-
-from fastapi import FastAPI
-from fastapi_proxy_lib.core.http import ReverseHttpProxy
-from starlette.requests import Request
-from starlette.responses import StreamingResponse
-
-AsyncContentStream = AsyncIterable[Union[str, bytes]]
-
-
-proxy = ReverseHttpProxy(base_url="http://www.example.com/")
-
-
-@asynccontextmanager
-async def close_proxy_event(_: FastAPI) -> AsyncIterator[None]:
-    """Close proxy."""
-    yield
-    await proxy.aclose()
-
-
-app = FastAPI(lifespan=close_proxy_event)
-
-
-async def new_content(origin_content: AsyncContentStream) -> AsyncContentStream:
-    """Fake content processing."""
-    async for chunk in origin_content:
-        # do some processing with chunk, e.g transcoding,
-        # here we just print and return it as an example.
-        print(chunk)
-        yield chunk
+--8<-- "docs_src/advanced/modify-response.py"
+```
 
+visit `/`, you will notice that the response body is printed to the console.
 
-@app.get("/{path:path}")
-async def _(request: Request, path: str = ""):
-    proxy_response = await proxy.proxy(request=request, path=path)
+## Modify (redefine) response only to particular endpoint
 
-    if isinstance(proxy_response, StreamingResponse):
-        # get the origin content stream
-        old_content = proxy_response.body_iterator
+```python
+--8<-- "docs_src/advanced/modify-response-particular.py"
+```
 
-        new_resp = StreamingResponse(
-            content=new_content(old_content),
-            status_code=proxy_response.status_code,
-            headers=proxy_response.headers,
-            media_type=proxy_response.media_type,
-        )
-        return new_resp
+In this example all requests except `GET /ip` will be passed to `httpbin.org`:
 
-    return proxy_response
+```bash
+# we assume your proxy server is running on `http://127.0.0.0:8000`
 
+# from `httpbin.org` which is proxied
+curl http://127.0.0.0:8000/user-agent   # { "user-agent": "curl/7.81.0" }
+# from your fastapi app
+curl http://127.0.0.0:8000/ip           # { "msg":"Method is redefined" }
 ```
-
-visit `/`, you will notice that the response body is printed to the console.

docs_src/advanced/modify-request.py

@@ -0,0 +1,24 @@
+from collections.abc import Generator
+from typing import Any
+
+import httpx
+from fastapi_proxy_lib.fastapi.app import reverse_http_app
+from httpx import Request
+
+
+class MyCustomAuth(httpx.Auth):
+    # ref: https://www.python-httpx.org/advanced/#customizing-authentication
+
+    def __init__(self, token: str):
+        self.token = token
+
+    def auth_flow(self, request: httpx.Request) -> Generator[Request, Any, None]:
+        # Send the request, with a custom `X-Authentication` header.
+        request.headers["X-Authentication"] = self.token
+        yield request
+
+
+app = reverse_http_app(
+    client=httpx.AsyncClient(auth=MyCustomAuth("bearer_token")),
+    base_url="http://www.httpbin.org/",
+)

docs_src/advanced/modify-response-particular.py

@@ -0,0 +1,27 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi_proxy_lib.core.http import ReverseHttpProxy
+from starlette.requests import Request
+
+proxy = ReverseHttpProxy(base_url="http://httpbin.org/")
+
+
+@asynccontextmanager
+async def close_proxy_event(_: FastAPI) -> AsyncIterator[None]:
+    """Close proxy."""
+    yield
+    await proxy.aclose()
+
+
+app = FastAPI(lifespan=close_proxy_event)
+
+
+@app.get("/{path:path}")
+@app.post("/{path:path}")
+async def _(request: Request, path: str = ""):
+    if path == "ip" and request.method == "GET":
+        return {"msg": "Method is redefined"}
+    else:
+        return await proxy.proxy(request=request, path=path)

docs_src/advanced/modify-response.py

@@ -0,0 +1,47 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi_proxy_lib.core.http import ReverseHttpProxy
+from starlette.requests import Request
+from starlette.responses import AsyncContentStream, StreamingResponse
+
+proxy = ReverseHttpProxy(base_url="http://www.example.com/")
+
+
+@asynccontextmanager
+async def close_proxy_event(_: FastAPI) -> AsyncIterator[None]:
+    """Close proxy."""
+    yield
+    await proxy.aclose()
+
+
+app = FastAPI(lifespan=close_proxy_event)
+
+
+async def new_content(origin_content: AsyncContentStream) -> AsyncContentStream:
+    """Fake content processing."""
+    async for chunk in origin_content:
+        # do some processing with chunk, e.g transcoding,
+        # here we just print and return it as an example.
+        print(chunk)
+        yield chunk
+
+
+@app.get("/{path:path}")
+async def _(request: Request, path: str = ""):
+    proxy_response = await proxy.proxy(request=request, path=path)
+
+    if isinstance(proxy_response, StreamingResponse):
+        # get the origin content stream
+        old_content = proxy_response.body_iterator
+
+        new_resp = StreamingResponse(
+            content=new_content(old_content),
+            status_code=proxy_response.status_code,
+            headers=proxy_response.headers,
+            media_type=proxy_response.media_type,
+        )
+        return new_resp
+
+    return proxy_response

mkdocs.yml

@@ -130,6 +130,7 @@ watch:
   - README.md
   - CONTRIBUTING.md
   - CHANGELOG.md
+  - docs_src/
 
 validation:
   omitted_files: warn

pyproject.toml

@@ -191,6 +191,9 @@ ignore = [
     # "SIM108",  # if-else-block-instead-of-if-exp
 ]
 
+[tool.ruff.lint.per-file-ignores]
+"docs_src/**/*.py" = ["D"]
+
 # https://docs.astral.sh/ruff/settings/#pydocstyle
 [tool.ruff.lint.pydocstyle]
 convention = "google"