file.attachments
================

.. py:module:: file.attachments


Attributes
----------

.. autoapisummary::

   file.attachments.IMAGE_MAX_SIZE
   file.attachments.IMAGE_QUALITY
   file.attachments.CHECKSUM_FUNCTION


Classes
-------

.. autoapisummary::

   file.attachments._ImageSaveOptionalParams
   file.attachments.ProcessedUploadedFile


Functions
---------

.. autoapisummary::

   file.attachments.get_svg_size_or_default
   file.attachments.strip_exif_and_store_image_size
   file.attachments.resize_image
   file.attachments.store_checksum
   file.attachments.sanitize_svg_images
   file.attachments.store_extract_and_pages


Module Contents
---------------

.. py:class:: _ImageSaveOptionalParams

   Bases: :py:obj:`TypedDict`


   dict() -> new empty dictionary
   dict(mapping) -> new dictionary initialized from a mapping object's
       (key, value) pairs
   dict(iterable) -> new dictionary initialized as if via:
       d = {}
       for k, v in iterable:
           d[k] = v
   dict(**kwargs) -> new dictionary initialized with the name=value pairs
       in the keyword argument list.  For example:  dict(one=1, two=2)


   .. py:attribute:: exif
      :type:  NotRequired[PIL.Image.Exif]


.. py:data:: IMAGE_MAX_SIZE
   :value: 4096


.. py:data:: IMAGE_QUALITY
   :value: 85


.. py:data:: CHECKSUM_FUNCTION
   :value: 'md5'


.. py:function:: get_svg_size_or_default(content: IO[bytes]) -> tuple[str, str]

.. py:function:: strip_exif_and_store_image_size(file: ProcessedUploadedFile, content: IO[bytes], content_type: str | None) -> IO[bytes] | None

.. py:function:: resize_image(content: IO[bytes], max_size: int = IMAGE_MAX_SIZE) -> IO[bytes]

   Resize an image so that neither dimension exceeds *max_size*.

   When a resize is performed the EXIF orientation is baked in and the EXIF
   block is stripped in the same pass, so the depot processor's EXIF-stripping
   step becomes a no-op and the image is only encoded once.

   Non-image streams and images that are already within the limit are returned
   unchanged (seeked to 0).  Large images are resampled into a new
   SpooledTemporaryFile.


.. py:function:: store_checksum(file: ProcessedUploadedFile, content: IO[bytes], content_type: str | None) -> None

.. py:function:: sanitize_svg_images(file: ProcessedUploadedFile, content: IO[bytes], content_type: str | None) -> IO[bytes]

.. py:function:: store_extract_and_pages(file: ProcessedUploadedFile, content: IO[bytes], content_type: str | None) -> None

.. py:class:: ProcessedUploadedFile(content, depot_name=None)

   Bases: :py:obj:`depot.fields.upload.UploadedFile`


   Simple :class:`depot.fields.interfaces.DepotFileInfo` implementation that stores files.

   Takes a file as content and uploads it to the depot while saving around
   most file information. Pay attention that if the file gets replaced
   through depot manually the ``UploadedFile`` will continue to have the old data.

   Also provides support for encoding/decoding using JSON for storage inside
   databases as a plain string.

   Default attributes provided for all ``UploadedFile`` include:
       - filename     - This is the name of the uploaded file
       - file_id      - This is the ID of the uploaded file
       - path         - This is a depot_name/file_id path which can
                        be used with :meth:`DepotManager.get_file` to retrieve the file
       - content_type - This is the content type of the uploaded file
       - uploaded_at  - This is the upload date in YYYY-MM-DD HH:MM:SS format
       - url          - Public url of the uploaded file
       - file         - The :class:`depot.io.interfaces.StoredFile` instance of the stored file


   .. py:attribute:: processors


   .. py:method:: process_content(content: depot.io.interfaces._FileContent, filename: str | None = None, content_type: str | None = None) -> None

      Standard implementation of :meth:`.DepotFileInfo.process_content`

      This is the standard depot implementation of files upload, it will
      store the file on the default depot and will provide the standard
      attributes.

      Subclasses will need to call this method to ensure the standard
      set of attributes is provided.