# Référence : réglages de projet

> Description neutre de `.turbo-python/settings.toml` : où il est cherché, ce qu'il peut contenir, et ce qui y écrit.

## Emplacement

| Propriété | Valeur |
| --- | --- |
| Dossier | `.turbo-python` dans le répertoire de travail de l'éditeur |
| Fichier | `.turbo-python/settings.toml` |
| Recherche | Le répertoire de travail seulement. Les dossiers parents ne sont **pas** parcourus. |
| Lecture | Au démarrage de l'éditeur, puis à chaque enregistrement du fichier depuis l'éditeur |
| Obligatoire | Non. Un projet qui n'en a pas obtient les valeurs par défaut ci-dessous. |

## Clés

Chaque clé est facultative, et chaque clé se trouve dans la table `[editor]`. Une clé absente garde sa valeur par défaut ; une clé présente l'emporte, y compris avec une valeur égale à la valeur par défaut.

| Clé | Type | Défaut | Description |
| --- | --- | --- | --- |
| `theme` | chaîne | le défaut de l'éditeur (`turbo-classic`) | Nom du thème de couleurs de démarrage, tel que listé par `turbo-python -list-themes` |
| `autosave` | booléen | `false` | Si les fichiers modifiés sont écrits sans qu'on le demande. Le fichier qu'écrit **Create project settings** le met à `true` ; la valeur par défaut ici est celle qui s'applique à un projet sans fichier de réglages du tout. |
| `autosave_delay` | chaîne | `"2s"` | Combien de temps attendre après la dernière frappe. Une durée Go : `"500ms"`, `"2s"`, `"1m"`. Consultée seulement quand `autosave` vaut true. |

### Exemple

```toml
[editor]
theme = "turbo-dark"
autosave = true
autosave_delay = "500ms"
```

## Priorité du thème

De la plus forte à la plus faible :

| Source | L'emporte sur |
| --- | --- |
| `-theme` sur la ligne de commande | tout |
| `theme` dans le fichier de réglages | le défaut intégré |
| Le défaut intégré `turbo-classic` | — |

Un nom de thème inconnu, à n'importe quel niveau, retombe sur le défaut intégré plutôt que d'échouer.

## Quand un changement prend effet

Le fichier est lu au démarrage, et **de nouveau à chaque enregistrement depuis l'éditeur** — un changement fait dans l'éditeur est donc en vigueur dès que vous appuyez sur `F2`, sans redémarrage.

| Clé | Ré-appliquée à l'enregistrement | Pourquoi |
| --- | --- | --- |
| `autosave` | oui | |
| `autosave_delay` | oui | |
| `theme` | **non** | Options ▸ Theme est la façon vivante de le changer, et y réécrit déjà le choix. Une option `-theme` donnée en ligne de commande est l'affirmation la plus explicite pour cette session, et l'enregistrement d'un fichier ne la contredit pas. |

| Résultat | Barre d'état |
| --- | --- |
| Lu et appliqué | `Applied .turbo-python/settings.toml — autosave on (2s)` |
| Lu et appliqué, autosave désactivée | `Applied .turbo-python/settings.toml — autosave off` |
| Enregistré, mais plus du TOML valide | `Saved, but not applied: …` — les valeurs précédentes restent en vigueur |

Enregistrer est enregistrer, quel qu'en soit l'auteur : la sauvegarde automatique qui écrit le fichier de réglages les ré-applique exactement comme `F2`. Une modification faite **hors** de l'éditeur n'est pas remarquée ; rien ne surveille le fichier.

## Sauvegarde automatique

| Comportement | Détail |
| --- | --- |
| Déclencheur | Le délai écoulé sans modification dans aucune fenêtre |
| Portée | Tout fichier ouvert qui a un nom, pas seulement celui au premier plan |
| Échéance | Une seule pour tout l'éditeur, relancée par toute modification dans n'importe quelle fenêtre |
| Fichiers sans nom | Jamais enregistrés ; jamais l'objet d'une question |
| Signalement | `Saved <nom>` dans la barre d'état |
| Échec | Signalé dans la barre d'état, jamais dans un dialogue, et non réessayé avant la modification suivante |
| Fermeture d'une fenêtre | Enregistre au lieu de demander, si le fichier a un nom |
| Sortie de l'éditeur | Enregistre au lieu de demander, si le fichier a un nom |

## Écritures

Le fichier de réglages est écrit par exactement deux actions. Rien d'autre dans l'éditeur n'y écrit, et rien ne le crée tout seul.

| Action | Effet |
| --- | --- |
| **Options ▸ Create project settings** | Crée `.turbo-python/settings.toml` avec le thème en cours, `autosave = true` et des commentaires explicatifs. Grisée dès que le projet en a un, elle ne peut donc pas être choisie deux fois. |
| **Options ▸ Theme** | Réécrit la valeur de `theme` **uniquement si le fichier existe déjà**. Commentaires, lignes vides, ordre des clés et commentaire de fin de la ligne du thème sont conservés. |

Les deux écrivent via un fichier temporaire du même dossier, renommé en place : une écriture interrompue laisse le fichier précédent intact.

## Entrées de menu

| Entrée | Menu | Fichier requis | Effet |
| --- | --- | --- | --- |
| Create project settings | Options | refuse le fichier | Comme ci-dessus, puis ouvre le fichier. Grisée dès que le projet en a un. |
| Project settings… | Options | exige le fichier | Ouvre `.turbo-python/settings.toml`. Grisée tant que le projet n'en a pas. |

## Erreurs

| Message | Cause |
| --- | --- |
| `turbo-python: reading …/settings.toml: …` sur la sortie d'erreur | Le fichier est là mais n'est pas du TOML valide. L'éditeur s'ouvre avec ses valeurs par défaut. |
| `reading …: autosave_delay "x" is not a duration such as "2s"` | `autosave_delay` n'est pas une durée Go |
| `reading …: autosave_delay must be positive, not "0s"` | `autosave_delay` est nul ou négatif |
| `Already there: .turbo-python/settings.toml` dans la barre d'état | Créer dans un projet qui en a déjà un. Inatteignable depuis le menu, qui grise l'entrée ; reste possible pour un appelant qui n'est pas un menu. |
| `Saved, but not applied: …` dans la barre d'état | Le fichier de réglages a été écrit mais ne s'analyse plus. Les valeurs précédentes restent en vigueur. |
| `This project has no .turbo-python/settings.toml yet.` | **Project settings…** dans un projet qui n'en a pas |
| `Theme set for this session only: …` | Le thème a changé mais le fichier de réglages n'a pas pu être écrit |

## Voir aussi

- [Donner ses propres réglages à un projet](../how-to/configure-a-project.md)
- [Réglages de projet](../explanation/project-settings.md)
- [Format des fichiers de thème](themes.md) — un autre fichier, dans le même langage