Configuration

Each of the following strings are valid as a dict key of the VIMAGE dict value. Confused? Take a look at a definition example of VIMAGE.

Note

The developer may provide a custom error which will be automatically HTML escaped. The string may also be translated. In order to do that, the value of the validation string must be a dict and the key of the custom error should be 'err'. Example:

from django.utils.translation import gettext_lazy as _

VIMAGE = {
    'myapp.models': {
        'SIZE': {
            'lt': 200,
            'err': _('Size should be less than <strong>200KB!</strong>'),
        },
    }
}

Note

If 'err' is not defined then a well-looking default error will appear.

[IMAGE {rule_name}] Validation error: {value} does not meet validation rule: {rule}.

  1. {rule_name} is replaced by the corresponding validation string
  2. {value} is replaced by the corresponding image value under test
  3. {rule} is replaced by the corresponding rule in a humanized form

'SIZE'

The 'SIZE' key corresponds to the image’s file size (measured in KB). It accepts two kind of value types: int or dict.

  • If it’s an int (must be a positive integer) then it is assumed that the file size of the uploaded image will be equal to the value defined.

    ‘SIZE’ with int as value
    VIMAGE = {
    'myapp.models': {
        # uploaded image file size should be equal to 100KB
        'SIZE': 100,
    }
}

  • If it’s a dict, then any str from operator strings table will be valid as long as it’s value is an int (positive integer). Also, take a look at this note.

    ‘SIZE’ with dict as value
    VIMAGE = {
    'myapp.models': {
        # uploaded image file size should be less than 200KB
        # and greater than 20KB
        'SIZE': {
            'lt': 200,
            'gt': 20,
            'err': 'custom error here'  # optional
        },
    }
}

'DIMENSIONS'

The 'DIMENSIONS' key corresponds to the image’s dimensions, width and height (measured in px). It accepts three kind of value types: tuple, list or dict.

  • If it’s a tuple (two-length tuple with positive integers) then it is assumed that the dimensions of the uploaded image will be equal to the value (tuple) defined ((width, height)).

    ‘DIMENSIONS’ with tuple as value
    VIMAGE = {
    'myapp.models': {
        # uploaded image dimensions should be equal to 800 x 600px
        # width == 800 and height == 600px
        'DIMENSIONS': (800, 600),
    }
}

  • If it’s a list (one or more two-length tuples with positive integers) then it is assumed that the dimensions of the uploaded image will be equal to one of the values defined in the list.

    ‘DIMENSIONS’ with list as value
    VIMAGE = {
    'myapp.models': {
        # uploaded image dimensions should be equal to one of the
        # following: 800x600px, 500x640px or 100x100px.
        'DIMENSIONS': [(800, 600), (500, 640), (100, 100)],
    }
}

  • If it’s a dict, then there are two cases. Either use operator strings table for keys and a two-length tuple of positive integers for values or use the strings 'w' and/or 'h' for keys and (another) dict for the value of each one using operator strings table for keys and a positive integer for values. Confused? Below are two examples that cover each case.

    ‘DIMENSIONS’ with dict as value and tuples as sub-values
    VIMAGE = {
    'myapp.models': {
        # uploaded image dimensions should be less than 1920x1080px
        # and greater than 800x768px.
        'DIMENSIONS': {
            'lt': (1920, 1080),
            'gt': (800, 768),
            'err': 'custom error here', # optional
        },
    }
}
    ‘DIMENSIONS’ with dict as value and 'w', 'h' as sub-keys
    VIMAGE = {
    'myapp.models': {
        # uploaded image width should not be equal to 800px and
        # height should be greater than 600px.
        'DIMENSIONS': {
            'w': {
                'ne': 800,  # set rule just for width
                'err': 'custom error here', # optional
            },
            'h': {
                'gt': 600,  # set rule just for height
                'err': 'custom error here', # optional
            }
        },
    }
}

    Note

    For custom error to work when defining both 'w' and 'h', the 'err' entry should be placed to both 'w' and 'h' dicts.

'FORMAT'

The 'FORMAT' key corresponds to the image’s format (it doesn’t have a measure unit since it’s just a string), i.e 'jpeg', 'png', 'webp' etc. Taking into account what image formats the browsers support VIMAGE allows the most used formats for the web, which are: 'jpeg', 'png', 'gif', 'bmp' and 'webp'. It accepts three kind of value types: str, list or dict.

  • If it’s a str then it is assumed that the format of the uploaded image will be equal to the value (str) defined.

    ‘FORMAT’ with str as value
    VIMAGE = {
    'myapp.models': {
        # uploaded image format should be 'jpeg'
        'FORMAT': 'jpeg',
    }
}

  • If it’s a list (list of strings) then it is assumed that the format of the uploaded image will be equal to one of the values defined in the list.

    ‘FORMAT’ with list as value
    VIMAGE = {
    'myapp.models': {
        # uploaded image format should be one of the following:
        # 'jpeg', 'png' or 'webp'.
        'FORMAT': ['jpeg', 'png', 'webp']
    }
}

  • If it’s a dict, then the keys must be either 'eq' or 'ne' (since the other operators cannot apply to str values) and as for the values they may be either a list or a str.

    ‘FORMAT’ with dict as value and str as sub-value
    VIMAGE = {
    'myapp.models': {
        # uploaded image format should not be 'png'.
        'FORMAT': {
            'ne': 'png',
            'err': 'custom error here', # optional
        },
    }
}
    ‘FORMAT’ with dict as value and list as sub-value
    VIMAGE = {
    'myapp.models': {
        # uploaded image format should not be equal to
        # neither `webp` nor 'bmp'.
        'FORMAT': {
            'ne': ['webp', 'bmp'],
            'err': 'custom error here', # optional
        },
    }
}

'ASPECT_RATIO'

The 'ASPECT_RATIO' key corresponds to the image’s width to height ratio (it doesn’t have a measure unit since it’s just a decimal number). It accepts two kind of value types: float or dict.

  • If it’s a float (positive) then it is assumed that the aspect ratio of the uploaded image will be equal to the value (float) defined.

    ‘ASPECT_RATIO’ with float as value
    VIMAGE = {
    'myapp.models': {
        # uploaded image aspect ratio should be equal to 1.2
        'ASPECT_RATIO': 1.2,
    }
}

  • If it’s a dict, then any str from operator strings table will be valid as long as it’s value is a positive float. Also, take a look at this note.

    ‘ASPECT_RATIO’ with dict as value
    VIMAGE = {
    'myapp.models': {
        # uploaded image aspect ratio should be less than 1.2
        'ASPECT_RATIO': {
            'lt': 2.1,
            'err': 'custom error here', # optional
        },
    }
}

If you are a table-person maybe this will help you:

Summarized table between validation strings and their dict values
Key Value type
'SIZE' <int> - image’s file size should be equal to this number <dict> - <operator_str>: <int>
'DIMENSIONS'

<tuple> - a two-length tuple of positive integers

<list> - a list of two-length tuples of positive integers

<dict> - <operator_str>: <tuple>

<dict> - 'w' and/or 'h': <dict> - <operator_str>: <int>
'FORMAT'

<str> - one of 'jpeg', 'png', 'gif', 'bmp', 'webp'

<list> - a list with one or more of the valid formats

<dict> - 'ne' or 'eq': <str> (one of the valid formats)

<dict> - 'ne' or 'eq': <list> (a list with one or more of the valid formats)
'ASPECT_RATIO'

<float> - a float number

<dict> - <operator_str>: <int>