This class provides functionality to rename files by appending a content-based hash for cache-busting and updates internal references within those files to point to the new hashed filenames. It supports processing for CSS and JavaScript files, including handling for source maps and modern JS module imports. The mixin manages multiple processing passes to resolve nested dependencies and ensures that file URLs are correctly mapped in both development and production environments.
Attributes
| Attribute | Type | Description |
|---|
| default_template | string = """url("%(url)s")""" | The default string template used to wrap processed URLs when no specific template is provided in the patterns. |
| max_post_process_passes | int = 5 | The maximum number of times the post-processing loop will run to resolve circular or nested file references. |
| support_js_module_import_aggregation | boolean = false | A boolean flag that determines whether JavaScript module import and export statements should be included in the URL replacement process. |
| patterns | tuple | A collection of file extensions and associated regex patterns used to find and replace file references with their hashed equivalents. |
| keep_intermediate_files | boolean = true | A boolean flag that controls whether intermediate versions of files created during multi-pass processing are saved to storage. |
Constructor
Signature
def HashedFilesMixin(
*args: any,
**kwargs: any
) - > null
Parameters
| Name | Type | Description |
|---|
| *args | any | Variable length argument list passed to the parent constructor. |
| **kwargs | any | Arbitrary keyword arguments passed to the parent constructor. |
Methods
file_hash()
@classmethod
def file_hash(
name: string,
content: [File](../../../core/files/base/file.md?sid=django_core_files_base_file) = null
) - > string
Return a hash of the file with the given name and optional content.
Parameters
| Name | Type | Description |
|---|
| name | string | The name of the file to be hashed |
| content | [File](../../../core/files/base/file.md?sid=django_core_files_base_file) = null | The file-like object containing the data to hash |
Returns
| Type | Description |
|---|
string | A 12-character MD5 hash string of the file content, or None if no content is provided |
hashed_name()
@classmethod
def hashed_name(
name: string,
content: [File](../../../core/files/base/file.md?sid=django_core_files_base_file) = null,
filename: string = null
) - > string
Generates a unique filename by appending a content hash to the original file name. This is used for cache-busting by ensuring file names change when their contents do.
Parameters
| Name | Type | Description |
|---|
| name | string | The base name or URL path used to construct the new hashed filename |
| content | [File](../../../core/files/base/file.md?sid=django_core_files_base_file) = null | Optional file-like object to hash; if omitted, the method attempts to open the file from storage |
| filename | string = null | The actual disk filename to use for hashing if it differs from the provided name |
Returns
| Type | Description |
|---|
string | The file path with the content hash inserted before the file extension |
url()
@classmethod
def url(
name: string,
force: boolean = false
) - > string
Return the non-hashed URL in DEBUG mode.
Parameters
| Name | Type | Description |
|---|
| name | string | The file path for which to generate a URL |
| force | boolean = false | Whether to bypass DEBUG settings and return a hashed URL |
Returns
| Type | Description |
|---|
string | The URL for the given file name, hashed unless DEBUG is True |
@classmethod
def get_comment_blocks(
content: string,
include_line_comments: boolean = false
) - > array
Return a list of (start, end) tuples for each comment block.
Parameters
| Name | Type | Description |
|---|
| content | string | The text content to scan for comment blocks |
| include_line_comments | boolean = false | Whether to include single-line comments in the results |
Returns
| Type | Description |
|---|
array | A list of tuples containing the start and end character indices of comments in the content |
@classmethod
def is_in_comment(
pos: integer,
comments: array
) - > boolean
Determines if a specific character position falls within any of the provided comment blocks. This helps avoid processing URLs found inside code comments.
Parameters
| Name | Type | Description |
|---|
| pos | integer | The character index to check |
| comments | array | A list of (start, end) tuples representing comment ranges |
Returns
| Type | Description |
|---|
boolean | True if the position is inside a comment block, False otherwise |
url_converter()
@classmethod
def url_converter(
name: string,
hashed_files: dict,
template: string = null,
comment_blocks: array = null
) - > callable
Return the custom URL converter for the given file name.
Parameters
| Name | Type | Description |
|---|
| name | string | The name of the file currently being processed |
| hashed_files | dict | A dictionary mapping original file paths to their hashed versions |
| template | string = null | The string template used to format the converted URL |
| comment_blocks | array = null | A list of character ranges to ignore during conversion |
Returns
| Type | Description |
|---|
callable | A function that takes a regex match object and returns a string with the hashed URL |
post_process()
@classmethod
def post_process(
paths: dict,
dry_run: boolean = false
) - > generator
Post process the given dictionary of files (called from collectstatic).
Parameters
| Name | Type | Description |
|---|
| paths | dict | A dictionary of file paths to be processed |
| dry_run | boolean = false | If true, the method returns early without performing any file operations |
Returns
| Type | Description |
|---|
generator | Yields tuples of (original_path, hashed_path, processed_status) |
clean_name()
@classmethod
def clean_name(
name: string
) - > string
Normalizes file paths by replacing backslashes with forward slashes. This ensures consistent path formatting across different operating systems.
Parameters
| Name | Type | Description |
|---|
| name | string | The file path to normalize |
Returns
| Type | Description |
|---|
string | The normalized path string |
hash_key()
@classmethod
def hash_key(
name: string
) - > string
Generates a lookup key for the hashed files cache. In this implementation, it returns the cleaned name directly.
Parameters
| Name | Type | Description |
|---|
| name | string | The cleaned file name |
Returns
| Type | Description |
|---|
string | The key used to identify the file in the hashed_files dictionary |
stored_name()
@classmethod
def stored_name(
name: string
) - > string
Retrieves the hashed name of a file from the internal cache or calculates it if missing. It will attempt multiple passes to resolve dependencies in adjustable files.
Parameters
| Name | Type | Description |
|---|
| name | string | The original file name to look up |
Returns
| Type | Description |
|---|
string | The final hashed filename |