# JsWeb 🚀
[](https://github.com/Jones-peter)
[](https://www.instagram.com/jones_peter__/)
[](https://www.linkedin.com/in/jones-peter-121157221/)
[](https://jonespeter.site)
A lightweight and modern Python web framework designed for speed, simplicity, and a great developer experience.
JsWeb provides the essential tools to build web applications and APIs quickly, without getting in your way. It's perfect for beginners learning web development and for experts who need to build and deploy fast.
---
## ✨ Features
- **Simple Routing:** Expressive and easy-to-use decorator-based routing.
- **Request & Response Objects:** Intuitive access to query parameters, form data, and response helpers.
- **Jinja2 Templating:** Includes built-in support for the powerful Jinja2 templating engine.
- **Custom Template Filters:** Easily extend Jinja2 with your own custom filters.
- **Lightweight & Fast:** No unnecessary bloat. JsWeb is built to be quick and efficient.
- **Built-in Dev Server:** A simple development server with auto-reload capabilities.
- **Helpful CLI:** A command-line interface to create new projects and manage your application.
---
## 📦 Installation
Get started with JsWeb by installing it from PyPI using `pip`.
```bash
pip install jsweb
```
---
## 🚀 Getting Started: A Complete Example
This guide will walk you through creating a multi-feature web application in just a few minutes.
### 1. Create a New Project
Use the `jsweb` CLI to generate a new project structure.
```bash
jsweb new my_jsweb_app
cd my_jsweb_app
```
This creates a directory with a basic `app.py`, a `templates` folder, and a `static` folder.
### 2. Update Your `app.py`
Replace the contents of `my_jsweb_app/app.py` with the following code. This example demonstrates routing, forms, query parameters, and custom template filters.
```python
# my_jsweb_app/app.py
from jsweb import JsWebApp, run, render, __VERSION__, html
# Initialize the application
app = JsWebApp()
# Define a custom filter for use in Jinja2 templates
@app.filter("shout")
def shout(text):
"""Converts text to uppercase and adds exclamation marks."""
return text.upper() + "!!!"
# Route for the home page
@app.route("/")
def home(req):
"""Renders a welcome page, passing context to the template."""
# Example dictionary to pass to the template
sample_data = {"one": "First Item", "two": "Second Item", "three": "Third Item"}
# Get a query parameter from the URL (e.g., /?name=World)
query_name = req.query.get("name", "Guest")
# Data to be passed into the template
context = {
"name": query_name,
"version": __VERSION__,
"items": sample_data
}
return render("welcome.html", context)
# Route to display a simple HTML form
@app.route("/form")
def form(req):
"""Returns a raw HTML response with a form."""
return html('''
<h1>Submit Your Name</h1>
<p><a href='/search?q=hello'>Test Query Params</a></p>
<form method="POST" action="/submit">
<input name="name" placeholder="Your name" />
<button type="submit">Submit</button>
</form>
''')
# Route to handle the form submission via POST
@app.route("/submit", methods=["POST"])
def submit(req):
"""Processes POST data from a form."""
name = req.form.get("name", "Anonymous")
return html(f"<h2>👋 Hello, {name}</h2>")
# Route to handle search queries from the URL
@app.route("/search")
def search(req):
"""Processes GET data from query parameters."""
query = req.query.get("q", "")
return html(f"<h2>🔍 You searched for: {query}</h2>")
# Standard entry point to run the app
if __name__ == "__main__":
run(app)
```
### 3. Create the Template
Create a file named `welcome.html` inside the `templates` folder and add the following content. This template will use the data and custom filter we defined in `app.py`.
```html
<!-- my_jsweb_app/templates/welcome.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Welcome to JsWeb</title>
<style>body { font-family: sans-serif; line-height: 1.6; padding: 2em; }</style>
</head>
<body>
<h1>Hello, {{ name | shout }}</h1>
<p>You are running JsWeb version <strong>{{ version }}</strong>.</p>
<h3>Here is your data:</h3>
<ul>
{% for key, value in items.items() %}
<li><strong>{{ key }}:</strong> {{ value }}</li>
{% endfor %}
</ul>
</body>
</html>
```
### 4. Run the Development Server
Now, run the application from your terminal:
```bash
jsweb run
```
The server will start on **http://127.0.0.1:8000**.
You can now test all the features:
- **Home Page:** Open [http://127.0.0.1:8000](http://127.0.0.1:8000)
- **With a Query Parameter:** Open [http://127.0.0.1:8000/?name=Alice](http://127.0.0.1:8000/?name=Alice)
- **Form Page:** Open [http://127.0.0.1:8000/form](http://127.0.0.1:8000/form) to submit your name.
- **Search Page:** Open [http://127.0.0.1:8000/search?q=python](http://127.0.0.1:8000/search?q=python)
## 📚 API Guide
### Application & Routing
Your application is an instance of `JsWebApp`. Routes are defined with the `@app.route()` decorator.
```python
from jsweb import JsWebApp
app = JsWebApp()
@app.route("/path")
def handler(req):
# ...
pass
```
By default, routes handle `GET` requests. To handle other methods, use the `methods` argument:
```python
@app.route("/submit", methods=["POST"])
def submit(req):
# This function only runs for POST requests
pass
```
### The Request Object (`req`)
Every route handler receives a `req` object, which gives you access to incoming request data.
- `req.query`: A dictionary-like object for URL query parameters (the part after `?`).
```python
# For a URL like /search?q=hello
query = req.query.get("q", "") # Returns "hello"
```
- `req.form`: A dictionary-like object for data submitted from an HTML form via `POST`.
```python
# For a form with <input name="name">
name = req.form.get("name", "Anonymous")
```
### Creating Responses
You can return a response in several ways:
1. **Render a Template:** Use the `render()` function to process a Jinja2 template. The second argument is a context dictionary, which makes variables available in the template.
```python
from jsweb import render
@app.route("/")
def home(req):
return render("template.html", {"name": "World"})
```
2. **Return Raw HTML:** Use the `html()` helper to quickly return a string as an HTML response.
```python
from jsweb import html
@app.route("/simple")
def simple(req):
return html("<h1>This is a heading</h1>")
```
### Custom Template Filters
You can easily add your own Jinja2 filters with the `@app.filter()` decorator. The function name becomes the filter name.
```python
@app.filter("shout")
def shout(text):
return text.upper() + "!!!"
# In a template: {{ my_variable | shout }}
```
## 💻 CLI Usage
- `jsweb new <project_name>`
- Creates a new project directory with a starter template.
- `jsweb run`
- Starts the development server in the current directory.
- `--host <ip>`: Sets the host to bind to (default: `127.0.0.1`).
- `--port <number>`: Sets the port to use (default: `8000`).
- `jsweb --version`
- Displays the installed version of JsWeb.
- `jsweb run --host 0.0.0.0` : for run server on your IP address on LAN
---
## Contributing 🤝💗
[](CONTRIBUTING.md)
## Reporting Bugs 🪲
If you encounter a bug, please open an issue on GitHub. Please include the following:
* Your version of jsweb.
* A clear and concise description of the bug.
* Steps to reproduce the behavior.
* A code snippet demonstrating the issue.
## Suggesting Enhancements 💭📈
If you have an idea for a new feature, feel free to open an issue to discuss it. Please provide:
* A clear description of the feature and the problem it solves.
* Any sample code or use-cases you might have in mind.
## License 🔒
This project is licensed under the MIT License.
## Contact 📧
For any questions or support, please contact [jonespetersoftware@gmail.com].
Raw data
{
"_id": null,
"home_page": "https://github.com/Jones-peter/jsweb",
"name": "jsweb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "Framework, Web, Python, JsWeb, Web Framework, WSGI, Web Server",
"author": "Jones Peter",
"author_email": "jonespetersoftware@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5b/4e/ee335c28aa764d4dda2d8e1bc2d313c75dd9365bb86114d763901b754a96/jsweb-0.1.0.tar.gz",
"platform": null,
"description": "# JsWeb \ud83d\ude80\n\n\n\n\n\n[](https://github.com/Jones-peter)\n[](https://www.instagram.com/jones_peter__/)\n[](https://www.linkedin.com/in/jones-peter-121157221/)\n[](https://jonespeter.site)\n\nA lightweight and modern Python web framework designed for speed, simplicity, and a great developer experience.\n\nJsWeb provides the essential tools to build web applications and APIs quickly, without getting in your way. It's perfect for beginners learning web development and for experts who need to build and deploy fast.\n\n---\n\n## \u2728 Features\n\n- **Simple Routing:** Expressive and easy-to-use decorator-based routing.\n- **Request & Response Objects:** Intuitive access to query parameters, form data, and response helpers.\n- **Jinja2 Templating:** Includes built-in support for the powerful Jinja2 templating engine.\n- **Custom Template Filters:** Easily extend Jinja2 with your own custom filters.\n- **Lightweight & Fast:** No unnecessary bloat. JsWeb is built to be quick and efficient.\n- **Built-in Dev Server:** A simple development server with auto-reload capabilities.\n- **Helpful CLI:** A command-line interface to create new projects and manage your application.\n---\n## \ud83d\udce6 Installation\n\nGet started with JsWeb by installing it from PyPI using `pip`.\n\n```bash\npip install jsweb\n```\n---\n## \ud83d\ude80 Getting Started: A Complete Example\n\nThis guide will walk you through creating a multi-feature web application in just a few minutes.\n\n### 1. Create a New Project\n\nUse the `jsweb` CLI to generate a new project structure.\n\n```bash\njsweb new my_jsweb_app\ncd my_jsweb_app\n```\n\nThis creates a directory with a basic `app.py`, a `templates` folder, and a `static` folder.\n\n### 2. Update Your `app.py`\n\nReplace the contents of `my_jsweb_app/app.py` with the following code. This example demonstrates routing, forms, query parameters, and custom template filters.\n\n```python\n# my_jsweb_app/app.py\n\nfrom jsweb import JsWebApp, run, render, __VERSION__, html\n\n# Initialize the application\napp = JsWebApp()\n\n\n# Define a custom filter for use in Jinja2 templates\n@app.filter(\"shout\")\ndef shout(text):\n \"\"\"Converts text to uppercase and adds exclamation marks.\"\"\"\n return text.upper() + \"!!!\"\n\n\n# Route for the home page\n@app.route(\"/\")\ndef home(req):\n \"\"\"Renders a welcome page, passing context to the template.\"\"\"\n # Example dictionary to pass to the template\n sample_data = {\"one\": \"First Item\", \"two\": \"Second Item\", \"three\": \"Third Item\"}\n \n # Get a query parameter from the URL (e.g., /?name=World)\n query_name = req.query.get(\"name\", \"Guest\")\n \n # Data to be passed into the template\n context = {\n \"name\": query_name,\n \"version\": __VERSION__,\n \"items\": sample_data\n }\n return render(\"welcome.html\", context)\n\n\n# Route to display a simple HTML form\n@app.route(\"/form\")\ndef form(req):\n \"\"\"Returns a raw HTML response with a form.\"\"\"\n return html('''\n <h1>Submit Your Name</h1>\n <p><a href='/search?q=hello'>Test Query Params</a></p>\n <form method=\"POST\" action=\"/submit\">\n <input name=\"name\" placeholder=\"Your name\" />\n <button type=\"submit\">Submit</button>\n </form>\n ''')\n\n\n# Route to handle the form submission via POST\n@app.route(\"/submit\", methods=[\"POST\"])\ndef submit(req):\n \"\"\"Processes POST data from a form.\"\"\"\n name = req.form.get(\"name\", \"Anonymous\")\n return html(f\"<h2>\ud83d\udc4b Hello, {name}</h2>\")\n\n\n# Route to handle search queries from the URL\n@app.route(\"/search\")\ndef search(req):\n \"\"\"Processes GET data from query parameters.\"\"\"\n query = req.query.get(\"q\", \"\")\n return html(f\"<h2>\ud83d\udd0d You searched for: {query}</h2>\")\n\n\n# Standard entry point to run the app\nif __name__ == \"__main__\":\n run(app)\n```\n\n### 3. Create the Template\n\nCreate a file named `welcome.html` inside the `templates` folder and add the following content. This template will use the data and custom filter we defined in `app.py`.\n\n```html\n<!-- my_jsweb_app/templates/welcome.html -->\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <meta charset=\"UTF-8\">\n <title>Welcome to JsWeb</title>\n <style>body { font-family: sans-serif; line-height: 1.6; padding: 2em; }</style>\n</head>\n<body>\n <h1>Hello, {{ name | shout }}</h1>\n <p>You are running JsWeb version <strong>{{ version }}</strong>.</p>\n \n <h3>Here is your data:</h3>\n <ul>\n {% for key, value in items.items() %}\n <li><strong>{{ key }}:</strong> {{ value }}</li>\n {% endfor %}\n </ul>\n</body>\n</html>\n```\n\n### 4. Run the Development Server\n\nNow, run the application from your terminal:\n\n```bash\njsweb run\n```\n\nThe server will start on **http://127.0.0.1:8000**.\n\nYou can now test all the features:\n- **Home Page:** Open [http://127.0.0.1:8000](http://127.0.0.1:8000)\n- **With a Query Parameter:** Open [http://127.0.0.1:8000/?name=Alice](http://127.0.0.1:8000/?name=Alice)\n- **Form Page:** Open [http://127.0.0.1:8000/form](http://127.0.0.1:8000/form) to submit your name.\n- **Search Page:** Open [http://127.0.0.1:8000/search?q=python](http://127.0.0.1:8000/search?q=python)\n\n## \ud83d\udcda API Guide\n\n### Application & Routing\n\nYour application is an instance of `JsWebApp`. Routes are defined with the `@app.route()` decorator.\n\n```python\nfrom jsweb import JsWebApp\n\napp = JsWebApp()\n\n@app.route(\"/path\")\ndef handler(req):\n # ...\n pass\n```\n\nBy default, routes handle `GET` requests. To handle other methods, use the `methods` argument:\n\n```python\n@app.route(\"/submit\", methods=[\"POST\"])\ndef submit(req):\n # This function only runs for POST requests\n pass\n```\n\n### The Request Object (`req`)\n\nEvery route handler receives a `req` object, which gives you access to incoming request data.\n\n- `req.query`: A dictionary-like object for URL query parameters (the part after `?`).\n ```python\n # For a URL like /search?q=hello\n query = req.query.get(\"q\", \"\") # Returns \"hello\"\n ```\n- `req.form`: A dictionary-like object for data submitted from an HTML form via `POST`.\n ```python\n # For a form with <input name=\"name\">\n name = req.form.get(\"name\", \"Anonymous\")\n ```\n\n### Creating Responses\n\nYou can return a response in several ways:\n\n1. **Render a Template:** Use the `render()` function to process a Jinja2 template. The second argument is a context dictionary, which makes variables available in the template.\n ```python\n from jsweb import render\n\n @app.route(\"/\")\n def home(req):\n return render(\"template.html\", {\"name\": \"World\"})\n ```\n\n2. **Return Raw HTML:** Use the `html()` helper to quickly return a string as an HTML response.\n ```python\n from jsweb import html\n\n @app.route(\"/simple\")\n def simple(req):\n return html(\"<h1>This is a heading</h1>\")\n ```\n\n### Custom Template Filters\n\nYou can easily add your own Jinja2 filters with the `@app.filter()` decorator. The function name becomes the filter name.\n\n```python\n@app.filter(\"shout\")\ndef shout(text):\n return text.upper() + \"!!!\"\n\n# In a template: {{ my_variable | shout }}\n```\n\n## \ud83d\udcbb CLI Usage\n\n- `jsweb new <project_name>`\n - Creates a new project directory with a starter template.\n- `jsweb run`\n - Starts the development server in the current directory.\n - `--host <ip>`: Sets the host to bind to (default: `127.0.0.1`).\n - `--port <number>`: Sets the port to use (default: `8000`).\n- `jsweb --version`\n - Displays the installed version of JsWeb.\n- `jsweb run --host 0.0.0.0` : for run server on your IP address on LAN\n\n---\n## Contributing \ud83e\udd1d\ud83d\udc97\n[](CONTRIBUTING.md)\n\n\n## Reporting Bugs \ud83e\udeb2\n\nIf you encounter a bug, please open an issue on GitHub. Please include the following:\n* Your version of jsweb.\n* A clear and concise description of the bug.\n* Steps to reproduce the behavior.\n* A code snippet demonstrating the issue.\n\n## Suggesting Enhancements \ud83d\udcad\ud83d\udcc8\n\nIf you have an idea for a new feature, feel free to open an issue to discuss it. Please provide:\n* A clear description of the feature and the problem it solves.\n* Any sample code or use-cases you might have in mind.\n\n## License \ud83d\udd12\n\nThis project is licensed under the MIT License.\n\n## Contact \ud83d\udce7\n\nFor any questions or support, please contact [jonespetersoftware@gmail.com].\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "JsWeb - A lightweight and modern Python web framework designed for speed and simplicity.",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/Jones-peter/jsweb/issues",
"Homepage": "https://github.com/Jones-peter/jsweb"
},
"split_keywords": [
"framework",
" web",
" python",
" jsweb",
" web framework",
" wsgi",
" web server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "759c8c55498167b4e7328f0b2bb39b5a38e2448b9dcc2ecef9cc93ac08ac91f0",
"md5": "0d10e21d1067f1fdd97c932e8c166c8b",
"sha256": "5d8ecf3f18b3e770e54d94f3567f004d31cefc67f37c2b1eceb666bca3dc99d2"
},
"downloads": -1,
"filename": "jsweb-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0d10e21d1067f1fdd97c932e8c166c8b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 14203,
"upload_time": "2025-07-10T11:36:32",
"upload_time_iso_8601": "2025-07-10T11:36:32.832254Z",
"url": "https://files.pythonhosted.org/packages/75/9c/8c55498167b4e7328f0b2bb39b5a38e2448b9dcc2ecef9cc93ac08ac91f0/jsweb-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5b4eee335c28aa764d4dda2d8e1bc2d313c75dd9365bb86114d763901b754a96",
"md5": "834fdc707f67ddc19a509eb687f5a7dc",
"sha256": "0b006db30004f0f5bc9a869fc0e0722434cd876bca87082bae6fd3b22dea2b53"
},
"downloads": -1,
"filename": "jsweb-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "834fdc707f67ddc19a509eb687f5a7dc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15831,
"upload_time": "2025-07-10T11:36:34",
"upload_time_iso_8601": "2025-07-10T11:36:34.248410Z",
"url": "https://files.pythonhosted.org/packages/5b/4e/ee335c28aa764d4dda2d8e1bc2d313c75dd9365bb86114d763901b754a96/jsweb-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 11:36:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Jones-peter",
"github_project": "jsweb",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jsweb"
}
JSON
