Package: picoweb
picoweb is a “micro” web micro-framework (thus, “pico-framework”) for
radically unbloated web applications using radically unbloated Python
implementation, Pycopy,https://github.com/pfalcon/pycopy.Features:Asynchronous from the start, using unbloated asyncio-like library
for Pycopy (uasyncio).
This means thatpicowebcan process multiple concurrent requests
at the same time (using I/O and/or CPU multiplexing).Small memory usage. Initial version required about 64K of heap for
a trivial web app, and since then, it was optimized to allow run
more or less realistic web app in ~36K of heap. More optimizations
on all the levels (Pycopy and up) are planned (but may lead to
API changes).Has API affinity with some well-known Python web micro-framework(s),
thus it should be an easy start if you have experience with them, and
existing applications can be potentially ported, instead of requiring
complete rewrite.Requirements and optional modulespicowebdepends onuasynciofor asynchronous networking
(https://github.com/pfalcon/pycopy-lib/tree/master/uasyncio).uasyncioitself requiresPycopy <https://github.com/pfalcon/pycopy>,
a minimalist, lightweight, and resource-efficient Python language
implementation.It is also indended to be used withutemplate(https://github.com/pfalcon/utemplate) for templating, but this is
a “soft” dependency - picoweb offers convenience functions to useutemplatetemplates, but if you don’t use them or will handle
templating in your app (e.g. with a different library), it won’t be
imported.For database access, there are following options (picowebdoes
not depend on any of them, up to your application to choose):btreebuiltin Pycopy module. This is a recommended way to do a database
storage forpicoweb, as it allows portability across all Pycopy
targets, starting with very memory- and storage-limited baremetal systems.btreedbwrapper on top ofbtreebuiltin module. This may add some
overhead, but may allow to make an application portable between different
database backends (filedbanduormbelow).https://github.com/pfalcon/pycopy-btreedbfiledb, for a simple database using files in a filesystemhttps://github.com/pfalcon/filedbuorm, for Sqlite3 database access (works only with Pycopy
Unix port)https://github.com/pfalcon/uormLast but not least,picowebuses a standardlogging-compatible
logger for diagnostic output (like a connection opened, errors and debug
information). However this output is optional, and otherwise you can use
a custom logging class instead of the standardlogging/uloggingmodule. Due to this, and to not put additional dependencies burden on
the small webapps for small systems,loggingmodule is not included
inpicoweb’s installation dependencies. Instead, a particular app
usingpicowebshould depend onpycopy-uloggingorpycopy-loggingpackage. Note that to disable use of logging,
an application should start up usingWebApp.run(debug=-1). The
default value fordebugparameter is 0 however, in which case
picoweb will useuloggingmodule (on which your application needs
to depend, again).Detailspicoweb API is roughly based on APIs of other well-known Python web
frameworks. The strongest affinity is Flask,http://flask.pocoo.org, as
arguably the most popular micro-framework. Some features are also based on
Bottle and Django. Note that this does not mean particular “compatibility”
with Flask, Bottle, or Django: most existing web frameworks are synchronous
(and threaded), while picoweb is async framework, so its architecture is
quite different. However, there is an aim to save porting efforts from
repetitive search & replace trials: for example, when methods do similar
things, they are likely named the same (but they may take slightly different
parameters, return different values, and behave slightly differently).The biggest difference is async, non-threaded nature of picoweb. That means
that the same code may handle multiple requests at the same time, but unlike
threaded environment, there’s no external context (like thread and thread
local storage) to associate with each request. Thus, there’re no “global”
(or thread-local “global”) request and response objects, like Flask,
Bottle, Django have. Instead, all picoweb functions explicitly pass the
current request and response objects around.Also, picoweb, being unbloated framework, tries to avoid avoidable
abstractions. For example, HTTP at the lowest level has just read and write
endpoints of a socket. To dispatch request, picoweb needs to pre-parse
some request data from input stream, and it saves that partially (sic!)
parsed data as a “request” object, and that’s what passed to application
handlers. However, there’s no unavoidable need to have a “response”
abstraction - the most efficient/lightweight application may want to
just write raw HTTP status line, headers, and body to the socket. Thus,
raw write stream is passed to application handlers as the “response” object.
(But high-level convenience functions to construct an HTTP response are
provided).API referenceThe best API reference currently are examples (see below) and thepicowebsource code itself. It’s under 10K, so enjoy:https://github.com/pfalcon/picoweb/blob/master/picoweb/__init__.pyNote that API is experimental and may undergo changes.Examplesexample_webapp.py-
A simple webapp showing you how to generate a complete HTTP response
yourself, usepicowebconvenience functions for HTTP headers generation,
and use of templates. Mapping from URLs to webapp view functions (“web
routes” or just “routes”) is done Django-style, using a centralized route
list.example_webapp2.py-
Like above, but usesapp.route()decorator for route specification,
Flask-style.examples/-
Additional examples for various features of picoweb. See comments in each
file for additional info. To run examples in this directory, you normally
would need to have picoweb installed (i.e. available in yourMICROPYPATH,
which defaults to~/.micropython/lib/).notes-pico- A more realistic
example webapp, ported from the Flask original.Running under CPython (regressed)Initial versions of picoweb could run under CPython, but later it was
further optimized for Pycopy, and ability to run under CPython
regressed. It’s still on TODO to fix it, instructions below tell how
it used to work.At least CPython 3.4.2 is required (for asyncio loop.create_task() support).
To run under CPython, uasyncio compatibility module for CPython is required
(pycopy-cpython-uasyncio). This and other dependencies can be installed
using requirements-cpython.txt:pip install -r requirements-cpython.txtReporting IssuesHere are a few guidelines to make feedback more productive:Please be considerate of the overall best practices and common pitfalls in
reporting issues, this document gives a good overview:How to Report Bugs Effectively.The reference platform forpicowebis the Unix port of Pycopy. All issues
reported must be validated against this version, to differentiate issues ofpicoweb/uasynciofrom the issues of your underlying platform.All reports must include version information of all components involved:
Pycopy, picoweb, uasyncio, uasyncio.core, any additional modules. Generally,
only the latest versions of the above are supported (this is what you get when
you install/reinstall components using theupippackage manager). The
version information are thus first of all important for yourself, the issue
reporter, it allows you to double-check if you’re using an outdated or
unsupported component.Feature requests:picowebis by definition a pico-framework, and bound
to stay so. Feature requests are welcome, but please be considerate that
they may be outside the scope of core project. There’s an easy way out
though: instead of putting more stuffintopicoweb, build new thingson topof it: via plugins, subclassing, additional modules etc. That’s
how it was intended to be from the beginning!We would like to establish a dedicated QA team to support users of this
project better. If you would like to sponsor this effort, please let us
know.