flask-artisan 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- flask_artisan-0.1.0/LICENSE +21 -0
- flask_artisan-0.1.0/PKG-INFO +385 -0
- flask_artisan-0.1.0/README.md +347 -0
- flask_artisan-0.1.0/pyproject.toml +75 -0
- flask_artisan-0.1.0/setup.cfg +4 -0
- flask_artisan-0.1.0/src/flask_artisan/__init__.py +36 -0
- flask_artisan-0.1.0/src/flask_artisan/application.py +120 -0
- flask_artisan-0.1.0/src/flask_artisan/auth/__init__.py +18 -0
- flask_artisan-0.1.0/src/flask_artisan/auth/authenticatable.py +50 -0
- flask_artisan-0.1.0/src/flask_artisan/auth/manager.py +173 -0
- flask_artisan-0.1.0/src/flask_artisan/auth/middleware.py +35 -0
- flask_artisan-0.1.0/src/flask_artisan/auth/provider.py +16 -0
- flask_artisan-0.1.0/src/flask_artisan/auth/tokens.py +66 -0
- flask_artisan-0.1.0/src/flask_artisan/cli.py +32 -0
- flask_artisan-0.1.0/src/flask_artisan/config.py +68 -0
- flask_artisan-0.1.0/src/flask_artisan/console.py +233 -0
- flask_artisan-0.1.0/src/flask_artisan/container.py +153 -0
- flask_artisan-0.1.0/src/flask_artisan/database/__init__.py +29 -0
- flask_artisan-0.1.0/src/flask_artisan/database/alembic_env/env.py +21 -0
- flask_artisan-0.1.0/src/flask_artisan/database/alembic_env/script.py.mako +28 -0
- flask_artisan-0.1.0/src/flask_artisan/database/connection.py +39 -0
- flask_artisan-0.1.0/src/flask_artisan/database/json.py +13 -0
- flask_artisan-0.1.0/src/flask_artisan/database/manager.py +109 -0
- flask_artisan-0.1.0/src/flask_artisan/database/migrations.py +109 -0
- flask_artisan-0.1.0/src/flask_artisan/database/model.py +354 -0
- flask_artisan-0.1.0/src/flask_artisan/database/provider.py +23 -0
- flask_artisan-0.1.0/src/flask_artisan/database/query.py +166 -0
- flask_artisan-0.1.0/src/flask_artisan/database/relations.py +95 -0
- flask_artisan-0.1.0/src/flask_artisan/env.py +35 -0
- flask_artisan-0.1.0/src/flask_artisan/facades.py +38 -0
- flask_artisan-0.1.0/src/flask_artisan/helpers.py +18 -0
- flask_artisan-0.1.0/src/flask_artisan/middleware.py +39 -0
- flask_artisan-0.1.0/src/flask_artisan/providers.py +19 -0
- flask_artisan-0.1.0/src/flask_artisan/route_provider.py +27 -0
- flask_artisan-0.1.0/src/flask_artisan/routing.py +277 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/.env.example +16 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/.gitignore +5 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/__init__.py +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/console/__init__.py +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/console/commands/__init__.py +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/http/__init__.py +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/http/controllers/__init__.py +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/http/controllers/auth_controller.py +21 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/http/controllers/home_controller.py +6 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/http/kernel.py +18 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/http/middleware/__init__.py +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/models/__init__.py +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/models/user.py +14 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/providers/__init__.py +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/providers/app_service_provider.py +11 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/app/providers/route_service_provider.py +7 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/bootstrap/__init__.py +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/bootstrap/app.py +5 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/config/app.py +20 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/config/auth.py +13 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/config/database.py +40 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/config/flask.py +6 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/database/.gitignore +2 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/database/migrations/.gitkeep +0 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/pytest.ini +3 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/requirements.txt +2 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/routes/api.py +19 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/routes/web.py +5 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/tests/test_app.py +5 -0
- flask_artisan-0.1.0/src/flask_artisan/skeleton/wsgi.py +1 -0
- flask_artisan-0.1.0/src/flask_artisan/stubs/command.stub +7 -0
- flask_artisan-0.1.0/src/flask_artisan/stubs/controller.resource.stub +23 -0
- flask_artisan-0.1.0/src/flask_artisan/stubs/controller.stub +3 -0
- flask_artisan-0.1.0/src/flask_artisan/stubs/middleware.stub +9 -0
- flask_artisan-0.1.0/src/flask_artisan/stubs/model.stub +8 -0
- flask_artisan-0.1.0/src/flask_artisan/stubs/provider.stub +11 -0
- flask_artisan-0.1.0/src/flask_artisan.egg-info/PKG-INFO +385 -0
- flask_artisan-0.1.0/src/flask_artisan.egg-info/SOURCES.txt +89 -0
- flask_artisan-0.1.0/src/flask_artisan.egg-info/dependency_links.txt +1 -0
- flask_artisan-0.1.0/src/flask_artisan.egg-info/entry_points.txt +2 -0
- flask_artisan-0.1.0/src/flask_artisan.egg-info/requires.txt +14 -0
- flask_artisan-0.1.0/src/flask_artisan.egg-info/top_level.txt +1 -0
- flask_artisan-0.1.0/tests/test_application.py +156 -0
- flask_artisan-0.1.0/tests/test_cli.py +200 -0
- flask_artisan-0.1.0/tests/test_config.py +48 -0
- flask_artisan-0.1.0/tests/test_console.py +216 -0
- flask_artisan-0.1.0/tests/test_console_discovery.py +134 -0
- flask_artisan-0.1.0/tests/test_container.py +233 -0
- flask_artisan-0.1.0/tests/test_env.py +43 -0
- flask_artisan-0.1.0/tests/test_facades.py +62 -0
- flask_artisan-0.1.0/tests/test_helpers.py +28 -0
- flask_artisan-0.1.0/tests/test_middleware.py +187 -0
- flask_artisan-0.1.0/tests/test_package.py +13 -0
- flask_artisan-0.1.0/tests/test_route_list.py +90 -0
- flask_artisan-0.1.0/tests/test_route_provider.py +103 -0
- flask_artisan-0.1.0/tests/test_routing.py +316 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 [Pierre AHOBLE]
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,385 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: flask-artisan
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Les conventions de Laravel pour Flask : conteneur, routage, ORM façon Eloquent, auth et commandes make:*.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/ahoblepierre/flask-artisan
|
|
7
|
+
Project-URL: Issues, https://github.com/ahoblepierre/flask-artisan/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/ahoblepierre/flask-artisan/blob/main/CHANGELOG.md
|
|
9
|
+
Keywords: flask,laravel,framework,orm,artisan
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Web Environment
|
|
12
|
+
Classifier: Framework :: Flask
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
|
|
22
|
+
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: flask>=3.0
|
|
27
|
+
Requires-Dist: python-dotenv>=1.0
|
|
28
|
+
Requires-Dist: sqlalchemy>=2.0
|
|
29
|
+
Requires-Dist: alembic>=1.13
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
32
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
33
|
+
Provides-Extra: pgsql
|
|
34
|
+
Requires-Dist: psycopg[binary]>=3.1; extra == "pgsql"
|
|
35
|
+
Provides-Extra: mysql
|
|
36
|
+
Requires-Dist: PyMySQL>=1.1; extra == "mysql"
|
|
37
|
+
Dynamic: license-file
|
|
38
|
+
|
|
39
|
+
# Flask-Artisan
|
|
40
|
+
|
|
41
|
+
**Les conventions de Laravel, mais c'est du Flask.**
|
|
42
|
+
|
|
43
|
+
Flask-Artisan donne une structure prête à l'emploi aux applications Flask : conteneur de services,
|
|
44
|
+
service providers, configuration par fichiers, façades et helpers. L'application reste un vrai
|
|
45
|
+
objet `Flask` : `flask run`, les extensions Flask et leur documentation fonctionnent tels quels.
|
|
46
|
+
|
|
47
|
+
> Version 0.1 (alpha) : l'API peut encore changer avant la 1.0. Voir le [changelog](https://github.com/ahoblepierre/flask-artisan/blob/main/CHANGELOG.md).
|
|
48
|
+
|
|
49
|
+
## Démarrer un projet
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pip install flask-artisan
|
|
53
|
+
flask-artisan new blog
|
|
54
|
+
cd blog
|
|
55
|
+
pip install -r requirements.txt
|
|
56
|
+
flask run
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Le projet généré :
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
blog/
|
|
63
|
+
├── app/http/controllers/ # controllers
|
|
64
|
+
├── app/http/kernel.py # middlewares : globaux, alias, groupes web et api
|
|
65
|
+
├── app/providers/ # AppServiceProvider, RouteServiceProvider
|
|
66
|
+
├── routes/web.py # routes web
|
|
67
|
+
├── routes/api.py # routes préfixées par /api
|
|
68
|
+
├── bootstrap/app.py # crée l'Application
|
|
69
|
+
├── app/models/ # modèles (User fourni)
|
|
70
|
+
├── config/app.py # nom, environnement, debug, clé, providers
|
|
71
|
+
├── config/database.py # connexions sqlite, mysql, mariadb, pgsql
|
|
72
|
+
├── database/migrations/ # migrations générées
|
|
73
|
+
├── config/flask.py # clés copiées dans app.config (extensions Flask)
|
|
74
|
+
├── tests/
|
|
75
|
+
├── wsgi.py # détecté par `flask run`
|
|
76
|
+
└── .env # APP_KEY générée automatiquement
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Conteneur de services
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
from flask_artisan import app
|
|
83
|
+
|
|
84
|
+
app().bind(Mailer, SmtpMailer) # nouvelle instance à chaque make
|
|
85
|
+
app().singleton(Cache, lambda app: RedisCache("...")) # une seule instance
|
|
86
|
+
app().make(ReportService) # dépendances du constructeur injectées d'après leurs annotations
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Routage
|
|
90
|
+
|
|
91
|
+
Les routes vivent dans `routes/web.py` et `routes/api.py` (préfixe `/api`). Elles sont enregistrées dans Flask : `url_for`, `flask routes` et les error handlers marchent comme d'habitude.
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
# routes/api.py
|
|
95
|
+
from flask_artisan import Route
|
|
96
|
+
from app.http.controllers.user_controller import UserController
|
|
97
|
+
from app.http.controllers.photo_controller import PhotoController
|
|
98
|
+
|
|
99
|
+
Route.get("/users", UserController.index).name("users.index")
|
|
100
|
+
Route.get("/users/<int:id>", UserController.show)
|
|
101
|
+
|
|
102
|
+
with Route.prefix("/admin").name("admin.").middleware("auth"):
|
|
103
|
+
Route.post("/users", UserController.store)
|
|
104
|
+
|
|
105
|
+
Route.resource("photos", PhotoController) # index, create, store, show, edit, update, destroy
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
- Verbes : `get`, `post`, `put`, `patch`, `delete`. Les groupes `with` s'imbriquent.
|
|
109
|
+
- `Route.resource` ne crée que les routes des méthodes que le controller définit. Le paramètre s'appelle `id`.
|
|
110
|
+
- Les valeurs d'URL arrivent telles que Flask les donne : écrivez `<int:id>` pour recevoir un entier. Une annotation `id: int` ne convertit rien.
|
|
111
|
+
- Une méthode héritée d'une classe parente se déclare sous la forme `(AdminController, "index")`. Avec `AdminController.index`, Python ne peut pas savoir quelle classe construire.
|
|
112
|
+
- Flask lit ce qui précède un point dans un nom de route comme un nom de blueprint. Un nom comme `admin.dashboard` est donc refusé si un blueprint `admin` est enregistré.
|
|
113
|
+
- On peut aussi déclarer des routes dans le `boot()` d'un provider. Après le boot, c'est trop tard.
|
|
114
|
+
|
|
115
|
+
### Controllers
|
|
116
|
+
|
|
117
|
+
Le conteneur construit le controller à chaque requête. Les méthodes reçoivent les valeurs d'URL, plus tout service annoncé par son type :
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
class UserController:
|
|
121
|
+
def __init__(self, users: UserRepository):
|
|
122
|
+
self.users = users
|
|
123
|
+
|
|
124
|
+
def show(self, id: int, logger: Logger):
|
|
125
|
+
return {"id": id} # dict → JSON, str → HTML, tuple → (corps, statut)
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
La même injection est disponible partout avec `app.call(fonction, **valeurs)`.
|
|
129
|
+
|
|
130
|
+
### Middlewares
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
from flask_artisan import Middleware
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
class EnsureJson(Middleware):
|
|
137
|
+
def handle(self, request, next):
|
|
138
|
+
if not request.is_json:
|
|
139
|
+
return {"error": "JSON attendu"}, 415
|
|
140
|
+
response = next(request)
|
|
141
|
+
response.headers["X-Api"] = "1"
|
|
142
|
+
return response
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Déclarez-les dans `app/http/kernel.py` :
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
class Kernel(HttpKernel):
|
|
149
|
+
global_middleware = [] # toutes les routes déclarées avec Route
|
|
150
|
+
middleware = {"json": EnsureJson} # alias : .middleware("json")
|
|
151
|
+
groups = {"web": [], "api": ["json"]} # appliqués à routes/web.py et routes/api.py
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Des paramètres peuvent suivre l'alias : `.middleware("throttle:60,1")` appelle `handle(request, next, "60", "1")`. Les routes `@app.route` natives ne passent pas par le kernel.
|
|
155
|
+
|
|
156
|
+
## Base de données
|
|
157
|
+
|
|
158
|
+
L'API est façon Eloquent. Le SQL de chaque base est délégué à SQLAlchemy 2, et les migrations à Alembic. On choisit la base dans `.env` :
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
DB_CONNECTION=sqlite # sqlite (par défaut, rien à installer), mysql, mariadb, pgsql
|
|
162
|
+
DB_HOST=127.0.0.1
|
|
163
|
+
DB_DATABASE=blog
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Pilotes : `pip install "flask-artisan[pgsql]"` (PostgreSQL) ou `"flask-artisan[mysql]"` (MySQL et MariaDB).
|
|
167
|
+
|
|
168
|
+
### Modèles
|
|
169
|
+
|
|
170
|
+
```python
|
|
171
|
+
from flask_artisan.database import (
|
|
172
|
+
Mapped, Model, SoftDeletes, belongs_to, belongs_to_many, column, foreign_id, has_many,
|
|
173
|
+
)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
class User(Model, SoftDeletes): # table "users", id, created_at, updated_at, deleted_at
|
|
177
|
+
name: Mapped[str]
|
|
178
|
+
email: Mapped[str] = column(unique=True)
|
|
179
|
+
password: Mapped[str]
|
|
180
|
+
posts = has_many("Post") # cherche Post.user_id
|
|
181
|
+
fillable = ["name", "email", "password"]
|
|
182
|
+
hidden = ["password"]
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
class Post(Model):
|
|
186
|
+
title: Mapped[str]
|
|
187
|
+
user_id: Mapped[int] = foreign_id("users")
|
|
188
|
+
user = belongs_to("User") # utilise user_id (nom de l'attribut + _id)
|
|
189
|
+
tags = belongs_to_many("Tag") # table pivot post_tag
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Requêtes
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
User.create(name="Ana", email="ana@x.io", password=hashed)
|
|
196
|
+
User.find(1)
|
|
197
|
+
User.find_or_fail(1) # 404 pendant une requête
|
|
198
|
+
User.where("name", "like", "A%").or_where("email", "like", "%@x.io").order_by("name").get()
|
|
199
|
+
User.where_in("id", [1, 2]).count()
|
|
200
|
+
User.with_("posts.tags").latest().first() # chargement immédiat des relations
|
|
201
|
+
user.update(name="Bob")
|
|
202
|
+
user.delete() # avec SoftDeletes : deleted_at rempli
|
|
203
|
+
User.with_trashed().get()
|
|
204
|
+
User.only_trashed().first().restore()
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
- Un controller peut renvoyer un modèle ou une liste de modèles : la réponse est du JSON, sans les champs de `hidden`.
|
|
208
|
+
- Avec `fillable`, toute autre clé est ignorée : `User.create(**request.form)` ne prend pas `is_admin` ni `csrf_token`. `id` et les dates ne sont jamais assignables en masse.
|
|
209
|
+
- **`save()` valide toute la session.** Si vous modifiez `a` puis appelez `b.save()`, `a` est aussi enregistré. Pour grouper plusieurs écritures :
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
from flask_artisan import DB
|
|
213
|
+
|
|
214
|
+
with DB.transaction(): # validé à la sortie, annulé sur exception
|
|
215
|
+
order.save()
|
|
216
|
+
stock.update(quantity=stock.quantity - 1)
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
`DB.session` donne la session SQLAlchemy, pour tout ce que l'API ne couvre pas.
|
|
220
|
+
|
|
221
|
+
La session est fermée automatiquement à la fin de chaque requête. Un script ou une commande qui tourne longtemps doit appeler `DB.remove()` quand il a fini, sinon sa connexion reste ouverte.
|
|
222
|
+
|
|
223
|
+
### Migrations
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
flask make:migration "create users" # compare les modèles à la base, écrit database/migrations/…
|
|
227
|
+
flask migrate # applique
|
|
228
|
+
flask migrate:rollback --step 1 # annule
|
|
229
|
+
flask migrate:status # [x] appliquée, [ ] en attente
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Relisez chaque migration générée. Alembic ne voit pas les renommages : il les écrit comme une suppression suivie d'un ajout.
|
|
233
|
+
|
|
234
|
+
Dans les tests, `DB.create_all()` crée les tables sans passer par les migrations. C'est pratique avec `DB_DATABASE=:memory:`.
|
|
235
|
+
|
|
236
|
+
## Authentification
|
|
237
|
+
|
|
238
|
+
Le `User` du squelette hache son mot de passe tout seul, à chaque affectation (`create`, `update`, `fill`, `user.password = ...`) :
|
|
239
|
+
|
|
240
|
+
```python
|
|
241
|
+
from flask_artisan.auth import Authenticatable, HasApiTokens
|
|
242
|
+
from flask_artisan.database import Mapped, Model
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
class User(Authenticatable, HasApiTokens, Model):
|
|
246
|
+
email: Mapped[str]
|
|
247
|
+
password: Mapped[str]
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
user = User.create(email="a@x", password="secret") # stocké haché (scrypt)
|
|
251
|
+
user.check_password("secret") # True
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Deux guards sont déclarés dans `config/auth.py` : `web` (session Flask) et `api` (token Bearer en base).
|
|
255
|
+
|
|
256
|
+
```python
|
|
257
|
+
from flask_artisan import Auth
|
|
258
|
+
|
|
259
|
+
Auth.attempt(email=email, password=password) # session : True/False
|
|
260
|
+
Auth.user(); Auth.id(); Auth.check()
|
|
261
|
+
Auth.login(user); Auth.logout()
|
|
262
|
+
|
|
263
|
+
user = Auth.validate(email=email, password=password) # l'utilisateur ou None, sans connexion
|
|
264
|
+
token = user.create_token("mobile") # "<id>|<secret>", visible une seule fois
|
|
265
|
+
Auth.guard("api").user() # depuis "Authorization: Bearer <token>"
|
|
266
|
+
Auth.user().current_access_token().delete() # révoque le token
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Protégez une route avec le middleware `auth` (guard par défaut) ou `auth:api`. Dans une route `auth:api`, `Auth.user()` renvoie l'utilisateur du token. Sans utilisateur, `auth:api` répond toujours 401 JSON. Avec un guard session, un client qui attend du JSON reçoit un 401 ; un navigateur est redirigé vers la route nommée `login` si elle existe. `last_used_at` d'un token est mis à jour au plus une fois par minute.
|
|
270
|
+
|
|
271
|
+
Le projet généré expose `/api/login`, `/api/user` et `/api/logout` :
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
flask make:migration init && flask migrate # tables users et personal_access_tokens
|
|
275
|
+
curl -X POST localhost:5000/api/login -H 'Content-Type: application/json' \
|
|
276
|
+
-d '{"email": "a@x", "password": "secret"}' # {"token": "1|..."}
|
|
277
|
+
curl localhost:5000/api/user -H 'Authorization: Bearer 1|...'
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
La session est un cookie signé avec `APP_KEY` : cette clé est obligatoire. Changer le mot de passe d'un utilisateur ferme ses sessions ; un `logout` ne fait que vider le cookie du navigateur courant (un cookie copié reste valide jusqu'à `PERMANENT_SESSION_LIFETIME`, 31 jours par défaut, réglable dans `config/flask.py`). Seul le hash SHA-256 de chaque token est stocké.
|
|
281
|
+
|
|
282
|
+
## Console
|
|
283
|
+
|
|
284
|
+
Les générateurs écrivent le fichier au bon endroit, avec un squelette prêt à l'emploi :
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
flask make:controller PhotoController # app/http/controllers/photo_controller.py
|
|
288
|
+
flask make:controller PhotoController --resource # les 7 méthodes de Route.resource
|
|
289
|
+
flask make:controller Admin/UserController # sous-dossier admin/
|
|
290
|
+
flask make:model Post # app/models/post.py
|
|
291
|
+
flask make:middleware EnsureJson # app/http/middleware/ensure_json.py
|
|
292
|
+
flask make:provider PaymentServiceProvider # app/providers/payment_service_provider.py
|
|
293
|
+
flask make:command SendEmails # app/console/commands/send_emails.py → flask app:send-emails
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Un fichier existant n'est jamais écrasé sans `--force`. `make:middleware` et `make:provider` affichent la ligne à ajouter au kernel ou à `config/app.py`.
|
|
297
|
+
|
|
298
|
+
Pas de `make:model -m` : les migrations sont générées depuis les colonnes du modèle. Ajoutez-les, puis lancez `flask make:migration`.
|
|
299
|
+
|
|
300
|
+
Vos commandes sont des commandes [Click](https://click.palletsprojects.com) dans `app/console/commands/`. Elles sont découvertes toutes seules et s'exécutent dans le contexte de l'application. Un fichier qui ne s'importe pas fait échouer les commandes du projet avec son nom (sur `flask --help`, Flask affiche l'erreur mais rend la main normalement). Les commandes du framework (`make:*`, `migrate`, `route:list`) et l'app web ne sont pas touchées :
|
|
301
|
+
|
|
302
|
+
```python
|
|
303
|
+
# app/console/commands/send_emails.py
|
|
304
|
+
import click
|
|
305
|
+
|
|
306
|
+
from app.models.user import User
|
|
307
|
+
|
|
308
|
+
|
|
309
|
+
@click.command("app:send-emails")
|
|
310
|
+
@click.argument("user_id", type=int)
|
|
311
|
+
def send_emails(user_id):
|
|
312
|
+
"""Envoie les emails en attente d'un utilisateur."""
|
|
313
|
+
click.echo(User.find_or_fail(user_id).email)
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
`flask route:list` affiche les routes déclarées avec `Route` :
|
|
317
|
+
|
|
318
|
+
```
|
|
319
|
+
Méthodes URI Nom Action Middlewares
|
|
320
|
+
POST /api/login api.login AuthController@login
|
|
321
|
+
GET /api/user api.user AuthController@user Authenticate:api
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
## Service providers
|
|
325
|
+
|
|
326
|
+
```python
|
|
327
|
+
from flask_artisan import ServiceProvider
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
class MailServiceProvider(ServiceProvider):
|
|
331
|
+
def register(self):
|
|
332
|
+
self.app.singleton(Mailer, SmtpMailer)
|
|
333
|
+
|
|
334
|
+
def boot(self):
|
|
335
|
+
mail_extension.init_app(self.app) # n'importe quelle extension Flask
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
Ajoutez la classe à `providers` dans `config/app.py`.
|
|
339
|
+
|
|
340
|
+
## Configuration
|
|
341
|
+
|
|
342
|
+
```python
|
|
343
|
+
# config/app.py
|
|
344
|
+
from flask_artisan import env
|
|
345
|
+
|
|
346
|
+
config = {"name": env("APP_NAME", "Blog"), "debug": env("APP_DEBUG", False)}
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
```python
|
|
350
|
+
from flask_artisan import config
|
|
351
|
+
|
|
352
|
+
config("app.name")
|
|
353
|
+
config("app.timezone", "UTC") # valeur par défaut
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
## Façades
|
|
357
|
+
|
|
358
|
+
```python
|
|
359
|
+
from flask_artisan import Config, Facade
|
|
360
|
+
|
|
361
|
+
Config.get("app.name")
|
|
362
|
+
|
|
363
|
+
|
|
364
|
+
class Mail(Facade):
|
|
365
|
+
accessor = Mailer # n'importe quelle clé du conteneur
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
Mail.send(...)
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
## Feuille de route v0.1 (publiée)
|
|
372
|
+
|
|
373
|
+
1. ✅ Socle : package, Application, conteneur, providers, config, façades
|
|
374
|
+
2. ✅ Routage et middlewares (`routes/web.py`, controllers en classes)
|
|
375
|
+
3. ✅ ORM façon Eloquent sur SQLAlchemy, migrations
|
|
376
|
+
4. ✅ Authentification (façade `Auth`, guards session et token)
|
|
377
|
+
5. ✅ Commandes `flask make:*`, `flask migrate`, `flask route:list`
|
|
378
|
+
|
|
379
|
+
## Contribuer
|
|
380
|
+
|
|
381
|
+
Voir [CONTRIBUTING.md](https://github.com/ahoblepierre/flask-artisan/blob/main/CONTRIBUTING.md).
|
|
382
|
+
|
|
383
|
+
## Licence
|
|
384
|
+
|
|
385
|
+
MIT
|