Gestion des versions de cache pour fichiers statiques et cookies dans Django.

These details have not been verified by PyPI

Project links

Project description

xeolux-cachekit

Package Django réutilisable pour gérer les versions de cache des fichiers statiques (CSS, JS, assets) et des cookies. Développé par XEOLUX.

Fonctionnalités

✅ Versionnement des URLs statiques : /static/css/main.css?v=1.0.3
✅ Détection automatique du type selon l'extension de fichier
✅ Strategy hash : version calculée depuis le contenu des fichiers (zéro gestion manuelle)
✅ Cookies versionnés : xeolux_consent_v1_0_0
✅ Context processor pour exposer les versions dans tous les templates
✅ Template tags {% versioned_static %}, {% versioned_static_as %}, {% cache_version %}
✅ Middleware Cache-Control: max-age=31536000, immutable sur les statiques versionnées
✅ Commande show_cache_versions pour diagnostiquer la configuration
✅ Commande bump_cache_version pour incrémenter une version (patch/minor/major)
✅ Compatible Django 4.2, 5.0, 5.1 — Python 3.10, 3.11, 3.12

Installation

pip install xeolux-cachekit

Ou en local depuis les sources :

pip install -e /chemin/vers/xeolux-cachekit

Configuration

1. `INSTALLED_APPS`

# settings.py
INSTALLED_APPS = [
    ...
    "xeolux_cachekit",
]

2. Context processor

TEMPLATES = [
    {
        ...
        "OPTIONS": {
            "context_processors": [
                ...
                "xeolux_cachekit.context_processors.cache_versions",
            ],
        },
    }
]

3. Middleware (optionnel)

Ajoute automatiquement Cache-Control: max-age=31536000, immutable sur les fichiers statiques versionnés.

MIDDLEWARE = [
    ...
    "xeolux_cachekit.middleware.CacheControlMiddleware",
]

4. Versions — Configuration

Option A — Configuration centralisée (recommandée) :

XEOLUX_CACHEKIT = {
    "global":      "1.0.0",
    "css":         "1.0.3",
    "js":          "1.2.0",
    "assets":      "1.0.8",
    "cookies":     "1.0.0",
    "query_param": "v",       # nom du paramètre dans l'URL
    "strategy":    "manual",  # "manual" ou "hash"
}

Option B — Strategy hash (zéro gestion manuelle) :

XEOLUX_CACHEKIT = {
    "strategy":    "hash",   # hash MD5 calculé depuis le contenu des fichiers
    "cookies":     "1.0.0",  # toujours manuel (pas de fichiers statiques)
    "global":      "1.0.0",
    "query_param": "v",
}
# → /static/css/main.css?v=a3f2c1d4

Option C — Variables individuelles :

XEOLUX_GLOBAL_VERSION = "1.0.0"
XEOLUX_CSS_VERSION    = "1.0.3"
XEOLUX_JS_VERSION     = "1.2.0"
XEOLUX_ASSETS_VERSION = "1.0.8"
XEOLUX_COOKIE_VERSION = "1.0.0"

Priorité : XEOLUX_CACHEKIT > variables individuelles > valeurs par défaut ("1.0.0" / "v" / "manual").

Utilisation dans les templates

{% load cachekit_tags %}

<!-- Détection automatique du type selon l'extension -->
<link rel="stylesheet" href="{% versioned_static 'css/main.css' %}">
<script src="{% versioned_static 'js/app.js' %}"></script>
<img src="{% versioned_static 'img/logo.svg' %}">
<link rel="icon" href="{% versioned_static 'favicon.ico' %}">

<!-- Forcer le type manuellement -->
<link rel="stylesheet" href="{% versioned_static_as 'css/main.css' 'css' %}">
<a href="{% versioned_static_as 'data/file.txt' 'global' %}">Télécharger</a>

<!-- Afficher uniquement la version (utile pour les attributs data- ou JS) -->
<body data-css-version="{% cache_version 'css' %}">
<script>window.ASSET_VERSION = "{% cache_version 'assets' %}";</script>

Variables du context processor disponibles directement :

<p>CSS : {{ CACHEKIT_CSS_VERSION }}</p>
<p>JS  : {{ CACHEKIT_JS_VERSION }}</p>

Types détectés automatiquement

Extension	Type
`.css`	`css`
`.js`	`js`
`.ico`, `.png`, `.jpg`, `.jpeg`, `.svg`, `.webp`, `.gif`, `.avif`	`assets`
Autre	`global`

Utilisation en Python

from xeolux_cachekit import get_cache_version, versioned_static_url

get_cache_version("css")     # "1.0.3"
get_cache_version("js")      # "1.2.0"
get_cache_version("assets")  # "1.0.8" ou hash "a3f2c1d4"
get_cache_version("cookies") # "1.0.0"
get_cache_version("global")  # "1.0.0"

versioned_static_url("css/main.css")                    # "/static/css/main.css?v=1.0.3"
versioned_static_url("data/file.txt", kind="global")    # "/static/data/file.txt?v=1.0.0"

Gestion des cookies versionnés

from xeolux_cachekit import (
    versioned_cookie_name,
    set_versioned_cookie,
    get_versioned_cookie,
)

versioned_cookie_name("xeolux_consent")
# → "xeolux_consent_v1_0_0"

# Dans une vue Django
def ma_vue(request):
    response = HttpResponse("OK")
    set_versioned_cookie(response, "xeolux_consent", "true", max_age=365 * 24 * 3600)
    return response

def ma_vue(request):
    consent = get_versioned_cookie(request, "xeolux_consent", default="false")

Commandes Django

Afficher les versions configurées

python manage.py show_cache_versions

XEOLUX CacheKit versions:
  - Global      : 1.0.0
  - CSS         : 1.0.3
  - JS          : 1.2.0
  - Assets      : 1.0.8
  - Cookies     : 1.0.0
  - Query param : v

Incrémenter une version

python manage.py bump_cache_version css             # 1.0.3 → 1.0.4  (patch, défaut)
python manage.py bump_cache_version js --minor      # 1.2.0 → 1.3.0
python manage.py bump_cache_version assets --major  # 1.0.8 → 2.0.0
python manage.py bump_cache_version all             # tout incrémenter
python manage.py bump_cache_version css --dry-run   # aperçu sans écriture

Si la version est définie via une variable d'environnement (os.environ, env(), etc.), la commande le détecte et affiche un message demandant de modifier le .env manuellement.

Lancer les tests

pip install pytest pytest-django
pytest

Configuration complète — Exemple

# settings.py

INSTALLED_APPS = [
    ...
    "xeolux_cachekit",
]

MIDDLEWARE = [
    ...
    "xeolux_cachekit.middleware.CacheControlMiddleware",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
                "xeolux_cachekit.context_processors.cache_versions",
            ],
        },
    }
]

XEOLUX_CACHEKIT = {
    "global":      "1.0.0",
    "css":         "1.0.3",
    "js":          "1.2.0",
    "assets":      "1.0.8",
    "cookies":     "1.0.0",
    "query_param": "v",
    "strategy":    "manual",  # ou "hash" pour hash automatique
}

Licence

MIT — voir LICENSE.

Package Django interne XEOLUX pour gérer les versions de cache des fichiers statiques (CSS, JS, assets) et des cookies.

Présentation

xeolux-cachekit permet d'ajouter automatiquement un paramètre de version aux URLs de fichiers statiques dans vos templates Django :

/static/css/main.css?v=1.0.3
/static/js/app.js?v=1.2.0
/static/img/logo.svg?v=1.0.8

Il fournit également des helpers pour nommer et manipuler les cookies avec un suffixe de version.

Installation locale

pip install -e /chemin/vers/xeolux-cachekit

Ou ajoutez dans votre requirements.txt / pyproject.toml :

xeolux-cachekit @ file:///chemin/vers/xeolux-cachekit

Configuration

1. Ajout dans INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    ...
    "xeolux_cachekit",
]

2. Ajout du context processor

# settings.py
TEMPLATES = [
    {
        ...
        "OPTIONS": {
            "context_processors": [
                ...
                "xeolux_cachekit.context_processors.cache_versions",
            ],
        },
    }
]

3. Configuration des versions

Option A — Configuration centralisée (recommandée) :

# settings.py
XEOLUX_CACHEKIT = {
    "global": "1.0.0",
    "css": "1.0.3",
    "js": "1.2.0",
    "assets": "1.0.8",
    "cookies": "1.0.0",
    "query_param": "v",    # nom du paramètre dans l'URL (?v=...)
}

Option B — Variables individuelles :

# settings.py
XEOLUX_GLOBAL_VERSION = "1.0.0"
XEOLUX_CSS_VERSION    = "1.0.3"
XEOLUX_JS_VERSION     = "1.2.0"
XEOLUX_ASSETS_VERSION = "1.0.8"
XEOLUX_COOKIE_VERSION = "1.0.0"

Priorité : XEOLUX_CACHEKIT > variables individuelles > valeurs par défaut ("1.0.0" / "v").

Utilisation dans les templates

{% load cachekit_tags %}

<!-- Détection automatique du type selon l'extension -->
<link rel="stylesheet" href="{% versioned_static 'css/main.css' %}">
<script src="{% versioned_static 'js/app.js' %}"></script>
<img src="{% versioned_static 'img/logo.svg' %}">
<link rel="icon" href="{% versioned_static 'favicon.ico' %}">

<!-- Forcer le type manuellement -->
<link rel="stylesheet" href="{% versioned_static_as 'css/main.css' 'css' %}">
<script src="{% versioned_static_as 'js/app.js' 'js' %}"></script>
<img src="{% versioned_static_as 'img/logo.png' 'assets' %}">
<a href="{% versioned_static_as 'data/file.txt' 'global' %}">Télécharger</a>

Les variables injectées par le context processor sont aussi disponibles directement :

<p>Version CSS : {{ CACHEKIT_CSS_VERSION }}</p>
<p>Version JS : {{ CACHEKIT_JS_VERSION }}</p>

Types détectés automatiquement

Extension	Type
`.css`	`css`
`.js`	`js`
`.ico`, `.png`, `.jpg`, `.jpeg`, `.svg`, `.webp`, `.gif`, `.avif`	`assets`
Autre	`global`

Utilisation en Python

from xeolux_cachekit import get_cache_version, versioned_static_url

# Obtenir une version
get_cache_version("css")       # "1.0.3"
get_cache_version("js")        # "1.2.0"
get_cache_version("assets")    # "1.0.8"
get_cache_version("cookies")   # "1.0.0"
get_cache_version("global")    # "1.0.0"

# Générer une URL versionnée
versioned_static_url("css/main.css")               # "/static/css/main.css?v=1.0.3"
versioned_static_url("img/logo.svg")               # "/static/img/logo.svg?v=1.0.8"
versioned_static_url("data/file.txt", kind="global")  # "/static/data/file.txt?v=1.0.0"

Gestion des cookies versionnés

from xeolux_cachekit import (
    versioned_cookie_name,
    set_versioned_cookie,
    get_versioned_cookie,
)

# Nom du cookie avec suffixe de version
versioned_cookie_name("xeolux_consent")
# → "xeolux_consent_v1_0_0"

# Définir un cookie versionné dans une vue Django
def ma_vue(request):
    response = HttpResponse("OK")
    set_versioned_cookie(response, "xeolux_consent", "true", max_age=365 * 24 * 3600)
    return response

# Lire un cookie versionné
def ma_vue(request):
    consent = get_versioned_cookie(request, "xeolux_consent", default="false")
    ...

Commande de diagnostic

python manage.py show_cache_versions

Sortie :

XEOLUX CacheKit versions:
  - Global      : 1.0.0
  - CSS         : 1.0.3
  - JS          : 1.2.0
  - Assets      : 1.0.8
  - Cookies     : 1.0.0
  - Query param : v

Lancer les tests

pip install pytest pytest-django
pytest

Exemple de configuration complète

# settings.py

INSTALLED_APPS = [
    ...
    "xeolux_cachekit",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
                "xeolux_cachekit.context_processors.cache_versions",
            ],
        },
    }
]

XEOLUX_CACHEKIT = {
    "global": "1.0.0",
    "css": "1.0.3",
    "js": "1.2.0",
    "assets": "1.0.8",
    "cookies": "1.0.0",
    "query_param": "v",
}

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

0.1.0

Apr 27, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xeolux_cachekit-0.1.0.tar.gz (28.9 kB view details)

Uploaded Apr 27, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

xeolux_cachekit-0.1.0-py3-none-any.whl (24.0 kB view details)

Uploaded Apr 27, 2026 Python 3

File details

Details for the file xeolux_cachekit-0.1.0.tar.gz.

File metadata

Download URL: xeolux_cachekit-0.1.0.tar.gz
Upload date: Apr 27, 2026
Size: 28.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.3

File hashes

Hashes for xeolux_cachekit-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`5876900912d80791590a71dc44d66210a197266d08ba7a0575df7c3a56778a45`
MD5	`6bf766e9be69d2e17e63a6a5c1d655d9`
BLAKE2b-256	`0734f3f37329d0dfb6550b2fe0e6de640a2f320a642a436594dcf83ce32b39b1`

See more details on using hashes here.

File details

Details for the file xeolux_cachekit-0.1.0-py3-none-any.whl.

File metadata

Download URL: xeolux_cachekit-0.1.0-py3-none-any.whl
Upload date: Apr 27, 2026
Size: 24.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.3

File hashes

Hashes for xeolux_cachekit-0.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`cdebc3b37f43b031ea71a9e60a77d449c70eb362a5ccfacb79a3c3ea22f4cdec`
MD5	`605a65811d4c5c329ac6995c923d8452`
BLAKE2b-256	`e48a0e3d34e85f31c3c73dd80f496e82408b88b2cb246fef891256c046288270`

See more details on using hashes here.

xeolux-cachekit 0.1.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

xeolux-cachekit

Fonctionnalités

Installation

Configuration

1. INSTALLED_APPS

2. Context processor

3. Middleware (optionnel)

4. Versions — Configuration

Utilisation dans les templates

Types détectés automatiquement

Utilisation en Python

Gestion des cookies versionnés

Commandes Django

Afficher les versions configurées

Incrémenter une version

Lancer les tests

Configuration complète — Exemple

Licence

Présentation

Installation locale

Configuration

1. Ajout dans INSTALLED_APPS

2. Ajout du context processor

3. Configuration des versions

Utilisation dans les templates

Types détectés automatiquement

Utilisation en Python

Gestion des cookies versionnés

Commande de diagnostic

Lancer les tests

Exemple de configuration complète

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

1. `INSTALLED_APPS`