# htagweb
[](https://github.com/manatlan/htagweb/actions/workflows/on_commit_do_all_unittests.yml)
<a href="https://pypi.org/project/htagweb/">
<img src="https://badge.fury.io/py/htagweb.svg?x" alt="Package version">
</a>
This module exposes htag's runners for the web. It's the official runners to expose
htag apps on the web, to handle multiple clients/session in the right way.
There are 3 runners:
- **AppServer** : the real one ;-)
- SimpleServer : for tests purposes
- HtagServer : (use SimpleServer) to browse/expose python/htag files in an UI.
## AppServer
It's the real runner to expose htag apps in a real production environment, and provide
all features, while maintaining tag instances like classical/desktop htag runners.
All htag apps are runned in its own process, and an user can only have an instance of an htag app. (so process are recreated when query params changes)
Process live as long as the server live (TODO: a TIMEOUT will be back soon)
**Features**
* based on [starlette](https://pypi.org/project/starlette/)
* use sessions (multiple ways to handle sessions (file, mem, etc ...))
* compatible with **uvloop** !!!
* compatible with multiple gunicorn/uvicorn/webworkers !!!
* compatible with [tag.update()](https://manatlan.github.io/htag/tag_update/)
* works on gnu/linux, ios or windows (from py3.7 to py3.11)!
* real starlette session available (in tag.state, and starlette request.session)
* compatible with oauth2 authent ( [authlib](https://pypi.org/project/Authlib/) )
* 'parano mode' (can aes encrypt all communications between client & server ... to avoid mitm'proxies on ws/http interactions)
* auto reconnect websocket
### Instanciate
Like a classical starlette'app :
```python
from htagweb import AppServer
from yourcode import YourApp # <-- your htag class
app=AppServer( YourApp, ... )
if __name__=="__main__":
app.run()
```
You can use the following parameters :
#### debug (bool)
- When False: (default) no debugging facilities
- When True: use starlette debugger.
#### ssl (bool)
- When False: (default) use "ws://" to connect the websocket
- When True: use "wss://" to connect the websocket
non-sense in http_only mode.
#### parano (bool)
- When False: (default) interactions between front/ui and back are in clear text (json), readable by a MITM.
- When True: interactions will be encrypted (less readable by a MITM, TODO: will try to use public/private keys in future)
this parameter is available on `app.handle(request, obj, ... parano=True|False ...)` too, to override defaults !
#### http_only (bool)
- When False: (default) it will use websocket interactions (between front/ui and back), with auto-reconnect feature.
- When True: it will use http interactions (between front/ui and back). But "tag.update" feature will not be available.
this parameter is available on `app.handle(request, obj, ... http_only=True|False ...)` too, to override defaults !
#### timeout_interaction (int)
It's the time (in seconds) for an interaction (or an initialization) for answering. If the timeout happens : the process/instance is killed.
By default, it's `60` seconds (1 minute).
#### timeout_inactivity (int)
It's the time (in seconds) of inactivities, after that : the process is detroyed.
By default, it's `0` (process lives as long as the server lives).
IMPORTANT : the "tag.update" feature doesn't reset the inactivity timeout !
#### session_factory (htagweb.sessions)
You can provide a Session Factory to handle the session in different modes.
- htagweb.sessions.MemDict (default) : sessions are stored in memory (renewed on reboot)
- htagweb.sessions.FileDict : sessions are stored in filesystem (renewed on reboot)
- htagweb.sessions.FilePersistentDict : make sessions persistent after reboot
## SimpleServer
It's a special runner for tests purposes. It doesn't provide all features (parano mode, ssl, session factory...).
Its main goal is to provide a simple runner during dev process, befause when you hit "F5" :
it will destroy/recreate the tag instances.
SimpleServer uses only websocket interactions (tag instances exist only during websocket connexions)
And it uses `htagweb.sessions.FileDict` as session manager.
## HtagServer
It's a special runner, which is mainly used by the `python3 -m htagweb`, to expose
current python/htag files in a browser. Its main goal is to test quickly the files
whose are in your folder, using an UI in your browser.
It uses the SimpleServer, so it does'nt provide all features (parano mode, ssl, session factory ...)
-------------------------------
## Roadmap / futur
- make it works with gunicorn again !!!!!!!!!!!!!!!!!!!!!!!!!
- better unittests !!!!!!!!!!!!!!!!
- better logging !!!!!!!!!!!!!!!!
- process lives : timeout !
- parano mode : use public/private keys ?
## Examples
A "hello world" could be :
```python
from htag import Tag
class App(Tag.div):
def init(self):
self+= "hello world"
from htagweb import AppServer
AppServer( App ).run()
```
or, with gunicorn (in a `server.py` file, as following):
```python
from htag import Tag
class App(Tag.div):
def init(self):
self+= "hello world"
from htagweb import AppServer
app=AppServer( App )
```
and run server :
```bash
gunicorn -w 4 -k uvicorn.workers.UvicornH11Worker -b localhost:8000 --preload server:app
```
See a more advanced example in [examples folder](https://github.com/manatlan/htagweb/tree/master/examples)
```bash
python3 examples/main.py
```
# Standalone module can act as server
The module can act as "development server", providing a way to quickly run any htag class in a browser. And let you browse current `*.py` files in a browser.
```bash
$ python3 -m htagweb
```
htagweb will look for an "index:App" (a file `index.py` (wich contains a htag.Tag subclass 'App').), and if it can't found it : expose its own htag app to let user browse pythons files in the browser (`/!\`)
or
```bash
$ python3 -m htagweb main:App
```
if you want to point the "/" (home path) to a file `main.py` (wich contains a htag.Tag subclass 'App').
Raw data
{
"_id": null,
"home_page": "https://github.com/manatlan/htagweb",
"name": "htagweb",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "htag,webserver",
"author": "manatlan",
"author_email": "manatlan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/dd/fa/74fdd28125c40e7d2967918f13c11a1fab3692a60686d88ddfaff1ad9781/htagweb-0.23.0.tar.gz",
"platform": null,
"description": "# htagweb\n\n[](https://github.com/manatlan/htagweb/actions/workflows/on_commit_do_all_unittests.yml)\n\n<a href=\"https://pypi.org/project/htagweb/\">\n <img src=\"https://badge.fury.io/py/htagweb.svg?x\" alt=\"Package version\">\n</a>\n\nThis module exposes htag's runners for the web. It's the official runners to expose\nhtag apps on the web, to handle multiple clients/session in the right way.\n\nThere are 3 runners:\n\n - **AppServer** : the real one ;-)\n - SimpleServer : for tests purposes\n - HtagServer : (use SimpleServer) to browse/expose python/htag files in an UI.\n\n## AppServer\n\nIt's the real runner to expose htag apps in a real production environment, and provide\nall features, while maintaining tag instances like classical/desktop htag runners.\n\nAll htag apps are runned in its own process, and an user can only have an instance of an htag app. (so process are recreated when query params changes)\nProcess live as long as the server live (TODO: a TIMEOUT will be back soon)\n\n**Features**\n\n * based on [starlette](https://pypi.org/project/starlette/)\n * use sessions (multiple ways to handle sessions (file, mem, etc ...))\n * compatible with **uvloop** !!!\n * compatible with multiple gunicorn/uvicorn/webworkers !!!\n * compatible with [tag.update()](https://manatlan.github.io/htag/tag_update/)\n * works on gnu/linux, ios or windows (from py3.7 to py3.11)!\n * real starlette session available (in tag.state, and starlette request.session)\n * compatible with oauth2 authent ( [authlib](https://pypi.org/project/Authlib/) )\n * 'parano mode' (can aes encrypt all communications between client & server ... to avoid mitm'proxies on ws/http interactions)\n * auto reconnect websocket\n\n### Instanciate\n\nLike a classical starlette'app :\n\n```python\nfrom htagweb import AppServer\nfrom yourcode import YourApp # <-- your htag class\n\napp=AppServer( YourApp, ... )\nif __name__==\"__main__\":\n app.run()\n```\n\nYou can use the following parameters :\n\n#### debug (bool)\n\n- When False: (default) no debugging facilities\n- When True: use starlette debugger.\n\n#### ssl (bool)\n\n- When False: (default) use \"ws://\" to connect the websocket\n- When True: use \"wss://\" to connect the websocket\n\nnon-sense in http_only mode.\n\n#### parano (bool)\n\n- When False: (default) interactions between front/ui and back are in clear text (json), readable by a MITM.\n- When True: interactions will be encrypted (less readable by a MITM, TODO: will try to use public/private keys in future)\n\nthis parameter is available on `app.handle(request, obj, ... parano=True|False ...)` too, to override defaults !\n\n#### http_only (bool)\n\n- When False: (default) it will use websocket interactions (between front/ui and back), with auto-reconnect feature.\n- When True: it will use http interactions (between front/ui and back). But \"tag.update\" feature will not be available.\n\nthis parameter is available on `app.handle(request, obj, ... http_only=True|False ...)` too, to override defaults !\n\n#### timeout_interaction (int)\n\nIt's the time (in seconds) for an interaction (or an initialization) for answering. If the timeout happens : the process/instance is killed.\nBy default, it's `60` seconds (1 minute).\n\n#### timeout_inactivity (int)\n\nIt's the time (in seconds) of inactivities, after that : the process is detroyed.\nBy default, it's `0` (process lives as long as the server lives).\n\nIMPORTANT : the \"tag.update\" feature doesn't reset the inactivity timeout !\n\n#### session_factory (htagweb.sessions)\n\nYou can provide a Session Factory to handle the session in different modes.\n\n- htagweb.sessions.MemDict (default) : sessions are stored in memory (renewed on reboot)\n- htagweb.sessions.FileDict : sessions are stored in filesystem (renewed on reboot)\n- htagweb.sessions.FilePersistentDict : make sessions persistent after reboot\n\n## SimpleServer\n\nIt's a special runner for tests purposes. It doesn't provide all features (parano mode, ssl, session factory...).\nIts main goal is to provide a simple runner during dev process, befause when you hit \"F5\" :\nit will destroy/recreate the tag instances.\n\nSimpleServer uses only websocket interactions (tag instances exist only during websocket connexions)\n\nAnd it uses `htagweb.sessions.FileDict` as session manager.\n\n## HtagServer\n\nIt's a special runner, which is mainly used by the `python3 -m htagweb`, to expose\ncurrent python/htag files in a browser. Its main goal is to test quickly the files\nwhose are in your folder, using an UI in your browser.\n\nIt uses the SimpleServer, so it does'nt provide all features (parano mode, ssl, session factory ...)\n\n-------------------------------\n\n## Roadmap / futur\n\n - make it works with gunicorn again !!!!!!!!!!!!!!!!!!!!!!!!!\n - better unittests !!!!!!!!!!!!!!!!\n - better logging !!!!!!!!!!!!!!!!\n - process lives : timeout !\n - parano mode : use public/private keys ?\n\n\n\n\n## Examples\n\nA \"hello world\" could be :\n\n```python\nfrom htag import Tag\n\nclass App(Tag.div):\n def init(self):\n self+= \"hello world\"\n\nfrom htagweb import AppServer\nAppServer( App ).run()\n```\n\nor, with gunicorn (in a `server.py` file, as following):\n\n```python\nfrom htag import Tag\n\nclass App(Tag.div):\n def init(self):\n self+= \"hello world\"\n\nfrom htagweb import AppServer\napp=AppServer( App )\n```\n\nand run server :\n\n```bash\ngunicorn -w 4 -k uvicorn.workers.UvicornH11Worker -b localhost:8000 --preload server:app\n```\n\nSee a more advanced example in [examples folder](https://github.com/manatlan/htagweb/tree/master/examples)\n\n```bash\npython3 examples/main.py\n```\n\n# Standalone module can act as server\n\nThe module can act as \"development server\", providing a way to quickly run any htag class in a browser. And let you browse current `*.py` files in a browser.\n\n```bash\n$ python3 -m htagweb\n```\nhtagweb will look for an \"index:App\" (a file `index.py` (wich contains a htag.Tag subclass 'App').), and if it can't found it : expose its own htag app to let user browse pythons files in the browser (`/!\\`)\n\nor\n\n```bash\n$ python3 -m htagweb main:App\n```\nif you want to point the \"/\" (home path) to a file `main.py` (wich contains a htag.Tag subclass 'App').\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "It's a robust webserver (http/ws) for hosting htag apps on the web (a process by user)",
"version": "0.23.0",
"project_urls": {
"Documentation": "https://github.com/manatlan/htagweb",
"Homepage": "https://github.com/manatlan/htagweb",
"Repository": "https://github.com/manatlan/htagweb"
},
"split_keywords": [
"htag",
"webserver"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9df1f1e6e490aa80d880108477a2a168363e68ae6a0b59385c8df81e4d39172b",
"md5": "b3d642238b945b08edd415cec9fd32ac",
"sha256": "f6eeb1f6d06070b6d908a1b12109393ca6760ef7c80cba41364ca74ca62c8de3"
},
"downloads": -1,
"filename": "htagweb-0.23.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b3d642238b945b08edd415cec9fd32ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 22098,
"upload_time": "2023-10-15T12:00:34",
"upload_time_iso_8601": "2023-10-15T12:00:34.892230Z",
"url": "https://files.pythonhosted.org/packages/9d/f1/f1e6e490aa80d880108477a2a168363e68ae6a0b59385c8df81e4d39172b/htagweb-0.23.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ddfa74fdd28125c40e7d2967918f13c11a1fab3692a60686d88ddfaff1ad9781",
"md5": "3094ddf708c3dffdfe8f2bfef3e47602",
"sha256": "0d97ec65549ac45088be104c39dcab415aaa9069688835b5c242bb261610256f"
},
"downloads": -1,
"filename": "htagweb-0.23.0.tar.gz",
"has_sig": false,
"md5_digest": "3094ddf708c3dffdfe8f2bfef3e47602",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 18878,
"upload_time": "2023-10-15T12:00:37",
"upload_time_iso_8601": "2023-10-15T12:00:37.119638Z",
"url": "https://files.pythonhosted.org/packages/dd/fa/74fdd28125c40e7d2967918f13c11a1fab3692a60686d88ddfaff1ad9781/htagweb-0.23.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-15 12:00:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "manatlan",
"github_project": "htagweb",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "htagweb"
}
JSON
