Getting Help

el
en
es
id
it
ja
ko
pl
pt-br
zh-hans
Langue : fr

1.8
1.10
1.11
2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
4.2
5.0
dev
Version de la documentation : 5.1

L’application de gestion des fichiers statiques (`staticfiles`)¶

django.contrib.staticfiles recueille les fichiers statiques à partir de chacune des applications (et de tous les autres endroits que vous spécifiez) en un seul endroit qui peut facilement être utilisé en production.

Voir aussi

Pour une introduction à l’application et quelques exemples d’utilisation des fichiers statiques, voir Gestion des fichiers statiques (par ex. images, JavaScript, CSS). Pour obtenir des instructions sur le déploiement des fichiers statiques, voir Déploiement des fichiers statiques.

Réglages¶

Voir réglages de staticfiles pour plus de détails sur les réglages suivants :

Stockages¶

`StaticFilesStorage`¶

class storage.StaticFilesStorage¶

Une sous-classe du moteur de stockage FileSystemStorage qui utilise le réglage STATIC_ROOT comme emplacement de base dans le système de fichiers et le réglage STATIC_URL comme URL de base.

storage.StaticFilesStorage.post_process(paths, **options)¶

Si cette méthode est définie pour un stockage, elle est appelée par la commande de gestion collectstatic après chaque exécution et reçoit les stockages locaux et les chemins des fichiers trouvés sous forme de dictionnaire, de même que les options de la ligne de commande. Elle renvoie des tuples de trois valeurs : chemin_original, chemin_traité, traité. Les valeurs de chemins sont des chaînes et traité est un booléen indiquant si la valeur a reçu un post-traitement, ou une exception si le post-traitement a échoué.

Le stockage ManifestStaticFilesStorage utilise cette classe en coulisses pour remplacer les chemins par leur équivalent « haché » et mettre à jour le cache de manière appropriée.

`ManifestStaticFilesStorage`¶

class storage.ManifestStaticFilesStorage¶

Une sous-classe du moteur de stockage StaticFilesStorage qui modifie les noms des fichiers qu’elle traite en ajoutant le hachage MD5 du contenu du fichier au nom de fichier. Par exemple, le fichier css/styles.css serait également enregistré en tant que css/styles.55e7cbb9ba48.css.

Le but de ce stockage est de continuer à servir les anciens fichiers au cas où certaines pages se réfèrent encore à ces fichiers, par exemple parce qu’elles sont mises en cache par vous-même ou un serveur mandataire externe. En outre, cela est très utile si vous souhaitez appliquer des en-têtes à date d’expiration très lointaine aux fichiers déployés pour accélérer le temps de chargement des pages lors des visites ultérieures.

Le moteur de stockage remplace automatiquement dans les fichiers enregistrés les chemins qui correspondent aux autres fichiers enregistrés par les chemins des copies en cache (en utilisant la méthode post_process()). Les expressions régulières utilisées pour rechercher ces chemins (django.contrib.staticfiles.storage.HashedFilesMixin.patterns) couvrent :

La règle @import et l’instruction url() des feuilles de style CSS.
Les commentaires source map dans les fichiers CSS et JavaScript.

Créez une sous-classe de ManifestStaticFilesStorage et définissez l’attribut support_js_module_import_aggregation à True si vous souhaitez activer la couverture expérimentale des expressions régulières pour :

Les importations de modules en JavaScript.
L”agrégation de modules en JavaScript.

Par exemple, le fichier 'css/styles.css' avec ce contenu :

@import url("../admin/css/base.css");

…serait remplacé par l’appel de la méthode url() du moteur de stockage ManifestStaticFilesStorage, enregistrant finalement un fichier 'css/styles.55e7cbb9ba48.css' avec le contenu suivant :

@import url("../admin/css/base.27e20196a850.css");

Utilisation de l’attribut HTML integrity avec des fichiers locaux

Lorsque l’attribut facultatif integrity est utilisé dans des balises comme <script> or <link>, sa valeur doit être calculée sur la base des fichiers réellement servis, et pas en fonction de ceux stockés sur le système de fichiers. C’est particulièrement important car selon la méthode de collection des fichiers statiques, leur somme de contrôle peut avoir changé (par exemple lors de l’utilisation de collectstatic). Actuellement, il n’existe pas d’outils prêts à l’emploi pour une telle tâche.

Vous pouvez modifier l’emplacement du fichier manifeste en utilisant une sous-classe personnalisée de ManifestStaticFilesStorage qui définit l’argument manifest_storage. Par exemple

from django.conf import settings
from django.contrib.staticfiles.storage import (
    ManifestStaticFilesStorage,
    StaticFilesStorage,
)


class MyManifestStaticFilesStorage(ManifestStaticFilesStorage):
    def __init__(self, *args, **kwargs):
        manifest_storage = StaticFilesStorage(location=settings.BASE_DIR)
        super().__init__(*args, manifest_storage=manifest_storage, **kwargs)

Références dans les commentaires

ManifestStaticFilesStorage n’ignore pas les chemins dans les instructions qui sont mises en commentaire. Cela peut planter s’ils contiennent des chemins inexistants. Vous devriez vérifier et éventuellement enlever les commentaires.

storage.ManifestStaticFilesStorage.manifest_hash¶

Cet attribut indique une empreinte unique qui change chaque fois qu’un fichier du manifeste est modifié. Cela peut être utile pour communiquer aux applications à page unique que les fichiers statiques du serveur ont été modifiés (en raison d’un nouveau déploiement).

storage.ManifestStaticFilesStorage.max_post_process_passes¶

Comme les fichiers statiques peuvent se référer à d’autres fichiers statiques qui ont besoin d’un remplacement de chemins, plusieurs passes de remplacements de chemins peuvent être nécessaires jusqu’à ce que les hachages de fichier convergent. Pour éviter une boucle sans fin en raison de hachages non convergeant (par exemple, si 'foo.css' se réfère à 'bar.css' qui référence 'foo.css'), un nombre maximum de passes est défini avant qu’un post-traitement soit abandonné. Dans le cas d’un nombre de références élevé, il pourrait être nécessaire d’augmenter ce nombre de passes. Ceci peut se faire en créant une sous-classe de ManifestStaticFilesStorage et en définissant l’attribut max_post_process_passes. Sa valeur par défaut est 5.

Pour activer le stockage ManifestStaticFilesStorage, vous devez vous assurer que les conditions suivantes sont remplies :

le moteur de stockage staticfiles dans le réglage STORAGES contient 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
le réglage DEBUG contient False
vous avez recueilli tous les fichiers statiques en utilisant la commande d’administration collectstatic

Comme la création du hachage MD5 peut diminuer la performance de votre site web, staticfiles stocke automatiquement la correspondance des noms hachés pour chaque fichier traité dans un fichier nommé staticfiles.json. Cela se produit une seule fois au moment où vous exécutez la commande collectstatic.

storage.ManifestStaticFilesStorage.manifest_strict¶

Si un fichier n’est pas trouvé dans le manifeste staticfiles.json lors de l’exécution, une exception ValueError est générée. Ce comportement peut être désactivé en créant une sous-classe de ManifestStaticFilesStorage et en définissant l’attribut manifest_strict à False – les chemins non existants seront laissés inchangés.

Comme il faut que la commande collectstatic ait été lancée, ce stockage ne doit normalement pas être utilisé lors de l’exécution des tests car collectstatic n’est pas exécutée dans une configuration de test normale. Lors des tests, vérifiez que le moteur de stockage staticfiles de STORAGES est défini sur autre chose, comme par exemple la valeur par défaut 'django.contrib.staticfiles.storage.StaticFilesStorage'.

storage.ManifestStaticFilesStorage.file_hash(name, content=None)¶

La méthode utilisée lors de la création du nom haché d’un fichier. Doit renvoyer une empreinte de hachage pour le nom de fichier donné et son contenu. Par défaut, on calcule un hachage MD5 à partir du contenu comme mentionné ci-dessus. N’hésitez pas à redéfinir cette méthode pour utiliser votre propre algorithme de hachage.

`ManifestFilesMixin`¶

class storage.ManifestFilesMixin¶

Utilisez cette classe mixin avec un stockage personnalisé pour ajouter au nom de fichier une empreinte MD5 du contenu du fichier, comme le fait ManifestStaticFilesStorage.

Le module `finders`¶

Le module finders (découverte des fichiers statiques) de staticfiles possède un attribut searched_locations qui est une liste de chemins de répertoires dans lesquels des fichiers statiques ont été recherchés. Exemple d’utilisation :

from django.contrib.staticfiles import finders

result = finders.find("css/base.css")
searched_locations = finders.searched_locations

Autres utilitaires¶

Il existe quelques autres utilitaires en plus de l’application staticfiles pour gérer les fichiers statiques :

Le processeur de contexte django.template.context_processors.static() qui ajoute STATIC_URL au contexte de chaque gabarit rendu avec RequestContext.
La balise de gabarit static de base qui prend un chemin et le combine avec le préfixe statique STATIC_URL. Si django.contrib.staticfiles est installée, la balise utilise plutôt la méthode url() du moteur de stockage staticfiles du réglage STORAGES.
La balise de gabarit get_static_prefix qui renseigne une variable de gabarit avec le préfixe statique STATIC_URL pour utilisation immédiate ou stockée dans une variable.
La balise de gabarit similaire get_media_prefix qui fonctionne comme get_static_prefix mais utilise MEDIA_URL.
La clé staticfiles dans django.core.files.storage.storages contient une instance prêt à l’emploi du moteur de stockage des fichiers statiques.

Vue pour l’utilisation des fichiers statiques en développement¶

Les outils concernant les fichiers statiques sont principalement conçus pour aider à déployer correctement les fichiers statiques en production. Cela implique généralement de dédier un serveur distinct pour les fichiers statiques, ce qui induit de trop nombreuses actions supplémentaires lorsque l’on développe en local sur un environnement de développement. Ainsi, l’application staticfiles est fournie avec une vue à la va-vite que vous pouvez utiliser pour s’occuper du service des fichiers lors du développement local.

views.serve(request, path)¶

Cette fonction de vue sert les fichiers statiques lors du développement.

Avertissement

Cette vue ne fonctionne que si le réglage DEBUG vaut True.

C’est parce que cette vue est totalement inefficace et probablement non sécurisée. Elle n’est destinée qu’au développement en local et ne devrait jamais être utilisée en production.

Note

Pour deviner les types de contenu des fichiers servis, cette vue exploite le module mimetypes de la bibliothèque Python standard, qui se base elle-même sur la correspondance des types de fichiers de la plate-forme sous-jacente. Si vous trouvez que cette vue ne renvoie pas les bons types de contenu pour certains fichiers, il est plus que probable que la correspondance des types de fichiers de la plate-forme est fausse ou doit être mise à jour. Ceci peut par exemple être réalisé par l’installation ou la mise à jour du paquet mailcap sur une distribution Red Hat, du paquet mime-support sur une distribution Debian ou en modifiant les clés sous HKEY_CLASSES_ROOT dans le registre Windows.

Cette vue est automatiquement activée par runserver (avec le réglage DEBUG à True). Pour utiliser la vue avec un autre serveur de développement local, ajoutez le code suivant à la fin de la configuration d’URL principale :

from django.conf import settings
from django.contrib.staticfiles import views
from django.urls import re_path

if settings.DEBUG:
    urlpatterns += [
        re_path(r"^static/(?P<path>.*)$", views.serve),
    ]

Remarque : le début du motif (r'^static/') devrait correspondre au réglage STATIC_URL.

Comme c’est un peu fastidieux, il existe aussi une fonction utilitaire qui fait cela pour vous :

urls.staticfiles_urlpatterns()¶

Cela renvoie le motif d’URL approprié pour servir les fichiers statiques et peut être ajouté à la liste de motifs d’URL déjà définie. Utilisez-la comme ceci :

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

# ... the rest of your URLconf here ...

urlpatterns += staticfiles_urlpatterns()

Cette fonction examine le réglage STATIC_URL et connecte la vue de service des fichiers statiques en conséquence. N’oubliez pas de définir le réglage STATICFILES_DIRS approprié pour faire savoir à django.contrib.staticfiles où rechercher les fichiers en plus des fichiers dans les répertoires des applications.

Avertissement

Cette fonction utilitaire ne fonctionne que si DEBUG vaut True et que le réglage STATIC_URL n’est ni vide ni une URL complète comme http://static.example.com/.

Cas de test particulier pour permettre le « test en live »¶

class testing.StaticLiveServerTestCase¶

Cette sous-classe de test unitaire TestCase hérite de django.test.LiveServerTestCase.

Tout comme sa classe parente, vous pouvez l’utiliser pour écrire des tests qui impliquent le fonctionnement du code testé et de son exploitation par des outils de test à travers HTTP (par ex. Selenium, PhantomJS, etc.), et pour lesquels il est nécessaire que les fichiers statiques soient également disponibles.

Mais étant donné qu’elle fait appel à la vue django.contrib.staticfiles.views.serve() présentée plus haut, elle peut servir de manière transparente au moment de l’exécution des tests les ressources statiques mises à disposition par le moteur de découverte de staticfiles. Cela signifie que vous n’avez pas besoin de lancer collectstatic préalablement ou dans le cadre de la configuration des tests.

L’infrastructure des « sites »

L’infrastructure de syndication par flux

Documentation

L’application de gestion des fichiers statiques (`staticfiles`)¶

Réglages¶

Commandes d’administration¶

`collectstatic`¶

Personnalisation de la liste des motifs ignorés¶

`findstatic`¶

`runserver`¶

Stockages¶

`StaticFilesStorage`¶

`ManifestStaticFilesStorage`¶

`ManifestFilesMixin`¶

Le module `finders`¶

Autres utilitaires¶

Vue pour l’utilisation des fichiers statiques en développement¶

Cas de test particulier pour permettre le « test en live »¶

Informations supplémentaires

Support Django!

Sommaire

Parcourir

Vous êtes ici :

Obtenir de l'aide

Télécharger :

Django Links

Learn More

Get Involved

Get Help

Follow Us

Support Us

Documentation

L’application de gestion des fichiers statiques (staticfiles)¶

Réglages¶

Commandes d’administration¶

collectstatic¶

Personnalisation de la liste des motifs ignorés¶

findstatic¶

runserver¶

Stockages¶

StaticFilesStorage¶

ManifestStaticFilesStorage¶

ManifestFilesMixin¶

Le module finders¶

Autres utilitaires¶

Vue pour l’utilisation des fichiers statiques en développement¶

Cas de test particulier pour permettre le « test en live »¶

Informations supplémentaires

Support Django!

Sommaire

Parcourir

Vous êtes ici :

Obtenir de l'aide

Télécharger :

L’application de gestion des fichiers statiques (`staticfiles`)¶

`collectstatic`¶

`findstatic`¶

`runserver`¶

`StaticFilesStorage`¶

`ManifestStaticFilesStorage`¶

`ManifestFilesMixin`¶

Le module `finders`¶