Metadata-Version: 2.4
Name: jdm-electron-flask
Version: 1.0.2
Summary: The Python backbone for jdm-electron-flask desktop apps
Author-email: JDM-Github <jdmaster888@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/JDM-Github/jdm-electron-flask
Project-URL: Repository, https://github.com/JDM-Github/jdm-electron-flask
Project-URL: Issues, https://github.com/JDM-Github/jdm-electron-flask/issues
Keywords: flask,electron,desktop,socketio,jdm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: flask>=3.0.0
Requires-Dist: flask-cors>=4.0.0
Requires-Dist: flask-socketio>=5.3.0
Requires-Dist: simple-websocket>=1.0.0

# jdm-electron-flask (Python)

> The Python backbone for [`jdm-electron-flask`](https://github.com/JDM-Github/jdm-electron-flask) desktop apps.

This package ships inside every project scaffolded by the `jdm-cli electron-flask` plugin. It provides the app factory, dynamic API registration, SocketIO setup, and environment-aware logging — so you build features, not boilerplate.

---

## Installation

You don't install this manually. It's included in the scaffolded `requirements.txt`:

```
jdm-electron-flask==1.0.0
```

If you need it standalone:

```bash
pip install jdm-electron-flask
```

---

## What it provides

### `create_app`
The Flask app factory. Handles config loading, SocketIO init, blueprint auto-discovery, and the React SPA catch-all route.

```python
# run.py
from jdm_electron_flask import create_app, get_socketio

app = create_app()
socketio = get_socketio()

if __name__ == "__main__":
    socketio.run(app, host="0.0.0.0", port=5000, debug=True)
```

### `JDMBlueprint`
Extended Blueprint with built-in response helpers.

```python
from jdm_electron_flask import JDMBlueprint

health_bp = JDMBlueprint("health", __name__)

@health_bp.route("/health")
def health():
    return health_bp.success({"status": "ok"})
```

### `JDMEvents`
Base class for organizing socket event handlers.

```python
from jdm_electron_flask import JDMEvents

class ConnectEvents(JDMEvents):
    def register(self):
        @self.socketio.on("connect")
        def on_connect():
            self.on_connect()

        @self.socketio.on("ping_server")
        def on_ping(data):
            self.emit("pong_client", {"echo": data})

ConnectEvents().register()
```

### `Printer`
Environment-aware logger. Prints in development, writes to `logs/<date>.log` in production/deployed.

```python
from jdm_electron_flask import Printer

Printer.success("Blueprint registered")
Printer.warn("Something is off")
Printer.error("Something broke")
Printer.info("Just FYI")
```

### Response helpers

```python
from jdm_electron_flask import success, error, paginate

return success({"user": "JDM"})
return error("Not found", status=404)
return paginate(items, total=100, page=1, per_page=10)
```

### Validators

```python
from jdm_electron_flask import validate_fields

valid, msg, data = validate_fields(["name", "email"])
if not valid:
    return error(msg)
```

---

## Dynamic API registration

Routes are controlled by `config/api.json`:

```json
{
    "health": {
        "link": "/api",
        "masterEnabled": true
    },
    "users": {
        "link": "/api/users",
        "masterEnabled": true,
        "disabledOnProduction": false,
        "disabledOnDeployed": false
    }
}
```

Adding a new route:
1. Add entry to `config/api.json`
2. Create `app/api/users.py` with a `users_bp` blueprint

That's it. No touching `__init__.py` ever again.

---

## Environment modes

| `FLASK_ENV` | Behavior |
|---|---|
| `development` | Debug on, console logging, all routes enabled |
| `production` | Debug off, file logging, respects `disabledOnProduction` |
| `deployed` | Debug off, file logging, respects `disabledOnDeployed` |

---

## Companion

This package is the Python half of the `jdm-electron-flask` ecosystem:

| Package | Role |
|---|---|
| [`jdm-electron-flask`](https://www.npmjs.com/package/jdm-electron-flask) (npm) | CLI plugin — scaffold, build, compile |
| `jdm-electron-flask` (PyPI) | Backend library — app factory, blueprints, sockets |

---

## License

MIT © [JDM-Github](https://github.com/JDM-Github)
