:py:mod:`dissect.target.helpers.magic.magic`
============================================

.. py:module:: dissect.target.helpers.magic.magic


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

Classes
~~~~~~~

.. autoapisummary::

   dissect.target.helpers.magic.magic.Magic


Functions
~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   dissect.target.helpers.magic.magic.from_file
   dissect.target.helpers.magic.magic.from_entry
   dissect.target.helpers.magic.magic.from_descriptor
   dissect.target.helpers.magic.magic.from_buffer


Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.target.helpers.magic.magic.MagicSignature
   dissect.target.helpers.magic.magic.MagicResult
   dissect.target.helpers.magic.magic.from_fh


.. py:type:: MagicSignature
   :canonical: tuple[str, str, bytes]


.. py:type:: MagicResult
   :canonical: str | None


.. py:class:: Magic

   Magic is a helper class for identifying files to a file type by magic bytes.

   This class mimics ``python-magic`` behaviour, however this implementation does
   not depend on the ``libmagic`` C-library system package. Instead a precompiled
   XML document of FreeDesktop's shared-mime-info project is used to identify files.

   Falls back to file extensions (where applicable) if no magic header is detected
   in the provided buffer.

   The underlying implementation currently does not support nested magic definitions
   and logical AND/OR matches, which somewhat limits the supported FreeDesktop XML
   magic signature set.

   .. code-block:: python

       from dissect.target.helpers import magic

       >>> magic.from_buffer(b"SQLite format 3 FILE DATAM<²¡")
       "SQLite3 database"

       >>> magic.from_file(target.fs.path("file.jpg"), mime=True)
       "image/jpg"

   Currently does not implement ``python-magic`` :class:`Magic` invocation behaviour.

   Resources:
       - https://github.com/ahupp/python-magic/blob/master/magic/__init__.py
       - https://github.com/file/file/tree/master/magic
       - https://freedesktop.org/wiki/Specifications/shared-mime-info-spec/
       - https://gitlab.freedesktop.org/xdg/shared-mime-info/-/blob/master/data/freedesktop.org.xml.in


   .. py:method:: detect(buf: BinaryIO, suffix: str | None = None, *, mime: bool = False) -> MagicResult
      :staticmethod:


      Searches ``mimetypes.MAP`` for the given bytes.


.. py:function:: from_file(path: pathlib.Path, *, mime: bool = False) -> MagicResult

   Detect file type from a :class:`Path` instance.


.. py:function:: from_entry(entry: dissect.target.filesystem.FilesystemEntry, *, mime: bool = False) -> MagicResult

   Detect file type from a :class:`FilesystemEntry` instance.


.. py:function:: from_descriptor(fh: BinaryIO, suffix: str | None = None, *, mime: bool = False) -> MagicResult

   Detect file type from a file descriptor or handle.


.. py:data:: from_fh

.. py:function:: from_buffer(buf: bytes, suffix: str | None = None, *, mime: bool = False) -> MagicResult

   Detect file type from provided bytes or buffer of bytes.