Metadata-Version: 2.4
Name: nexfpy
Version: 1.0.0
Summary: A lightweight, batteries-included Python web framework.
Author-email: attendance1978-wq <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/attendance1978-wq/NexusFlowpy
Project-URL: Repository, https://github.com/attendance1978-wq/NexusFlowpy.git
Project-URL: Issues, https://github.com/attendance1978-wq/NexusFlowpy/issues
Project-URL: Changelog, https://github.com/attendance1978-wq/NexusFlowpy/releases
Keywords: web,framework,wsgi,http
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: templating
Requires-Dist: jinja2>=3.0; extra == "templating"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: jinja2>=3.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# NexusFlow

<p align="center">
  <img src="image.png" alt="NexusFlow Banner" width="800">
</p>

A lightweight, batteries-included Python web framework — the simplicity
of Flask with a bit more structure out of the box. **Zero required
dependencies.**

<p align="center">
  <img src="https://img.shields.io/badge/python-3.7+-blue.svg" alt="Python Version">
  <img src="https://img.shields.io/badge/dependencies-none-brightgreen.svg" alt="Zero Dependencies">
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT">
  <img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Test Coverage">
</p>

📖 **Full documentation:** see the [`docs/`](docs/README.md) folder for
complete guides on routing, requests/responses, middleware, templating,
error handling, static files, the CLI, testing, deployment, and a full
API reference. This README is a quick overview — `docs/` has the
complete picture.

## Features

- Flask-style routing with typed converters: `<int:id>`, `<float:x>`, `<slug:s>`, `<uuid:u>`, `<path:p>`
- `Request` / `Response` objects with JSON, form, multipart file upload, query string, and cookie handling
- Middleware pipeline (`app.use(...)`) — request/response wrapping, logging, CORS, security headers included
- `before_request` / `after_request` hooks and custom `errorhandler`s
- Automatic response coercion: return a string, dict, tuple, or `Response` — dicts become JSON automatically
- Built-in templating: uses **Jinja2** automatically if installed, otherwise falls back to a small
  dependency-free template engine (`{{ var }}`, `{% if %}`, `{% for %}`) so the framework works with
  nothing installed at all
- Static file serving for development
- Zero-dependency development server with optional auto-reload (`app.run(debug=True)`)
- `nexusflow startproject myapp` CLI scaffolding tool
- Full WSGI compatibility — deploy with gunicorn, uWSGI, or any WSGI host

## Installation

```bash
pip install -e .              # from this directory, editable install
pip install -e ".[templating]"  # + Jinja2 for full templating support
pip install -e ".[dev]"         # + pytest, for running the test suite
```

## Quick start

```python
# app.py
from nexusflow import NexusFlow, Response

app = NexusFlow(__name__)

@app.route("/")
def index(request):
    return "Hello, NexusFlow!"

@app.get("/users/<int:user_id>")
def get_user(request, user_id):
    return {"id": user_id, "name": "Ada"}  # auto-coerced to JSON

@app.post("/users")
def create_user(request):
    data = request.json()
    return {"created": data}, 201

if __name__ == "__main__":
    app.run(debug=True)
```

```bash
python app.py
# -> NexusFlow running on http://127.0.0.1:8000
```

## Scaffold a new project

```bash
python -m nexusflow.cli startproject myapp
cd myapp
python app.py
```

(Once installed via pip, this is also available as the `nexusflow` command:
`nexusflow startproject myapp`.)

## Routing

```python
@app.get("/posts/<slug>")
@app.post("/posts")
@app.route("/files/<path:filepath>", methods=["GET"])
def handler(request, **params): ...

app.url_for("route_name", id=5)  # reverse routing
```

## Middleware

```python
from nexusflow.middleware import Middleware, LoggingMiddleware, CORSMiddleware

class TimingMiddleware(Middleware):
    def handle(self, request, call_next):
        response = call_next(request)
        response.headers["X-Powered-By"] = "NexusFlow"
        return response

app.use(LoggingMiddleware())
app.use(CORSMiddleware(allow_origin="*"))
app.use(TimingMiddleware())
```

## Templating

Put templates in `templates/` (configurable via `template_folder=`) and:

```python
@app.get("/")
def index(request):
    return app.render_template("index.html", title="Home")
```

Install Jinja2 (`pip install jinja2`) for full inheritance/filters/macros support.
Without it, NexusFlow's built-in engine still handles variables, `if`/`else`, and `for` loops.

## Error handling

```python
from nexusflow import NotFound

@app.get("/items/<int:item_id>")
def get_item(request, item_id):
    if item_id not in DB:
        raise NotFound(f"Item {item_id} not found")
    return DB[item_id]

@app.errorhandler(404)
def not_found(request, exc):
    return {"error": exc.message}, 404
```

## Project layout

```
nexusflow/            # the framework package
  app.py               # NexusFlow application class (WSGI entrypoint)
  routing.py           # URL routing + converters
  http/
    request.py          # Request object
    response.py          # Response / JSONResponse / HTMLResponse / RedirectResponse
  middleware.py         # Middleware base + built-ins
  templating.py         # Jinja2 wrapper + dependency-free fallback engine
  static.py             # Dev static file serving
  server.py             # wsgiref-based dev server with auto-reload
  cli.py                # `nexusflow startproject` / `runserver`
examples/hello_world/   # runnable example app (pages + JSON API)
tests/                  # pytest suite (32 tests, routing/app/request/templating)
docs/                  # complete documentation (see docs/README.md)
CHANGELOG.md           # release history
```

## Documentation

| Guide | Covers |
|---|---|
| [Getting Started](docs/getting-started.md) | Install, first app, project layout |
| [Routing](docs/routing.md) | Path patterns, converters, methods, reverse URLs |
| [Requests & Responses](docs/requests-responses.md) | Full `Request`/`Response` API |
| [Middleware](docs/middleware.md) | Pipeline, built-ins, writing your own |
| [Templating](docs/templating.md) | Jinja2 mode + built-in fallback engine |
| [Error Handling](docs/error-handling.md) | Exceptions, status codes, custom handlers |
| [Static Files](docs/static-files.md) | Serving assets in development |
| [CLI Reference](docs/cli.md) | `startproject` / `runserver` |
| [Testing](docs/testing.md) | In-process `TestClient`, writing app tests |
| [Deployment](docs/deployment.md) | gunicorn/uWSGI/mod_wsgi, production checklist |
| [API Reference](docs/api-reference.md) | Every public class, function, method |
| [FAQ & Troubleshooting](docs/faq.md) | Common issues and fixes |

## Running tests

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## Deploying to production

NexusFlow apps are standard WSGI apps — the `app` object itself is the WSGI callable:

```bash
gunicorn app:app --workers 4 --bind 0.0.0.0:8000
```

The built-in dev server (`app.run()`) is for local development only.

## License

MIT
