{"id":13594474,"url":"https://github.com/pfalcon/picoweb","last_synced_at":"2025-10-24T12:43:54.897Z","repository":{"id":17562866,"uuid":"20366218","full_name":"pfalcon/picoweb","owner":"pfalcon","description":"Really minimal web application framework for the Pycopy project (minimalist Python dialect) and its \"uasyncio\" async framework","archived":false,"fork":false,"pushed_at":"2024-01-23T08:50:20.000Z","size":112,"stargazers_count":514,"open_issues_count":22,"forks_count":100,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-04-12T12:54:43.367Z","etag":null,"topics":["async","asyncio","micro-framework","micropython","minimalist","nano-framework","pycopy","python","unbloated","webapp","webserver"],"latest_commit_sha":null,"homepage":"https://github.com/pfalcon/pycopy","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pfalcon.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-05-31T22:14:49.000Z","updated_at":"2025-02-25T10:16:46.000Z","dependencies_parsed_at":"2024-06-09T10:03:19.309Z","dependency_job_id":null,"html_url":"https://github.com/pfalcon/picoweb","commit_stats":{"total_commits":196,"total_committers":6,"mean_commits":"32.666666666666664","dds":"0.030612244897959218","last_synced_commit":"b74428ebdde97ed1795338c13a3bdf05d71366a0"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Fpicoweb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Fpicoweb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Fpicoweb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Fpicoweb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pfalcon","download_url":"https://codeload.github.com/pfalcon/picoweb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544146,"owners_count":22088807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","asyncio","micro-framework","micropython","minimalist","nano-framework","pycopy","python","unbloated","webapp","webserver"],"created_at":"2024-08-01T16:01:34.135Z","updated_at":"2025-10-24T12:43:54.840Z","avatar_url":"https://github.com/pfalcon.png","language":"Python","readme":"picoweb\n=======\n\npicoweb is a \"micro\" web micro-framework (thus, \"pico-framework\") for\nradically unbloated web applications using radically unbloated Python\nimplementation, Pycopy, https://github.com/pfalcon/pycopy .\n\nFeatures:\n\n* Asynchronous from the start, using unbloated asyncio-like library\n  for Pycopy (`uasyncio \u003chttps://github.com/pfalcon/pycopy-lib/tree/master/uasyncio\u003e`_).\n  This means that ``picoweb`` can process multiple concurrent requests\n  at the same time (using I/O and/or CPU multiplexing).\n* Small memory usage. Initial version required about 64K of heap for\n  a trivial web app, and since then, it was optimized to allow run\n  more or less realistic web app in ~36K of heap. More optimizations\n  on all the levels (Pycopy and up) are planned (but may lead to\n  API changes).\n* Has API affinity with some well-known Python web micro-framework(s),\n  thus it should be an easy start if you have experience with them, and\n  existing applications can be potentially ported, instead of requiring\n  complete rewrite.\n\n\nRequirements and optional modules\n---------------------------------\n\n``picoweb`` depends on ``uasyncio`` for asynchronous networking\n(https://github.com/pfalcon/pycopy-lib/tree/master/uasyncio).\n``uasyncio`` itself requires `Pycopy \u003chttps://github.com/pfalcon/pycopy\u003e`,\na minimalist, lightweight, and resource-efficient Python language\nimplementation.\n\nIt is also indended to be used with ``utemplate``\n(https://github.com/pfalcon/utemplate) for templating, but this is\na \"soft\" dependency - picoweb offers convenience functions to use\n``utemplate`` templates, but if you don't use them or will handle\ntemplating in your app (e.g. with a different library), it won't be\nimported.\n\nFor database access, there are following options (``picoweb`` does\nnot depend on any of them, up to your application to choose):\n\n* `btree \u003chttps://pycopy.readthedocs.io/en/latest/library/btree.html\u003e`_\n  builtin Pycopy module. This is a recommended way to do a database\n  storage for `picoweb`, as it allows portability across all Pycopy\n  targets, starting with very memory- and storage-limited baremetal systems.\n* ``btreedb`` wrapper on top of ``btree`` builtin module. This may add some\n  overhead, but may allow to make an application portable between different\n  database backends (`filedb` and `uorm` below).\n  https://github.com/pfalcon/pycopy-btreedb\n* ``filedb``, for a simple database using files in a filesystem\n  https://github.com/pfalcon/filedb\n* ``uorm``, for Sqlite3 database access (works only with Pycopy\n  Unix port) https://github.com/pfalcon/uorm\n\nLast but not least, ``picoweb`` uses a standard ``logging``-compatible\nlogger for diagnostic output (like a connection opened, errors and debug\ninformation). However this output is optional, and otherwise you can use\na custom logging class instead of the standard ``logging``/``ulogging``\nmodule. Due to this, and to not put additional dependencies burden on\nthe small webapps for small systems, ``logging`` module is not included\nin ``picoweb``'s installation dependencies. Instead, a particular app\nusing ``picoweb`` should depend on ``pycopy-ulogging`` or\n``pycopy-logging`` package. Note that to disable use of logging,\nan application should start up using ``WebApp.run(debug=-1)``. The\ndefault value for ``debug`` parameter is 0 however, in which case\npicoweb will use ``ulogging`` module (on which your application needs\nto depend, again).\n\n\nDetails\n-------\n\npicoweb API is roughly based on APIs of other well-known Python web\nframeworks. The strongest affinity is Flask, http://flask.pocoo.org, as\narguably the most popular micro-framework. Some features are also based on\nBottle and Django. Note that this does not mean particular \"compatibility\"\nwith Flask, Bottle, or Django: most existing web frameworks are synchronous\n(and threaded), while picoweb is async framework, so its architecture is\nquite different. However, there is an aim to save porting efforts from\nrepetitive search \u0026 replace trials: for example, when methods do similar\nthings, they are likely named the same (but they may take slightly different\nparameters, return different values, and behave slightly differently).\n\nThe biggest difference is async, non-threaded nature of picoweb. That means\nthat the same code may handle multiple requests at the same time, but unlike\nthreaded environment, there's no external context (like thread and thread\nlocal storage) to associate with each request. Thus, there're no \"global\"\n(or thread-local \"global\") request and response objects, like Flask,\nBottle, Django have. Instead, all picoweb functions explicitly pass the\ncurrent request and response objects around.\n\nAlso, picoweb, being unbloated framework, tries to avoid avoidable\nabstractions. For example, HTTP at the lowest level has just read and write\nendpoints of a socket. To dispatch request, picoweb needs to pre-parse\nsome request data from input stream, and it saves that partially (sic!)\nparsed data as a \"request\" object, and that's what passed to application\nhandlers. However, there's no unavoidable need to have a \"response\"\nabstraction - the most efficient/lightweight application may want to\njust write raw HTTP status line, headers, and body to the socket. Thus,\nraw write stream is passed to application handlers as the \"response\" object.\n(But high-level convenience functions to construct an HTTP response are\nprovided).\n\n\nAPI reference\n-------------\n\nThe best API reference currently are examples (see below) and the ``picoweb``\nsource code itself. It's under 10K, so enjoy:\nhttps://github.com/pfalcon/picoweb/blob/master/picoweb/__init__.py\n\nNote that API is experimental and may undergo changes.\n\n\nExamples\n--------\n\n* `example_webapp.py \u003chttps://github.com/pfalcon/picoweb/blob/master/example_webapp.py\u003e`_ -\n  A simple webapp showing you how to generate a complete HTTP response\n  yourself, use ``picoweb`` convenience functions for HTTP headers generation,\n  and use of templates. Mapping from URLs to webapp view functions (\"web\n  routes\" or just \"routes\") is done Django-style, using a centralized route\n  list.\n* `example_webapp2.py \u003chttps://github.com/pfalcon/picoweb/blob/master/example_webapp2.py\u003e`_ -\n  Like above, but uses ``app.route()`` decorator for route specification,\n  Flask-style.\n* `examples/ \u003chttps://github.com/pfalcon/picoweb/tree/master/examples\u003e`_ -\n  Additional examples for various features of picoweb. See comments in each\n  file for additional info. To run examples in this directory, you normally\n  would need to have picoweb installed (i.e. available in your ``MICROPYPATH``,\n  which defaults to ``~/.micropython/lib/``).\n* `notes-pico \u003chttps://github.com/pfalcon/notes-pico\u003e`_ - A more realistic\n  example webapp, ported from the Flask original.\n\n\nRunning under CPython (regressed)\n---------------------------------\n\nInitial versions of picoweb could run under CPython, but later it was\nfurther optimized for Pycopy, and ability to run under CPython\nregressed. It's still on TODO to fix it, instructions below tell how\nit used to work.\n\nAt least CPython 3.4.2 is required (for asyncio loop.create_task() support).\nTo run under CPython, uasyncio compatibility module for CPython is required\n(pycopy-cpython-uasyncio). This and other dependencies can be installed\nusing requirements-cpython.txt::\n\n    pip install -r requirements-cpython.txt\n\nReporting Issues\n----------------\n\nHere are a few guidelines to make feedback more productive:\n\n1. Please be considerate of the overall best practices and common pitfalls in\n   reporting issues, this document gives a good overview:\n   `How to Report Bugs Effectively \u003chttps://www.chiark.greenend.org.uk/~sgtatham/bugs.html\u003e`_.\n2. The reference platform for ``picoweb`` is the Unix port of Pycopy. All issues\n   reported must be validated against this version, to differentiate issues of\n   ``picoweb``/``uasyncio`` from the issues of your underlying platform.\n3. All reports must include version information of all components involved:\n   Pycopy, picoweb, uasyncio, uasyncio.core, any additional modules. Generally,\n   only the latest versions of the above are supported (this is what you get when\n   you install/reinstall components using the ``upip`` package manager). The\n   version information are thus first of all important for yourself, the issue\n   reporter, it allows you to double-check if you're using an outdated or\n   unsupported component.\n4. Feature requests: ``picoweb`` is by definition a pico-framework, and bound\n   to stay so. Feature requests are welcome, but please be considerate that\n   they may be outside the scope of core project. There's an easy way out\n   though: instead of putting more stuff *into* ``picoweb``, build new things\n   *on top* of it: via plugins, subclassing, additional modules etc. That's\n   how it was intended to be from the beginning!\n5. We would like to establish a dedicated QA team to support users of this\n   project better. If you would like to sponsor this effort, please let us\n   know.\n","funding_links":[],"categories":["Python","Networking"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfalcon%2Fpicoweb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpfalcon%2Fpicoweb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfalcon%2Fpicoweb/lists"}