diff --git a/CHANGELOG.md b/CHANGELOG.md index 59e3ca2..e50aabc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- **Italian translations for the model-definition rules.** The documentation + for `DOL011` through `DOL015` is now available in Italian, with a dedicated + index linked from the complete rule reference. Refs #52. + ### Fixed - **DOL007 no longer fires on attribute accesses that cost nothing.** diff --git a/docs/i18n/rules/it/DOL011.md b/docs/i18n/rules/it/DOL011.md new file mode 100644 index 0000000..8733ec4 --- /dev/null +++ b/docs/i18n/rules/it/DOL011.md @@ -0,0 +1,27 @@ +# DOL011 - null=True su CharField/TextField + +**Gravità predefinita:** warning · **Applicabilità:** suggestion · **Categoria:** model + +Rileva `null=True` su un `CharField` o un `TextField`. La documentazione di Django stessa lo sconsiglia: una colonna di testo che accetta valori nulli ha due distinti valori per indicare l'assenza di dati, `NULL` e la stringa vuota `''`. Di conseguenza, ogni parte del codice che la utilizza deve controllarli entrambi e le query come `field=''` ignorano silenziosamente le righe contenenti `NULL`. La convenzione di Django prevede una colonna `NOT NULL` con `blank=True` per rendere il campo facoltativo a livello di form, memorizzando `''` quando il valore è assente. La QuickFix ("Replace null=True with blank=True") sostituisce l'argomento sul posto; è un suggerimento perché la modifica richiede una migrazione e, in presenza di dati esistenti, la conversione dei valori `NULL` in `''`. + +## Non corretto + +```python +class Profile(models.Model): + bio = models.TextField(null=True) +``` + +## Corretto + +```python +class Profile(models.Model): + bio = models.TextField(blank=True) +``` + +## Soppressione + +```python +# django-orm-lens-disable-next-line DOL011 +``` + +Un'eccezione legittima è rappresentata dai campi di testo con `unique=True` nei quali più valori assenti non devono entrare in conflitto: in quel caso, sopprimi la regola. In alternativa, disattivala per l'area di lavoro in `.vscode/settings.json`: `{"djangoOrmLens.rules": {"DOL011": "off"}}`. diff --git a/docs/i18n/rules/it/DOL012.md b/docs/i18n/rules/it/DOL012.md new file mode 100644 index 0000000..cc1298e --- /dev/null +++ b/docs/i18n/rules/it/DOL012.md @@ -0,0 +1,30 @@ +# DOL012 - Modello privo del metodo __str__ + +**Gravità predefinita:** info · **Applicabilità:** suggestion · **Categoria:** model + +Rileva una classe che eredita da `models.Model` e nel cui corpo non è definito alcun metodo `__str__` (i modelli astratti con `abstract = True` in `Meta` vengono ignorati). Senza `__str__`, gli elenchi dell'area di amministrazione, i menu a discesa dei `ForeignKey`, le rappresentazioni nella shell e `{{ obj }}` nei template vengono tutti visualizzati come `ModelName object (1)`, un risultato inutile per le persone e durante il debug. Non è disponibile una QuickFix: generare un corpo significativo richiede di scegliere quale campo mostrare, una decisione che può prendere soltanto chi conosce il modello. + +## Non corretto + +```python +class Article(models.Model): + title = models.CharField(max_length=255) +``` + +## Corretto + +```python +class Article(models.Model): + title = models.CharField(max_length=255) + + def __str__(self) -> str: + return self.title +``` + +## Soppressione + +```python +# django-orm-lens-disable-next-line DOL012 +``` + +In alternativa, disattiva la regola per l'area di lavoro in `.vscode/settings.json`: `{"djangoOrmLens.rules": {"DOL012": "off"}}`. diff --git a/docs/i18n/rules/it/DOL013.md b/docs/i18n/rules/it/DOL013.md new file mode 100644 index 0000000..f3071a5 --- /dev/null +++ b/docs/i18n/rules/it/DOL013.md @@ -0,0 +1,27 @@ +# DOL013 - ForeignKey senza on_delete + +**Gravità predefinita:** error · **Applicabilità:** suggestion · **Categoria:** model + +Rileva una chiamata a `ForeignKey(...)` priva dell'argomento nominato `on_delete=`. `on_delete` è obbligatorio da Django 2.0: ometterlo genera un `TypeError` non appena viene caricato il modulo del modello, quindi la regola rileva il problema durante la scrittura del codice, prima ancora di eseguire l'applicazione. La QuickFix ("Add on_delete=models.CASCADE (edit to your policy)") inserisce `on_delete=models.CASCADE` come modello da adattare. È un suggerimento, non una correzione sicura: la politica di eliminazione è una vera decisione progettuale. `CASCADE` elimina silenziosamente i record dipendenti, mentre `PROTECT`, `SET_NULL`, `SET_DEFAULT` o `DO_NOTHING` potrebbero essere più adatti ai dati effettivi. + +## Non corretto + +```python +class Book(models.Model): + author = models.ForeignKey(Author) +``` + +## Corretto + +```python +class Book(models.Model): + author = models.ForeignKey(Author, on_delete=models.CASCADE) +``` + +## Soppressione + +```python +# django-orm-lens-disable-next-line DOL013 +``` + +In alternativa, disattiva la regola per l'area di lavoro in `.vscode/settings.json`: `{"djangoOrmLens.rules": {"DOL013": "off"}}`. diff --git a/docs/i18n/rules/it/DOL014.md b/docs/i18n/rules/it/DOL014.md new file mode 100644 index 0000000..b67d54c --- /dev/null +++ b/docs/i18n/rules/it/DOL014.md @@ -0,0 +1,27 @@ +# DOL014 - CharField senza max_length + +**Gravità predefinita:** error · **Applicabilità:** suggestion · **Categoria:** model + +Rileva una chiamata a `CharField(...)` priva dell'argomento nominato `max_length=`. Django richiede `max_length` per `CharField`; senza questo argomento, il modello non supera i controlli di Django durante il caricamento. Si tratta quindi di un'altra classe di errori che, altrimenti, emergerebbe soltanto al successivo `runserver` o `makemigrations`. La QuickFix ("Add max_length=255 (edit as needed)") inserisce `max_length=255` come modello da adattare: 255 è una convenzione comune, non una costante speciale, quindi la dimensione della colonna deve essere scelta in base ai dati. È un suggerimento perché il limite corretto dipende dal caso d'uso; se il testo è davvero senza limiti, `TextField` è il campo più adatto. + +## Non corretto + +```python +class Tag(models.Model): + name = models.CharField() +``` + +## Corretto + +```python +class Tag(models.Model): + name = models.CharField(max_length=255) +``` + +## Soppressione + +```python +# django-orm-lens-disable-next-line DOL014 +``` + +In alternativa, disattiva la regola per l'area di lavoro in `.vscode/settings.json`: `{"djangoOrmLens.rules": {"DOL014": "off"}}`. diff --git a/docs/i18n/rules/it/DOL015.md b/docs/i18n/rules/it/DOL015.md new file mode 100644 index 0000000..ea8e497 --- /dev/null +++ b/docs/i18n/rules/it/DOL015.md @@ -0,0 +1,33 @@ +# DOL015 - max_length su TextField non ha effetto sul database + +**Gravità predefinita:** hint · **Applicabilità:** suggestion · **Categoria:** model + +Rileva `max_length=` su un `TextField(...)`. `TextField` viene mappato a `TEXT`/`CLOB`; Django applica il suo `max_length` soltanto nel widget del form generato automaticamente, mai a livello di database. L'argomento sembra quindi definire un limite rigido, ma non è così: le scritture dirette tramite ORM, le operazioni in blocco e i salvataggi diretti dall'area di amministrazione possono tutti superarlo. Se occorre un limite applicato dal database, usa `CharField(max_length=...)`; se il testo è davvero senza limiti, rimuovi l'argomento. La QuickFix ("Remove max_length from TextField") elimina l'argomento; è un suggerimento perché, in alternativa, potrebbe essere preferibile passare a `CharField`. + +## Non corretto + +```python +class Comment(models.Model): + body = models.TextField(max_length=500) +``` + +## Corretto + +```python +class Comment(models.Model): + body = models.TextField() +``` + +Oppure, quando il limite deve essere applicato a livello di database: + +```python + body = models.CharField(max_length=500) +``` + +## Soppressione + +```python +# django-orm-lens-disable-next-line DOL015 +``` + +Sopprimi la regola se usi intenzionalmente `max_length` soltanto come limite a livello di form. In alternativa, disattivala per l'area di lavoro in `.vscode/settings.json`: `{"djangoOrmLens.rules": {"DOL015": "off"}}`. diff --git a/docs/i18n/rules/it/README.md b/docs/i18n/rules/it/README.md new file mode 100644 index 0000000..a56bd58 --- /dev/null +++ b/docs/i18n/rules/it/README.md @@ -0,0 +1,15 @@ +# Riferimento delle regole + +Questa sezione contiene la traduzione italiana delle regole di Django ORM Lens relative alla definizione dei modelli. Ogni codice `DOL` identifica un controllo statico eseguito dall'estensione VS Code durante la scrittura del codice. + +Per le regole non ancora tradotte, consulta il [riferimento completo in inglese](../../../rules/README.md). + +## Regole di definizione dei modelli + +| Codice | Regola | Categoria | Gravità predefinita | Applicabilità | +|---|---|---|---|---| +| [DOL011](DOL011.md) | `null=True` su CharField/TextField | model | warning | suggestion | +| [DOL012](DOL012.md) | Modello privo del metodo `__str__` | model | info | suggestion | +| [DOL013](DOL013.md) | ForeignKey senza `on_delete` | model | error | suggestion | +| [DOL014](DOL014.md) | CharField senza `max_length` | model | error | suggestion | +| [DOL015](DOL015.md) | `max_length` su TextField non ha effetto sul database | model | hint | suggestion | diff --git a/docs/rules/README.md b/docs/rules/README.md index 0f14259..6927c6a 100644 --- a/docs/rules/README.md +++ b/docs/rules/README.md @@ -1,5 +1,6 @@ # Rule reference +🌐 [Italiano](../i18n/rules/it/README.md) - model rules (`DOL011`-`DOL015`) 🌐 [Tiếng Việt](../i18n/rules/vi/README.md) — queryset rules (`DOL001`–`DOL007`) Django ORM Lens ships two rule surfaces: