WredDocs
Browse documentation

Documentation overview

Tutorial

Reference

Project

Development & contributing

Make a small change, demonstrate the behavior, and explain it clearly. The framework is tiny; the pull request does not need a cinematic universe.

Set up a checkout

Terminal
git clone https://gitman.io/git/patx/wred
cd wred
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[server]' pymongo servestatic

For the core framework alone, python -m pip install -e . installs Wred and orjson. Starlette and itsdangerous are only needed for the tutorial recipes using them.

Run the existing checks

The repository uses Python’s unittest runner. From the repository root:

Terminal
python -m unittest tests.test_wred
python -m unittest tests.test_example_app
python -m unittest discover -s tests

The core suite exercises request parsing, routes, responses, mounted paths, and protocol boundaries. The example-app suite needs PyMongo and ServeStatic installed. The database integration suite also imports those dependencies and is skipped unless its MongoDB URI is set.

Use a disposable MongoDB instance for integration checks:

Terminal
WRED_TEST_MONGODB_URI='mongodb://127.0.0.1:27017'   python -m unittest tests.test_notebook

The integration suite creates uniquely named databases beginning with wred_test_ and drops them during cleanup. The supplied credentials need permission for that work. Use a test database server, not production with a hopeful expression.

Keep changes reviewable

Start with the observable behavior you want to change. Keep Wred’s core focused on HTTP routing and responses; middleware and application modules are good homes for optional behavior. Explain any API or compatibility changes in the accompanying docs.

When adding a regression check, exercise the actual affected boundary and describe what would fail without the fix. Prefer a small meaningful case to a second copy of the implementation dressed as a test.

Edit and preview these docs

The documentation is plain HTML with shared CSS and JavaScript in docs/tutorial/. There is no framework build. Serve the docs directory to browse it locally:

Terminal
python -m http.server 8001 --bind 127.0.0.1 --directory docs

Open http://127.0.0.1:8001/tutorial/. The downloadable frontend example needs its ASGI server for its API; serving the documentation itself does not start that application.

After changing page text or adding a page, rebuild the offline search index:

Terminal
python docs/tutorial/build_search.py
node --check docs/tutorial/tutorial.js
git diff --check

Pages and navigation still work without JavaScript. Code-copy buttons and full-text search use the shared script; the search index is a local JavaScript file, so it also works without fetching a service.

Report a bug with a reproduction

Include the Wred and Python versions, the ASGI server and relevant options, a minimal app, the request you sent, the expected and actual responses, and the traceback if there is one. For proxy issues, say whether the same request works against the backend directly.

Remove passwords, tokens, cookies, database credentials, and personal data from examples. Use the project repository for ordinary bug reports and contributions. See deployment boundaries for vulnerability-reporting guidance.

License

Wred is distributed under the BSD 3-Clause license. The complete terms are in the repository’s LICENSE file; retain that file and the applicable notices when redistributing. This paragraph is a signpost to the license, not a replacement for it.