Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
7ee1c7eef9 |
5
.coveragerc
Normal file
5
.coveragerc
Normal file
@@ -0,0 +1,5 @@
|
||||
[run]
|
||||
omit=
|
||||
src/microdot_websocket_alt.py
|
||||
src/microdot_asgi_websocket.py
|
||||
src/microdot_ssl.py
|
||||
3
.flake8
Normal file
3
.flake8
Normal file
@@ -0,0 +1,3 @@
|
||||
[flake8]
|
||||
select = C,E,F,W,B,B950
|
||||
per-file-ignores = ./*/__init__.py:F401
|
||||
3
.github/FUNDING.yml
vendored
Normal file
3
.github/FUNDING.yml
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
github: miguelgrinberg
|
||||
patreon: miguelgrinberg
|
||||
custom: https://paypal.me/miguelgrinberg
|
||||
26
.github/ISSUE_TEMPLATE/bug_report.md
vendored
26
.github/ISSUE_TEMPLATE/bug_report.md
vendored
@@ -1,26 +0,0 @@
|
||||
---
|
||||
name: Bug report
|
||||
about: Create a report to help us improve
|
||||
title: ''
|
||||
labels: ''
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
**IMPORTANT**: If you have a question, or you are not sure if you have found a bug in this package, then you are in the wrong place. Hit back in your web browser, and then open a GitHub Discussion instead. Likewise, if you are unable to provide the information requested below, open a discussion to troubleshoot your issue.
|
||||
|
||||
**Describe the bug**
|
||||
A clear and concise description of what the bug is. If you are getting errors, please include the complete error message, including the stack trace.
|
||||
|
||||
**To Reproduce**
|
||||
Steps to reproduce the behavior:
|
||||
1. Go to '...'
|
||||
2. Click on '....'
|
||||
3. Scroll down to '....'
|
||||
4. See error
|
||||
|
||||
**Expected behavior**
|
||||
A clear and concise description of what you expected to happen.
|
||||
|
||||
**Additional context**
|
||||
Add any other context about the problem here.
|
||||
5
.github/ISSUE_TEMPLATE/config.yml
vendored
5
.github/ISSUE_TEMPLATE/config.yml
vendored
@@ -1,5 +0,0 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: GitHub Discussions
|
||||
url: https://github.com/miguelgrinberg/microdot/discussions
|
||||
about: Ask questions here.
|
||||
20
.github/ISSUE_TEMPLATE/feature_request.md
vendored
20
.github/ISSUE_TEMPLATE/feature_request.md
vendored
@@ -1,20 +0,0 @@
|
||||
---
|
||||
name: Feature request
|
||||
about: Suggest an idea for this project
|
||||
title: ''
|
||||
labels: ''
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
**Is your feature request related to a problem? Please describe.**
|
||||
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
|
||||
|
||||
**Describe the solution you'd like**
|
||||
A clear and concise description of what you want to happen.
|
||||
|
||||
**Describe alternatives you've considered**
|
||||
A clear and concise description of any alternative solutions or features you've considered.
|
||||
|
||||
**Additional context**
|
||||
Add any other context or screenshots about the feature request here.
|
||||
40
.github/workflows/tests.yml
vendored
40
.github/workflows/tests.yml
vendored
@@ -11,23 +11,22 @@ jobs:
|
||||
name: lint
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-python@v3
|
||||
- uses: actions/checkout@v2
|
||||
- uses: actions/setup-python@v2
|
||||
- run: python -m pip install --upgrade pip wheel
|
||||
- run: pip install tox tox-gh-actions
|
||||
- run: tox -eflake8
|
||||
- run: tox -edocs
|
||||
tests:
|
||||
name: tests
|
||||
strategy:
|
||||
matrix:
|
||||
os: [ubuntu-latest, macos-latest, windows-latest]
|
||||
python: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
|
||||
python: ['3.6', '3.7', '3.8', '3.9', '3.10']
|
||||
fail-fast: false
|
||||
runs-on: ${{ matrix.os }}
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-python@v3
|
||||
- uses: actions/checkout@v2
|
||||
- uses: actions/setup-python@v2
|
||||
with:
|
||||
python-version: ${{ matrix.python }}
|
||||
- run: python -m pip install --upgrade pip wheel
|
||||
@@ -37,40 +36,27 @@ jobs:
|
||||
name: tests-micropython
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-python@v3
|
||||
- uses: actions/checkout@v2
|
||||
- uses: actions/setup-python@v2
|
||||
- run: python -m pip install --upgrade pip wheel
|
||||
- run: pip install tox tox-gh-actions
|
||||
- run: tox -eupy
|
||||
tests-circuitpython:
|
||||
name: tests-circuitpython
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-python@v3
|
||||
- run: python -m pip install --upgrade pip wheel
|
||||
- run: pip install tox tox-gh-actions
|
||||
- run: tox -ecpy
|
||||
coverage:
|
||||
name: coverage
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-python@v3
|
||||
- uses: actions/checkout@v2
|
||||
- uses: actions/setup-python@v2
|
||||
- run: python -m pip install --upgrade pip wheel
|
||||
- run: pip install tox tox-gh-actions
|
||||
- run: pip install tox tox-gh-actions codecov
|
||||
- run: tox
|
||||
- uses: codecov/codecov-action@v3
|
||||
with:
|
||||
files: ./coverage.xml
|
||||
fail_ci_if_error: true
|
||||
token: ${{ secrets.CODECOV_TOKEN }}
|
||||
- run: codecov
|
||||
benchmark:
|
||||
name: benchmark
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-python@v3
|
||||
- uses: actions/checkout@v2
|
||||
- uses: actions/setup-python@v2
|
||||
- run: python -m pip install --upgrade pip wheel
|
||||
- run: pip install tox tox-gh-actions
|
||||
- run: tox -ebenchmark
|
||||
|
||||
9
.gitignore
vendored
9
.gitignore
vendored
@@ -25,8 +25,6 @@ wheels/
|
||||
.installed.cfg
|
||||
*.egg
|
||||
MANIFEST
|
||||
requirements.txt
|
||||
requirements-dev.txt
|
||||
|
||||
# PyInstaller
|
||||
# Usually these files are written by a python script from a template
|
||||
@@ -92,8 +90,6 @@ venv/
|
||||
ENV/
|
||||
env.bak/
|
||||
venv.bak/
|
||||
.direnv
|
||||
.envrc
|
||||
|
||||
# Spyder project settings
|
||||
.spyderproject
|
||||
@@ -107,8 +103,3 @@ venv.bak/
|
||||
|
||||
# mypy
|
||||
.mypy_cache/
|
||||
|
||||
# other
|
||||
*.der
|
||||
*.pem
|
||||
*_txt.py
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
version: 2
|
||||
|
||||
build:
|
||||
os: ubuntu-22.04
|
||||
tools:
|
||||
python: "3.11"
|
||||
|
||||
sphinx:
|
||||
configuration: docs/conf.py
|
||||
|
||||
python:
|
||||
install:
|
||||
- method: pip
|
||||
path: .
|
||||
extra_requirements:
|
||||
- docs
|
||||
212
CHANGES.md
212
CHANGES.md
@@ -1,217 +1,5 @@
|
||||
# Microdot change log
|
||||
|
||||
**Release 2.5.0** - 2025-12-21
|
||||
|
||||
- CSRF protection [#335](https://github.com/miguelgrinberg/microdot/issues/335) ([commit](https://github.com/miguelgrinberg/microdot/commit/0bae4c9477e9fdb231d1979cc6ed26c31e12b1aa))
|
||||
- Added support for ASGI lifespan events [#322](https://github.com/miguelgrinberg/microdot/issues/322) ([commit](https://github.com/miguelgrinberg/microdot/commit/f128b3ded45ccd418a00d199769240342a613b5e))
|
||||
- Added `scheme` and `route` attributes to the request object ([commit](https://github.com/miguelgrinberg/microdot/commit/1c7020ca1a3e5a6a1549dc52de38a0b7fd0a439a))
|
||||
- Added `Login.get_current_user()` helper method ([commit](https://github.com/miguelgrinberg/microdot/commit/053b8a81380fcdf285592a32e6b590ee50b7d048))
|
||||
|
||||
**Release 2.4.0** - 2025-11-08
|
||||
|
||||
- SSE: Add support for the retry command and keepalive comments ([commit](https://github.com/miguelgrinberg/microdot/commit/d0808efa6b32e00992596f1bb3d4c3a372df2168))
|
||||
- Ignore `expires` and `max_age` arguments if passed to `Response.delete_cookie` [#323](https://github.com/miguelgrinberg/microdot/issues/323) ([commit](https://github.com/miguelgrinberg/microdot/commit/d61785b2e8d18438e5031de9c49e61642e5cfb3f))
|
||||
- Ignore "muted" errors during request creation ([commit](https://github.com/miguelgrinberg/microdot/commit/ce9de6e37a6323664eb7666b817932f371f1e099))
|
||||
- Add package version to `microdot/__init__.py` file [#312](https://github.com/miguelgrinberg/microdot/issues/312) ([commit](https://github.com/miguelgrinberg/microdot/commit/38f5a27b33c7968fc7414b67742e034e2b9a09ca))
|
||||
|
||||
**Release 2.3.5** - 2025-10-18
|
||||
|
||||
- Always encode ASGI response bodies to bytes ([commit](https://github.com/miguelgrinberg/microdot/commit/f70c524fb0bdc8c5fef2223c82f5e339445bc5fa))
|
||||
- Remove unused instance variable in `Microdot` class ([commit](https://github.com/miguelgrinberg/microdot/commit/27fc03f10047e4483f8d19559025d728b14a27c8))
|
||||
|
||||
**Release 2.3.4** - 2025-10-16
|
||||
|
||||
- Prevent reading past EOF in multipart parser [#309](https://github.com/miguelgrinberg/microdot/issues/309) ([commit](https://github.com/miguelgrinberg/microdot/commit/6045390cef8735cbbc9f5f7eee7a3912f00e284d))
|
||||
- Generate a valid CORS response when the request is badly formatted [#305](https://github.com/miguelgrinberg/microdot/issues/305) ([commit](https://github.com/miguelgrinberg/microdot/commit/cca0b0f693c909134bc19eb41dfb5a86226e032b))
|
||||
- Faster HTTP streaming when using ASGI [#318](https://github.com/miguelgrinberg/microdot/issues/318) ([commit](https://github.com/miguelgrinberg/microdot/commit/7addcf4bb51f1caf57663c5bb4d8cc16ee6391e1))
|
||||
- Parse empty cookies [#308](https://github.com/miguelgrinberg/microdot/issues/308) ([commit](https://github.com/miguelgrinberg/microdot/commit/c12d4658091ff7eec1ac67c83bcd51eb38af9db7))
|
||||
- Add weather dashboard example [#303](https://github.com/miguelgrinberg/microdot/issues/303) ([commit](https://github.com/miguelgrinberg/microdot/commit/7071358b1f95892b1342226b43411e036be67d3a))
|
||||
- Add Python 3.13 and 3.14 to the CI builds ([commit](https://github.com/miguelgrinberg/microdot/commit/e9c9937b41e652876241307307f3e855f4f07379))
|
||||
|
||||
**Release 2.3.3** - 2025-07-01
|
||||
|
||||
- Handle partial reads in WebSocket class [#294](https://github.com/miguelgrinberg/microdot/issues/294) ([commit](https://github.com/miguelgrinberg/microdot/commit/9bc3dced6c1f582dde0496961d25170b448ad8d7))
|
||||
- Add SVG to supported mimetypes [#302](https://github.com/miguelgrinberg/microdot/issues/302) ([commit](https://github.com/miguelgrinberg/microdot/commit/1d419ce59bf7006617109c05dc2d6fc6d1dc8235)) (thanks **Ozuba**!)
|
||||
- Do not silence exceptions that occur in the SSE task ([commit](https://github.com/miguelgrinberg/microdot/commit/654a85f46b7dd7a1e94f81193c4a78a8a1e99936))
|
||||
- Add Support for SSE responses in the test client ([commit](https://github.com/miguelgrinberg/microdot/commit/f5d3d931edfbacedebf5fdf938ef77c5ee910380))
|
||||
- Documentation improvements for the `Request` class ([commit](https://github.com/miguelgrinberg/microdot/commit/3dffa05ffb229813156b71e10a85283bdaa26d5e))
|
||||
- Additional documentation for the `URLPattern` class ([commit](https://github.com/miguelgrinberg/microdot/commit/786e5e533748e1343612c97123773aec9a1a99fc))
|
||||
- More detailed documentation for route responses ([commit](https://github.com/miguelgrinberg/microdot/commit/dc61470fa959549bb43313906ba6ed9f686babc2))
|
||||
- Additional documentation on WebSocket and SSE disconnections ([commit](https://github.com/miguelgrinberg/microdot/commit/7c98c4589de4774a88381b393444c75094532550))
|
||||
- More detailed documentation for `current_user` ([commit](https://github.com/miguelgrinberg/microdot/commit/e146e2d08deddf9b924c7657f04db28d71f34221))
|
||||
- Add a sub-application example ([commit](https://github.com/miguelgrinberg/microdot/commit/d7a9c535639268e415714b12ac898ae38e516308))
|
||||
|
||||
**Release 2.3.2** - 2025-05-08
|
||||
|
||||
- Use async error handlers in auth module [#298](https://github.com/miguelgrinberg/microdot/issues/298) ([commit](https://github.com/miguelgrinberg/microdot/commit/d9d7ff0825e4c5fbed6564d3684374bf3937df11))
|
||||
|
||||
**Release 2.3.1** - 2025-04-13
|
||||
|
||||
- Additional support needed when using `orjson` ([commit](https://github.com/miguelgrinberg/microdot/commit/cd0b3234ddb0c8ff4861d369836ec2aed77494db))
|
||||
|
||||
**Release 2.3.0** - 2025-04-12
|
||||
|
||||
- Support optional authentication methods ([commit](https://github.com/miguelgrinberg/microdot/commit/f317b15bdbf924007e5e3414e0c626baccc3ede6))
|
||||
- Catch SSL exceptions while writing the response [#206](https://github.com/miguelgrinberg/microdot/issues/206) ([commit](https://github.com/miguelgrinberg/microdot/commit/e7ee74d6bba74cfd89b9ddc38f28e02514eb1791))
|
||||
- Use `orjson` instead of `json` if available ([commit](https://github.com/miguelgrinberg/microdot/commit/086f2af3deab86d4340f3f1feb9e019de59f351d))
|
||||
- Addressed typing warnings from pyright ([commit](https://github.com/miguelgrinberg/microdot/commit/b6f232db1125045d79c444c736a2ae59c5501fdd))
|
||||
|
||||
**Release 2.2.0** - 2025-03-22
|
||||
|
||||
- Support for `multipart/form-data` requests [#287](https://github.com/miguelgrinberg/microdot/issues/287) ([commit](https://github.com/miguelgrinberg/microdot/commit/11a91a60350518e426b557fae8dffe75912f8823))
|
||||
- Support custom path components in URLs ([commit #1](https://github.com/miguelgrinberg/microdot/commit/c92b5ae28222af5a1094f5d2f70a45d4d17653d5) [commit #2](https://github.com/miguelgrinberg/microdot/commit/aa76e6378b37faab52008a8aab8db75f81b29323))
|
||||
- Expose the Jinja environment as `Template.jinja_env` ([commit](https://github.com/miguelgrinberg/microdot/commit/953dd9432122defe943f0637bbe7e01f2fc7743f))
|
||||
- Simplified urldecode logic ([commit #1](https://github.com/miguelgrinberg/microdot/commit/3bc31f10b2b2d4460c62366013278d87665f0f97) [commit #2](https://github.com/miguelgrinberg/microdot/commit/d203df75fef32c7cc0fe7cc6525e77522b37a289))
|
||||
- Additional urldecode tests ([commit](https://github.com/miguelgrinberg/microdot/commit/99f65c0198590c0dfb402c24685b6f8dfba1935d))
|
||||
- Documentation improvements ([commit](https://github.com/miguelgrinberg/microdot/commit/c6b99b6d8117d4e40e16d5b953dbf4deb023d24d))
|
||||
- Update micropython version used in tests to 1.24.1 ([commit](https://github.com/miguelgrinberg/microdot/commit/4cc2e95338a7de3b03742389004147ee21285621))
|
||||
|
||||
**Release 2.1.0** - 2025-02-04
|
||||
|
||||
- User login support ([commit](https://github.com/miguelgrinberg/microdot/commit/d807011ad006e53e70c4594d7eac04d03bb08681))
|
||||
- Basic and token authentication support ([commit](https://github.com/miguelgrinberg/microdot/commit/675c9787974da926af446974cd96ef224e0ee27f))
|
||||
- Added `local` argument to the `app.mount()` method, to define sub-application specific before and after request handlers ([commit](https://github.com/miguelgrinberg/microdot/commit/fd7931e1aec173c60f81dad18c1a102ed8f0e081))
|
||||
- Added `Request.url_prefix`, `Request.subapp` and local mounts ([commit](https://github.com/miguelgrinberg/microdot/commit/fd7931e1aec173c60f81dad18c1a102ed8f0e081))
|
||||
- Added a front end to the SSE example [#281](https://github.com/miguelgrinberg/microdot/issues/281) ([commit](https://github.com/miguelgrinberg/microdot/commit/d487a73c1ea5b3467e23907618b348ca52e0235c)) (thanks **Maxi**!)
|
||||
- Additional ``app.mount()`` unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/cd87abba30206ec6d3928e0aabacb2fccf7baf70))
|
||||
|
||||
**Release 2.0.7** - 2024-11-10
|
||||
|
||||
- Accept responses with just a status code [#263](https://github.com/miguelgrinberg/microdot/issues/263) ([commit #1](https://github.com/miguelgrinberg/microdot/commit/4eac013087f807cafa244b8a6b7b0ed4c82ff150) [commit #2](https://github.com/miguelgrinberg/microdot/commit/c46e4291061046f1be13f300dd08645b71c16635))
|
||||
- Fixed compressed file content-type assignment [#251](https://github.com/miguelgrinberg/microdot/issues/251) ([commit](https://github.com/miguelgrinberg/microdot/commit/482ab6d5ca068d71ea6301f45918946161e9fcc1)) (thanks **Lukas Kremla**!)
|
||||
- Better documentation for start_server[#252](https://github.com/miguelgrinberg/microdot/issues/252) ([commit](https://github.com/miguelgrinberg/microdot/commit/0a021462e0c42c249d587a2d600f5a21a408adfc))
|
||||
- Fix URLs in documentation [#253](https://github.com/miguelgrinberg/microdot/issues/253) ([commit](https://github.com/miguelgrinberg/microdot/commit/5e5fc5e93e11cbf6e3dc8036494e8732d1815d3e)) (thanks **Stanislav Garanzha**!)
|
||||
|
||||
**Release 2.0.6** - 2024-06-18
|
||||
|
||||
- Add event ID to the SSE implementation [#213](https://github.com/miguelgrinberg/microdot/issues/213) ([commit](https://github.com/miguelgrinberg/microdot/commit/904d5fcaa2d19d939a719b8e68c4dee3eb470739)) (thanks **Hamsanger**!)
|
||||
- Configurable session cookie options [#242](https://github.com/miguelgrinberg/microdot/issues/242) ([commit](https://github.com/miguelgrinberg/microdot/commit/0151611fc84fec450820d673f4c4d70c32c990a7))
|
||||
- Improved cookie support in the test client ([commit](https://github.com/miguelgrinberg/microdot/commit/4cb155ee411dc2d9c9f15714cb32b25ba79b156a))
|
||||
- Cookie path support in session extension and test client ([commit](https://github.com/miguelgrinberg/microdot/commit/6ffb8a8fe920111c4d8c16e98715a0d5ee2d1da3))
|
||||
- Refactor `Session` class to make it more reusable ([commit](https://github.com/miguelgrinberg/microdot/commit/dea79c5ce224dec7858ffef45a42bed442fd3a5a))
|
||||
- Use `@functools.wraps` on decorated functions ([commit](https://github.com/miguelgrinberg/microdot/commit/f6876c0d154adcae96098405fb6a1fdf1ea4ec28))
|
||||
- Removed outdated import from documentation [#216](https://github.com/miguelgrinberg/microdot/issues/216) ([commit](https://github.com/miguelgrinberg/microdot/commit/6b1fd6191702e7a9ad934fddfcdd0a3cebea7c94)) (thanks **Carlo Colombo**!)
|
||||
- Add roadmap details to readme ([commit](https://github.com/miguelgrinberg/microdot/commit/a0ea439def238084c4d68309c0992b66ffd28ad6))
|
||||
|
||||
**Release 2.0.5** - 2024-03-09
|
||||
|
||||
- Correct handling of 0 as an integer argument (regression from #207) [#212](https://github.com/miguelgrinberg/microdot/issues/212) ([commit](https://github.com/miguelgrinberg/microdot/commit/d0a4cf8fa7dfb1da7466157b18d3329a8cf9a5df))
|
||||
|
||||
**Release 2.0.4** - 2024-02-20
|
||||
|
||||
- Do not use regexes for parsing simple URLs [#207](https://github.com/miguelgrinberg/microdot/issues/207) ([commit #1](https://github.com/miguelgrinberg/microdot/commit/38262c56d34784401659639b482a4a1224e1e59a) [commit #2](https://github.com/miguelgrinberg/microdot/commit/f6cba2c0f7e18e2f32b5adb779fb037b6c473eab))
|
||||
- Added documentation on using alternative uTemplate loaders ([commit](https://github.com/miguelgrinberg/microdot/commit/bf519478cbc6e296785241cd7d01edb23c317cd3))
|
||||
- Added CircuitPython builds ([commit](https://github.com/miguelgrinberg/microdot/commit/e44c271bae88f4327d3eda16d8780ac264d1ebab))
|
||||
|
||||
**Release 2.0.3** - 2024-01-07
|
||||
|
||||
- Add a limit to WebSocket message size [#193](https://github.com/miguelgrinberg/microdot/issues/193) ([commit](https://github.com/miguelgrinberg/microdot/commit/5d188e8c0ddef6ce633ca702dbdd4a90f2799597))
|
||||
- Pass keyword arguments to thread executor in the correct way [#195](https://github.com/miguelgrinberg/microdot/issues/195) ([commit](https://github.com/miguelgrinberg/microdot/commit/6712c47400d7c426c88032f65ab74466524eccab))
|
||||
- Update uasyncio library used in tests to include new TLS support ([commit](https://github.com/miguelgrinberg/microdot/commit/c8c91e83457d24320f22c9a74e80b15e06b072ca))
|
||||
- Documentation improvements ([commit](https://github.com/miguelgrinberg/microdot/commit/b80b6b64d02d21400ca8a5077f5ed1127cc202ae))
|
||||
|
||||
**Release 2.0.2** - 2023-12-28
|
||||
|
||||
- Support binary data in the SSE extension ([commit](https://github.com/miguelgrinberg/microdot/commit/1fc11193da0d298f5539e2ad218836910a13efb2))
|
||||
- Upgrade micropython tests to use v1.22 + initial CircuitPython testing work ([commit](https://github.com/miguelgrinberg/microdot/commit/79452a46992351ccad2c0317c20bf50be0d76641))
|
||||
- Improvements to migration guide ([commit](https://github.com/miguelgrinberg/microdot/commit/84842e39c360a8b3ddf36feac8af201fb19bbb0b))
|
||||
- Remove spurious async in documentation example [#187](https://github.com/miguelgrinberg/microdot/issues/187) ([commit](https://github.com/miguelgrinberg/microdot/commit/ad368be993e2e3007579f1d3880e36d60c71da92)) (thanks **Tak Tran**!)
|
||||
|
||||
**Release 2.0.1** - 2023-12-23
|
||||
|
||||
- Addressed some inadvertent mistakes in the template extensions ([commit](https://github.com/miguelgrinberg/microdot/commit/bd18ceb4424e9dfb52b1e6d498edd260aa24fc53))
|
||||
|
||||
**Release 2.0.0** - 2023-12-22
|
||||
|
||||
- Major redesign [#186](https://github.com/miguelgrinberg/microdot/issues/186) ([commit](https://github.com/miguelgrinberg/microdot/commit/20ea305fe793eb206b52af9eb5c5f3c1e9f57dbb))
|
||||
- Code reorganization as a `microdot` package
|
||||
- Asyncio is now the core implementation
|
||||
- New support for Server-Sent Events (SSE)
|
||||
- Several extensions redesigned
|
||||
- Support for "partitioned" cookies
|
||||
- [Cross-compiling and freezing](https://microdot.readthedocs.io/en/stable/freezing.html) guidance
|
||||
- A [Migration Guide](https://microdot.readthedocs.io/en/stable/migrating.html) to help transition to version 2 from older releases
|
||||
|
||||
**Release 1.3.4** - 2023-11-08
|
||||
|
||||
- Handle change in `wait_closed()` behavior in Python 3.12 [#177](https://github.com/miguelgrinberg/microdot/issues/177) ([commit](https://github.com/miguelgrinberg/microdot/commit/5550b20cdd347d59e2aa68f6ebf9e9abffaff9fc))
|
||||
- Added missing request argument in some documentation examples [#163](https://github.com/miguelgrinberg/microdot/issues/163) ([commit](https://github.com/miguelgrinberg/microdot/commit/744548f8dc33a72512b34c4001ee9c6c1edd22ee))
|
||||
- Fix minor documentation typos [#161](https://github.com/miguelgrinberg/microdot/issues/161) ([commit](https://github.com/miguelgrinberg/microdot/commit/2e4911d10826cbb3914de4a45e495c3be36543fa)) (thanks **Andy Piper**!)
|
||||
|
||||
**Release 1.3.3** - 2023-07-16
|
||||
|
||||
- Handle query string arguments without value [#149](https://github.com/miguelgrinberg/microdot/issues/149) ([commit](https://github.com/miguelgrinberg/microdot/commit/3554bc91cb1523efa5b66fe3ef173f8e86e8c2a0))
|
||||
- Support empty responses with ASGI adapter ([commit](https://github.com/miguelgrinberg/microdot/commit/e09e9830f43af41d38775547637558494151a385))
|
||||
- Added CORS extension to Python package ([commit](https://github.com/miguelgrinberg/microdot/commit/304ca2ef6881fe718126b3e308211e760109d519))
|
||||
- Document access to WSGI and ASGI attributes [#153](https://github.com/miguelgrinberg/microdot/issues/153) ([commit](https://github.com/miguelgrinberg/microdot/commit/d99df2c4010ab70c60b86ab334d656903e04eb26))
|
||||
- Upgrade micropython tests to use v1.20 ([commit](https://github.com/miguelgrinberg/microdot/commit/e0f0565551966ee0238a5a1819c78a13639ad704))
|
||||
|
||||
**Release 1.3.2** - 2023-06-13
|
||||
|
||||
- In ASGI, return headers as strings and not binary [#144](https://github.com/miguelgrinberg/microdot/issues/144) ([commit](https://github.com/miguelgrinberg/microdot/commit/e92310fa55bbffcdcbb33f560e27c3579d7ac451))
|
||||
- Incorrect import in `static_async.py` example ([commit](https://github.com/miguelgrinberg/microdot/commit/c07a53943508e64baea160748e67efc92e75b036))
|
||||
|
||||
**Release 1.3.1** - 2023-05-21
|
||||
|
||||
- Support negative numbers for int path components [#137](https://github.com/miguelgrinberg/microdot/issues/137) ([commit](https://github.com/miguelgrinberg/microdot/commit/a0dd7c8ab6d681932324e56ed101aba861a105a0))
|
||||
- Use a more conservative default for socket timeout [#130](https://github.com/miguelgrinberg/microdot/issues/130) ([commit](https://github.com/miguelgrinberg/microdot/commit/239cf4ff37268a7e2467b93be44fe9f91cee8aee))
|
||||
- More robust check for socket timeout error code [#106](https://github.com/miguelgrinberg/microdot/issues/106) ([commit](https://github.com/miguelgrinberg/microdot/commit/efec9f14be7b6f3451e4d1d0fe7e528ce6ca74dc))
|
||||
- WebSocket error when handling PING packet [#129](https://github.com/miguelgrinberg/microdot/issues/129) ([commit](https://github.com/miguelgrinberg/microdot/commit/87cd098f66e24bed6bbad29b1490a129e355bbb3))
|
||||
- Explicitly set UTF-8 encoding for HTML files in examples [#132](https://github.com/miguelgrinberg/microdot/issues/132) ([commit](https://github.com/miguelgrinberg/microdot/commit/f81de6d9582f4905b9c2735d3c639b92d7e77994))
|
||||
|
||||
**Release 1.3.0** - 2023-04-08
|
||||
|
||||
- Cross-Origin Resource Sharing (CORS) extension [#45](https://github.com/miguelgrinberg/microdot/issues/45) ([commit](https://github.com/miguelgrinberg/microdot/commit/67798f7dbffb30018ab4b62a9aaa297f63bc9e64))
|
||||
- Respond to `HEAD` and `OPTIONS` requests ([commit](https://github.com/miguelgrinberg/microdot/commit/6a31f89673518e79fef5659c04e609b7976a5e34))
|
||||
- Tolerate slightly invalid formats in query strings [#126](https://github.com/miguelgrinberg/microdot/issues/126) ([commit](https://github.com/miguelgrinberg/microdot/commit/a1b061656fa19dae583951596b0f1f0603652a56))
|
||||
- Support compressed files in `send_file()` [#93](https://github.com/miguelgrinberg/microdot/issues/93) ([commit](https://github.com/miguelgrinberg/microdot/commit/daf1001ec55ab38e6cdfee4931729a3b7506858b))
|
||||
- Add `max_age` argument to `send_file()` ([commit](https://github.com/miguelgrinberg/microdot/commit/e684ee32d91d3e2ab9569bb5fd342986c010ffeb))
|
||||
- Add `update()` method to `NoCaseDict` class ([commit](https://github.com/miguelgrinberg/microdot/commit/ea6766cea96b756b36ed777f9c1b6a6680db09ba))
|
||||
- Set exit code to 1 for failed MicroPython test runs ([commit](https://github.com/miguelgrinberg/microdot/commit/a350e8fd1e55fac12c9e5b909cfa82d880b177ef))
|
||||
|
||||
**Release 1.2.4** - 2023-03-03
|
||||
|
||||
- One more attempt to correct build issues ([commit](https://github.com/miguelgrinberg/microdot/commit/cb39898829f4edc233ab4e7ba3f7ef3c5c50f196))
|
||||
|
||||
**Release 1.2.3** - 2023-03-03
|
||||
|
||||
- Corrected a problem with previous build.
|
||||
|
||||
**Release 1.2.2** - 2023-03-03
|
||||
|
||||
- Add a socket read timeout to abort incomplete requests [#99](https://github.com/miguelgrinberg/microdot/issues/99) ([commit](https://github.com/miguelgrinberg/microdot/commit/d0d358f94a63f8565d6406feff0c6e7418cc7f81))
|
||||
- More robust timeout handling [#106](https://github.com/miguelgrinberg/microdot/issues/106) ([commit](https://github.com/miguelgrinberg/microdot/commit/4d432a7d6cd88b874a8b825fb62891ed22881f74))
|
||||
- Add @after_error_handler decorator [#97](https://github.com/miguelgrinberg/microdot/issues/97) ([commit](https://github.com/miguelgrinberg/microdot/commit/fcaeee69052b5681706f65b022e667baeee30d4d))
|
||||
- Return headers as lowercase byte sequences as required by ASGI ([commit](https://github.com/miguelgrinberg/microdot/commit/ddb3b8f442d3683df04554104edaf8acd9c68148))
|
||||
- Async example of static file serving ([commit](https://github.com/miguelgrinberg/microdot/commit/680cd9c023352f0ff03d67f1041ea174b7b7385b))
|
||||
- Fixing broken links to examples in documentation [#101](https://github.com/miguelgrinberg/microdot/issues/101) ([commit](https://github.com/miguelgrinberg/microdot/commit/c00b24c9436e1b8f3d4c9bb6f2adfca988902e91)) (thanks **Eric Welch**!)
|
||||
- Add scrollbar to documentation's left sidebar ([commit](https://github.com/miguelgrinberg/microdot/commit/2aa90d42451dc64c84efcc4f40a1b6c8d1ef1e8d))
|
||||
- Documentation typo [#90](https://github.com/miguelgrinberg/microdot/issues/90) ([commit](https://github.com/miguelgrinberg/microdot/commit/81394980234f24aac834faf8e2e8225231e9014b)) (thanks **William Wheeler**!)
|
||||
- Add CPU timing to benchmark ([commit](https://github.com/miguelgrinberg/microdot/commit/9398c960752f87bc32d7c4349cbf594e5d678e99))
|
||||
- Upgrade uasyncio release used in tests ([commit](https://github.com/miguelgrinberg/microdot/commit/3d6815119ca1ec989f704f626530f938c857a8e5))
|
||||
- Update unittest library for MicroPython ([commit](https://github.com/miguelgrinberg/microdot/commit/ecd84ecb7bd3c29d5af96739442b908badeab804))
|
||||
- New build of micropython for unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/818f98d9a4e531e01c0f913813425ab2b40c289d))
|
||||
- Remove 3.6, add 3.11 to builds ([commit](https://github.com/miguelgrinberg/microdot/commit/dd15d90239b73b5fd413515c9cd4ac23f6d42f67))
|
||||
|
||||
**Release 1.2.1** - 2022-12-06
|
||||
|
||||
- Error handling invokes parent exceptions [#74](https://github.com/miguelgrinberg/microdot/issues/74) ([commit](https://github.com/miguelgrinberg/microdot/commit/24d74fb8483b04e8abe6e303e06f0a310f32700b)) (thanks **Diego Pomares**!)
|
||||
- Addressed error when deleting a user session in async app [#86](https://github.com/miguelgrinberg/microdot/issues/86) ([commit](https://github.com/miguelgrinberg/microdot/commit/5a589afd5e519e94e84fc1ee69033f2dad51c3ea))
|
||||
- Add asyncio file upload example ([commit](https://github.com/miguelgrinberg/microdot/commit/c841cbedda40f59a9d87f6895fdf9fd954f854a2))
|
||||
- New Jinja and uTemplate examples with Bootstrap ([commit](https://github.com/miguelgrinberg/microdot/commit/211ad953aeedb4c7f73fe210424aa173b4dc7fee))
|
||||
- Fix typos in documentation [#77](https://github.com/miguelgrinberg/microdot/issues/77) ([commit](https://github.com/miguelgrinberg/microdot/commit/4a9b92b800d3fd87110f7bc9f546c10185ee13bc)) (thanks **Diego Pomares**!)
|
||||
- Add missing exception argument to error handler example in documentation [#73](https://github.com/miguelgrinberg/microdot/issues/73) ([commit](https://github.com/miguelgrinberg/microdot/commit/c443599089f2127d1cb052dfba8a05c1969d65e3)) (thanks **Diego Pomares**!)
|
||||
|
||||
**Release 1.2.0** - 2022-09-25
|
||||
|
||||
- Use a case insensitive dict for headers ([commit #1](https://github.com/miguelgrinberg/microdot/commit/b0fd6c432371ca5cb10d07ff84c4deed7aa0ce2e) [commit #2](https://github.com/miguelgrinberg/microdot/commit/a8515c97b030f942fa6ca85cbe1772291468fb0d))
|
||||
- urlencode() helper function ([commit #1](https://github.com/miguelgrinberg/microdot/commit/672512e086384e808489305502e6ebebcc5a888f) [commit #2](https://github.com/miguelgrinberg/microdot/commit/b133dcc34368853ee685396a1bcb50360e807813))
|
||||
- Added `request.url` attribute with the complete URL of the request ([commit](https://github.com/miguelgrinberg/microdot/commit/1547e861ee28d43d10fe4c4ed1871345d4b81086))
|
||||
- Do not log HTTPException occurrences ([commit](https://github.com/miguelgrinberg/microdot/commit/cbefb6bf3a3fdcff8b7a8bacad3449be18e46e3b))
|
||||
- Cache user session for performance ([commit](https://github.com/miguelgrinberg/microdot/commit/01947b101ebe198312c88d73872e3248024918f0))
|
||||
- File upload example ([commit](https://github.com/miguelgrinberg/microdot/commit/8ebe81c09b604ddc1123e78ad6bc87ceda5f8597))
|
||||
- Minor documentation styling fixes ([commit](https://github.com/miguelgrinberg/microdot/commit/4f263c63ab7bb1ce0dd48d8e00f3c6891e1bf07e))
|
||||
|
||||
**Release 1.1.1** - 2022-09-18
|
||||
|
||||
- Make WebSocket internals consistent between TLS and non-TLS [#61](https://github.com/miguelgrinberg/microdot/issues/61) ([commit](https://github.com/miguelgrinberg/microdot/commit/5693b812ceb2c0d51ec3c991adf6894a87e6fcc7))
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
include README.md LICENSE tox.ini
|
||||
recursive-include docs *
|
||||
recursive-exclude docs/_build *
|
||||
recursive-include tests *
|
||||
exclude **/*.pyc
|
||||
28
README.md
28
README.md
@@ -3,9 +3,9 @@
|
||||
|
||||
*“The impossibly small web framework for Python and MicroPython”*
|
||||
|
||||
Microdot is a minimalistic Python web framework inspired by Flask. Given its
|
||||
small size, it can run on systems with limited resources such as
|
||||
microcontrollers. Both standard Python (CPython) and MicroPython are supported.
|
||||
Microdot is a minimalistic Python web framework inspired by Flask, and designed
|
||||
to run on systems with limited resources such as microcontrollers. It runs on
|
||||
standard Python and on MicroPython.
|
||||
|
||||
```python
|
||||
from microdot import Microdot
|
||||
@@ -13,7 +13,7 @@ from microdot import Microdot
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
async def index(request):
|
||||
def index(request):
|
||||
return 'Hello, world!'
|
||||
|
||||
app.run()
|
||||
@@ -21,23 +21,5 @@ app.run()
|
||||
|
||||
## Resources
|
||||
|
||||
- [Documentation](https://microdot.readthedocs.io/en/latest/)
|
||||
- [Change Log](https://github.com/miguelgrinberg/microdot/blob/main/CHANGES.md)
|
||||
- Documentation
|
||||
- [Latest](https://microdot.readthedocs.io/en/latest/)
|
||||
- [Stable (v2)](https://microdot.readthedocs.io/en/stable/)
|
||||
- Legacy (v1)
|
||||
- [Code](https://github.com/miguelgrinberg/microdot/tree/v1)
|
||||
- [Documentation](https://microdot.readthedocs.io/en/v1/)
|
||||
|
||||
## Roadmap
|
||||
|
||||
The following features are planned for future releases of Microdot, both for
|
||||
MicroPython and CPython:
|
||||
|
||||
- Authentication support, similar to [Flask-Login](https://github.com/maxcountryman/flask-login) for Flask (**Added in version 2.1**)
|
||||
- Support for forms encoded in `multipart/form-data` format (**Added in version 2.2**)
|
||||
- CSRF protection extension
|
||||
- Pub/sub mini-framework for WebSocket and SSE
|
||||
- OpenAPI integration, similar to [APIFairy](https://github.com/miguelgrinberg/apifairy) for Flask
|
||||
|
||||
Do you have other ideas to propose? Let's [discuss them](https://github.com/:miguelgrinberg/microdot/discussions/new?category=ideas)!
|
||||
|
||||
Binary file not shown.
BIN
bin/micropython
BIN
bin/micropython
Binary file not shown.
5
docs/_static/css/custom.css
vendored
5
docs/_static/css/custom.css
vendored
@@ -1,8 +1,3 @@
|
||||
.py.class, .py.function, .py.method, .py.property {
|
||||
margin-top: 20px;
|
||||
}
|
||||
|
||||
div.sphinxsidebar {
|
||||
max-height: 100%;
|
||||
overflow-y: auto;
|
||||
}
|
||||
|
||||
109
docs/api.rst
Normal file
109
docs/api.rst
Normal file
@@ -0,0 +1,109 @@
|
||||
API Reference
|
||||
=============
|
||||
|
||||
``microdot`` module
|
||||
-------------------
|
||||
|
||||
.. autoclass:: microdot.Microdot
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot.Request
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot.Response
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot.NoCaseDict
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot.MultiDict
|
||||
:members:
|
||||
|
||||
``microdot_asyncio`` module
|
||||
---------------------------
|
||||
|
||||
.. autoclass:: microdot_asyncio.Microdot
|
||||
:inherited-members:
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot_asyncio.Request
|
||||
:inherited-members:
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot_asyncio.Response
|
||||
:inherited-members:
|
||||
:members:
|
||||
|
||||
``microdot_utemplate`` module
|
||||
-----------------------------
|
||||
|
||||
.. automodule:: microdot_utemplate
|
||||
:members:
|
||||
|
||||
``microdot_jinja`` module
|
||||
-------------------------
|
||||
|
||||
.. automodule:: microdot_jinja
|
||||
:members:
|
||||
|
||||
``microdot_session`` module
|
||||
---------------------------
|
||||
|
||||
.. automodule:: microdot_session
|
||||
:members:
|
||||
|
||||
``microdot_websocket`` module
|
||||
------------------------------
|
||||
|
||||
.. automodule:: microdot_websocket
|
||||
:members:
|
||||
|
||||
``microdot_asyncio_websocket`` module
|
||||
-------------------------------------
|
||||
|
||||
.. automodule:: microdot_asyncio_websocket
|
||||
:members:
|
||||
|
||||
``microdot_asgi_websocket`` module
|
||||
-------------------------------------
|
||||
|
||||
.. automodule:: microdot_asgi_websocket
|
||||
:members:
|
||||
|
||||
``microdot_ssl`` module
|
||||
-----------------------
|
||||
|
||||
.. automodule:: microdot_ssl
|
||||
:members:
|
||||
|
||||
``microdot_test_client`` module
|
||||
-------------------------------
|
||||
|
||||
.. autoclass:: microdot_test_client.TestClient
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot_test_client.TestResponse
|
||||
:members:
|
||||
|
||||
``microdot_asyncio_test_client`` module
|
||||
---------------------------------------
|
||||
|
||||
.. autoclass:: microdot_asyncio_test_client.TestClient
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot_asyncio_test_client.TestResponse
|
||||
:members:
|
||||
|
||||
``microdot_wsgi`` module
|
||||
------------------------
|
||||
|
||||
.. autoclass:: microdot_wsgi.Microdot
|
||||
:members:
|
||||
:exclude-members: shutdown, run
|
||||
|
||||
``microdot_asgi`` module
|
||||
------------------------
|
||||
|
||||
.. autoclass:: microdot_asgi.Microdot
|
||||
:members:
|
||||
:exclude-members: shutdown, run
|
||||
@@ -1,6 +0,0 @@
|
||||
ASGI
|
||||
----
|
||||
|
||||
.. autoclass:: microdot.asgi.Microdot
|
||||
:members:
|
||||
:exclude-members: shutdown, run
|
||||
@@ -1,7 +0,0 @@
|
||||
Authentication
|
||||
--------------
|
||||
|
||||
.. automodule:: microdot.auth
|
||||
:inherited-members:
|
||||
:special-members: __call__
|
||||
:members:
|
||||
@@ -1,5 +0,0 @@
|
||||
Cross-Origin Resource Sharing (CORS)
|
||||
------------------------------------
|
||||
|
||||
.. automodule:: microdot.cors
|
||||
:members:
|
||||
@@ -1,5 +0,0 @@
|
||||
Cross-Site Request Forgery (CSRF) Protection
|
||||
--------------------------------------------
|
||||
|
||||
.. automodule:: microdot.csrf
|
||||
:members:
|
||||
@@ -1,21 +0,0 @@
|
||||
API Reference
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
microdot
|
||||
multipart
|
||||
websocket
|
||||
sse
|
||||
utemplate
|
||||
jinja
|
||||
sessions
|
||||
auth
|
||||
login
|
||||
cors
|
||||
csrf
|
||||
test_client
|
||||
asgi
|
||||
wsgi
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
Templates (Jinja)
|
||||
-----------------
|
||||
|
||||
.. automodule:: microdot.jinja
|
||||
:members:
|
||||
@@ -1,7 +0,0 @@
|
||||
User Logins
|
||||
-----------
|
||||
|
||||
.. automodule:: microdot.login
|
||||
:inherited-members:
|
||||
:special-members: __call__
|
||||
:members:
|
||||
@@ -1,14 +0,0 @@
|
||||
Core API
|
||||
--------
|
||||
|
||||
.. autoclass:: microdot.Microdot
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot.Request
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot.Response
|
||||
:members:
|
||||
|
||||
.. autoclass:: microdot.URLPattern
|
||||
:members:
|
||||
@@ -1,5 +0,0 @@
|
||||
Multipart Forms
|
||||
---------------
|
||||
|
||||
.. automodule:: microdot.multipart
|
||||
:members:
|
||||
@@ -1,5 +0,0 @@
|
||||
User Sessions
|
||||
-------------
|
||||
|
||||
.. automodule:: microdot.session
|
||||
:members:
|
||||
@@ -1,5 +0,0 @@
|
||||
Server-Sent Events (SSE)
|
||||
------------------------
|
||||
|
||||
.. automodule:: microdot.sse
|
||||
:members:
|
||||
@@ -1,5 +0,0 @@
|
||||
Test Client
|
||||
-----------
|
||||
|
||||
.. automodule:: microdot.test_client
|
||||
:members:
|
||||
@@ -1,5 +0,0 @@
|
||||
Templates (uTemplate)
|
||||
---------------------
|
||||
|
||||
.. automodule:: microdot.utemplate
|
||||
:members:
|
||||
@@ -1,5 +0,0 @@
|
||||
WebSocket
|
||||
---------
|
||||
|
||||
.. automodule:: microdot.websocket
|
||||
:members:
|
||||
@@ -1,6 +0,0 @@
|
||||
WSGI
|
||||
----
|
||||
|
||||
.. autoclass:: microdot.wsgi.Microdot
|
||||
:members:
|
||||
:exclude-members: shutdown, run
|
||||
@@ -46,8 +46,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'furo'
|
||||
html_title = 'Microdot'
|
||||
html_theme = 'alabaster'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
@@ -59,6 +58,12 @@ html_css_files = [
|
||||
]
|
||||
|
||||
html_theme_options = {
|
||||
'github_user': 'miguelgrinberg',
|
||||
'github_repo': 'microdot',
|
||||
'github_banner': True,
|
||||
'github_button': True,
|
||||
'github_type': 'star',
|
||||
'fixed_sidebar': True,
|
||||
}
|
||||
|
||||
autodoc_default_options = {
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
Contributing
|
||||
------------
|
||||
|
||||
Thank you for your interest in Microdot!
|
||||
|
||||
Please visit the `GitHub repository <https://github.com/miguelgrinberg/microdot>`_
|
||||
to learn about the project and find open issues and pull requests.
|
||||
495
docs/extensions.rst
Normal file
495
docs/extensions.rst
Normal file
@@ -0,0 +1,495 @@
|
||||
Core Extensions
|
||||
---------------
|
||||
|
||||
Microdot is a highly extensible web application framework. The extensions
|
||||
described in this section are maintained as part of the Microdot project and
|
||||
can be obtained from the same source code repository.
|
||||
|
||||
Asynchronous Support with Asyncio
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | CPython: None
|
||||
| MicroPython: `uasyncio <https://github.com/micropython/micropython/tree/master/extmod/uasyncio>`_
|
||||
|
||||
* - Examples
|
||||
- | `hello_async.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_async.py>`_
|
||||
|
||||
Microdot can be extended to use an asynchronous programming model based on the
|
||||
``asyncio`` package. When the :class:`Microdot <microdot_asyncio.Microdot>`
|
||||
class is imported from the ``microdot_asyncio`` package, an asynchronous server
|
||||
is used, and handlers can be defined as coroutines.
|
||||
|
||||
The example that follows uses ``asyncio`` coroutines for concurrency::
|
||||
|
||||
from microdot_asyncio import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
async def hello(request):
|
||||
return 'Hello, world!'
|
||||
|
||||
app.run()
|
||||
|
||||
Rendering HTML Templates
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Many web applications use HTML templates for rendering content to clients.
|
||||
Microdot includes extensions to render templates with the
|
||||
`utemplate <https://github.com/pfalcon/utemplate>`_ package on CPython and
|
||||
MicroPython, and with `Jinja <https://jinja.palletsprojects.com/>`_ only on
|
||||
CPython.
|
||||
|
||||
Using the uTemplate Engine
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_utemplate.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_utemplate.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | `utemplate <https://github.com/pfalcon/utemplate/tree/master/utemplate>`_
|
||||
|
||||
* - Examples
|
||||
- | `hello_utemplate.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_utemplate.py>`_
|
||||
| `hello_utemplate_async.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_utemplate_async.py>`_
|
||||
|
||||
The :func:`render_template <microdot_utemplate.render_template>` function is
|
||||
used to render HTML templates with the uTemplate engine. The first argument is
|
||||
the template filename, relative to the templates directory, which is
|
||||
*templates* by default. Any additional arguments are passed to the template
|
||||
engine to be used as arguments.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot_utemplate import render_template
|
||||
|
||||
@app.get('/')
|
||||
def index(req):
|
||||
return render_template('index.html')
|
||||
|
||||
The default location from where templates are loaded is the *templates*
|
||||
subdirectory. This location can be changed with the
|
||||
:func:`init_templates <microdot_utemplate.init_templates>` function::
|
||||
|
||||
from microdot_utemplate import init_templates
|
||||
|
||||
init_templates('my_templates')
|
||||
|
||||
Using the Jinja Engine
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython only
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_jinja.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_jinja.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | `Jinja2 <https://jinja.palletsprojects.com/>`_
|
||||
|
||||
* - Examples
|
||||
- | `hello_jinja.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_jinja.py>`_
|
||||
|
||||
The :func:`render_template <microdot_jinja.render_template>` function is used
|
||||
to render HTML templates with the Jinja engine. The first argument is the
|
||||
template filename, relative to the templates directory, which is *templates* by
|
||||
default. Any additional arguments are passed to the template engine to be used
|
||||
as arguments.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot_jinja import render_template
|
||||
|
||||
@app.get('/')
|
||||
def index(req):
|
||||
return render_template('index.html')
|
||||
|
||||
The default location from where templates are loaded is the *templates*
|
||||
subdirectory. This location can be changed with the
|
||||
:func:`init_templates <microdot_jinja.init_templates>` function::
|
||||
|
||||
from microdot_jinja import init_templates
|
||||
|
||||
init_templates('my_templates')
|
||||
|
||||
.. note::
|
||||
The Jinja extension is not compatible with MicroPython.
|
||||
|
||||
Maintaing Secure User Sessions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_session.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | CPython: `PyJWT <https://pyjwt.readthedocs.io/>`_
|
||||
| MicroPython: `jwt.py <https://github.com/micropython/micropython-lib/blob/master/python-ecosys/pyjwt/jwt.py>`_,
|
||||
`hmac <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/hmac/hmac.py>`_
|
||||
|
||||
* - Examples
|
||||
- | `login.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/login.py>`_
|
||||
|
||||
The session extension provides a secure way for the application to maintain
|
||||
user sessions. The session is stored as a signed cookie in the client's
|
||||
browser, in `JSON Web Token (JWT) <https://en.wikipedia.org/wiki/JSON_Web_Token>`_
|
||||
format.
|
||||
|
||||
To work with user sessions, the application first must configure the secret key
|
||||
that will be used to sign the session cookies. It is very important that this
|
||||
key is kept secret. An attacker who is in possession of this key can generate
|
||||
valid user session cookies with any contents.
|
||||
|
||||
To set the secret key, use the :func:`set_session_secret_key <microdot_session.set_session_secret_key>` function::
|
||||
|
||||
from microdot_session import set_session_secret_key
|
||||
|
||||
set_session_secret_key('top-secret!')
|
||||
|
||||
To :func:`get_session <microdot_session.get_session>`,
|
||||
:func:`update_session <microdot_session.update_session>` and
|
||||
:func:`delete_session <microdot_session.delete_session>` functions are used
|
||||
inside route handlers to retrieve, store and delete session data respectively.
|
||||
The :func:`with_session <microdot_session.with_session>` decorator is provided
|
||||
as a convenient way to retrieve the session at the start of a route handler.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot import Microdot
|
||||
from microdot_session import set_session_secret_key, with_session, \
|
||||
update_session, delete_session
|
||||
|
||||
app = Microdot()
|
||||
set_session_secret_key('top-secret')
|
||||
|
||||
@app.route('/', methods=['GET', 'POST'])
|
||||
@with_session
|
||||
def index(req, session):
|
||||
username = session.get('username')
|
||||
if req.method == 'POST':
|
||||
username = req.form.get('username')
|
||||
update_session(req, {'username': username})
|
||||
return redirect('/')
|
||||
if username is None:
|
||||
return 'Not logged in'
|
||||
else:
|
||||
return 'Logged in as ' + username
|
||||
|
||||
@app.post('/logout')
|
||||
def logout(req):
|
||||
delete_session(req)
|
||||
return redirect('/')
|
||||
|
||||
WebSocket Support
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_websocket.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `echo.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo.py>`_
|
||||
| `echo_wsgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_wsgi.py>`_
|
||||
|
||||
The WebSocket extension provides a way for the application to handle WebSocket
|
||||
requests. The :func:`websocket <microdot_websocket.with_websocket>` decorator
|
||||
is used to mark a route handler as a WebSocket handler. The handler receives
|
||||
a WebSocket object as a second argument. The WebSocket object provides
|
||||
``send()`` and ``receive()`` methods to send and receive messages respectively.
|
||||
|
||||
Example::
|
||||
|
||||
@app.route('/echo')
|
||||
@with_websocket
|
||||
def echo(request, ws):
|
||||
while True:
|
||||
message = ws.receive()
|
||||
ws.send(message)
|
||||
|
||||
.. note::
|
||||
An unsupported *microsoft_websocket_alt.py* module, with the same
|
||||
interface, is also provided. This module uses the native WebSocket support
|
||||
in MicroPython that powers the WebREPL, and may provide slightly better
|
||||
performance for MicroPython low-end boards. This module is not compatible
|
||||
with CPython.
|
||||
|
||||
Asynchronous WebSocket
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
|
||||
| `microdot_websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_websocket.py>`_
|
||||
| `microdot_asyncio_websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio_websocket.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | CPython: None
|
||||
| MicroPython: `uasyncio <https://github.com/micropython/micropython/tree/master/extmod/uasyncio>`_
|
||||
|
||||
* - Examples
|
||||
- | `echo_async.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_async.py>`_
|
||||
|
||||
This extension has the same interface as the synchronous WebSocket extension,
|
||||
but the ``receive()`` and ``send()`` methods are asynchronous.
|
||||
|
||||
.. note::
|
||||
An unsupported *microsoft_asgi_websocket.py* module, with the same
|
||||
interface, is also provided. This module must be used instead of
|
||||
*microsoft_asyncio_websocket.py* when the ASGI support is used. The
|
||||
`echo_asgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_asgi.py>`_
|
||||
example shows how to use this module.
|
||||
|
||||
HTTPS Support
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_ssl.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_ssl.py>`_
|
||||
|
||||
* - Examples
|
||||
- | `hello_tls.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/tls/hello_tls.py>`_
|
||||
| `hello_asyncio_tls.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/tls/hello_asyncio_tls.py>`_
|
||||
|
||||
The ``run()`` function accepts an optional ``ssl`` argument, through which an
|
||||
initialized ``SSLContext`` object can be passed. MicroPython does not currently
|
||||
have a ``SSLContext`` implementation, so the ``microdot_ssl`` module provides
|
||||
a basic implementation that can be used to create a context.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot import Microdot
|
||||
from microdot_ssl import create_ssl_context
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
def index(req):
|
||||
return 'Hello, World!'
|
||||
|
||||
sslctx = create_ssl_context('cert.der', 'key.der')
|
||||
app.run(port=4443, debug=True, ssl=sslctx)
|
||||
|
||||
.. note::
|
||||
The ``microdot_ssl`` module is only needed for MicroPython. When used under
|
||||
CPython, this module creates a standard ``SSLContext`` instance.
|
||||
|
||||
.. note::
|
||||
The ``uasyncio`` library for MicroPython does not currently support TLS, so
|
||||
this feature is not available for asynchronous applications on that
|
||||
platform. The ``asyncio`` library for CPython is fully supported.
|
||||
|
||||
Test Client
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_test_client.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
The Microdot Test Client is a utility class that can be used during testing to
|
||||
send requests into the application.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot import Microdot
|
||||
from microdot_test_client import TestClient
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
def index(req):
|
||||
return 'Hello, World!'
|
||||
|
||||
def test_app():
|
||||
client = TestClient(app)
|
||||
response = client.get('/')
|
||||
assert response.text == 'Hello, World!'
|
||||
|
||||
See the documentation for the :class:`TestClient <microdot_test_client.TestClient>`
|
||||
class for more details.
|
||||
|
||||
Asynchronous Test Client
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
|
||||
| `microdot_test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_test_client.py>`_
|
||||
| `microdot_asyncio_test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio_test_client.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
Similar to the :class:`TestClient <microdot_test_client.TestClient>` class
|
||||
above, but for asynchronous applications.
|
||||
|
||||
Example usage::
|
||||
|
||||
from microdot_asyncio_test_client import TestClient
|
||||
|
||||
async def test_app():
|
||||
client = TestClient(app)
|
||||
response = await client.get('/')
|
||||
assert response.text == 'Hello, World!'
|
||||
|
||||
See the :class:`reference documentation <microdot_asyncio_test_client.TestClient>`
|
||||
for details.
|
||||
|
||||
Deploying on a Production Web Server
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The ``Microdot`` class creates its own simple web server. This is enough for an
|
||||
application deployed with MicroPython, but when using CPython it may be useful
|
||||
to use a separate, battle-tested web server. To address this need, Microdot
|
||||
provides extensions that implement the WSGI and ASGI protocols.
|
||||
|
||||
Using a WSGI Web Server
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython only
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_wsgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_wsgi.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | A WSGI web server, such as `Gunicorn <https://gunicorn.org/>`_.
|
||||
|
||||
* - Examples
|
||||
- | `hello_wsgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_wsgi.py>`_
|
||||
|
||||
|
||||
The ``microdot_wsgi`` module provides an extended ``Microdot`` class that
|
||||
implements the WSGI protocol and can be used with a compliant WSGI web server
|
||||
such as `Gunicorn <https://gunicorn.org/>`_ or
|
||||
`uWSGI <https://uwsgi-docs.readthedocs.io/en/latest/>`_.
|
||||
|
||||
To use a WSGI web server, the application must import the
|
||||
:class:`Microdot <microdot_wsgi.Microdot>` class from the ``microdot_wsgi``
|
||||
module::
|
||||
|
||||
from microdot_wsgi import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
def index(req):
|
||||
return 'Hello, World!'
|
||||
|
||||
The ``app`` application instance created from this class is a WSGI application
|
||||
that can be used with any complaint WSGI web server. If the above application
|
||||
is stored in a file called *test.py*, then the following command runs the
|
||||
web application using the Gunicorn web server::
|
||||
|
||||
gunicorn test:app
|
||||
|
||||
Using an ASGI Web Server
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython only
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
| `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
|
||||
| `microdot_asgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asgi.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | An ASGI web server, such as `Uvicorn <https://uvicorn.org/>`_.
|
||||
|
||||
* - Examples
|
||||
- | `hello_asgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_asgi.py>`_
|
||||
|
||||
The ``microdot_asgi`` module provides an extended ``Microdot`` class that
|
||||
implements the ASGI protocol and can be used with a compliant ASGI server such
|
||||
as `Uvicorn <https://www.uvicorn.org/>`_.
|
||||
|
||||
To use an ASGI web server, the application must import the
|
||||
:class:`Microdot <microdot_asgi.Microdot>` class from the ``microdot_asgi``
|
||||
module::
|
||||
|
||||
from microdot_asgi import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
async def index(req):
|
||||
return 'Hello, World!'
|
||||
|
||||
The ``app`` application instance created from this class is an ASGI application
|
||||
that can be used with any complaint ASGI web server. If the above application
|
||||
is stored in a file called *test.py*, then the following command runs the
|
||||
web application using the Uvicorn web server::
|
||||
|
||||
uvicorn test:app
|
||||
|
||||
@@ -1,112 +0,0 @@
|
||||
Authentication
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `auth.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/auth.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `basic_auth.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/auth/basic_auth.py>`_
|
||||
| `token_auth.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/auth/token_auth.py>`_
|
||||
|
||||
The authentication extension provides helper classes for two commonly used
|
||||
authentication patterns, described below.
|
||||
|
||||
Basic Authentication
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
`Basic Authentication <https://en.wikipedia.org/wiki/Basic_access_authentication>`_
|
||||
is a method of authentication that is part of the HTTP specification. It allows
|
||||
clients to authenticate to a server using a username and a password. Web
|
||||
browsers have native support for Basic Authentication and will automatically
|
||||
prompt the user for a username and a password when a protected resource is
|
||||
accessed.
|
||||
|
||||
To use Basic Authentication, create an instance of the :class:`BasicAuth <microdot.auth.BasicAuth>`
|
||||
class::
|
||||
|
||||
from microdot.auth import BasicAuth
|
||||
|
||||
auth = BasicAuth(app)
|
||||
|
||||
Next, create an authentication function. The function must accept a request
|
||||
object and a username and password pair provided by the user. If the
|
||||
credentials are valid, the function must return an object that represents the
|
||||
user. If the authentication function cannot validate the user provided
|
||||
credentials it must return ``None``. Decorate the function with
|
||||
``@auth.authenticate``::
|
||||
|
||||
@auth.authenticate
|
||||
async def verify_user(request, username, password):
|
||||
user = await load_user_from_database(username)
|
||||
if user and user.verify_password(password):
|
||||
return user
|
||||
|
||||
To protect a route with authentication, add the ``auth`` instance as a
|
||||
decorator::
|
||||
|
||||
@app.route('/')
|
||||
@auth
|
||||
async def index(request):
|
||||
return f'Hello, {request.g.current_user}!'
|
||||
|
||||
While running an authenticated request, the user object returned by the
|
||||
authenticaction function is accessible as ``request.g.current_user``.
|
||||
|
||||
If an endpoint is intended to work with or without authentication, then it can
|
||||
be protected with the ``auth.optional`` decorator::
|
||||
|
||||
@app.route('/')
|
||||
@auth.optional
|
||||
async def index(request):
|
||||
if request.g.current_user:
|
||||
return f'Hello, {request.g.current_user}!'
|
||||
else:
|
||||
return 'Hello, anonymous user!'
|
||||
|
||||
As shown in the example, a route can check ``request.g.current_user`` to
|
||||
determine if the user is authenticated or not.
|
||||
|
||||
Token Authentication
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To set up token authentication, create an instance of
|
||||
:class:`TokenAuth <microdot.auth.TokenAuth>`::
|
||||
|
||||
from microdot.auth import TokenAuth
|
||||
|
||||
auth = TokenAuth()
|
||||
|
||||
Then add a function that verifies the token and returns the user it belongs to,
|
||||
or ``None`` if the token is invalid or expired::
|
||||
|
||||
@auth.authenticate
|
||||
async def verify_token(request, token):
|
||||
return load_user_from_token(token)
|
||||
|
||||
As with Basic authentication, the ``auth`` instance is used as a decorator to
|
||||
protect your routes, and the authenticated user is accessible from the request
|
||||
object as ``request.g.current_user``::
|
||||
|
||||
@app.route('/')
|
||||
@auth
|
||||
async def index(request):
|
||||
return f'Hello, {request.g.current_user}!'
|
||||
|
||||
Optional authentication can also be used with tokens::
|
||||
|
||||
@app.route('/')
|
||||
@auth.optional
|
||||
async def index(request):
|
||||
if request.g.current_user:
|
||||
return f'Hello, {request.g.current_user}!'
|
||||
else:
|
||||
return 'Hello, anonymous user!'
|
||||
@@ -1,34 +0,0 @@
|
||||
Cross-Origin Resource Sharing (CORS)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `cors.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/cors.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `app.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/cors/app.py>`_
|
||||
|
||||
The CORS extension provides support for `Cross-Origin Resource Sharing
|
||||
(CORS) <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_. CORS is a
|
||||
mechanism that allows web applications running on different origins to access
|
||||
resources from each other. For example, a web application running on
|
||||
``https://example.com`` can access resources from ``https://api.example.com``.
|
||||
|
||||
To enable CORS support, create an instance of the
|
||||
:class:`CORS <microdot.cors.CORS>` class and configure the desired options.
|
||||
Example::
|
||||
|
||||
from microdot import Microdot
|
||||
from microdot.cors import CORS
|
||||
|
||||
app = Microdot()
|
||||
cors = CORS(app, allowed_origins=['https://example.com'],
|
||||
allow_credentials=True)
|
||||
@@ -1,94 +0,0 @@
|
||||
Cross-Site Request Forgery (CSRF) Protection
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `csrf.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/csrf.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `app.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/csrf/app.py>`_
|
||||
|
||||
The CSRF extension provides protection against `Cross-Site Request Forgery
|
||||
(CSRF) <https://owasp.org/www-community/attacks/csrf>`_ attacks. This
|
||||
protection defends against attackers attempting to submit forms or other
|
||||
state-changing requests from their own site on behalf of unsuspecting victims,
|
||||
while taking advantage of the victims previously established sessions or
|
||||
cookies to impersonate them.
|
||||
|
||||
This extension checks the ``Sec-Fetch-Site`` header sent by all modern web
|
||||
browsers to achieve this protection. As a fallback mechanism for older browsers
|
||||
that do not support this header, this extension can be linked to the CORS
|
||||
extension to validate the ``Origin`` header. If you are interested in the
|
||||
details of this protection mechanism, it is described in the
|
||||
`OWASP CSRF Prevention Cheat Sheet <https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#fetch-metadata-headers>`_
|
||||
page.
|
||||
|
||||
.. note::
|
||||
As of December 2025, OWASP considers the use of Fetch Metadata Headers for
|
||||
CSRF protection a
|
||||
`defense in depth <https://en.wikipedia.org/wiki/Defence_in_depth>`_
|
||||
technique that is insufficient on its own.
|
||||
|
||||
There is an interesting
|
||||
`discussion <https://github.com/OWASP/CheatSheetSeries/issues/1803>`_ on
|
||||
this topic in the OWASP GitHub repository where it appears to be agreement
|
||||
that this technique provides complete protection for the vast majority of
|
||||
use cases. If you are unsure if this method works for your use case, please
|
||||
read this discussion to have more context and make the right decision.
|
||||
|
||||
To enable CSRF protection, create an instance of the
|
||||
:class:`CSRF <microdot.csrf.CSRF>` class and configure the desired options.
|
||||
Example::
|
||||
|
||||
from microdot import Microdot
|
||||
from microdot.cors import CORS
|
||||
from microdot.csrf import CSRF
|
||||
|
||||
app = Microdot()
|
||||
cors = CORS(app, allowed_origins=['https://example.com'])
|
||||
csrf = CSRF(app, cors)
|
||||
|
||||
This will protect all routes that use a state-changing method (``POST``,
|
||||
``PUT``, ``PATCH`` or ``DELETE``) and will return a 403 status code response to
|
||||
any requests that fail the CSRF check.
|
||||
|
||||
If there are routes that need to be exempted from the CSRF check, they can be
|
||||
decorated with the :meth:`csrf.exempt <microdot.csrf.CSRF.exempt>` decorator::
|
||||
|
||||
@app.post('/webhook')
|
||||
@csrf.exempt
|
||||
async def webhook(request):
|
||||
# ...
|
||||
|
||||
For some applications it may be more convenient to have CSRF checks turned off
|
||||
by default, and only apply them to explicitly selected routes. In this case,
|
||||
pass ``protect_all=False`` when you construct the ``CSRF`` instance and use the
|
||||
:meth:`csrf.protect <microdot.csrf.CSRF.protect>` decorator::
|
||||
|
||||
csrf = CSRF(app, cors, protect_all=False)
|
||||
|
||||
@app.post('/submit-form')
|
||||
@csrf.protect
|
||||
async def submit_form(request):
|
||||
# ...
|
||||
|
||||
By default, requests coming from different subdomains are considered to be
|
||||
cross-site, and as such they will not pass the CSRF check. If you'd like
|
||||
subdomain requests to be considered safe, then set the
|
||||
``allow_subdomains=True`` option when you create the ``CSRF`` class.
|
||||
|
||||
.. note::
|
||||
This extension is designed to block requests issued by web browsers when
|
||||
they are found to be unsafe or unauthorized by the application owner. The
|
||||
method used to determine if a request should be allowed or not is based on
|
||||
the value of headers that are only sent by web browsers. Clients other than
|
||||
web browsers are not affected by this extension and can send requests
|
||||
freely.
|
||||
@@ -1,21 +0,0 @@
|
||||
Core Extensions
|
||||
---------------
|
||||
|
||||
Microdot is a highly extensible web application framework. The extensions
|
||||
described in this section are maintained as part of the Microdot project in
|
||||
the same source code repository.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
multipart
|
||||
websocket
|
||||
sse
|
||||
templates
|
||||
sessions
|
||||
auth
|
||||
login
|
||||
cors
|
||||
csrf
|
||||
test_client
|
||||
production
|
||||
@@ -1,85 +0,0 @@
|
||||
User Logins
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `login.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/auth.py>`_
|
||||
| `session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/session.py>`_
|
||||
| `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
|
||||
* - Required external dependencies
|
||||
- | CPython: `PyJWT <https://pyjwt.readthedocs.io/>`_
|
||||
| MicroPython: `jwt.py <https://github.com/micropython/micropython-lib/blob/master/python-ecosys/pyjwt/jwt.py>`_,
|
||||
`hmac.py <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/hmac/hmac.py>`_
|
||||
* - Examples
|
||||
- | `login.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/login/login.py>`_
|
||||
|
||||
The login extension provides user login functionality. The logged in state of
|
||||
the user is stored in the user session cookie, and an optional "remember me"
|
||||
cookie can also be added to keep the user logged in across browser sessions.
|
||||
|
||||
To use this extension, create instances of the
|
||||
:class:`Session <microdot.session.Session>` and :class:`Login <microdot.login.Login>`
|
||||
class::
|
||||
|
||||
Session(app, secret_key='top-secret!')
|
||||
login = Login()
|
||||
|
||||
The ``Login`` class accept an optional argument with the URL of the login page.
|
||||
The default for this URL is */login*.
|
||||
|
||||
The application must represent users as objects with an ``id`` attribute. A
|
||||
function decorated with ``@login.user_loader`` is used to load a user object::
|
||||
|
||||
@login.user_loader
|
||||
async def get_user(user_id):
|
||||
return database.get_user(user_id)
|
||||
|
||||
The application must implement the login form. At the point in which the user
|
||||
credentials have been received and verified, a call to the
|
||||
:func:`login_user() <microdot.login.Login.login_user>` function must be made to
|
||||
record the user in the user session::
|
||||
|
||||
@app.route('/login', methods=['GET', 'POST'])
|
||||
async def login(request):
|
||||
# ...
|
||||
if user.check_password(password):
|
||||
return await login.login_user(request, user, remember=remember_me)
|
||||
return redirect('/login')
|
||||
|
||||
The optional ``remember`` argument is used to add a remember me cookie that
|
||||
will log the user in automatically in future sessions. A value of ``True`` will
|
||||
keep the log in active for 30 days. Alternatively, an integer number of days
|
||||
can be passed in this argument.
|
||||
|
||||
Any routes that require the user to be logged in must be decorated with
|
||||
:func:`@login <microdot.login.Login.__call__>`::
|
||||
|
||||
@app.route('/')
|
||||
@login
|
||||
async def index(request):
|
||||
# ...
|
||||
|
||||
Routes that are of a sensitive nature can be decorated with
|
||||
:func:`@login.fresh <microdot.login.Login.fresh>`
|
||||
instead. This decorator requires that the user has logged in during the current
|
||||
session, and will ask the user to logged in again if the session was
|
||||
authenticated through a remember me cookie::
|
||||
|
||||
@app.get('/fresh')
|
||||
@login.fresh
|
||||
async def fresh(request):
|
||||
# ...
|
||||
|
||||
To log out a user, the :func:`logout_user() <microdot.auth.Login.logout_user>`
|
||||
is used::
|
||||
|
||||
@app.post('/logout')
|
||||
@login
|
||||
async def logout(request):
|
||||
await login.logout_user(request)
|
||||
return redirect('/')
|
||||
@@ -1,73 +0,0 @@
|
||||
Multipart Forms
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `multipart.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/multipart.py>`_
|
||||
| `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `formdata.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/uploads/formdata.py>`_
|
||||
|
||||
The multipart extension handles multipart forms, including those that have file
|
||||
uploads.
|
||||
|
||||
The :func:`with_form_data <microdot.multipart.with_form_data>` decorator
|
||||
provides the simplest way to work with these forms. With this decorator added
|
||||
to the route, whenever the client sends a multipart request the
|
||||
:attr:`request.form <microdot.Request.form>` and
|
||||
:attr:`request.files <microdot.Request.files>` properties are populated with
|
||||
the submitted data. For form fields the field values are always strings. For
|
||||
files, they are instances of the
|
||||
:class:`FileUpload <microdot.multipart.FileUpload>` class.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot.multipart import with_form_data
|
||||
|
||||
@app.post('/upload')
|
||||
@with_form_data
|
||||
async def upload(request):
|
||||
print('form fields:', request.form)
|
||||
print('files:', request.files)
|
||||
|
||||
One disadvantage of the ``@with_form_data`` decorator is that it has to copy
|
||||
any uploaded files to memory or temporary disk files, depending on their size.
|
||||
The :attr:`FileUpload.max_memory_size <microdot.multipart.FileUpload.max_memory_size>`
|
||||
attribute can be used to control the cutoff size above which a file upload
|
||||
is transferred to a temporary file.
|
||||
|
||||
A more performant alternative to the ``@with_form_data`` decorator is the
|
||||
:class:`FormDataIter <microdot.multipart.FormDataIter>` class, which iterates
|
||||
over the form fields sequentially, giving the application the option to parse
|
||||
the form fields on the fly and decide what to copy and what to discard. When
|
||||
using ``FormDataIter`` the ``request.form`` and ``request.files`` attributes
|
||||
are not used.
|
||||
|
||||
Example::
|
||||
|
||||
|
||||
from microdot.multipart import FormDataIter
|
||||
|
||||
@app.post('/upload')
|
||||
async def upload(request):
|
||||
async for name, value in FormDataIter(request):
|
||||
print(name, value)
|
||||
|
||||
For fields that contain an uploaded file, the ``value`` returned by the
|
||||
iterator is the same ``FileUpload`` instance. The application can choose to
|
||||
save the file with the :meth:`save() <microdot.multipart.FileUpload.save>`
|
||||
method, or read it with the :meth:`read() <microdot.multipart.FileUpload.read>`
|
||||
method, optionally passing a size to read it in chunks. The
|
||||
:meth:`copy() <microdot.multipart.FileUpload.copy>` method is also available to
|
||||
apply the copying logic used by the ``@with_form_data`` decorator, which is
|
||||
inefficient but allows the file to be set aside to be processed later, after
|
||||
the remaining form fields.
|
||||
@@ -1,120 +0,0 @@
|
||||
Production Deployments
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The ``Microdot`` class creates its own simple web server. This is enough for an
|
||||
application deployed with MicroPython, but when using CPython it may be useful
|
||||
to use a separate, battle-tested web server. To address this need, Microdot
|
||||
provides extensions that implement the ASGI and WSGI protocols.
|
||||
|
||||
Using an ASGI Web Server
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython only
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `asgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/asgi.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | An ASGI web server, such as `Uvicorn <https://www.uvicorn.org/>`_.
|
||||
|
||||
* - Examples
|
||||
- | `hello_asgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_asgi.py>`_
|
||||
| `hello_asgi.py (uTemplate) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/utemplate/hello_asgi.py>`_
|
||||
| `hello_asgi.py (Jinja) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/jinja/hello_asgi.py>`_
|
||||
| `echo_asgi.py (WebSocket) <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_asgi.py>`_
|
||||
|
||||
The ``asgi`` module provides an extended ``Microdot`` class that
|
||||
implements the ASGI protocol and can be used with a compliant ASGI server such
|
||||
as `Uvicorn <https://www.uvicorn.org/>`_.
|
||||
|
||||
To use an ASGI web server, the application must import the
|
||||
:class:`Microdot <microdot.asgi.Microdot>` class from the ``asgi`` module::
|
||||
|
||||
from microdot.asgi import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
async def index(req):
|
||||
return 'Hello, World!'
|
||||
|
||||
The ``app`` application instance created from this class can be used as the
|
||||
ASGI callable with any complaint ASGI web server. If the above example
|
||||
application was stored in a file called *test.py*, then the following command
|
||||
runs the web application using the Uvicorn web server::
|
||||
|
||||
uvicorn test:app
|
||||
|
||||
When using the ASGI support, the ``scope`` dictionary provided by the web
|
||||
server is available to request handlers as ``request.asgi_scope``.
|
||||
|
||||
The application instance can be initialized with ``lifespan_startup`` and
|
||||
``lifespan_shutdown`` arguments, which are invoked when the web server sends
|
||||
the ASGI lifespan signals with the ASGI scope as only argument::
|
||||
|
||||
async def startup(scope):
|
||||
pass
|
||||
|
||||
async def shutdown(scope):
|
||||
pass
|
||||
|
||||
app = Microdot(lifespan_startup=startup, lifespan_shutdown=shutdown)
|
||||
|
||||
Using a WSGI Web Server
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython only
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `wsgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/wsgi.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | A WSGI web server, such as `Gunicorn <https://gunicorn.org/>`_.
|
||||
|
||||
* - Examples
|
||||
- | `hello_wsgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_wsgi.py>`_
|
||||
| `hello_wsgi.py (uTemplate) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/utemplate/hello_wsgi.py>`_
|
||||
| `hello_wsgi.py (Jinja) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/jinja/hello_wsgi.py>`_
|
||||
| `echo_wsgi.py (WebSocket) <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_wsgi.py>`_
|
||||
|
||||
|
||||
The ``wsgi`` module provides an extended ``Microdot`` class that implements the
|
||||
WSGI protocol and can be used with a compliant WSGI web server such as
|
||||
`Gunicorn <https://gunicorn.org/>`_ or
|
||||
`uWSGI <https://uwsgi-docs.readthedocs.io/en/latest/>`_.
|
||||
|
||||
To use a WSGI web server, the application must import the
|
||||
:class:`Microdot <microdot.wsgi.Microdot>` class from the ``wsgi`` module::
|
||||
|
||||
from microdot.wsgi import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
def index(req):
|
||||
return 'Hello, World!'
|
||||
|
||||
The ``app`` application instance created from this class can be used as a WSGI
|
||||
callbable with any complaint WSGI web server. If the above application
|
||||
was stored in a file called *test.py*, then the following command runs the
|
||||
web application using the Gunicorn web server::
|
||||
|
||||
gunicorn test:app
|
||||
|
||||
When using the WSGI support, the ``environ`` dictionary provided by the web
|
||||
server is available to request handlers as ``request.environ``.
|
||||
|
||||
.. note::
|
||||
In spite of WSGI being a synchronous protocol, the Microdot application
|
||||
internally runs under an asyncio event loop. For that reason, the
|
||||
recommendation to prefer ``async def`` handlers over ``def`` still applies
|
||||
under WSGI. Consult the :ref:`Concurrency` section for a discussion of how
|
||||
the two types of functions are handled by Microdot.
|
||||
@@ -1,68 +0,0 @@
|
||||
Secure User Sessions
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/session.py>`_
|
||||
| `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | CPython: `PyJWT <https://pyjwt.readthedocs.io/>`_
|
||||
| MicroPython: `jwt.py <https://github.com/micropython/micropython-lib/blob/master/python-ecosys/pyjwt/jwt.py>`_,
|
||||
`hmac.py <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/hmac/hmac.py>`_
|
||||
|
||||
* - Examples
|
||||
- | `login.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/sessions/login.py>`_
|
||||
|
||||
The session extension provides a secure way for the application to maintain
|
||||
user sessions. The session data is stored as a signed cookie in the client's
|
||||
browser, in `JSON Web Token (JWT) <https://en.wikipedia.org/wiki/JSON_Web_Token>`_
|
||||
format.
|
||||
|
||||
To work with user sessions, the application first must configure a secret key
|
||||
that will be used to sign the session cookies. It is very important that this
|
||||
key is kept secret, as its name implies. An attacker who is in possession of
|
||||
this key can generate valid user session cookies with any contents.
|
||||
|
||||
To initialize the session extension and configure the secret key, create a
|
||||
:class:`Session <microdot.session.Session>` object::
|
||||
|
||||
Session(app, secret_key='top-secret')
|
||||
|
||||
The :func:`with_session <microdot.session.with_session>` decorator is the
|
||||
most convenient way to retrieve the session at the start of a request::
|
||||
|
||||
from microdot import Microdot, redirect
|
||||
from microdot.session import Session, with_session
|
||||
|
||||
app = Microdot()
|
||||
Session(app, secret_key='top-secret')
|
||||
|
||||
@app.route('/', methods=['GET', 'POST'])
|
||||
@with_session
|
||||
async def index(req, session):
|
||||
username = session.get('username')
|
||||
if req.method == 'POST':
|
||||
username = req.form.get('username')
|
||||
session['username'] = username
|
||||
session.save()
|
||||
return redirect('/')
|
||||
if username is None:
|
||||
return 'Not logged in'
|
||||
else:
|
||||
return 'Logged in as ' + username
|
||||
|
||||
@app.post('/logout')
|
||||
@with_session
|
||||
async def logout(req, session):
|
||||
session.delete()
|
||||
return redirect('/')
|
||||
|
||||
The :func:`save() <microdot.session.SessionDict.save>` and
|
||||
:func:`delete() <microdot.session.SessionDict.delete>` methods are used to update
|
||||
and destroy the user session respectively.
|
||||
@@ -1,60 +0,0 @@
|
||||
Server-Sent Events
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `sse.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/sse.py>`_
|
||||
| `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `counter.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/sse/counter.py>`_
|
||||
|
||||
The Server-Sent Events (SSE) extension simplifies the creation of a streaming
|
||||
endpoint that follows the SSE web standard. The :func:`with_sse <microdot.sse.with_sse>`
|
||||
decorator is used to mark a route as an SSE handler. Decorated routes receive
|
||||
an SSE object as second argument. The SSE object provides a ``send()``
|
||||
asynchronous method to send an event to the client.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot.sse import with_sse
|
||||
|
||||
@app.route('/events')
|
||||
@with_sse
|
||||
async def events(request, sse):
|
||||
for i in range(10):
|
||||
await asyncio.sleep(1)
|
||||
await sse.send({'counter': i}) # unnamed event
|
||||
await sse.send('end', event='comment') # named event
|
||||
|
||||
To end the SSE connection, the route handler can exit, without returning
|
||||
anything, as shown in the above examples.
|
||||
|
||||
If the client ends the SSE connection from their side, the route function is
|
||||
cancelled. The route function can catch the ``CancelledError`` exception from
|
||||
asyncio to perform cleanup tasks::
|
||||
|
||||
@app.route('/events')
|
||||
@with_sse
|
||||
async def events(request, sse):
|
||||
try:
|
||||
i = 0
|
||||
while True:
|
||||
await asyncio.sleep(1)
|
||||
await sse.send({'counter': i})
|
||||
i += 1
|
||||
except asyncio.CancelledError:
|
||||
print('Client disconnected!')
|
||||
|
||||
.. note::
|
||||
The SSE protocol is unidirectional, so there is no ``receive()`` method in
|
||||
the SSE object. For bidirectional communication with the client, use the
|
||||
WebSocket extension.
|
||||
@@ -1,123 +0,0 @@
|
||||
Templates
|
||||
~~~~~~~~~
|
||||
|
||||
Many web applications use HTML templates for rendering content to clients.
|
||||
Microdot includes extensions to render templates with the
|
||||
`utemplate <https://github.com/pfalcon/utemplate>`_ package on CPython and
|
||||
MicroPython, and with `Jinja <https://jinja.palletsprojects.com/>`_ only on
|
||||
CPython.
|
||||
|
||||
Using the uTemplate Engine
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `utemplate.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/utemplate.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | `utemplate <https://github.com/pfalcon/utemplate/tree/master/utemplate>`_
|
||||
|
||||
* - Examples
|
||||
- | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/utemplate/hello.py>`_
|
||||
|
||||
The :class:`Template <microdot.utemplate.Template>` class is used to load a
|
||||
template. The argument is the template filename, relative to the templates
|
||||
directory, which is *templates* by default.
|
||||
|
||||
The ``Template`` object has a :func:`render() <microdot.utemplate.Template.render>`
|
||||
method that renders the template to a string. This method receives any
|
||||
arguments that are used by the template.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot.utemplate import Template
|
||||
|
||||
@app.get('/')
|
||||
async def index(req):
|
||||
return Template('index.html').render()
|
||||
|
||||
The ``Template`` object also has a :func:`generate() <microdot.utemplate.Template.generate>`
|
||||
method, which returns a generator instead of a string. The
|
||||
:func:`render_async() <microdot.utemplate.Template.render_async>` and
|
||||
:func:`generate_async() <microdot.utemplate.Template.generate_async>` methods
|
||||
are the asynchronous versions of these two methods.
|
||||
|
||||
The default location from where templates are loaded is the *templates*
|
||||
subdirectory. This location can be changed with the
|
||||
:func:`Template.initialize <microdot.utemplate.Template.initialize>` class
|
||||
method::
|
||||
|
||||
Template.initialize('my_templates')
|
||||
|
||||
By default templates are automatically compiled the first time they are
|
||||
rendered, or when their last modified timestamp is more recent than the
|
||||
compiledo file's timestamp. This loading behavior can be changed by switching
|
||||
to a different template loader. For example, if the templates are pre-compiled,
|
||||
the timestamp check and compile steps can be removed by switching to the
|
||||
"compiled" template loader::
|
||||
|
||||
from utemplate import compiled
|
||||
from microdot.utemplate import Template
|
||||
|
||||
Template.initialize(loader_class=compiled.Loader)
|
||||
|
||||
Consult the `uTemplate documentation <https://github.com/pfalcon/utemplate>`_
|
||||
for additional information regarding template loaders.
|
||||
|
||||
Using the Jinja Engine
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython only
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `jinja.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/jinja.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | `Jinja2 <https://jinja.palletsprojects.com/>`_
|
||||
|
||||
* - Examples
|
||||
- | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/jinja/hello.py>`_
|
||||
|
||||
The :class:`Template <microdot.jinja.Template>` class is used to load a
|
||||
template. The argument is the template filename, relative to the templates
|
||||
directory, which is *templates* by default.
|
||||
|
||||
The ``Template`` object has a :func:`render() <microdot.jinja.Template.render>`
|
||||
method that renders the template to a string. This method receives any
|
||||
arguments that are used by the template.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot.jinja import Template
|
||||
|
||||
@app.get('/')
|
||||
async def index(req):
|
||||
return Template('index.html').render()
|
||||
|
||||
The ``Template`` object also has a :func:`generate() <microdot.jinja.Template.generate>`
|
||||
method, which returns a generator instead of a string.
|
||||
|
||||
The default location from where templates are loaded is the *templates*
|
||||
subdirectory. This location can be changed with the
|
||||
:func:`Template.initialize <microdot.jinja.Template.initialize>` class method::
|
||||
|
||||
Template.initialize('my_templates')
|
||||
|
||||
The ``initialize()`` method also accepts ``enable_async`` argument, which
|
||||
can be set to ``True`` if asynchronous rendering of templates is desired. If
|
||||
this option is enabled, then the
|
||||
:func:`render_async() <microdot.jinja.Template.render_async>` and
|
||||
:func:`generate_async() <microdot.jinja.Template.generate_async>` methods
|
||||
must be used.
|
||||
|
||||
.. note::
|
||||
The Jinja extension is not compatible with MicroPython.
|
||||
@@ -1,36 +0,0 @@
|
||||
Test Client
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/test_client.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
The Microdot Test Client is a utility class that can be used in tests to send
|
||||
requests into the application without having to start a web server.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot import Microdot
|
||||
from microdot.test_client import TestClient
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
def index(req):
|
||||
return 'Hello, World!'
|
||||
|
||||
async def test_app():
|
||||
client = TestClient(app)
|
||||
response = await client.get('/')
|
||||
assert response.text == 'Hello, World!'
|
||||
|
||||
See the documentation for the :class:`TestClient <microdot.test_client.TestClient>`
|
||||
class for more details.
|
||||
@@ -1,63 +0,0 @@
|
||||
WebSocket
|
||||
~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Compatibility
|
||||
- | CPython & MicroPython
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/websocket.py>`_
|
||||
| `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `echo.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo.py>`_
|
||||
|
||||
The WebSocket extension gives the application the ability to handle WebSocket
|
||||
requests. The :func:`with_websocket <microdot.websocket.with_websocket>`
|
||||
decorator is used to mark a route handler as a WebSocket handler. Decorated
|
||||
routes receive a WebSocket object as a second argument. The WebSocket object
|
||||
provides ``send()`` and ``receive()`` asynchronous methods to send and receive
|
||||
messages respectively.
|
||||
|
||||
Example::
|
||||
|
||||
from microdot.websocket import with_websocket
|
||||
|
||||
@app.route('/echo')
|
||||
@with_websocket
|
||||
async def echo(request, ws):
|
||||
while True:
|
||||
message = await ws.receive()
|
||||
await ws.send(message)
|
||||
|
||||
To end the WebSocket connection, the route handler can exit, without returning
|
||||
anything::
|
||||
|
||||
@app.route('/echo')
|
||||
@with_websocket
|
||||
async def echo(request, ws):
|
||||
while True:
|
||||
message = await ws.receive()
|
||||
if message == 'exit':
|
||||
break
|
||||
await ws.send(message)
|
||||
await ws.send('goodbye')
|
||||
|
||||
If the client ends the WebSocket connection from their side, the route function
|
||||
is cancelled. The route function can catch the ``CancelledError`` exception
|
||||
from asyncio to perform cleanup tasks::
|
||||
|
||||
@app.route('/echo')
|
||||
@with_websocket
|
||||
async def echo(request, ws):
|
||||
try:
|
||||
while True:
|
||||
message = await ws.receive()
|
||||
await ws.send(message)
|
||||
except asyncio.CancelledError:
|
||||
print('Client disconnected!')
|
||||
@@ -1,113 +0,0 @@
|
||||
Cross-Compiling and Freezing Microdot
|
||||
-------------------------------------
|
||||
|
||||
.. note::
|
||||
This section only applies when using Microdot on MicroPython.
|
||||
|
||||
Microdot is a fairly small framework, so its size is not something you need to
|
||||
be concerned about unless you are working with MicroPython on hardware with a
|
||||
very small amount of disk space and/or RAM. In such cases every byte counts, so
|
||||
this section provides some recommendations on how to keep Microdot's footprint
|
||||
as small as possible.
|
||||
|
||||
Choosing What Modules to Install
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Microdot has a modular design that allows you to only install the modules that
|
||||
your application needs.
|
||||
|
||||
For minimal web application support based on the core Microdot web server
|
||||
without extensions, you can just copy `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/microdot.py>`_
|
||||
to the source directory on your device. The core Microdot web server does not
|
||||
have any dependencies, so you don't need to install anything else.
|
||||
|
||||
If your application uses some of the provided extensions to the core web
|
||||
server, then instead of installing *microdot.py* you'll need to create a
|
||||
*microdot* subdirectory and install the following files in it:
|
||||
|
||||
- `__init__.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/__init__.py>`_
|
||||
- `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/microdot.py>`_
|
||||
- Any extension modules that you need from the `microdot <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot>`_ source directory.
|
||||
|
||||
Some of the extensions also have dependencies of their own, so you may need to
|
||||
install those in your device as well (outside of the ``microdot``
|
||||
subdirectory). Consult the documentation of each extension to learn if any
|
||||
third-party dependencies are required.
|
||||
|
||||
Cross-Compiling
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
An issue that is common with low-end microcontroller boards is that they do not
|
||||
have enough RAM for the MicroPython compiler to compile the source files, but
|
||||
once the code is compiled they are able to run it just fine.
|
||||
|
||||
To address this, MicroPython allows you to cross-compile source files on your
|
||||
desktop or laptop computer and then upload their compiled versions to the
|
||||
device. A good strategy is to cross-compile all the dependencies that are used
|
||||
by your application, since these are not going to be updated very often. If the
|
||||
goal is to minimize the use of RAM, you can also opt to cross-compile your
|
||||
application source files.
|
||||
|
||||
The MicroPython cross-compiler is available as a package that you can install
|
||||
on standard Python. You must determine the version of MicroPython that you will
|
||||
be running on your device, and install the compiler that matches that version.
|
||||
For example, if you plan to use MicroPython 1.21.0 on your device, you can
|
||||
install the cross-compiler for this version with the following command::
|
||||
|
||||
pip install mpy-cross==1.21.0
|
||||
|
||||
Then run the cross-compiler for each source file that you want to compile.
|
||||
Since the cross-compilation happens on your computer, you will need to have
|
||||
copies of all the source files you need to compile locally on your disk. Here
|
||||
is how you can compile the *microdot.py* file, assuming you have a copy in the
|
||||
current directory in your computer::
|
||||
|
||||
mpy-cross microdot.py
|
||||
|
||||
The cross-compiler will create a file with the same name as the source file,
|
||||
but with the extension changed to *.mpy*.
|
||||
|
||||
Once you have all your dependencies compiled, you can replace the *.py* files
|
||||
in your device with their corresponding *.mpy* versions. MicroPython
|
||||
automatically recognizes *.mpy* files, so there is no need to make any changes
|
||||
to any source code to start using compiled files.
|
||||
|
||||
Freezing
|
||||
~~~~~~~~
|
||||
|
||||
The ultimate option to reduce the size of a MicroPython application is to
|
||||
"freeze" it. Freezing is a process that takes MicroPython source code (either
|
||||
dependencies, application code or both), pre-compiles it and incorporates it
|
||||
into a custom-built MicroPython firmware that is flashed to the device.
|
||||
|
||||
Freezing MicroPython modules to firmware has the advantage that the code is
|
||||
imported directly from the device's ROM, leaving more RAM available for
|
||||
application use.
|
||||
|
||||
The process to create a custom firmware is unfortunately non-trivial and
|
||||
different for each microcontroller platform, so you will need to consult the
|
||||
MicroPython documentation that applies to your device to learn how to do this.
|
||||
|
||||
The part of the process that is common to all devices is the creation of a
|
||||
`manifest file <https://docs.micropython.org/en/latest/reference/manifest.html>`_
|
||||
to tell the MicroPython firmware builder which packages and modules to freeze.
|
||||
|
||||
For a minimal installation of Microdot consisting only in its *microdot.py*
|
||||
source file, the manifest file that you need use to build the firmware must
|
||||
include the following declaration::
|
||||
|
||||
module('microdot')
|
||||
|
||||
If instead you are working with a version of Microdot that includes some or all
|
||||
of its extensions, then the manifest file must reference the ``microdot``
|
||||
package plus any third-party dependencies that are needed. Below is a manifest
|
||||
file for a complete Microdot installation that includes all the extensions::
|
||||
|
||||
package('microdot')
|
||||
package('utemplate') # required only if templates are used
|
||||
module('pyjwt') # required only if user sessions are used
|
||||
|
||||
In this example, the *microdot* and *utemplate* packages must be available in
|
||||
the directory where the manifest file is located so that the MicroPython build
|
||||
can find them. The `pyjwt` module is part of the MicroPython standard library
|
||||
and will be downloaded as part of the build.
|
||||
@@ -1,11 +0,0 @@
|
||||
Implementation notes
|
||||
--------------------
|
||||
|
||||
This section covers some implementation aspects of Microdot.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
migrating
|
||||
freezing
|
||||
|
||||
@@ -1,145 +0,0 @@
|
||||
Migrating to Microdot 2.x from Older Releases
|
||||
---------------------------------------------
|
||||
|
||||
Version 2 of Microdot incorporates feedback received from users of earlier
|
||||
releases, and attempts to improve and correct some design decisions that have
|
||||
proven to be problematic.
|
||||
|
||||
For this reason most applications built for earlier versions will need to be
|
||||
updated to work correctly with Microdot 2. This section describes the backwards
|
||||
incompatible changes that were made.
|
||||
|
||||
Code reorganization
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Microdot source code has been moved into a ``microdot`` package,
|
||||
eliminating the need for each extension to be named with a *microdot_* prefix.
|
||||
|
||||
As a result of this change, all extensions have been renamed to shorter names.
|
||||
For example, the *microdot_cors.py* module is now called *cors.py*.
|
||||
|
||||
This change affects the way extensions are imported. Instead of this::
|
||||
|
||||
from microdot_cors import CORS
|
||||
|
||||
the import statement should be::
|
||||
|
||||
from microdot.cors import CORS
|
||||
|
||||
No more synchronous web server
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In earlier releases of Microdot the core web server was built on synchronous
|
||||
Python, and asynchronous support was enabled with the asyncio extension.
|
||||
|
||||
Microdot 2 eliminates the synchronous web server, and implements the core
|
||||
server logic directly with asyncio, eliminating the need for an asyncio
|
||||
extension.
|
||||
|
||||
Any applications built using the asyncio extension will need to update their
|
||||
imports from this::
|
||||
|
||||
from microdot_asyncio import Microdot
|
||||
|
||||
to this::
|
||||
|
||||
from microdot import Microdot
|
||||
|
||||
Applications that were built using the synchronous web server do not need to
|
||||
change their imports, but will now work asynchronously. Review the
|
||||
:ref:`Concurrency` section to learn about the potential issues when using
|
||||
``def`` function handlers, and the benefits of transitioning to ``async def``
|
||||
handlers.
|
||||
|
||||
Removed extensions
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Some extensions became unnecessary and have been removed or merged with other
|
||||
extensions:
|
||||
|
||||
- *microdot_asyncio.py*: this is now the core web server.
|
||||
- *microdot_asyncio_websocket.py*: this is now the main WebSocket extension.
|
||||
- *microdot_asyncio_test_client.py*: this is now the main test client
|
||||
extension.
|
||||
- *microdot_asgi_websocket.py*: the functionality in this extension is now
|
||||
available in the ASGI extension.
|
||||
- *microdot_ssl.py*: this extension was only used with the synchronous web
|
||||
server, so it is not needed anymore.
|
||||
- *microdot_websocket_alt.py*: this extension was only used with the
|
||||
synchronous web server, so it is not needed anymore.
|
||||
|
||||
No more ``render_template()`` function
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Jinja and uTemplate extensions have been redesigned to work better under
|
||||
the asynchronous engine, and as a result, the ``render_template()`` function
|
||||
has been eliminated.
|
||||
|
||||
Instead of this::
|
||||
|
||||
return render_template('index.html', title='Home')
|
||||
|
||||
use this::
|
||||
|
||||
return Template('index.html').render(title='Home')
|
||||
|
||||
As a result of this change, it is now possible to use asynchronous rendering::
|
||||
|
||||
return await Template('index.html').render_async(title='Home')
|
||||
|
||||
Also thanks to this redesign, the template can be streamed instead of returned
|
||||
as a single string::
|
||||
|
||||
return Template('index.html').generate(title='Home')
|
||||
|
||||
Streamed templates also have an asynchronous version::
|
||||
|
||||
return Template('index.html').generate_async(title='Home')
|
||||
|
||||
Class-based user sessions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The session extension has been completely redesigned. To initialize session
|
||||
support for the application, create a ``Session`` object::
|
||||
|
||||
app = Microdot()
|
||||
Session(app, secret_key='top-secret!')
|
||||
|
||||
The ``@with_session`` decorator is used to include the session in a request::
|
||||
|
||||
@app.get('/')
|
||||
@with_session
|
||||
async def index(request, session):
|
||||
# ...
|
||||
|
||||
The ``session`` can be used as a dictionary to retrieve or change the session.
|
||||
To save the session when it has been modified, call its ``save()`` method::
|
||||
|
||||
@app.get('/')
|
||||
@with_session
|
||||
async def index(request, session):
|
||||
# ...
|
||||
session.save()
|
||||
return 'OK'
|
||||
|
||||
To delete the session, call its ``delete()`` method before returning from the
|
||||
request.
|
||||
|
||||
WSGI extension redesign
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Given that the synchronous web server has been removed, the WSGI extension has
|
||||
been redesigned to work as a synchronous wrapper for the asynchronous web
|
||||
server.
|
||||
|
||||
Applications using the WSGI extension continue to run under an asynchronous
|
||||
loop and should try to use the recommended ``async def`` handlers, but can be
|
||||
deployed with standard WSGI servers such as Gunicorn.
|
||||
|
||||
WebSocket support when using the WSGI extension is enabled when using a
|
||||
compatible web server. At this time only Gunicorn is supported for WebSocket.
|
||||
Given that WebSocket support is asynchronous, it would be better to switch to
|
||||
the ASGI extension, which has full support for WebSocket as defined in the ASGI
|
||||
specification.
|
||||
|
||||
As before, the WSGI extension is not available under MicroPython.
|
||||
@@ -9,19 +9,16 @@ Microdot
|
||||
*"The impossibly small web framework for Python and MicroPython"*
|
||||
|
||||
Microdot is a minimalistic Python web framework inspired by
|
||||
`Flask <https://flask.palletsprojects.com/>`_. Given its size, it can run on
|
||||
systems with limited resources such as microcontrollers. Both standard Python
|
||||
(CPython) and `MicroPython <https://micropython.org>`_ are supported.
|
||||
`Flask <https://flask.palletsprojects.com/>`_, and designed to run on
|
||||
systems with limited resources such as microcontrollers. It runs on standard
|
||||
Python and on `MicroPython <https://micropython.org>`_.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 3
|
||||
|
||||
intro
|
||||
users-guide/index
|
||||
extensions/index
|
||||
implementation/index
|
||||
api/index
|
||||
contributing
|
||||
extensions
|
||||
api
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`search`
|
||||
|
||||
770
docs/intro.rst
770
docs/intro.rst
@@ -1,44 +1,754 @@
|
||||
Installation
|
||||
------------
|
||||
|
||||
The installation method is different depending on which flavor of Python you
|
||||
are using.
|
||||
|
||||
CPython Installation
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For use with standard Python (CPython) projects, Microdot and all of its core
|
||||
extensions are installed with ``pip`` or any of its alternatives::
|
||||
For standard Python (CPython) projects, Microdot and all of its core extensions
|
||||
can be installed with ``pip``::
|
||||
|
||||
pip install microdot
|
||||
|
||||
MicroPython Installation
|
||||
For MicroPython, you can install it with ``upip`` if that option is available,
|
||||
but the recommended approach is to manually copy *microdot.py* and any
|
||||
desired optional extension source files from the
|
||||
`GitHub repository <https://github.com/miguelgrinberg/microdot/tree/main/src>`_
|
||||
into your device, possibly after
|
||||
`compiling <https://docs.micropython.org/en/latest/reference/mpyfiles.html>`_
|
||||
them to *.mpy* files. These source files can also be
|
||||
`frozen <https://docs.micropython.org/en/latest/develop/optimizations.html?highlight=frozen#frozen-bytecode>`_
|
||||
and incorporated into a custom MicroPython firmware.
|
||||
|
||||
Getting Started
|
||||
---------------
|
||||
|
||||
This section describes the main features of Microdot in an informal manner. For
|
||||
detailed reference information, consult the :ref:`API Reference`.
|
||||
|
||||
A Simple Microdot Web Server
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The following is an example of a simple web server::
|
||||
|
||||
from microdot import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
def index(request):
|
||||
return 'Hello, world!'
|
||||
|
||||
app.run()
|
||||
|
||||
The script imports the :class:`Microdot <microdot.Microdot>` class and creates
|
||||
an application instance from it.
|
||||
|
||||
The application instance provides a :func:`route() <microdot.Microdot.route>`
|
||||
decorator, which is used to define one or more routes, as needed by the
|
||||
application.
|
||||
|
||||
The ``route()`` decorator takes the path portion of the URL as an
|
||||
argument, and maps it to the decorated function, so that the function is called
|
||||
when the client requests the URL. The function is passed a
|
||||
:class:`Request <microdot.Request>` object as an argument, which provides
|
||||
access to the information passed by the client. The value returned by the
|
||||
function is sent back to the client as the response.
|
||||
|
||||
The :func:`run() <microdot.Microdot.run>` method starts the application's web
|
||||
server on port 5000 (or the port number passed in the ``port`` argument). This
|
||||
method blocks while it waits for connections from clients.
|
||||
|
||||
Running with CPython
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello.py>`_
|
||||
|
||||
When using CPython, you can start the web server by running the script that
|
||||
defines and runs the application instance::
|
||||
|
||||
python main.py
|
||||
|
||||
While the script is running, you can open a web browser and navigate to
|
||||
*http://localhost:5000/*, which is the default address for the Microdot web
|
||||
server. From other computers in the same network, use the IP address or
|
||||
hostname of the computer running the script instead of ``localhost``.
|
||||
|
||||
Running with MicroPython
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For MicroPython, the recommended approach is to manually copy the necessary
|
||||
source files from the
|
||||
`GitHub repository <https://github.com/miguelgrinberg/microdot/tree/main/src>`_
|
||||
into your device.
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
Use the following guidelines to know what files to copy:
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
|
||||
|
||||
* For a minimal setup with only the base web server functionality, copy
|
||||
`microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
|
||||
to your device.
|
||||
* For a configuration that includes one or more of the optional extensions,
|
||||
create a *microdot* directory in your device and copy the following files:
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* `__init__.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/__init__.py>`_
|
||||
* `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
|
||||
* any needed `extensions <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot>`_.
|
||||
* - Examples
|
||||
- | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello.py>`_
|
||||
| `gpio.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/gpio/gpio.py>`_
|
||||
|
||||
Some of the low end devices are perfectly capable of running Microdot once
|
||||
compiled, but do not have enough RAM for the compiler. For these cases you can
|
||||
`pre-compile <https://docs.micropython.org/en/latest/reference/mpyfiles.html>`_
|
||||
the files to *.mpy* files for the version of MicroPython that you use in your
|
||||
device.
|
||||
When using MicroPython, you can upload a *main.py* file containing the web
|
||||
server code to your device along with *microdot.py*. MicroPython will
|
||||
automatically run *main.py* when the device is powered on, so the web server
|
||||
will automatically start. The application can be accessed on port 5000 at the
|
||||
device's IP address. As indicated above, the port can be changed by passing the
|
||||
``port`` argument to the ``run()`` method.
|
||||
|
||||
If space in your device is extremely tight, you may also consider
|
||||
`freezing <https://docs.micropython.org/en/latest/develop/optimizations.html?highlight=frozen#frozen-bytecode>`_
|
||||
the Microdot files and incorporating them into a custom MicroPython firmware.
|
||||
.. note::
|
||||
Microdot does not configure the network interface of the device in which it
|
||||
is running. If your device requires a network connection to be made in
|
||||
advance, for example to a Wi-Fi access point, this must be configured before
|
||||
the ``run()`` method is invoked.
|
||||
|
||||
Defining Routes
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The :func:`route() <microdot.Microdot.route>` decorator is used to associate an
|
||||
application URL with the function that handles it. The only required argument
|
||||
to the decorator is the path portion of the URL.
|
||||
|
||||
The following example creates a route for the root URL of the application::
|
||||
|
||||
@app.route('/')
|
||||
def index(request):
|
||||
return 'Hello, world!'
|
||||
|
||||
When a client requests the root URL (for example, *http://localhost:5000/*),
|
||||
Microdot will call the ``index()`` function, passing it a
|
||||
:class:`Request <microdot.Request>` object. The return value of the function
|
||||
is the response that is sent to the client.
|
||||
|
||||
Below is a another example, this one with a route for a URL with two components
|
||||
in its path::
|
||||
|
||||
@app.route('/users/active')
|
||||
def active_users(request):
|
||||
return 'Active users: Susan, Joe, and Bob'
|
||||
|
||||
The complete URL that maps to this route is
|
||||
*http://localhost:5000/users/active*.
|
||||
|
||||
An application can include multiple routes. Microdot uses the path portion of
|
||||
the URL to determine the correct route function to call for each incoming
|
||||
request.
|
||||
|
||||
Choosing the HTTP Method
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
All the example routes shown above are associated with ``GET`` requests. But
|
||||
applications often need to define routes for other HTTP methods, such as
|
||||
``POST``, ``PUT``, ``PATCH`` and ``DELETE``. The ``route()`` decorator takes a
|
||||
``methods`` optional argument, in which the application can provide a list of
|
||||
HTTP methods that the route should be associated with on the given path.
|
||||
|
||||
The following example defines a route that handles ``GET`` and ``POST``
|
||||
requests within the same function::
|
||||
|
||||
@app.route('/invoices', methods=['GET', 'POST'])
|
||||
def invoices(request):
|
||||
if request.method == 'GET':
|
||||
return 'get invoices'
|
||||
elif request.method == 'POST':
|
||||
return 'create an invoice'
|
||||
|
||||
In cases like the above, where a single URL is used to handle multiple HTTP
|
||||
methods, it may be desirable to write a separate function for each HTTP method.
|
||||
The above example can be implemented with two routes as follows::
|
||||
|
||||
@app.route('/invoices', methods=['GET'])
|
||||
def get_invoices(request):
|
||||
return 'get invoices'
|
||||
|
||||
@app.route('/invoices', methods=['POST'])
|
||||
def create_invoice(request):
|
||||
return 'create an invoice'
|
||||
|
||||
Microdot provides the :func:`get() <microdot.Microdot.get>`,
|
||||
:func:`post() <microdot.Microdot.post>`, :func:`put() <microdot.Microdot.put>`,
|
||||
:func:`patch() <microdot.Microdot.patch>`, and
|
||||
:func:`delete() <microdot.Microdot.delete>` decorator shortcuts as well. The
|
||||
two example routes above can be written more concisely with them::
|
||||
|
||||
@app.get('/invoices')
|
||||
def get_invoices(request):
|
||||
return 'get invoices'
|
||||
|
||||
@app.post('/invoices')
|
||||
def create_invoice(request):
|
||||
return 'create an invoice'
|
||||
|
||||
Including Dynamic Components in the URL Path
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The examples shown above all use hardcoded URL paths. Microdot also supports
|
||||
the definition of routes that have dynamic components in the path. For example,
|
||||
the following route associates all URLs that have a path following the pattern
|
||||
*http://localhost:5000/users/<username>* with the ``get_user()`` function::
|
||||
|
||||
@app.get('/users/<username>')
|
||||
def get_user(request, username):
|
||||
return 'User: ' + username
|
||||
|
||||
As shown in the example, a path components that is enclosed in angle brackets
|
||||
is considered dynamic. Microdot accepts any values for that section of the URL
|
||||
path, and passes the value received to the function as an argument after
|
||||
the request object.
|
||||
|
||||
Routes are not limited to a single dynamic component. The following route shows
|
||||
how multiple dynamic components can be included in the path::
|
||||
|
||||
@app.get('/users/<firstname>/<lastname>')
|
||||
def get_user(request, firstname, lastname):
|
||||
return 'User: ' + firstname + ' ' + lastname
|
||||
|
||||
Dynamic path components are considered to be strings by default. An explicit
|
||||
type can be specified as a prefix, separated from the dynamic component name by
|
||||
a colon. The following route has two dynamic components declared as an integer
|
||||
and a string respectively::
|
||||
|
||||
@app.get('/users/<int:id>/<string:username>')
|
||||
def get_user(request, id, username):
|
||||
return 'User: ' + username + ' (' + str(id) + ')'
|
||||
|
||||
If a dynamic path component is defined as an integer, the value passed to the
|
||||
route function is also an integer. If the client sends a value that is not an
|
||||
integer in the corresponding section of the URL path, then the URL will not
|
||||
match and the route will not be called.
|
||||
|
||||
A special type ``path`` can be used to capture the remainder of the path as a
|
||||
single argument::
|
||||
|
||||
@app.get('/tests/<path:path>')
|
||||
def get_test(request, path):
|
||||
return 'Test: ' + path
|
||||
|
||||
For the most control, the ``re`` type allows the application to provide a
|
||||
custom regular expression for the dynamic component. The next example defines
|
||||
a route that only matches usernames that begin with an upper or lower case
|
||||
letter, followed by a sequence of letters or numbers::
|
||||
|
||||
@app.get('/users/<re:[a-zA-Z][a-zA-Z0-9]*:username>')
|
||||
def get_user(request, username):
|
||||
return 'User: ' + username
|
||||
|
||||
.. note::
|
||||
Dynamic path components are passed to route functions as keyword arguments,
|
||||
so the names of the function arguments must match the names declared in the
|
||||
path specification.
|
||||
|
||||
Before and After Request Handlers
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
It is common for applications to need to perform one or more actions before a
|
||||
request is handled. Examples include authenticating and/or authorizing the
|
||||
client, opening a connection to a database, or checking if the requested
|
||||
resource can be obtained from a cache. The
|
||||
:func:`before_request() <microdot.Microdot.before_request>` decorator registers
|
||||
a function to be called before the request is dispatched to the route function.
|
||||
|
||||
The following example registers a before request handler that ensures that the
|
||||
client is authenticated before the request is handled::
|
||||
|
||||
@app.before_request
|
||||
def authenticate(request):
|
||||
user = authorize(request)
|
||||
if not user:
|
||||
return 'Unauthorized', 401
|
||||
request.g.user = user
|
||||
|
||||
Before request handlers receive the request object as an argument. If the
|
||||
function returns a value, Microdot sends it to the client as the response, and
|
||||
does not invoke the route function. This gives before request handlers the
|
||||
power to intercept a request if necessary. The example above uses this
|
||||
technique to prevent an unauthorized user from accessing the requested
|
||||
resource.
|
||||
|
||||
After request handlers registered with the
|
||||
:func:`after_request() <microdot.Microdot.after_request>` decorator are called
|
||||
after the route function returns a response. Their purpose is to perform any
|
||||
common closing or cleanup tasks. The next example shows a combination of before
|
||||
and after request handlers that print the time it takes for a request to be
|
||||
handled::
|
||||
|
||||
@app.before_request
|
||||
def start_timer(request):
|
||||
request.g.start_time = time.time()
|
||||
|
||||
@ap.after_request
|
||||
def end_timer(request, response):
|
||||
duration = time.time() - request.g.start_time
|
||||
print(f'Request took {duration:0.2f} seconds')
|
||||
|
||||
After request handlers receive the request and response objects as arguments.
|
||||
The function can return a modified response object to replace the original. If
|
||||
the function does not return a value, then the original response object is
|
||||
used.
|
||||
|
||||
.. note::
|
||||
The :ref:`request.g <The "g" Object>` object is a special object that allows
|
||||
the before and after request handlers, as well sa the route function to
|
||||
share data during the life of the request.
|
||||
|
||||
Error Handlers
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
When an error occurs during the handling of a request, Microdot ensures that
|
||||
the client receives an appropriate error response. Some of the common errors
|
||||
automatically handled by Microdot are:
|
||||
|
||||
- 400 for malformed requests.
|
||||
- 404 for URLs that are not defined.
|
||||
- 405 for URLs that are defined, but not for the requested HTTP method.
|
||||
- 413 for requests that are larger than the allowed size.
|
||||
- 500 when the application raises an exception.
|
||||
|
||||
While the above errors are fully complaint with the HTTP specification, the
|
||||
application might want to provide custom responses for them. The
|
||||
:func:`errorhandler() <microdot.Microdot.errorhandler>` decorator registers
|
||||
a functions to respond to specific error codes. The following example shows a
|
||||
custom error handler for 404 errors::
|
||||
|
||||
@app.errorhandler(404)
|
||||
def not_found(request):
|
||||
return {'error': 'resource not found'}, 404
|
||||
|
||||
The ``errorhandler()`` decorator has a second form, in which it takes an
|
||||
exception class as an argument. Microdot will then invoke the handler when an
|
||||
exception of that class is raised. The next example provides a custom response
|
||||
for division by zero errors::
|
||||
|
||||
@app.errorhandler(ZeroDivisionError)
|
||||
def division_by_zero(request):
|
||||
return {'error': 'division by zero'}, 500
|
||||
|
||||
Mounting a Sub-Application
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Small Microdot applications can be written an a single source file, but this
|
||||
is not the best option for applications that past certain size. To make it
|
||||
simpler to write large applications, Microdot supports the concept of
|
||||
sub-applications that can be "mounted" on a larger application, possibly with
|
||||
a common URL prefix applied to all of its routes.
|
||||
|
||||
Consider, for example, a *customers.py* sub-application that implements
|
||||
operations on customers::
|
||||
|
||||
from microdot import Microdot
|
||||
|
||||
customers_app = Microdot()
|
||||
|
||||
@customers_app.get('/')
|
||||
def get_customers(request):
|
||||
# return all customers
|
||||
|
||||
@customers_app.post('/')
|
||||
def new_customer(request):
|
||||
# create a new customer
|
||||
|
||||
In the same way, the *orders.py* sub-application implements operations on
|
||||
customer orders::
|
||||
|
||||
from microdot import Microdot
|
||||
|
||||
orders_app = Microdot()
|
||||
|
||||
@orders_app.get('/')
|
||||
def get_orders(request):
|
||||
# return all orders
|
||||
|
||||
@orders_app.post('/')
|
||||
def new_order(request):
|
||||
# create a new order
|
||||
|
||||
Now the main application, which is stored in *main.py*, can import and mount
|
||||
the sub-applications to build the combined application::
|
||||
|
||||
from microdot import Microdot
|
||||
from customers import customers_app
|
||||
from orders import orders_app
|
||||
|
||||
def create_app():
|
||||
app = Microdot()
|
||||
app.mount(customers_app, url_prefix='/customers')
|
||||
app.mount(orders_app, url_prefix='/orders')
|
||||
return app
|
||||
|
||||
app = create_app()
|
||||
app.run()
|
||||
|
||||
The resulting application will have the customer endpoints available at
|
||||
*/customers/* and the order endpoints available at */orders/*.
|
||||
|
||||
.. note::
|
||||
Before request, after request and error handlers defined in the
|
||||
sub-application are also copied over to the main application at mount time.
|
||||
Once installed in the main application, these handlers will apply to the
|
||||
whole application and not just the sub-application in which they were
|
||||
created.
|
||||
|
||||
Shutting Down the Server
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Web servers are designed to run forever, and are often stopped by sending them
|
||||
an interrupt signal. But having a way to gracefully stop the server is
|
||||
sometimes useful, especially in testing environments. Microdot provides a
|
||||
:func:`shutdown() <microdot.Microdot.shutdown>` method that can be invoked
|
||||
during the handling of a route to gracefully shut down the server when that
|
||||
request completes. The next example shows how to use this feature::
|
||||
|
||||
@app.get('/shutdown')
|
||||
def shutdown(request):
|
||||
request.app.shutdown()
|
||||
return 'The server is shutting down...'
|
||||
|
||||
The Request Object
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The :class:`Request <microdot.Request>` object encapsulates all the information
|
||||
passed by the client. It is passed as an argument to route handlers, as well as
|
||||
to before request, after request and error handlers.
|
||||
|
||||
Request Attributes
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The request object provides access to the request attributes, including:
|
||||
|
||||
- :attr:`method <microdot.Request.method>`: The HTTP method of the request.
|
||||
- :attr:`path <microdot.Request.path>`: The path of the request.
|
||||
- :attr:`args <microdot.Request.args>`: The query string parameters of the
|
||||
request, as a :class:`MultiDict <microdot.MultiDict>` object.
|
||||
- :attr:`headers <microdot.Request.headers>`: The headers of the request, as a
|
||||
dictionary.
|
||||
- :attr:`cookies <microdot.Request.cookies>`: The cookies that the client sent
|
||||
with the request, as a dictionary.
|
||||
- :attr:`content_type <microdot.Request.content_type>`: The content type
|
||||
specified by the client, or ``None`` if no content type was specified.
|
||||
- :attr:`content_length <microdot.Request.content_length>`: The content
|
||||
length of the request, or 0 if no content length was specified.
|
||||
- :attr:`client_addr <microdot.Request.client_addr>`: The network address of
|
||||
the client, as a tuple (host, port).
|
||||
- :attr:`app <microdot.Request.app>`: The application instance that created the
|
||||
request.
|
||||
|
||||
JSON Payloads
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
When the client sends a request that contains JSON data in the body, the
|
||||
application can access the parsed JSON data using the
|
||||
:attr:`json <microdot.Request.json>` attribute. The following example shows how
|
||||
to use this attribute::
|
||||
|
||||
@app.post('/customers')
|
||||
def create_customer(request):
|
||||
customer = request.json
|
||||
# do something with customer
|
||||
return {'success': True}
|
||||
|
||||
.. note::
|
||||
The client must set the ``Content-Type`` header to ``application/json`` for
|
||||
the ``json`` attribute of the request object to be populated.
|
||||
|
||||
URLEncoded Form Data
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The request object also supports standard HTML form submissions through the
|
||||
:attr:`form <microdot.Request.form>` attribute, which presents the form data
|
||||
as a :class:`MultiDict <microdot.MultiDict>` object. Example::
|
||||
|
||||
@app.route('/', methods=['GET', 'POST'])
|
||||
def index(req):
|
||||
name = 'Unknown'
|
||||
if req.method == 'POST':
|
||||
name = req.form.get('name')
|
||||
return f'Hello {name}'
|
||||
|
||||
.. note::
|
||||
Form submissions are only parsed when the ``Content-Type`` header is set by
|
||||
the client to ``application/x-www-form-urlencoded``. Form submissions using
|
||||
the ``multipart/form-data`` content type are currently not supported.
|
||||
|
||||
Accessing the Raw Request Body
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For cases in which neither JSON nor form data is expected, the
|
||||
:attr:`body <microdot.Request.body>` request attribute returns the entire body
|
||||
of the request as a byte sequence.
|
||||
|
||||
If the expected body is too large to fit in memory, the application can use the
|
||||
:attr:`stream <microdot.Request.stream>` request attribute to read the body
|
||||
contents as a file-like object.
|
||||
|
||||
Cookies
|
||||
^^^^^^^
|
||||
|
||||
Cookies that are sent by the client are made available throught the
|
||||
:attr:`cookies <microdot.Request.cookies>` attribute of the request object in
|
||||
dictionary form.
|
||||
|
||||
The "g" Object
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes applications need to store data during the lifetime of a request, so
|
||||
that it can be shared between the before or after request handlers and the
|
||||
route function. The request object provides the :attr:`g <microdot.Request.g>`
|
||||
attribute for that purpose.
|
||||
|
||||
In the following example, a before request handler
|
||||
authorizes the client and stores the username so that the route function can
|
||||
use it::
|
||||
|
||||
@app.before_request
|
||||
def authorize(request):
|
||||
username = authenticate_user(request)
|
||||
if not username:
|
||||
return 'Unauthorized', 401
|
||||
request.g.username = username
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
return f'Hello, {request.g.username}!'
|
||||
|
||||
Request-Specific After Request Handlers
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes applications need to perform operations on the response object,
|
||||
before it is sent to the client, for example to set or remove a cookie. A good
|
||||
option to use for this is to define a request-specific after request handler
|
||||
using the :func:`after_request <microdot.Microdot.after_request>` decorator.
|
||||
Request-specific after request handlers are called by Microdot after the route
|
||||
function returns and all the application's after request handlers have been
|
||||
called.
|
||||
|
||||
The next example shows how a cookie can be updated using a request-specific
|
||||
after request handler defined inside a route function::
|
||||
|
||||
@app.post('/logout')
|
||||
def logout(request):
|
||||
@request.after_request
|
||||
def reset_session(request, response):
|
||||
response.set_cookie('session', '', http_only=True)
|
||||
return response
|
||||
|
||||
return 'Logged out'
|
||||
|
||||
Request Limits
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
To help prevent malicious attacks, Microdot provides some configuration options
|
||||
to limit the amount of information that is accepted:
|
||||
|
||||
- :attr:`max_content_length <microdot.Microdot.max_content_length>`: The
|
||||
maximum size accepted for the request body, in bytes. When a client sends a
|
||||
request that is larger than this, the server will respond with a 413 error.
|
||||
The default is 16KB.
|
||||
- :attr:`max_body_length <microdot.Microdot.max_body_length>`: The maximum
|
||||
size that is loaded in the :attr:`body <microdot.Request.body>` attribute, in
|
||||
bytes. Requests that have a body that is larger than this size but smaller
|
||||
than the size set for ``max_content_length`` can only be accessed through the
|
||||
:attr:`stream <microdot.Request.stream>` attribute. The default is also 16KB.
|
||||
- :attr:`max_readline <microdot.Microdot.max_readline>`: The maximum allowed
|
||||
size for a request line, in bytes. The default is 2KB.
|
||||
|
||||
The following example configures the application to accept requests with
|
||||
payloads up to 1MB big, but prevents requests that are larger than 8KB from
|
||||
being loaded into memory::
|
||||
|
||||
Request.max_content_length = 1024 * 1024
|
||||
Request.max_body_length = 8 * 1024
|
||||
|
||||
Responses
|
||||
~~~~~~~~~
|
||||
|
||||
The value or values that are returned from the route function are used by
|
||||
Microdot to build the response that is sent to the client. The following
|
||||
sections describe the different types of responses that are supported.
|
||||
|
||||
The Three Parts of a Response
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Route functions can return one, two or three values. The first or only value is
|
||||
always returned to the client in the response body::
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
return 'Hello, World!'
|
||||
|
||||
In the above example, Microdot issues a standard 200 status code response, and
|
||||
inserts the necessary headers.
|
||||
|
||||
The applicaton can provide its own status code as a second value returned from
|
||||
the route. The example below returns a 202 status code::
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
return 'Hello, World!', 202
|
||||
|
||||
The application can also return a third value, a dictionary with additional
|
||||
headers that are added to, or replace the default ones provided by Microdot.
|
||||
The next example returns an HTML response, instead of a default text response::
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
return '<h1>Hello, World!</h1>', 202, {'Content-Type': 'text/html'}
|
||||
|
||||
If the application needs to return custom headers, but does not need to change
|
||||
the default status code, then it can return two values, omitting the stauts
|
||||
code::
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
return '<h1>Hello, World!</h1>', {'Content-Type': 'text/html'}
|
||||
|
||||
The application can also return a :class:`Response <microdot.Response>` object
|
||||
containing all the details of the response as a single value.
|
||||
|
||||
JSON Responses
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
If the application needs to return a response with JSON formatted data, it can
|
||||
return a dictionary or a list as the first value, and Microdot will
|
||||
automatically format the response as JSON.
|
||||
|
||||
Example::
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
return {'hello': 'world'}
|
||||
|
||||
.. note::
|
||||
A ``Content-Type`` header set to ``application/json`` is automatically added
|
||||
to the response.
|
||||
|
||||
Redirects
|
||||
^^^^^^^^^
|
||||
|
||||
The :func:`redirect <microdot.Response.redirect>` function is a helper that
|
||||
creates redirect responses::
|
||||
|
||||
from microdot import redirect
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
return redirect('/about')
|
||||
|
||||
File Responses
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
The :func:`send_file <microdot.Response.send_file>` function builds a response
|
||||
object for a file::
|
||||
|
||||
from microdot import send_file
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
return send_file('/static/index.html')
|
||||
|
||||
.. note::
|
||||
Unlike other web frameworks, Microdot does not automatically configure a
|
||||
route to serve static files. The following is an example route that can be
|
||||
added to the application to serve static files from a *static* directory in
|
||||
the project::
|
||||
|
||||
@app.route('/static/<path:path>')
|
||||
def static(request, path):
|
||||
if '..' in path:
|
||||
# directory traversal is not allowed
|
||||
return 'Not found', 404
|
||||
return send_file('static/' + path)
|
||||
|
||||
Streaming Responses
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Instead of providing a response as a single value, an application can opt to
|
||||
return a response that is generated in chunks by returning a generator. The
|
||||
example below returns all the numbers in the fibonacci sequence below 100::
|
||||
|
||||
@app.get('/fibonacci')
|
||||
def fibonacci(request):
|
||||
def generate_fibonacci():
|
||||
a, b = 0, 1
|
||||
while a < 100:
|
||||
yield str(a) + '\n'
|
||||
a, b = b, a + b
|
||||
|
||||
return generate_fibonacci()
|
||||
|
||||
Changing the Default Response Content Type
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Microdot uses a ``text/plain`` content type by default for responses that do
|
||||
not explicitly include the ``Content-Type`` header. The application can change
|
||||
this default by setting the desired content type in the
|
||||
:attr:`default_content_type <microdot.Response.default_content_type>` attribute
|
||||
of the :class:`Response <microdot.Response>` class.
|
||||
|
||||
The example that follows configures the application to use ``text/html`` as
|
||||
default content type::
|
||||
|
||||
from microdot import Response
|
||||
|
||||
Response.default_content_type = 'text/html'
|
||||
|
||||
Setting Cookies
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Many web applications rely on cookies to maintain client state between
|
||||
requests. Cookies can be set with the ``Set-Cookie`` header in the response,
|
||||
but since this is such a common practice, Microdot provides the
|
||||
:func:`set_cookie() <microdot.Response.set_cookie>` method in the response
|
||||
object to add a properly formatted cookie header to the response.
|
||||
|
||||
Given that route functions do not normally work directly with the response
|
||||
object, the recommended way to set a cookie is to do it in a
|
||||
:ref:`Request-Specific After Request Handler <Request-Specific After Request Handlers>`.
|
||||
|
||||
Example::
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
@request.after_request
|
||||
def set_cookie(request, response):
|
||||
response.set_cookie('name', 'value')
|
||||
return response
|
||||
|
||||
return 'Hello, World!'
|
||||
|
||||
Another option is to create a response object directly in the route function::
|
||||
|
||||
@app.get('/')
|
||||
def index(request):
|
||||
response = Response('Hello, World!')
|
||||
response.set_cookie('name', 'value')
|
||||
return response
|
||||
|
||||
.. note::
|
||||
Standard cookies do not offer sufficient privacy and security controls, so
|
||||
never store sensitive information in them unless you are adding additional
|
||||
protection mechanisms such as encryption or cryptographic signing. The
|
||||
:ref:`session <Maintaing Secure User Sessions>` extension implements signed
|
||||
cookies that prevent tampering by malicious actors.
|
||||
|
||||
Concurrency
|
||||
~~~~~~~~~~~
|
||||
|
||||
By default, Microdot runs in synchronous (single-threaded) mode. However, if
|
||||
the ``threading`` module is available, each request will be started on a
|
||||
separate thread and requests will be handled concurrently.
|
||||
|
||||
Be aware that most microcontroller boards support a very limited form of
|
||||
multi-threading that is not appropriate for concurrent request handling. For
|
||||
that reason, use of the `threading <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/threading/threading.py>`_
|
||||
module on microcontroller platforms is not recommended.
|
||||
|
||||
The :ref:`micropython_asyncio <Asynchronous Support with Asyncio>` extension
|
||||
provides a more robust concurrency option that is supported even on low-end
|
||||
MicroPython boards.
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
Concurrency
|
||||
~~~~~~~~~~~
|
||||
|
||||
Microdot implements concurrency through the ``asyncio`` package, which means
|
||||
that applications must be careful to prevent blocking in their handlers.
|
||||
|
||||
"async def" handlers
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The recommendation for route handlers in Microdot is to use asynchronous
|
||||
functions, declared as ``async def``. Microdot executes these handler
|
||||
functions as native asynchronous tasks. The standard considerations for writing
|
||||
asynchronous code apply, and in particular blocking calls should be avoided to
|
||||
ensure the application runs smoothly and is always responsive.
|
||||
|
||||
"def" handlers
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Microdot also supports the use of synchronous route handlers, declared as
|
||||
standard ``def`` functions. These handlers are handled differently under
|
||||
CPython and MicroPython.
|
||||
|
||||
When running on CPython, Microdot executes synchronous handlers in a
|
||||
`thread executor <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor>`_,
|
||||
which uses a thread pool. The use of blocking or CPU intensive code in these
|
||||
handlers does not have such a negative effect on the application, because
|
||||
handlers do not run on the same thread as the asynchronous loop. On the other
|
||||
hand, the application will be affected by threading issues such as those caused
|
||||
by the Global Interpreter Lock.
|
||||
|
||||
Under MicroPython the situation is different. Most microcontroller boards
|
||||
do not have or have very limited threading support, so Microdot executes
|
||||
synchronous handlers in the main and often only thread available. This means
|
||||
that these functions will block the asynchronous loop when they take too long
|
||||
to complete. The use of properly written asynchronous handlers should be
|
||||
preferred.
|
||||
@@ -1,378 +0,0 @@
|
||||
Defining Routes
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
In Microdot, routes define the logic of the web application.
|
||||
|
||||
The route decorator
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
The :func:`route() <microdot.Microdot.route>` decorator is used to associate an
|
||||
application URL with the function that handles it. The only required argument
|
||||
to the decorator is the path portion of the URL.
|
||||
|
||||
The following example creates a route for the root URL of the application::
|
||||
|
||||
@app.route('/')
|
||||
async def index(request):
|
||||
return 'Hello, world!'
|
||||
|
||||
When a client requests the root URL (for example, *http://localhost:5000/*),
|
||||
Microdot will call the ``index()`` function, passing it a
|
||||
:class:`Request <microdot.Request>` object. The return value of the function
|
||||
is the response that is sent to the client.
|
||||
|
||||
Below is another example, this one with a route for a URL with two components
|
||||
in its path::
|
||||
|
||||
@app.route('/users/active')
|
||||
async def active_users(request):
|
||||
return 'Active users: Susan, Joe, and Bob'
|
||||
|
||||
The complete URL that maps to this route is
|
||||
*http://localhost:5000/users/active*.
|
||||
|
||||
An application can define multiple routes. Microdot uses the path portion of
|
||||
the URL to determine the correct route function to call for each incoming
|
||||
request.
|
||||
|
||||
Choosing the HTTP Method
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
All the example routes shown above are associated with ``GET`` requests, which
|
||||
are the default. Applications often need to define routes for other HTTP
|
||||
methods, such as ``POST``, ``PUT``, ``PATCH`` and ``DELETE``. The ``route()``
|
||||
decorator takes a ``methods`` optional argument, in which the application can
|
||||
provide a list of HTTP methods that the route should be associated with on the
|
||||
given path.
|
||||
|
||||
The following example defines a route that handles ``GET`` and ``POST``
|
||||
requests within the same function::
|
||||
|
||||
@app.route('/invoices', methods=['GET', 'POST'])
|
||||
async def invoices(request):
|
||||
if request.method == 'GET':
|
||||
return 'get invoices'
|
||||
elif request.method == 'POST':
|
||||
return 'create an invoice'
|
||||
|
||||
As an alternative to the example above, in which a single function is used to
|
||||
handle multiple HTTP methods, sometimes it may be desirable to write a separate
|
||||
function for each HTTP method. The above example can be implemented with two
|
||||
routes as follows::
|
||||
|
||||
@app.route('/invoices', methods=['GET'])
|
||||
async def get_invoices(request):
|
||||
return 'get invoices'
|
||||
|
||||
@app.route('/invoices', methods=['POST'])
|
||||
async def create_invoice(request):
|
||||
return 'create an invoice'
|
||||
|
||||
Microdot provides the :func:`get() <microdot.Microdot.get>`,
|
||||
:func:`post() <microdot.Microdot.post>`, :func:`put() <microdot.Microdot.put>`,
|
||||
:func:`patch() <microdot.Microdot.patch>`, and
|
||||
:func:`delete() <microdot.Microdot.delete>` decorators as shortcuts for the
|
||||
corresponding HTTP methods. The two example routes above can be written more
|
||||
concisely with them::
|
||||
|
||||
@app.get('/invoices')
|
||||
async def get_invoices(request):
|
||||
return 'get invoices'
|
||||
|
||||
@app.post('/invoices')
|
||||
async def create_invoice(request):
|
||||
return 'create an invoice'
|
||||
|
||||
Including Dynamic Components in the URL Path
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The examples shown above all use hardcoded URL paths. Microdot also supports
|
||||
the definition of routes that have dynamic components in the path. For example,
|
||||
the following route associates all URLs that have a path following the pattern
|
||||
*http://localhost:5000/users/<username>* with the ``get_user()`` function::
|
||||
|
||||
@app.get('/users/<username>')
|
||||
async def get_user(request, username):
|
||||
return 'User: ' + username
|
||||
|
||||
As shown in the example, a path component that is enclosed in angle brackets
|
||||
is considered a placeholder. Microdot accepts any values for that portion of
|
||||
the URL path, and passes the value received to the function as an argument
|
||||
after the request object.
|
||||
|
||||
Routes are not limited to a single dynamic component. The following route shows
|
||||
how multiple dynamic components can be included in the path::
|
||||
|
||||
@app.get('/users/<firstname>/<lastname>')
|
||||
async def get_user(request, firstname, lastname):
|
||||
return 'User: ' + firstname + ' ' + lastname
|
||||
|
||||
Dynamic path components are considered to be strings by default. An explicit
|
||||
type can be specified as a prefix, separated from the dynamic component name by
|
||||
a colon. The following route has two dynamic components declared as an integer
|
||||
and a string respectively::
|
||||
|
||||
@app.get('/users/<int:id>/<string:username>')
|
||||
async def get_user(request, id, username):
|
||||
return 'User: ' + username + ' (' + str(id) + ')'
|
||||
|
||||
If a dynamic path component is defined as an integer, the value passed to the
|
||||
route function is also an integer. If the client sends a value that is not an
|
||||
integer in the corresponding section of the URL path, then the URL will not
|
||||
match and the route will not be called.
|
||||
|
||||
A special type ``path`` can be used to capture the remainder of the path as a
|
||||
single argument. The difference between an argument of type ``path`` and one of
|
||||
type ``string`` is that the latter stops capturing when a ``/`` appears in the
|
||||
URL::
|
||||
|
||||
@app.get('/tests/<path:path>')
|
||||
async def get_test(request, path):
|
||||
return 'Test: ' + path
|
||||
|
||||
The ``re`` type allows the application to provide a custom regular expression
|
||||
for the dynamic component. The next example defines a route that only matches
|
||||
usernames that begin with an upper or lower case letter, followed by a sequence
|
||||
of letters or numbers::
|
||||
|
||||
@app.get('/users/<re:[a-zA-Z][a-zA-Z0-9]*:username>')
|
||||
async def get_user(request, username):
|
||||
return 'User: ' + username
|
||||
|
||||
The ``re`` type returns the URL component as a string, which sometimes may not
|
||||
be the most convenient. To convert a path component to something more
|
||||
meaningful than a string, the application can register a custom URL component
|
||||
type and provide a parser function that performs the conversion. In the
|
||||
following example, a ``hex`` custom type is registered to automatically
|
||||
convert hex numbers given in the path to numbers::
|
||||
|
||||
from microdot import URLPattern
|
||||
|
||||
URLPattern.register_type('hex', parser=lambda value: int(value, 16))
|
||||
|
||||
@app.get('/users/<hex:user_id>')
|
||||
async def get_user(request, user_id):
|
||||
user = get_user_by_id(user_id)
|
||||
# ...
|
||||
|
||||
In addition to the parser, the custom URL component can include a pattern,
|
||||
given as a regular expression. When a pattern is provided, the URL component
|
||||
will only match if the regular expression matches the value passed in the URL.
|
||||
The ``hex`` example above can be expanded with a pattern as follows::
|
||||
|
||||
URLPattern.register_type('hex', pattern='[0-9a-fA-F]+',
|
||||
parser=lambda value: int(value, 16))
|
||||
|
||||
In cases where a pattern isn't provided, or when the pattern is unable to
|
||||
filter out all invalid values, the parser function can return ``None`` to
|
||||
indicate a failed match. The next example shows how the parser for the ``hex``
|
||||
type can be expanded to do that::
|
||||
|
||||
def hex_parser(value):
|
||||
try:
|
||||
return int(value, 16)
|
||||
except ValueError:
|
||||
return None
|
||||
|
||||
URLPattern.register_type('hex', parser=hex_parser)
|
||||
|
||||
.. note::
|
||||
Dynamic path components are passed to route functions as keyword arguments,
|
||||
so the names of the function arguments must match the names declared in the
|
||||
path specification.
|
||||
|
||||
Before and After Request Handlers
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
It is common for applications to need to perform one or more actions before a
|
||||
request is handled. Examples include authenticating and/or authorizing the
|
||||
client, opening a connection to a database, or checking if the requested
|
||||
resource can be obtained from a cache. The
|
||||
:func:`before_request() <microdot.Microdot.before_request>` decorator registers
|
||||
a function to be called before the request is dispatched to the route function.
|
||||
|
||||
The following example registers a before-request handler that ensures that the
|
||||
client is authenticated before the request is handled::
|
||||
|
||||
@app.before_request
|
||||
async def authenticate(request):
|
||||
user = authorize(request)
|
||||
if not user:
|
||||
return 'Unauthorized', 401
|
||||
request.g.user = user
|
||||
|
||||
Before-request handlers receive the request object as an argument. If the
|
||||
function returns a value, Microdot sends it to the client as the response, and
|
||||
does not invoke the route function. This gives before-request handlers the
|
||||
power to intercept a request if necessary. The example above uses this
|
||||
technique to prevent an unauthorized user from accessing the requested
|
||||
route.
|
||||
|
||||
After-request handlers registered with the
|
||||
:func:`after_request() <microdot.Microdot.after_request>` decorator are called
|
||||
after the route function returns a response. Their purpose is to perform any
|
||||
common closing or cleanup tasks. The next example shows a combination of
|
||||
before- and after-request handlers that print the time it takes for a request
|
||||
to be handled::
|
||||
|
||||
@app.before_request
|
||||
async def start_timer(request):
|
||||
request.g.start_time = time.time()
|
||||
|
||||
@app.after_request
|
||||
async def end_timer(request, response):
|
||||
duration = time.time() - request.g.start_time
|
||||
print(f'Request took {duration:0.2f} seconds')
|
||||
|
||||
After-request handlers receive the request and response objects as arguments,
|
||||
and they can return a modified response object to replace the original. If
|
||||
no value is returned from an after-request handler, then the original response
|
||||
object is used.
|
||||
|
||||
The after-request handlers are only invoked for successful requests. The
|
||||
:func:`after_error_request() <microdot.Microdot.after_error_request>`
|
||||
decorator can be used to register a function that is called after an error
|
||||
occurs. The function receives the request and the error response and is
|
||||
expected to return an updated response object after performing any necessary
|
||||
cleanup.
|
||||
|
||||
.. note::
|
||||
The :ref:`request.g <The "g" Object>` object used in many of the above
|
||||
examples is a special object that allows the before- and after-request
|
||||
handlers, as well as the route function to share data during the life of the
|
||||
request.
|
||||
|
||||
Error Handlers
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
When an error occurs during the handling of a request, Microdot ensures that
|
||||
the client receives an appropriate error response. Some of the common errors
|
||||
automatically handled by Microdot are:
|
||||
|
||||
- 400 for malformed requests.
|
||||
- 404 for URLs that are unknown.
|
||||
- 405 for URLs that are known, but not implemented for the requested HTTP
|
||||
method.
|
||||
- 413 for requests that are larger than the allowed size.
|
||||
- 500 when the application raises an unhandled exception.
|
||||
|
||||
While the above errors are fully complaint with the HTTP specification, the
|
||||
application might want to provide custom responses for them. The
|
||||
:func:`errorhandler() <microdot.Microdot.errorhandler>` decorator registers
|
||||
functions to respond to specific error codes. The following example shows a
|
||||
custom error handler for 404 errors::
|
||||
|
||||
@app.errorhandler(404)
|
||||
async def not_found(request):
|
||||
return {'error': 'resource not found'}, 404
|
||||
|
||||
The ``errorhandler()`` decorator has a second form, in which it takes an
|
||||
exception class as an argument. Microdot will invoke the handler when an
|
||||
unhandled exception that is an instance of the given class is raised. The next
|
||||
example provides a custom response for division by zero errors::
|
||||
|
||||
@app.errorhandler(ZeroDivisionError)
|
||||
async def division_by_zero(request, exception):
|
||||
return {'error': 'division by zero'}, 500
|
||||
|
||||
When the raised exception class does not have an error handler defined, but
|
||||
one or more of its parent classes do, Microdot makes an attempt to invoke the
|
||||
most specific handler.
|
||||
|
||||
Mounting a Sub-Application
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Small Microdot applications can be written as a single source file, but this
|
||||
is not the best option for applications that pass a certain size. To make it
|
||||
simpler to write large applications, Microdot supports the concept of
|
||||
sub-applications that can be "mounted" on a larger application, possibly with
|
||||
a common URL prefix applied to all of its routes. For developers familiar with
|
||||
the Flask framework, this is a similar concept to Flask's blueprints.
|
||||
|
||||
Consider, for example, a *customers.py* sub-application that implements
|
||||
operations on customers::
|
||||
|
||||
from microdot import Microdot
|
||||
|
||||
customers_app = Microdot()
|
||||
|
||||
@customers_app.get('/')
|
||||
async def get_customers(request):
|
||||
# return all customers
|
||||
|
||||
@customers_app.post('/')
|
||||
async def new_customer(request):
|
||||
# create a new customer
|
||||
|
||||
Similar to the above, the *orders.py* sub-application implements operations on
|
||||
customer orders::
|
||||
|
||||
from microdot import Microdot
|
||||
|
||||
orders_app = Microdot()
|
||||
|
||||
@orders_app.get('/')
|
||||
async def get_orders(request):
|
||||
# return all orders
|
||||
|
||||
@orders_app.post('/')
|
||||
async def new_order(request):
|
||||
# create a new order
|
||||
|
||||
Now the main application, which is stored in *main.py*, can import and mount
|
||||
the sub-applications to build the larger combined application::
|
||||
|
||||
from microdot import Microdot
|
||||
from customers import customers_app
|
||||
from orders import orders_app
|
||||
|
||||
def create_app():
|
||||
app = Microdot()
|
||||
app.mount(customers_app, url_prefix='/customers')
|
||||
app.mount(orders_app, url_prefix='/orders')
|
||||
return app
|
||||
|
||||
app = create_app()
|
||||
app.run()
|
||||
|
||||
The resulting application will have the customer endpoints available at
|
||||
*/customers/* and the order endpoints available at */orders/*.
|
||||
|
||||
.. note::
|
||||
During the handling of a request, the
|
||||
:attr:`Request.url_prefix <microdot.Microdot.url_prefix>` attribute is
|
||||
set to the URL prefix under which the sub-application was mounted, or an
|
||||
empty string if the endpoint did not come from a sub-application or the
|
||||
sub-application was mounted without a URL prefix. It is possible to issue a
|
||||
redirect that is relative to the sub-application as follows::
|
||||
|
||||
return redirect(request.url_prefix + '/relative-url')
|
||||
|
||||
When mounting an application as shown above, before-request, after-request and
|
||||
error handlers defined in the sub-application are copied over to the main
|
||||
application at mount time. Once installed in the main application, these
|
||||
handlers will apply to the whole application and not just the sub-application
|
||||
in which they were created.
|
||||
|
||||
The :func:`mount() <microdot.Microdot.mount>` method has a ``local`` argument
|
||||
that defaults to ``False``. When this argument is set to ``True``, the
|
||||
before-request, after-request and error handlers defined in the sub-application
|
||||
will only apply to the sub-application.
|
||||
|
||||
Shutting Down the Server
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Web servers are designed to run forever, and are often stopped by sending them
|
||||
an interrupt signal. But having a way to gracefully stop the server is
|
||||
sometimes useful, especially in testing environments. Microdot provides a
|
||||
:func:`shutdown() <microdot.Microdot.shutdown>` method that can be invoked
|
||||
during the handling of a route to gracefully shut down the server when that
|
||||
request completes. The next example shows how to use this feature::
|
||||
|
||||
@app.get('/shutdown')
|
||||
async def shutdown(request):
|
||||
request.app.shutdown()
|
||||
return 'The server is shutting down...'
|
||||
|
||||
The request that invokes the ``shutdown()`` method will complete, and then the
|
||||
server will not accept any new requests and stop once any remaining requests
|
||||
complete. At this point the ``app.run()`` call will return.
|
||||
@@ -1,18 +0,0 @@
|
||||
User's Guide
|
||||
------------
|
||||
|
||||
This section describes the main features of Microdot.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
intro
|
||||
defining-routes
|
||||
request-object
|
||||
responses
|
||||
concurrency
|
||||
|
||||
For detailed reference information, consult the :ref:`API Reference`.
|
||||
|
||||
If you are familiar with releases of Microdot before 2.x, review the
|
||||
:ref:`Migration Guide <Migrating to Microdot 2.x from Older Releases>`.
|
||||
@@ -1,160 +0,0 @@
|
||||
Introduction
|
||||
~~~~~~~~~~~~
|
||||
|
||||
This section covers how to create and run a basic Microdot web application.
|
||||
|
||||
A simple web server
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following is an example of a simple web server::
|
||||
|
||||
from microdot import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
async def index(request):
|
||||
return 'Hello, world!'
|
||||
|
||||
app.run()
|
||||
|
||||
The script imports the :class:`Microdot <microdot.Microdot>` class and creates
|
||||
an application instance from it.
|
||||
|
||||
The application instance provides a :func:`route() <microdot.Microdot.route>`
|
||||
decorator, which is used to define one or more routes, as needed by the
|
||||
application.
|
||||
|
||||
The ``route()`` decorator takes the path portion of the URL as an
|
||||
argument, and maps it to the decorated function, so that the function is called
|
||||
when the client requests the URL.
|
||||
|
||||
When the function is called, it is passed a :class:`Request <microdot.Request>`
|
||||
object as an argument, which provides access to the information passed by the
|
||||
client. The value returned by the function is sent back to the client as the
|
||||
response.
|
||||
|
||||
Microdot is an asynchronous framework that uses the ``asyncio`` package. Route
|
||||
handler functions can be defined as ``async def`` or ``def`` functions, but
|
||||
``async def`` functions are recommended for performance.
|
||||
|
||||
The :func:`run() <microdot.Microdot.run>` method starts the application's web
|
||||
server on port 5000 by default, and creates its own asynchronous loop. This
|
||||
method blocks while it waits for connections from clients.
|
||||
|
||||
For some applications it may be necessary to run the web server alongside other
|
||||
asynchronous tasks, on an already running loop. In that case, instead of
|
||||
``app.run()`` the web server can be started by invoking the
|
||||
:func:`start_server() <microdot.Microdot.start_server>` coroutine as shown in
|
||||
the following example::
|
||||
|
||||
import asyncio
|
||||
from microdot import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
@app.route('/')
|
||||
async def index(request):
|
||||
return 'Hello, world!'
|
||||
|
||||
async def main():
|
||||
# start the server in a background task
|
||||
server = asyncio.create_task(app.start_server())
|
||||
|
||||
# ... do other asynchronous work here ...
|
||||
|
||||
# cleanup before ending the application
|
||||
await server
|
||||
|
||||
asyncio.run(main())
|
||||
|
||||
Running with CPython
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello.py>`_
|
||||
|
||||
When using CPython, you can start the web server by running the script that
|
||||
has the ``app.run()`` call at the bottom::
|
||||
|
||||
python main.py
|
||||
|
||||
After starting the script, open a web browser and navigate to
|
||||
*http://localhost:5000/* to access the application at the default address for
|
||||
the Microdot web server. From other computers in the same network, use the IP
|
||||
address or hostname of the computer running the script instead of
|
||||
``localhost``.
|
||||
|
||||
Running with MicroPython
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
|
||||
* - Required Microdot source files
|
||||
- | `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
|
||||
|
||||
* - Required external dependencies
|
||||
- | None
|
||||
|
||||
* - Examples
|
||||
- | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello.py>`_
|
||||
| `gpio.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/gpio/gpio.py>`_
|
||||
|
||||
When using MicroPython, you can upload a *main.py* file containing the web
|
||||
server code to your device, along with the required Microdot files, as defined
|
||||
in the :ref:`MicroPython Installation` section.
|
||||
|
||||
MicroPython will automatically run *main.py* when the device is powered on, so
|
||||
the web server will automatically start. The application can be accessed on
|
||||
port 5000 at the device's IP address. As indicated above, the port can be
|
||||
changed by passing the ``port`` argument to the ``run()`` method.
|
||||
|
||||
.. note::
|
||||
Microdot does not configure the network interface of the device in which it
|
||||
is running. If your device requires a network connection to be made in
|
||||
advance, for example to a Wi-Fi access point, this must be configured before
|
||||
the ``run()`` method is invoked.
|
||||
|
||||
Web Server Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The :func:`run() <microdot.Microdot.run>` and
|
||||
:func:`start_server() <microdot.Microdot.start_server>` methods support a few
|
||||
arguments to configure the web server.
|
||||
|
||||
- ``port``: The port number to listen on. Pass the desired port number in this
|
||||
argument to use a port different than the default of 5000. For example::
|
||||
|
||||
app.run(port=6000)
|
||||
|
||||
- ``host``: The IP address of the network interface to listen on. By default
|
||||
the server listens on all available interfaces. To listen only on the local
|
||||
loopback interface, pass ``'127.0.0.1'`` as value for this argument.
|
||||
- ``debug``: when set to ``True``, the server ouputs logging information to the
|
||||
console. The default is ``False``.
|
||||
- ``ssl``: an ``SSLContext`` instance that configures the server to use TLS
|
||||
encryption, or ``None`` to disable TLS use. The default is ``None``. The
|
||||
following example demonstrates how to configure the server with an SSL
|
||||
certificate stored in *cert.pem* and *key.pem* files::
|
||||
|
||||
import ssl
|
||||
|
||||
# ...
|
||||
|
||||
sslctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
|
||||
sslctx.load_cert_chain('cert.pem', 'key.pem')
|
||||
app.run(port=4443, debug=True, ssl=sslctx)
|
||||
|
||||
.. note::
|
||||
When using CPython, the certificate and key files must be given in PEM
|
||||
format. When using MicroPython, these files must be given in DER format.
|
||||
@@ -1,169 +0,0 @@
|
||||
The Request Object
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The :class:`Request <microdot.Request>` object encapsulates all the information
|
||||
passed by the client. It is passed as an argument to route handlers, as well as
|
||||
to before-request, after-request and error handlers.
|
||||
|
||||
Request Attributes
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The request object provides access to the request attributes, including:
|
||||
|
||||
- :attr:`method <microdot.Request.method>`: The HTTP method of the request.
|
||||
- :attr:`path <microdot.Request.path>`: The path of the request.
|
||||
- :attr:`args <microdot.Request.args>`: The query string parameters of the
|
||||
request, as a :class:`MultiDict <microdot.MultiDict>` object.
|
||||
- :attr:`headers <microdot.Request.headers>`: The headers of the request, as a
|
||||
dictionary.
|
||||
- :attr:`cookies <microdot.Request.cookies>`: The cookies that the client sent
|
||||
with the request, as a dictionary.
|
||||
- :attr:`content_type <microdot.Request.content_type>`: The content type
|
||||
specified by the client, or ``None`` if no content type was specified.
|
||||
- :attr:`content_length <microdot.Request.content_length>`: The content
|
||||
length of the request, or 0 if no content length was specified.
|
||||
- :attr:`json <microdot.Request.json>`: The parsed JSON data in the request
|
||||
body. See :ref:`below <JSON Payloads>` for additional details.
|
||||
- :attr:`form <microdot.Request.form>`: The parsed form data in the request
|
||||
body, as a dictionary. See :ref:`below <Form Data>` for additional details.
|
||||
- :attr:`files <microdot.Request.files>`: A dictionary with the file uploads
|
||||
included in the request body. Note that file uploads are only supported when
|
||||
the :ref:`Multipart Forms` extension is used.
|
||||
- :attr:`client_addr <microdot.Request.client_addr>`: The network address of
|
||||
the client, as a tuple (host, port).
|
||||
- :attr:`app <microdot.Request.app>`: The application instance that created the
|
||||
request.
|
||||
- :attr:`g <microdot.Request.g>`: The ``g`` object, where handlers can store
|
||||
request-specific data to be shared among handlers. See :ref:`The "g" Object`
|
||||
for details.
|
||||
|
||||
JSON Payloads
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
When the client sends a request that contains JSON data in the body, the
|
||||
application can access the parsed JSON data using the
|
||||
:attr:`json <microdot.Request.json>` attribute. The following example shows how
|
||||
to use this attribute::
|
||||
|
||||
@app.post('/customers')
|
||||
async def create_customer(request):
|
||||
customer = request.json
|
||||
# do something with customer
|
||||
return {'success': True}
|
||||
|
||||
.. note::
|
||||
The client must set the ``Content-Type`` header to ``application/json`` for
|
||||
the ``json`` attribute of the request object to be populated.
|
||||
|
||||
Form Data
|
||||
^^^^^^^^^
|
||||
|
||||
The request object also supports standard HTML form submissions through the
|
||||
:attr:`form <microdot.Request.form>` attribute, which presents the form data
|
||||
as a :class:`MultiDict <microdot.MultiDict>` object. Example::
|
||||
|
||||
@app.route('/', methods=['GET', 'POST'])
|
||||
async def index(req):
|
||||
name = 'Unknown'
|
||||
if req.method == 'POST':
|
||||
name = req.form.get('name')
|
||||
return f'Hello {name}'
|
||||
|
||||
.. note::
|
||||
Form submissions automatically parsed when the ``Content-Type`` header is
|
||||
set by the client to ``application/x-www-form-urlencoded``. For form
|
||||
submissions that use the ``multipart/form-data`` content type the
|
||||
:ref:`Multipart Forms` extension must be used.
|
||||
|
||||
Accessing the Raw Request Body
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For cases in which neither JSON nor form data is expected, the
|
||||
:attr:`body <microdot.Request.body>` request attribute returns the entire body
|
||||
of the request as a byte sequence.
|
||||
|
||||
If the expected body is too large to fit safely in memory, the application can
|
||||
use the :attr:`stream <microdot.Request.stream>` request attribute to read the
|
||||
body contents as a file-like object. The
|
||||
:attr:`max_body_length <microdot.Request.max_body_length>` attribute of the
|
||||
request object defines the size at which bodies are streamed instead of loaded
|
||||
into memory.
|
||||
|
||||
Cookies
|
||||
^^^^^^^
|
||||
|
||||
Cookies that are sent by the client are made available through the
|
||||
:attr:`cookies <microdot.Request.cookies>` attribute of the request object in
|
||||
dictionary form.
|
||||
|
||||
The "g" Object
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes applications need to store data during the lifetime of a request, so
|
||||
that it can be shared between the before- and after-request handlers, the
|
||||
route function and any error handlers. The request object provides the
|
||||
:attr:`g <microdot.Request.g>` attribute for that purpose.
|
||||
|
||||
In the following example, a before request handler authorizes the client and
|
||||
stores the username so that the route function can use it::
|
||||
|
||||
@app.before_request
|
||||
async def authorize(request):
|
||||
username = authenticate_user(request)
|
||||
if not username:
|
||||
return 'Unauthorized', 401
|
||||
request.g.username = username
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
return f'Hello, {request.g.username}!'
|
||||
|
||||
Request-Specific After-Request Handlers
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes applications need to perform operations on the response object
|
||||
before it is sent to the client, for example to set or remove a cookie. A good
|
||||
option to use for this is to define a request-specific after-request handler
|
||||
using the :func:`after_request <microdot.Microdot.after_request>` decorator.
|
||||
Request-specific after-request handlers are called by Microdot after the route
|
||||
function returns and all the application-wide after-request handlers have been
|
||||
called.
|
||||
|
||||
The next example shows how a cookie can be updated using a request-specific
|
||||
after-request handler defined inside a route function::
|
||||
|
||||
@app.post('/logout')
|
||||
async def logout(request):
|
||||
@request.after_request
|
||||
def reset_session(request, response):
|
||||
response.set_cookie('session', '', http_only=True)
|
||||
return response
|
||||
|
||||
return 'Logged out'
|
||||
|
||||
Request Limits
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
To help prevent malicious attacks, Microdot provides some configuration options
|
||||
to limit the amount of information that is accepted:
|
||||
|
||||
- :attr:`max_content_length <microdot.Request.max_content_length>`: The
|
||||
maximum size accepted for the request body, in bytes. When a client sends a
|
||||
request that is larger than this, the server will respond with a 413 error.
|
||||
The default is 16KB.
|
||||
- :attr:`max_body_length <microdot.Request.max_body_length>`: The maximum
|
||||
size that is loaded in the :attr:`body <microdot.Request.body>` attribute, in
|
||||
bytes. Requests that have a body that is larger than this size but smaller
|
||||
than the size set for ``max_content_length`` can only be accessed through the
|
||||
:attr:`stream <microdot.Request.stream>` attribute. The default is also 16KB.
|
||||
- :attr:`max_readline <microdot.Request.max_readline>`: The maximum allowed
|
||||
size for a request line, in bytes. The default is 2KB.
|
||||
|
||||
The following example configures the application to accept requests with
|
||||
payloads up to 1MB in size, but prevents requests that are larger than 8KB from
|
||||
being loaded into memory::
|
||||
|
||||
from microdot import Request
|
||||
|
||||
Request.max_content_length = 1024 * 1024
|
||||
Request.max_body_length = 8 * 1024
|
||||
@@ -1,200 +0,0 @@
|
||||
Responses
|
||||
~~~~~~~~~
|
||||
|
||||
The value or values that are returned from the route function are used by
|
||||
Microdot to build the response that is sent to the client. The following
|
||||
sections describe the different types of responses that are supported.
|
||||
|
||||
The Three Parts of a Response
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Route functions can return one, two or three values. The first and most
|
||||
important value is the response body::
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
return 'Hello, World!'
|
||||
|
||||
In the above example, Microdot issues a standard 200 status code response
|
||||
indicating a successful request. The body of the response is the
|
||||
``'Hello, World!'`` string returned by the function. Microdot includes default
|
||||
headers with this response, including the ``Content-Type`` header set to
|
||||
``text/plain`` to indicate a response in plain text.
|
||||
|
||||
The application can provide its own status code as a second value returned from
|
||||
the route to override the 200 default. The example below returns a 202 status
|
||||
code::
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
return 'Hello, World!', 202
|
||||
|
||||
The application can also return a third value, a dictionary with additional
|
||||
headers that are added to, or replace the default ones included by Microdot.
|
||||
The next example returns an HTML response, instead of the default plain text
|
||||
response::
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
return '<h1>Hello, World!</h1>', 202, {'Content-Type': 'text/html'}
|
||||
|
||||
If the application does not need to return a body, then it can omit it and
|
||||
have the status code as the first or only returned value::
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
return 204
|
||||
|
||||
Likewise, if the application needs to return a body and custom headers, but
|
||||
does not need to change the default status code, then it can return two values,
|
||||
omitting the status code::
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
return '<h1>Hello, World!</h1>', {'Content-Type': 'text/html'}
|
||||
|
||||
Lastly, the application can also return a :class:`Response <microdot.Response>`
|
||||
object containing all the details of the response as a single value.
|
||||
|
||||
JSON Responses
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
If the application needs to return a response with JSON formatted data, it can
|
||||
return a dictionary or a list as the first value, and Microdot will
|
||||
automatically format the response as JSON.
|
||||
|
||||
Example::
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
return {'hello': 'world'}
|
||||
|
||||
.. note::
|
||||
A ``Content-Type`` header set to ``application/json`` is automatically added
|
||||
to the response.
|
||||
|
||||
Redirects
|
||||
^^^^^^^^^
|
||||
|
||||
The :func:`redirect <microdot.Response.redirect>` function is a helper that
|
||||
creates redirect responses::
|
||||
|
||||
from microdot import redirect
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
return redirect('/about')
|
||||
|
||||
File Responses
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
The :func:`send_file <microdot.Response.send_file>` function builds a response
|
||||
object for a file::
|
||||
|
||||
from microdot import send_file
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
return send_file('/static/index.html')
|
||||
|
||||
A suggested caching duration can be returned to the client in the ``max_age``
|
||||
argument::
|
||||
|
||||
from microdot import send_file
|
||||
|
||||
@app.get('/')
|
||||
async def image(request):
|
||||
return send_file('/static/image.jpg', max_age=3600) # in seconds
|
||||
|
||||
.. note::
|
||||
Unlike other web frameworks, Microdot does not automatically configure a
|
||||
route to serve static files. The following is an example route that can be
|
||||
added to the application to serve static files from a *static* directory in
|
||||
the project::
|
||||
|
||||
@app.route('/static/<path:path>')
|
||||
async def static(request, path):
|
||||
if '..' in path:
|
||||
# directory traversal is not allowed
|
||||
return 'Not found', 404
|
||||
return send_file('static/' + path, max_age=86400)
|
||||
|
||||
Streaming Responses
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Instead of providing a response as a single value, an application can opt to
|
||||
return a response that is generated in chunks, by returning a Python generator.
|
||||
The example below returns all the numbers in the fibonacci sequence below 100::
|
||||
|
||||
@app.get('/fibonacci')
|
||||
async def fibonacci(request):
|
||||
async def generate_fibonacci():
|
||||
a, b = 0, 1
|
||||
while a < 100:
|
||||
yield str(a) + '\n'
|
||||
a, b = b, a + b
|
||||
|
||||
return generate_fibonacci()
|
||||
|
||||
.. note::
|
||||
Under CPython, the generator function can be a ``def`` or ``async def``
|
||||
function, as well as a class-based generator.
|
||||
|
||||
Under MicroPython, asynchronous generator functions are not supported, so
|
||||
only ``def`` generator functions can be used. Asynchronous class-based
|
||||
generators are supported.
|
||||
|
||||
Changing the Default Response Content Type
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Microdot uses a ``text/plain`` content type by default for responses that do
|
||||
not explicitly include the ``Content-Type`` header. The application can change
|
||||
this default by setting the desired content type in the
|
||||
:attr:`default_content_type <microdot.Response.default_content_type>` attribute
|
||||
of the :class:`Response <microdot.Response>` class.
|
||||
|
||||
The example that follows configures the application to use ``text/html`` as
|
||||
default content type::
|
||||
|
||||
from microdot import Response
|
||||
|
||||
Response.default_content_type = 'text/html'
|
||||
|
||||
Setting Cookies
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Many web applications rely on cookies to maintain client state between
|
||||
requests. Cookies can be set with the ``Set-Cookie`` header in the response,
|
||||
but since this is such a common practice, Microdot provides the
|
||||
:func:`set_cookie() <microdot.Response.set_cookie>` method in the response
|
||||
object to add a properly formatted cookie header to the response.
|
||||
|
||||
Given that route functions do not normally work directly with the response
|
||||
object, the recommended way to set a cookie is to do it in a
|
||||
:ref:`request-specific after-request handler <Request-Specific After-Request Handlers>`.
|
||||
|
||||
Example::
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
@request.after_request
|
||||
async def set_cookie(request, response):
|
||||
response.set_cookie('name', 'value')
|
||||
return response
|
||||
|
||||
return 'Hello, World!'
|
||||
|
||||
Another option is to create a response object directly in the route function::
|
||||
|
||||
@app.get('/')
|
||||
async def index(request):
|
||||
response = Response('Hello, World!')
|
||||
response.set_cookie('name', 'value')
|
||||
return response
|
||||
|
||||
.. note::
|
||||
Standard cookies do not offer sufficient privacy and security controls, so
|
||||
never store sensitive information in them unless you are adding additional
|
||||
protection mechanisms such as encryption or cryptographic signing. The
|
||||
:ref:`session <Maintaining Secure User Sessions>` extension implements signed
|
||||
cookies that prevent tampering by malicious actors.
|
||||
@@ -1 +0,0 @@
|
||||
This directory contains examples that demonstrate basic and token authentication.
|
||||
@@ -1,30 +1,26 @@
|
||||
from microdot import Microdot
|
||||
from microdot.auth import BasicAuth
|
||||
from pbkdf2 import generate_password_hash, check_password_hash
|
||||
from microdot_auth import BasicAuth
|
||||
|
||||
|
||||
# this example provides an implementation of the generate_password_hash and
|
||||
# check_password_hash functions that can be used in MicroPython. On CPython
|
||||
# there are many other options for password hashisng so there is no need to use
|
||||
# this custom solution.
|
||||
USERS = {
|
||||
'susan': generate_password_hash('hello'),
|
||||
'david': generate_password_hash('bye'),
|
||||
}
|
||||
app = Microdot()
|
||||
auth = BasicAuth()
|
||||
basic_auth = BasicAuth()
|
||||
|
||||
USERS = {
|
||||
'susan': 'hello',
|
||||
'david': 'bye',
|
||||
}
|
||||
|
||||
|
||||
@auth.authenticate
|
||||
async def check_credentials(request, username, password):
|
||||
if username in USERS and check_password_hash(USERS[username], password):
|
||||
return username
|
||||
@basic_auth.callback
|
||||
def verify_password(request, username, password):
|
||||
if username in USERS and USERS[username] == password:
|
||||
request.g.user = username
|
||||
return True
|
||||
|
||||
|
||||
@app.route('/')
|
||||
@auth
|
||||
async def index(request):
|
||||
return f'Hello, {request.g.current_user}!'
|
||||
@basic_auth
|
||||
def index(request):
|
||||
return f'Hello, {request.g.user}!'
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
|
||||
60
examples/auth/login_auth.py
Normal file
60
examples/auth/login_auth.py
Normal file
@@ -0,0 +1,60 @@
|
||||
from microdot import Microdot, redirect
|
||||
from microdot_session import set_session_secret_key
|
||||
from microdot_login import LoginAuth
|
||||
|
||||
app = Microdot()
|
||||
set_session_secret_key('top-secret')
|
||||
login_auth = LoginAuth()
|
||||
|
||||
USERS = {
|
||||
'susan': 'hello',
|
||||
'david': 'bye',
|
||||
}
|
||||
|
||||
|
||||
@login_auth.callback
|
||||
def check_user(request, user_id):
|
||||
request.g.user = user_id
|
||||
return True
|
||||
|
||||
|
||||
@app.route('/')
|
||||
@login_auth
|
||||
def index(request):
|
||||
return f'''
|
||||
<h1>Login Auth Example</h1>
|
||||
<p>Hello, {request.g.user}!</p>
|
||||
<form method="POST" action="/logout">
|
||||
<button type="submit">Logout</button>
|
||||
</form>
|
||||
''', {'Content-Type': 'text/html'}
|
||||
|
||||
|
||||
@app.route('/login', methods=['GET', 'POST'])
|
||||
def login(request):
|
||||
if request.method == 'GET':
|
||||
return '''
|
||||
<h1>Login Auth Example</h1>
|
||||
<form method="POST">
|
||||
<input name="username" placeholder="username">
|
||||
<input name="password" type="password" placeholder="password">
|
||||
<button type="submit">Login</button>
|
||||
</form>
|
||||
''', {'Content-Type': 'text/html'}
|
||||
username = request.form['username']
|
||||
password = request.form['password']
|
||||
if USERS.get(username) == password:
|
||||
login_auth.login_user(request, username)
|
||||
return login_auth.redirect_to_next(request)
|
||||
else:
|
||||
return redirect('/login')
|
||||
|
||||
|
||||
@app.post('/logout')
|
||||
def logout(request):
|
||||
login_auth.logout_user(request)
|
||||
return redirect('/')
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
app.run(debug=True)
|
||||
@@ -1,47 +0,0 @@
|
||||
import os
|
||||
import hashlib
|
||||
|
||||
# PBKDF2 secure password hashing algorithm obtained from:
|
||||
# https://codeandlife.com/2023/01/06/how-to-calculate-pbkdf2-hmac-sha256-with-
|
||||
# python,-example-code/
|
||||
|
||||
|
||||
def sha256(b):
|
||||
return hashlib.sha256(b).digest()
|
||||
|
||||
|
||||
def ljust(b, n, f):
|
||||
return b + f * (n - len(b))
|
||||
|
||||
|
||||
def gethmac(key, content):
|
||||
okeypad = bytes(v ^ 0x5c for v in ljust(key, 64, b'\0'))
|
||||
ikeypad = bytes(v ^ 0x36 for v in ljust(key, 64, b'\0'))
|
||||
return sha256(okeypad + sha256(ikeypad + content))
|
||||
|
||||
|
||||
def pbkdf2(pwd, salt, iterations=1000):
|
||||
U = salt + b'\x00\x00\x00\x01'
|
||||
T = bytes(64)
|
||||
for _ in range(iterations):
|
||||
U = gethmac(pwd, U)
|
||||
T = bytes(a ^ b for a, b in zip(U, T))
|
||||
return T
|
||||
|
||||
|
||||
# The number of iterations may need to be adjusted depending on the hardware.
|
||||
# Lower numbers make the password hashing algorithm faster but less secure, so
|
||||
# the largest number that can be tolerated should be used.
|
||||
def generate_password_hash(password, salt=None, iterations=100000):
|
||||
salt = salt or os.urandom(16)
|
||||
dk = pbkdf2(password.encode(), salt, iterations)
|
||||
return f'pbkdf2-hmac-sha256:{salt.hex()}:{iterations}:{dk.hex()}'
|
||||
|
||||
|
||||
def check_password_hash(password_hash, password):
|
||||
algorithm, salt, iterations, dk = password_hash.split(':')
|
||||
iterations = int(iterations)
|
||||
if algorithm != 'pbkdf2-hmac-sha256':
|
||||
return False
|
||||
return pbkdf2(password.encode(), salt=bytes.fromhex(salt),
|
||||
iterations=iterations) == bytes.fromhex(dk)
|
||||
@@ -1,25 +1,26 @@
|
||||
from microdot import Microdot
|
||||
from microdot.auth import TokenAuth
|
||||
from microdot_auth import TokenAuth
|
||||
|
||||
app = Microdot()
|
||||
auth = TokenAuth()
|
||||
token_auth = TokenAuth()
|
||||
|
||||
TOKENS = {
|
||||
'susan-token': 'susan',
|
||||
'david-token': 'david',
|
||||
'hello': 'susan',
|
||||
'bye': 'david',
|
||||
}
|
||||
|
||||
|
||||
@auth.authenticate
|
||||
async def check_token(request, token):
|
||||
@token_auth.callback
|
||||
def verify_token(request, token):
|
||||
if token in TOKENS:
|
||||
return TOKENS[token]
|
||||
request.g.user = TOKENS[token]
|
||||
return True
|
||||
|
||||
|
||||
@app.route('/')
|
||||
@auth
|
||||
async def index(request):
|
||||
return f'Hello, {request.g.current_user}!'
|
||||
@token_auth
|
||||
def index(request):
|
||||
return f'Hello, {request.g.user}!'
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
|
||||
@@ -4,7 +4,7 @@ app = Microdot()
|
||||
|
||||
|
||||
@app.get('/')
|
||||
async def index(req):
|
||||
def index(req):
|
||||
return {'hello': 'world'}
|
||||
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
from microdot.asgi import Microdot
|
||||
from microdot_asgi import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
|
||||
11
examples/benchmark/mem_async.py
Normal file
11
examples/benchmark/mem_async.py
Normal file
@@ -0,0 +1,11 @@
|
||||
from microdot_asyncio import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
|
||||
@app.get('/')
|
||||
async def index(req):
|
||||
return {'hello': 'world'}
|
||||
|
||||
|
||||
app.run()
|
||||
@@ -4,5 +4,5 @@ app = FastAPI()
|
||||
|
||||
|
||||
@app.get('/')
|
||||
async def index():
|
||||
def index():
|
||||
return {'hello': 'world'}
|
||||
|
||||
@@ -4,5 +4,5 @@ app = Quart(__name__)
|
||||
|
||||
|
||||
@app.get('/')
|
||||
async def index():
|
||||
def index():
|
||||
return {'hello': 'world'}
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
from microdot.wsgi import Microdot
|
||||
from microdot_wsgi import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
|
||||
@@ -1,9 +0,0 @@
|
||||
pip-tools
|
||||
flask
|
||||
quart
|
||||
fastapi
|
||||
gunicorn
|
||||
uvicorn
|
||||
requests
|
||||
psutil
|
||||
humanize
|
||||
@@ -1,113 +1,33 @@
|
||||
#
|
||||
# This file is autogenerated by pip-compile with Python 3.12
|
||||
# by the following command:
|
||||
#
|
||||
# pip-compile requirements.in
|
||||
#
|
||||
aiofiles==23.2.1
|
||||
# via quart
|
||||
annotated-types==0.6.0
|
||||
# via pydantic
|
||||
anyio==3.7.1
|
||||
# via starlette
|
||||
blinker==1.7.0
|
||||
# via
|
||||
# flask
|
||||
# quart
|
||||
build==1.0.3
|
||||
# via pip-tools
|
||||
certifi==2024.7.4
|
||||
# via requests
|
||||
charset-normalizer==3.3.2
|
||||
# via requests
|
||||
click==8.1.7
|
||||
# via
|
||||
# flask
|
||||
# pip-tools
|
||||
# quart
|
||||
# uvicorn
|
||||
fastapi==0.109.1
|
||||
# via -r requirements.in
|
||||
flask==3.0.0
|
||||
# via
|
||||
# -r requirements.in
|
||||
# quart
|
||||
gunicorn==23.0.0
|
||||
# via -r requirements.in
|
||||
h11==0.16.0
|
||||
# via
|
||||
# hypercorn
|
||||
# uvicorn
|
||||
# wsproto
|
||||
h2==4.3.0
|
||||
# via hypercorn
|
||||
hpack==4.1.0
|
||||
# via h2
|
||||
humanize==4.9.0
|
||||
# via -r requirements.in
|
||||
hypercorn==0.15.0
|
||||
# via quart
|
||||
hyperframe==6.1.0
|
||||
# via h2
|
||||
idna==3.7
|
||||
# via
|
||||
# anyio
|
||||
# requests
|
||||
aiofiles==0.8.0
|
||||
anyio==3.6.1
|
||||
blinker==1.5
|
||||
certifi==2022.6.15
|
||||
charset-normalizer==2.1.0
|
||||
click==8.1.3
|
||||
fastapi==0.79.0
|
||||
Flask==2.2.1
|
||||
gunicorn==20.1.0
|
||||
h11==0.13.0
|
||||
h2==4.1.0
|
||||
hpack==4.0.0
|
||||
humanize==4.3.0
|
||||
hypercorn==0.13.2
|
||||
hyperframe==6.0.1
|
||||
idna==3.3
|
||||
itsdangerous==2.1.2
|
||||
# via
|
||||
# flask
|
||||
# quart
|
||||
jinja2==3.1.6
|
||||
# via
|
||||
# flask
|
||||
# quart
|
||||
markupsafe==2.1.3
|
||||
# via
|
||||
# jinja2
|
||||
# quart
|
||||
# werkzeug
|
||||
packaging==23.2
|
||||
# via
|
||||
# build
|
||||
# gunicorn
|
||||
pip-tools==7.3.0
|
||||
# via -r requirements.in
|
||||
Jinja2==3.1.2
|
||||
MarkupSafe==2.1.1
|
||||
microdot
|
||||
priority==2.0.0
|
||||
# via hypercorn
|
||||
psutil==5.9.6
|
||||
# via -r requirements.in
|
||||
pydantic==2.5.2
|
||||
# via fastapi
|
||||
pydantic-core==2.14.5
|
||||
# via pydantic
|
||||
pyproject-hooks==1.0.0
|
||||
# via build
|
||||
quart==0.20.0
|
||||
# via -r requirements.in
|
||||
requests==2.32.4
|
||||
# via -r requirements.in
|
||||
sniffio==1.3.0
|
||||
# via anyio
|
||||
starlette==0.35.1
|
||||
# via fastapi
|
||||
typing-extensions==4.9.0
|
||||
# via
|
||||
# fastapi
|
||||
# pydantic
|
||||
# pydantic-core
|
||||
urllib3==2.6.0
|
||||
# via requests
|
||||
uvicorn==0.24.0.post1
|
||||
# via -r requirements.in
|
||||
werkzeug==3.0.6
|
||||
# via
|
||||
# flask
|
||||
# quart
|
||||
wheel==0.42.0
|
||||
# via pip-tools
|
||||
wsproto==1.2.0
|
||||
# via hypercorn
|
||||
|
||||
# The following packages are considered to be unsafe in a requirements file:
|
||||
# pip
|
||||
# setuptools
|
||||
psutil==5.9.1
|
||||
pydantic==1.9.1
|
||||
quart==0.18.0
|
||||
requests==2.28.1
|
||||
sniffio==1.2.0
|
||||
starlette==0.19.1
|
||||
toml==0.10.2
|
||||
typing_extensions==4.3.0
|
||||
urllib3==1.26.11
|
||||
uvicorn==0.18.2
|
||||
Werkzeug==2.2.1
|
||||
wsproto==1.1.0
|
||||
|
||||
14
examples/benchmark/results.txt
Normal file
14
examples/benchmark/results.txt
Normal file
@@ -0,0 +1,14 @@
|
||||
❯ curl -X GET http://localhost:5000/ <-- microdot
|
||||
{"ram": 8429568}%
|
||||
❯ curl -X GET http://localhost:5000/ <-- microdot_asyncio
|
||||
{"ram": 12410880}%
|
||||
❯ curl -X GET http://localhost:8000/ <-- microdot_wsgi
|
||||
{"ram": 9101312}%
|
||||
❯ curl -X GET http://localhost:8000/ <-- microdot_asgi
|
||||
{"ram": 18620416}%
|
||||
❯ curl -X GET http://localhost:5000/ <-- flask app.run
|
||||
{"ram":25460736}
|
||||
❯ curl -X GET http://localhost:5000/ <-- flask run
|
||||
{"ram":26210304}
|
||||
❯ curl -X GET http://localhost:5000/ <-- quart run
|
||||
{"ram":31748096}%
|
||||
@@ -1,7 +1,6 @@
|
||||
import os
|
||||
import subprocess
|
||||
import time
|
||||
from timeit import timeit
|
||||
import requests
|
||||
import psutil
|
||||
import humanize
|
||||
@@ -14,8 +13,13 @@ apps = [
|
||||
),
|
||||
(
|
||||
'micropython mem.py',
|
||||
{'MICROPYPATH': '../../src'},
|
||||
'microdot-micropython-sync'
|
||||
),
|
||||
(
|
||||
'micropython mem_async.py',
|
||||
{'MICROPYPATH': '../../src:../../libs/micropython'},
|
||||
'microdot-micropython'
|
||||
'microdot-micropython-async'
|
||||
),
|
||||
(
|
||||
['python', '-c', 'import time; time.sleep(10)'],
|
||||
@@ -25,65 +29,66 @@ apps = [
|
||||
(
|
||||
'python mem.py',
|
||||
{'PYTHONPATH': '../../src'},
|
||||
'microdot-cpython'
|
||||
'microdot-cpython-sync'
|
||||
),
|
||||
(
|
||||
'uvicorn --workers 1 --port 5000 mem_asgi:app',
|
||||
'python mem_async.py',
|
||||
{'PYTHONPATH': '../../src'},
|
||||
'microdot-uvicorn'
|
||||
'microdot-cpython-async'
|
||||
),
|
||||
(
|
||||
'gunicorn --workers 1 --bind :5000 mem_wsgi:app',
|
||||
{'PYTHONPATH': '../../src'},
|
||||
'microdot-gunicorn'
|
||||
'microdot-gunicorn-sync'
|
||||
),
|
||||
(
|
||||
'uvicorn --workers 1 --port 5000 mem_asgi:app',
|
||||
{'PYTHONPATH': '../../src'},
|
||||
'microdot-uvicorn-async'
|
||||
),
|
||||
(
|
||||
'flask run',
|
||||
{'FLASK_APP': 'mem_flask.py'},
|
||||
'flask-run'
|
||||
'flask-run-sync'
|
||||
),
|
||||
(
|
||||
'quart run',
|
||||
{'QUART_APP': 'mem_quart.py'},
|
||||
'quart-run'
|
||||
'quart-run-async'
|
||||
),
|
||||
(
|
||||
'gunicorn --workers 1 --bind :5000 mem_flask:app',
|
||||
{},
|
||||
'flask-gunicorn'
|
||||
'flask-gunicorn-sync'
|
||||
),
|
||||
(
|
||||
'uvicorn --workers 1 --port 5000 mem_quart:app',
|
||||
{},
|
||||
'quart-uvicorn'
|
||||
'quart-uvicorn-async'
|
||||
),
|
||||
(
|
||||
'uvicorn --workers 1 --port 5000 mem_fastapi:app',
|
||||
{},
|
||||
'fastapi-uvicorn'
|
||||
'fastapi-uvicorn-async'
|
||||
),
|
||||
]
|
||||
|
||||
for app, env, name in apps:
|
||||
p = subprocess.Popen(
|
||||
app.split() if isinstance(app, str) else app,
|
||||
env={'PATH': os.environ['PATH'] + ':../../bin', **env},
|
||||
env={'PATH': os.environ['PATH'], **env},
|
||||
stdout=subprocess.DEVNULL,
|
||||
stderr=subprocess.DEVNULL
|
||||
)
|
||||
time.sleep(1)
|
||||
tm = 0
|
||||
if not name.startswith('baseline'):
|
||||
def req():
|
||||
r = requests.get('http://localhost:5000')
|
||||
r.raise_for_status()
|
||||
|
||||
tm = timeit(req, number=1000)
|
||||
r = requests.get('http://localhost:5000')
|
||||
r.raise_for_status()
|
||||
proc = psutil.Process(p.pid)
|
||||
mem = proc.memory_info().rss
|
||||
for child in proc.children(recursive=True):
|
||||
mem += child.memory_info().rss
|
||||
bar = '*' * (mem // (1024 * 1024))
|
||||
print(f'{name:<28}{tm:10.2f}s {humanize.naturalsize(mem):>10} {bar}')
|
||||
print(f'{name:<28}{humanize.naturalsize(mem):>10} {bar}')
|
||||
p.terminate()
|
||||
time.sleep(1)
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
This directory contains Cross-Origin Resource Sharing (CORS) examples.
|
||||
@@ -1,14 +0,0 @@
|
||||
from microdot import Microdot
|
||||
from microdot.cors import CORS
|
||||
|
||||
app = Microdot()
|
||||
CORS(app, allowed_origins=['https://example.org'], allow_credentials=True)
|
||||
|
||||
|
||||
@app.route('/')
|
||||
def index(request):
|
||||
return 'Hello World!'
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
app.run()
|
||||
@@ -1,41 +0,0 @@
|
||||
# CSRF Example
|
||||
|
||||
This is a small example that demonstrates how the CSRF protection in Microdot
|
||||
works.
|
||||
|
||||
## Running the example
|
||||
|
||||
Start by cloning the repostory or copying the two example files *app.py* and
|
||||
*evil.py* to your computer. The only dependency these examples need to run is `microdot`, so create a virtual environment and run:
|
||||
|
||||
pip install microdot
|
||||
|
||||
You need two terminals. On the first one, run:
|
||||
|
||||
python app.py
|
||||
|
||||
To see the application open *http://localhost:5000* on your web browser. The
|
||||
application allows you to make payments through a web form. Each payment that
|
||||
you make reduces the balance in your account. Type an amount in the form field and press the "Issue Payment" button to see how the balance decreases.
|
||||
|
||||
Leave the application running. On the second terminal run:
|
||||
|
||||
python evil.py
|
||||
|
||||
Open a second browser tab and navigate to *http://localhost:5001*. This
|
||||
application simulates a malicious web site that tries to steal money from your
|
||||
account. It does this by sending a cross-site form submission to the above
|
||||
application.
|
||||
|
||||
The application presents a form that fools you into thinking you can win some
|
||||
money. Clicking the button triggers the cross-site request to the form in the
|
||||
first application, with the payment amount set to $100.
|
||||
|
||||
Because the application has CSRF protection enabled, the cross-site request
|
||||
fails.
|
||||
|
||||
If you want to see how the attack can succeed, open *app.py* in your editor and
|
||||
comment out the line that creates the ``csrf`` object. Restart *app.py* in your
|
||||
first terminal, then go back to the second browser tab and click the
|
||||
"Win $100!" button again. You will now see that the form is submitted
|
||||
successfully and your balance in the first application is decremented by $100.
|
||||
@@ -1,40 +0,0 @@
|
||||
from microdot import Microdot, redirect
|
||||
from microdot.cors import CORS
|
||||
from microdot.csrf import CSRF
|
||||
|
||||
app = Microdot()
|
||||
cors = CORS(app, allowed_origins=['http://localhost:5000'])
|
||||
csrf = CSRF(app, cors)
|
||||
|
||||
balance = 1000
|
||||
|
||||
|
||||
@app.route('/', methods=['GET', 'POST'])
|
||||
def index(request):
|
||||
global balance
|
||||
if request.method == 'POST':
|
||||
try:
|
||||
balance -= float(request.form['amount'])
|
||||
except ValueError:
|
||||
pass
|
||||
return redirect('/')
|
||||
|
||||
page = f'''<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<title>CSRF Example</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>CSRF Example</h1>
|
||||
<p>You have ${balance:.02f}</p>
|
||||
<form method="POST" action="">
|
||||
Pay $<input type="text" name="amount" size="10" />
|
||||
<input type="submit" value="Issue Payment" />
|
||||
</form>
|
||||
</body>
|
||||
</html>'''
|
||||
return page, {'Content-Type': 'text/html'}
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
app.run(debug=True)
|
||||
@@ -1,25 +0,0 @@
|
||||
from microdot import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
|
||||
@app.route('/', methods=['GET', 'POST'])
|
||||
def index(request):
|
||||
page = '''<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<title>CSRF Example</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Evil Site</h1>
|
||||
<form method="POST" action="http://localhost:5000">
|
||||
<input type="hidden" name="amount" value="100" />
|
||||
<input type="submit" value="Win $100!" />
|
||||
</form>
|
||||
</body>
|
||||
</html>'''
|
||||
return page, {'Content-Type': 'text/html'}
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
app.run(port=5001, debug=True)
|
||||
@@ -2,7 +2,6 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>Microdot GPIO Example</title>
|
||||
<meta charset="UTF-8">
|
||||
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
|
||||
<script>
|
||||
function getCookie(name) {
|
||||
|
||||
@@ -1,104 +0,0 @@
|
||||
# Microdot Weather Dashboard
|
||||
|
||||
This example reports the temperature and humidity, both as a web application
|
||||
and as a JSON API.
|
||||
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
- A microcontroller that supports MicroPython (e.g. ESP8266, ESP32, Raspberry
|
||||
Pi Pico W, etc.)
|
||||
- A DHT22 temperature and humidity sensor
|
||||
- A breadboard and some jumper wires to create the circuit
|
||||
|
||||
## Circuit
|
||||
|
||||
Install the microconller and the DHT22 sensor on different parts of the
|
||||
breadboard. Make the following connections with jumper wires:
|
||||
|
||||
- from a microcontroller power pin (3.3V or 5V) to the left pin of the DHT22
|
||||
sensor.
|
||||
- from a microcontroller `GND` pin to the right pin of the DHT22 sensor.
|
||||
- from any available microcontroller GPIO pin to the middle pin of the DHT22
|
||||
sensor. If the DHT22 sensor has 4 pins instead of 3, use the one on the left,
|
||||
next to the pin receiving power.
|
||||
|
||||
The following diagram shows a possible wiring for this circuit using an ESP8266
|
||||
microcontroller and the 4-pin variant of the DHT22. In this diagram the data
|
||||
pin of the DHT22 sensor is connected to pin `D2` of the ESP8266, which is
|
||||
assigned to GPIO #4. Note that the location of the pins in the microcontroller
|
||||
board will vary depending on which microcontroller you use.
|
||||
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
Edit *config.py* as follows:
|
||||
|
||||
- Set the `DHT22_PIN` variable to the GPIO pin number connected to the sensor's
|
||||
data pin. Make sure you consult the documentation for your microcontroller to
|
||||
learn what number you should use for your chosen GPIO pin. In the example
|
||||
diagram above, the value should be 4.
|
||||
- Enter your Wi-Fi SSID name and password in this file.
|
||||
|
||||
Install MicroPython on your microcontroller board following instructions on the
|
||||
MicroPython website. Then use a tool such as
|
||||
[rshell](https://github.com/dhylands/rshell) to upload the following files to
|
||||
the board:
|
||||
|
||||
- *main.py*
|
||||
- *config.py*
|
||||
- *index.html*
|
||||
- *microdot.py*
|
||||
|
||||
You can find *microdot.py* in the *src/microdot* directory of this repository.
|
||||
|
||||
If you are using a low end microcontroller such as the ESP8266, it is quite
|
||||
possible that the *microdot.py* file will fail to compile due to the
|
||||
MicroPython compiler needing more RAM than available in the device. In that
|
||||
case, you can install the `mpy-cross` Python package in your computer (same
|
||||
version as your MicroPython firmware) and precompile this file. The precompiled
|
||||
file will have the name *microdot.mpy*. Upload this file and remove
|
||||
*microdot.py* from the device.
|
||||
|
||||
When the device is restarted after the files were uploaded, it will connect to
|
||||
Wi-Fi and then start a web server on port 8000. One way to find out which IP
|
||||
address was assigned to your device is to check your Wi-Fi's router
|
||||
administration panel. Another option is to connect to the MicroPython REPL with
|
||||
`rshell` or any other tool that you like, and then press Ctrl-D at the
|
||||
MicroPython prompt to soft boot the device. The IP address is printed to the
|
||||
terminal on startup.
|
||||
|
||||
You should not upload other *.py* files that exist in this directory to your
|
||||
device. These files are used when running with emulated hardware.
|
||||
|
||||
## Trying out the application
|
||||
|
||||
Once the device is running the server, you can connect to it using a web
|
||||
browser. For example, if your device's Wi-Fi connection was assigned the IP
|
||||
address 192.168.0.145, type *http://192.168.0.45:8000/* in your browser's
|
||||
address bar. Note it is *http://* and not *https://*. This example does not use
|
||||
the TLS/SSL protocol.
|
||||
|
||||
To test the JSON API, you can use `curl` or your favorite HTTP client. The API
|
||||
endpoint uses the */api* path, with the same URL as the main website. Here is
|
||||
an example using `curl`:
|
||||
|
||||
```bash
|
||||
$ curl http://192.168.0.145:8000/api
|
||||
{"temperature": 21.6, "humidity": 58.9, "time": 1752444652}
|
||||
```
|
||||
|
||||
The `temperature` value is given in degrees Celsius. The `humidity` value is
|
||||
given as a percentage. The `time` value is a UNIX timestamp.
|
||||
|
||||
## Running in Emulation mode
|
||||
|
||||
You can run this application on your computer, directly from this directory.
|
||||
When used in this way, the DHT22 hardware is emulated, and the temperature and
|
||||
humidity values are randomly generated.
|
||||
|
||||
The only dependency that is needed for this application to run in emulation
|
||||
mode is `microdot`, so make sure that is installed, or else add a copy of the
|
||||
*microdot.py* from the *src/microdot* directory in this folder.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 116 KiB |
@@ -1,3 +0,0 @@
|
||||
DHT22_PIN = 4 # GPIO pin for DHT22 sensor
|
||||
WIFI_ESSID = 'your_wifi_ssid'
|
||||
WIFI_PASSWORD = 'your_wifi_password'
|
||||
@@ -1,26 +0,0 @@
|
||||
"""
|
||||
DO NOT UPLOAD THIS FILE TO YOUR MICROPYTHON DEVICE
|
||||
|
||||
This module emulates MicroPython's DHT22 driver. It can be used when running
|
||||
on a system without the DHT22 hardware.
|
||||
|
||||
The temperature and humidity values that are returned are random values.
|
||||
"""
|
||||
|
||||
from random import random
|
||||
|
||||
|
||||
class DHT22:
|
||||
def __init__(self, pin):
|
||||
self.pin = pin
|
||||
|
||||
def measure(self):
|
||||
pass
|
||||
|
||||
def temperature(self):
|
||||
"""Return a random temperature between 10 and 30 degrees Celsius."""
|
||||
return random() * 20 + 10
|
||||
|
||||
def humidity(self):
|
||||
"""Return a random humidity between 30 and 70 percent."""
|
||||
return random() * 40 + 30
|
||||
@@ -1,169 +0,0 @@
|
||||
<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Microdot Weather Dashboard</title>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/gauge.js/1.3.9/gauge.min.js" integrity="sha512-/gkYCBz4KVyJb3Shz6Z1kKu9Za5EdInNezzsm2O/DPvAYhCeIOounTzi7yuIF526z3rNZfIDxcx+rJAD07p8aA==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
|
||||
<style>
|
||||
html, body {
|
||||
height: 95%;
|
||||
font-family: Arial, sans-serif;
|
||||
}
|
||||
#container {
|
||||
position: relative;
|
||||
top: 50%;
|
||||
left: 50%;
|
||||
transform: translate(-50%, -50%);
|
||||
}
|
||||
h1 {
|
||||
font-size: 1.5em;
|
||||
}
|
||||
h1, p {
|
||||
text-align: center;
|
||||
}
|
||||
table {
|
||||
margin-left: auto;
|
||||
margin-right: auto;
|
||||
}
|
||||
table h1 {
|
||||
margin-top: 0;
|
||||
}
|
||||
table p {
|
||||
margin: 0;
|
||||
}
|
||||
#temperature, #humidity {
|
||||
width: 100%;
|
||||
max-width: 400px;
|
||||
aspect-ratio: 2;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="container">
|
||||
<h1>Microdot Weather Dashboard</h1>
|
||||
<table cellspacing="0" cellpadding="0">
|
||||
<tr>
|
||||
<td>
|
||||
<canvas id="temperature" width="400" height="200"></canvas>
|
||||
</td>
|
||||
<td>
|
||||
<canvas id="humidity" width="400" height="200"></canvas>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>Temperature</p>
|
||||
<h1><span id="temperature-text">??</span>°C</h1>
|
||||
</td>
|
||||
<td>
|
||||
<p>Humidity</p>
|
||||
<h1><span id="humidity-text">??</span>%</h1>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
<p><i>Last updated: <span id="time-text">...</span></i></p>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<script>
|
||||
// create the temperature gauge
|
||||
let temperatureGauge = new Gauge(document.getElementById('temperature')).setOptions({
|
||||
angle: 0,
|
||||
lineWidth: 0.3,
|
||||
radiusScale: 1,
|
||||
pointer: {
|
||||
length: 0.6,
|
||||
strokeWidth: 0.035,
|
||||
color: '#000000',
|
||||
},
|
||||
limitMax: false,
|
||||
limitMin: false,
|
||||
highDpiSupport: true,
|
||||
staticLabels: {
|
||||
font: "14px sans-serif",
|
||||
labels: [-30, -20, -10, 0, 10, 20, 30, 40, 50],
|
||||
color: "#000000",
|
||||
fractionDigits: 0,
|
||||
},
|
||||
staticZones: [
|
||||
{strokeStyle: "#85a6e8", min: -30, max: 0},
|
||||
{strokeStyle: "#a5dde8", min: 0, max: 10},
|
||||
{strokeStyle: "#a5e8a6", min: 10, max: 20},
|
||||
{strokeStyle: "#e8d8a5", min: 20, max: 30},
|
||||
{strokeStyle: "#e8a8a5", min: 30, max: 50},
|
||||
],
|
||||
renderTicks: {
|
||||
divisions: 8,
|
||||
divWidth: 1.1,
|
||||
divLength: 0.7,
|
||||
divColor: '#333333',
|
||||
subDivisions: 4,
|
||||
subLength: 0.3,
|
||||
subWidth: 0.6,
|
||||
subColor: '#666666'
|
||||
}
|
||||
});
|
||||
temperatureGauge.maxValue = 50;
|
||||
temperatureGauge.setMinValue(-30);
|
||||
temperatureGauge.animationSpeed = 36;
|
||||
temperatureGauge.set(0);
|
||||
|
||||
let humidityGauge = new Gauge(document.getElementById('humidity')).setOptions({
|
||||
angle: 0,
|
||||
lineWidth: 0.3,
|
||||
radiusScale: 1,
|
||||
pointer: {
|
||||
length: 0.6,
|
||||
strokeWidth: 0.035,
|
||||
color: '#000000',
|
||||
},
|
||||
limitMax: false,
|
||||
limitMin: false,
|
||||
highDpiSupport: true,
|
||||
staticLabels: {
|
||||
font: "14px sans-serif",
|
||||
labels: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
|
||||
color: "#000000",
|
||||
fractionDigits: 0,
|
||||
},
|
||||
staticZones: [
|
||||
{strokeStyle: "#85a6e8", min: 0, max: 40},
|
||||
{strokeStyle: "#a5e8a6", min: 40, max: 70},
|
||||
{strokeStyle: "#e8a8a5", min: 70, max: 100},
|
||||
],
|
||||
renderTicks: {
|
||||
divisions: 10,
|
||||
divWidth: 1.1,
|
||||
divLength: 0.7,
|
||||
divColor: '#333333',
|
||||
subDivisions: 4,
|
||||
subLength: 0.3,
|
||||
subWidth: 0.6,
|
||||
subColor: '#666666'
|
||||
}
|
||||
});
|
||||
humidityGauge.maxValue = 100;
|
||||
humidityGauge.setMinValue(0);
|
||||
humidityGauge.animationSpeed = 36;
|
||||
humidityGauge.set(0);
|
||||
|
||||
async function update() {
|
||||
const response = await fetch('/api');
|
||||
if (response.ok) {
|
||||
const data = await response.json();
|
||||
temperatureGauge.set(data.temperature);
|
||||
humidityGauge.set(data.humidity);
|
||||
document.getElementById('temperature-text').textContent = data.temperature;
|
||||
document.getElementById('humidity-text').textContent = data.humidity;
|
||||
document.getElementById('time-text').textContent = new Date(data.time * 1000).toLocaleString();
|
||||
}
|
||||
setTimeout(update, 60000); // refresh every minute
|
||||
}
|
||||
update();
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,12 +0,0 @@
|
||||
"""
|
||||
DO NOT UPLOAD THIS FILE TO YOUR MICROPYTHON DEVICE
|
||||
|
||||
This module emulates parts of MicroPython's `machine` module, to enable to run
|
||||
MicroPython applications on UNIX, Mac or Windows systems without dedicated
|
||||
hardware.
|
||||
"""
|
||||
|
||||
|
||||
class Pin:
|
||||
def __init__(self, pin):
|
||||
self.pin = pin
|
||||
@@ -1,112 +0,0 @@
|
||||
import asyncio
|
||||
import dht
|
||||
import gc
|
||||
import machine
|
||||
import network
|
||||
import socket
|
||||
import time
|
||||
|
||||
import config
|
||||
from microdot import Microdot, send_file
|
||||
|
||||
app = Microdot()
|
||||
current_temperature = None
|
||||
current_humidity = None
|
||||
current_time = None
|
||||
|
||||
|
||||
def wifi_connect():
|
||||
"""Connect to the configured Wi-Fi network.
|
||||
Returns the IP address of the connected interface.
|
||||
"""
|
||||
ap_if = network.WLAN(network.AP_IF)
|
||||
ap_if.active(False)
|
||||
|
||||
sta_if = network.WLAN(network.STA_IF)
|
||||
if not sta_if.isconnected():
|
||||
print('connecting to network...')
|
||||
sta_if.active(True)
|
||||
sta_if.connect(config.WIFI_ESSID, config.WIFI_PASSWORD)
|
||||
for i in range(20):
|
||||
if sta_if.isconnected():
|
||||
break
|
||||
time.sleep(1)
|
||||
if not sta_if.isconnected():
|
||||
raise RuntimeError('Could not connect to network')
|
||||
return sta_if.ifconfig()[0]
|
||||
|
||||
|
||||
def get_current_time():
|
||||
"""Return the current Unix time.
|
||||
Note that because many microcontrollers do not have a clock, this function
|
||||
makes a call to an NTP server to obtain the current time. A Wi-Fi
|
||||
connection needs to be in place before calling this function.
|
||||
"""
|
||||
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
|
||||
s.settimeout(5)
|
||||
s.sendto(b'\x1b' + 47 * b'\0',
|
||||
socket.getaddrinfo('pool.ntp.org', 123)[0][4])
|
||||
msg, _ = s.recvfrom(1024)
|
||||
return ((msg[40] << 24) | (msg[41] << 16) | (msg[42] << 8) | msg[43]) - \
|
||||
2208988800
|
||||
|
||||
|
||||
def get_current_weather():
|
||||
"""Read the temperature and humidity from the DHT22 sensor.
|
||||
Returns them as a tuple. The returned temperature is in degrees Celcius.
|
||||
The humidity is a 0-100 percentage.
|
||||
"""
|
||||
d = dht.DHT22(machine.Pin(config.DHT22_PIN))
|
||||
d.measure()
|
||||
return d.temperature(), d.humidity()
|
||||
|
||||
|
||||
async def refresh_weather():
|
||||
"""Background task that updates the temperature and humidity.
|
||||
This task is designed to run in the background. It connects to the DHT22
|
||||
temperature and humidity sensor once per minute and stores the updated
|
||||
readings in global variables.
|
||||
"""
|
||||
global current_temperature
|
||||
global current_humidity
|
||||
global current_time
|
||||
|
||||
while True:
|
||||
try:
|
||||
t = get_current_time()
|
||||
temp, hum = get_current_weather()
|
||||
except asyncio.CancelledError:
|
||||
raise
|
||||
except Exception as error:
|
||||
print(f'Could not obtain weather, error: {error}')
|
||||
else:
|
||||
current_time = t
|
||||
current_temperature = int(temp * 10) / 10
|
||||
current_humidity = int(hum * 10) / 10
|
||||
gc.collect()
|
||||
await asyncio.sleep(60)
|
||||
|
||||
|
||||
@app.route('/')
|
||||
async def index(request):
|
||||
return send_file('index.html')
|
||||
|
||||
|
||||
@app.route('/api')
|
||||
async def api(request):
|
||||
return {
|
||||
'temperature': current_temperature,
|
||||
'humidity': current_humidity,
|
||||
'time': current_time,
|
||||
}
|
||||
|
||||
|
||||
async def start():
|
||||
ip = wifi_connect()
|
||||
print(f'Starting server at http://{ip}:8000...')
|
||||
bgtask = asyncio.create_task(refresh_weather())
|
||||
server = asyncio.create_task(app.start_server(port=8000))
|
||||
await asyncio.gather(server, bgtask)
|
||||
|
||||
|
||||
asyncio.run(start())
|
||||
@@ -1,31 +0,0 @@
|
||||
"""
|
||||
DO NOT UPLOAD THIS FILE TO YOUR MICROPYTHON DEVICE
|
||||
|
||||
This module emulates parts of MicroPython's `network` module, in particular
|
||||
those related to establishing a Wi-Fi connection. This enables to run
|
||||
MicroPython applications on UNIX, Mac or Windows systems without dedicated
|
||||
hardware.
|
||||
|
||||
Note that no connections are attempted. The assumption is that the system is
|
||||
already connected. The "127.0.0.1" address is always returned.
|
||||
"""
|
||||
|
||||
AP_IF = 1
|
||||
STA_IF = 2
|
||||
|
||||
|
||||
class WLAN:
|
||||
def __init__(self, network):
|
||||
self.network = network
|
||||
|
||||
def isconnected(self):
|
||||
return True
|
||||
|
||||
def ifconfig(self):
|
||||
return ('127.0.0.1', 'n/a', 'n/a', 'n/a')
|
||||
|
||||
def connect(self):
|
||||
pass
|
||||
|
||||
def active(self, active=None):
|
||||
pass
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 56 KiB |
@@ -2,11 +2,10 @@ from microdot import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
html = '''<!DOCTYPE html>
|
||||
htmldoc = '''<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Microdot Example Page</title>
|
||||
<meta charset="UTF-8">
|
||||
</head>
|
||||
<body>
|
||||
<div>
|
||||
@@ -20,12 +19,12 @@ html = '''<!DOCTYPE html>
|
||||
|
||||
|
||||
@app.route('/')
|
||||
async def hello(request):
|
||||
return html, 200, {'Content-Type': 'text/html'}
|
||||
def hello(request):
|
||||
return htmldoc, 200, {'Content-Type': 'text/html'}
|
||||
|
||||
|
||||
@app.route('/shutdown')
|
||||
async def shutdown(request):
|
||||
def shutdown(request):
|
||||
request.app.shutdown()
|
||||
return 'The server is shutting down...'
|
||||
|
||||
|
||||
@@ -1,12 +1,11 @@
|
||||
from microdot.asgi import Microdot
|
||||
from microdot_asgi import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
html = '''<!DOCTYPE html>
|
||||
htmldoc = '''<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Microdot Example Page</title>
|
||||
<meta charset="UTF-8">
|
||||
</head>
|
||||
<body>
|
||||
<div>
|
||||
@@ -21,7 +20,7 @@ html = '''<!DOCTYPE html>
|
||||
|
||||
@app.route('/')
|
||||
async def hello(request):
|
||||
return html, 200, {'Content-Type': 'text/html'}
|
||||
return htmldoc, 200, {'Content-Type': 'text/html'}
|
||||
|
||||
|
||||
@app.route('/shutdown')
|
||||
|
||||
32
examples/hello/hello_async.py
Normal file
32
examples/hello/hello_async.py
Normal file
@@ -0,0 +1,32 @@
|
||||
from microdot_asyncio import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
htmldoc = '''<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Microdot Example Page</title>
|
||||
</head>
|
||||
<body>
|
||||
<div>
|
||||
<h1>Microdot Example Page</h1>
|
||||
<p>Hello from Microdot!</p>
|
||||
<p><a href="/shutdown">Click to shutdown the server</a></p>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
'''
|
||||
|
||||
|
||||
@app.route('/')
|
||||
async def hello(request):
|
||||
return htmldoc, 200, {'Content-Type': 'text/html'}
|
||||
|
||||
|
||||
@app.route('/shutdown')
|
||||
async def shutdown(request):
|
||||
request.app.shutdown()
|
||||
return 'The server is shutting down...'
|
||||
|
||||
|
||||
app.run(debug=True)
|
||||
@@ -1,16 +1,16 @@
|
||||
from microdot import Microdot, Response
|
||||
from microdot.jinja import Template
|
||||
from microdot_jinja import render_template
|
||||
|
||||
app = Microdot()
|
||||
Response.default_content_type = 'text/html'
|
||||
|
||||
|
||||
@app.route('/', methods=['GET', 'POST'])
|
||||
async def index(req):
|
||||
def index(req):
|
||||
name = None
|
||||
if req.method == 'POST':
|
||||
name = req.form.get('name')
|
||||
return Template('index.html').generate(name=name)
|
||||
return render_template('index_jinja.html', name=name)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
@@ -1,16 +1,16 @@
|
||||
from microdot import Microdot, Response
|
||||
from microdot.utemplate import Template
|
||||
from microdot_utemplate import render_template
|
||||
|
||||
app = Microdot()
|
||||
Response.default_content_type = 'text/html'
|
||||
|
||||
|
||||
@app.route('/', methods=['GET', 'POST'])
|
||||
async def index(req):
|
||||
def index(req):
|
||||
name = None
|
||||
if req.method == 'POST':
|
||||
name = req.form.get('name')
|
||||
return Template('index.html').render(name=name)
|
||||
return render_template('index_utemplate.html', name=name)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
@@ -1,5 +1,5 @@
|
||||
from microdot.wsgi import Microdot, Response
|
||||
from microdot.jinja import Template
|
||||
from microdot_asyncio import Microdot, Response
|
||||
from microdot_utemplate import render_template
|
||||
|
||||
app = Microdot()
|
||||
Response.default_content_type = 'text/html'
|
||||
@@ -10,7 +10,7 @@ async def index(req):
|
||||
name = None
|
||||
if req.method == 'POST':
|
||||
name = req.form.get('name')
|
||||
return Template('index.html').render(name=name)
|
||||
return render_template('index.html', name=name)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
@@ -1,12 +1,11 @@
|
||||
from microdot.wsgi import Microdot
|
||||
from microdot_wsgi import Microdot
|
||||
|
||||
app = Microdot()
|
||||
|
||||
html = '''<!DOCTYPE html>
|
||||
htmldoc = '''<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Microdot Example Page</title>
|
||||
<meta charset="UTF-8">
|
||||
</head>
|
||||
<body>
|
||||
<div>
|
||||
@@ -21,7 +20,7 @@ html = '''<!DOCTYPE html>
|
||||
|
||||
@app.route('/')
|
||||
def hello(request):
|
||||
return html, 200, {'Content-Type': 'text/html'}
|
||||
return htmldoc, 200, {'Content-Type': 'text/html'}
|
||||
|
||||
|
||||
@app.route('/shutdown')
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>Microdot + Jinja example</title>
|
||||
<meta charset="UTF-8">
|
||||
</head>
|
||||
<body>
|
||||
<h1>Microdot + Jinja example</h1>
|
||||
@@ -3,7 +3,6 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>Microdot + uTemplate example</title>
|
||||
<meta charset="UTF-8">
|
||||
</head>
|
||||
<body>
|
||||
<h1>Microdot + uTemplate example</h1>
|
||||
@@ -1 +0,0 @@
|
||||
This directory contains examples that demonstrate user logins.
|
||||
@@ -1,123 +0,0 @@
|
||||
from microdot import Microdot, redirect
|
||||
from microdot.session import Session
|
||||
from microdot.login import Login
|
||||
from pbkdf2 import generate_password_hash, check_password_hash
|
||||
|
||||
# this example provides an implementation of the generate_password_hash and
|
||||
# check_password_hash functions that can be used in MicroPython. On CPython
|
||||
# there are many other options for password hashisng so there is no need to use
|
||||
# this custom solution.
|
||||
|
||||
|
||||
class User:
|
||||
def __init__(self, id, username, password):
|
||||
self.id = id
|
||||
self.username = username
|
||||
self.password_hash = self.create_hash(password)
|
||||
|
||||
def create_hash(self, password):
|
||||
return generate_password_hash(password)
|
||||
|
||||
def check_password(self, password):
|
||||
return check_password_hash(self.password_hash, password)
|
||||
|
||||
|
||||
USERS = {
|
||||
'user001': User('user001', 'susan', 'hello'),
|
||||
'user002': User('user002', 'david', 'bye'),
|
||||
}
|
||||
|
||||
app = Microdot()
|
||||
Session(app, secret_key='top-secret!')
|
||||
login = Login()
|
||||
|
||||
|
||||
@login.user_loader
|
||||
async def get_user(user_id):
|
||||
return USERS.get(user_id)
|
||||
|
||||
|
||||
@app.route('/login', methods=['GET', 'POST'])
|
||||
async def login_page(request):
|
||||
if request.method == 'GET':
|
||||
return '''
|
||||
<!doctype html>
|
||||
<html>
|
||||
<body>
|
||||
<h1>Please Login</h1>
|
||||
<form method="POST">
|
||||
<p>
|
||||
Username<br>
|
||||
<input name="username" autofocus>
|
||||
</p>
|
||||
<p>
|
||||
Password:<br>
|
||||
<input name="password" type="password">
|
||||
<br>
|
||||
</p>
|
||||
<p>
|
||||
<input name="remember_me" type="checkbox"> Remember me
|
||||
<br>
|
||||
</p>
|
||||
<p>
|
||||
<button type="submit">Login</button>
|
||||
</p>
|
||||
</form>
|
||||
</body>
|
||||
</html>
|
||||
''', {'Content-Type': 'text/html'}
|
||||
username = request.form['username']
|
||||
password = request.form['password']
|
||||
remember_me = bool(request.form.get('remember_me'))
|
||||
|
||||
for user in USERS.values():
|
||||
if user.username == username:
|
||||
if user.check_password(password):
|
||||
return await login.login_user(request, user,
|
||||
remember=remember_me)
|
||||
return redirect('/login')
|
||||
|
||||
|
||||
@app.route('/')
|
||||
@login
|
||||
async def index(request):
|
||||
return f'''
|
||||
<!doctype html>
|
||||
<html>
|
||||
<body>
|
||||
<h1>Hello, {request.g.current_user.username}!</h1>
|
||||
<p>
|
||||
<a href="/fresh">Click here</a> to access the fresh login page.
|
||||
</p>
|
||||
<form method="POST" action="/logout">
|
||||
<button type="submit">Logout</button>
|
||||
</form>
|
||||
</body>
|
||||
</html>
|
||||
''', {'Content-Type': 'text/html'}
|
||||
|
||||
|
||||
@app.get('/fresh')
|
||||
@login.fresh
|
||||
async def fresh(request):
|
||||
return f'''
|
||||
<!doctype html>
|
||||
<html>
|
||||
<body>
|
||||
<h1>Hello, {request.g.current_user.username}!</h1>
|
||||
<p>This page requires a fresh login session.</p>
|
||||
<p><a href="/">Go back</a> to the main page.</p>
|
||||
</body>
|
||||
</html>
|
||||
''', {'Content-Type': 'text/html'}
|
||||
|
||||
|
||||
@app.post('/logout')
|
||||
@login
|
||||
async def logout(request):
|
||||
await login.logout_user(request)
|
||||
return redirect('/')
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
app.run(debug=True)
|
||||
@@ -1,47 +0,0 @@
|
||||
import os
|
||||
import hashlib
|
||||
|
||||
# PBKDF2 secure password hashing algorithm obtained from:
|
||||
# https://codeandlife.com/2023/01/06/how-to-calculate-pbkdf2-hmac-sha256-with-
|
||||
# python,-example-code/
|
||||
|
||||
|
||||
def sha256(b):
|
||||
return hashlib.sha256(b).digest()
|
||||
|
||||
|
||||
def ljust(b, n, f):
|
||||
return b + f * (n - len(b))
|
||||
|
||||
|
||||
def gethmac(key, content):
|
||||
okeypad = bytes(v ^ 0x5c for v in ljust(key, 64, b'\0'))
|
||||
ikeypad = bytes(v ^ 0x36 for v in ljust(key, 64, b'\0'))
|
||||
return sha256(okeypad + sha256(ikeypad + content))
|
||||
|
||||
|
||||
def pbkdf2(pwd, salt, iterations=1000):
|
||||
U = salt + b'\x00\x00\x00\x01'
|
||||
T = bytes(64)
|
||||
for _ in range(iterations):
|
||||
U = gethmac(pwd, U)
|
||||
T = bytes(a ^ b for a, b in zip(U, T))
|
||||
return T
|
||||
|
||||
|
||||
# The number of iterations may need to be adjusted depending on the hardware.
|
||||
# Lower numbers make the password hashing algorithm faster but less secure, so
|
||||
# the largest number that can be tolerated should be used.
|
||||
def generate_password_hash(password, salt=None, iterations=100000):
|
||||
salt = salt or os.urandom(16)
|
||||
dk = pbkdf2(password.encode(), salt, iterations)
|
||||
return f'pbkdf2-hmac-sha256:{salt.hex()}:{iterations}:{dk.hex()}'
|
||||
|
||||
|
||||
def check_password_hash(password_hash, password):
|
||||
algorithm, salt, iterations, dk = password_hash.split(':')
|
||||
iterations = int(iterations)
|
||||
if algorithm != 'pbkdf2-hmac-sha256':
|
||||
return False
|
||||
return pbkdf2(password.encode(), salt=bytes.fromhex(salt),
|
||||
iterations=iterations) == bytes.fromhex(dk)
|
||||
@@ -1,14 +1,11 @@
|
||||
# This is a simple example that demonstrates how to use the user session, but
|
||||
# is not intended as a complete login solution. See the login subdirectory for
|
||||
# a more complete example.
|
||||
from microdot import Microdot, Response, redirect
|
||||
from microdot.session import Session, with_session
|
||||
from microdot_session import set_session_secret_key, with_session, \
|
||||
update_session, delete_session
|
||||
|
||||
BASE_TEMPLATE = '''<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Microdot login example</title>
|
||||
<meta charset="UTF-8">
|
||||
</head>
|
||||
<body>
|
||||
<h1>Microdot login example</h1>
|
||||
@@ -20,7 +17,7 @@ LOGGED_OUT = '''<p>You are not logged in.</p>
|
||||
<form method="POST">
|
||||
<p>
|
||||
Username:
|
||||
<input name="username" autofocus />
|
||||
<input type="text" name="username" autofocus />
|
||||
</p>
|
||||
<input type="submit" value="Submit" />
|
||||
</form>'''
|
||||
@@ -31,19 +28,18 @@ LOGGED_IN = '''<p>Hello <b>{username}</b>!</p>
|
||||
</form>'''
|
||||
|
||||
app = Microdot()
|
||||
Session(app, secret_key='top-secret')
|
||||
set_session_secret_key('top-secret')
|
||||
Response.default_content_type = 'text/html'
|
||||
|
||||
|
||||
@app.get('/')
|
||||
@app.post('/')
|
||||
@with_session
|
||||
async def index(req, session):
|
||||
def index(req, session):
|
||||
username = session.get('username')
|
||||
if req.method == 'POST':
|
||||
username = req.form.get('username')
|
||||
session['username'] = username
|
||||
session.save()
|
||||
update_session(req, {'username': username})
|
||||
return redirect('/')
|
||||
if username is None:
|
||||
return BASE_TEMPLATE.format(content=LOGGED_OUT)
|
||||
@@ -53,9 +49,8 @@ async def index(req, session):
|
||||
|
||||
|
||||
@app.post('/logout')
|
||||
@with_session
|
||||
async def logout(req, session):
|
||||
session.delete()
|
||||
def logout(req):
|
||||
delete_session(req)
|
||||
return redirect('/')
|
||||
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user