:py:mod:`dissect.target.loader`
===============================

.. py:module:: dissect.target.loader


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

Classes
~~~~~~~

.. autoapisummary::

   dissect.target.loader.Loader



Functions
~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   dissect.target.loader.register
   dissect.target.loader.open



Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.target.loader.RawLoader


.. py:data:: RawLoader
   :type: Loader

   A lazy loaded :class:`dissect.target.loaders.raw.RawLoader`.

.. py:class:: Loader(path: pathlib.Path, **kwargs)


   A base class for loading a specific path and coupling it to a :class:`Target <dissect.target.target.Target>`.

   Implementors of this class are responsible for mapping any type of source data
   to a :class:`Target <dissect.target.target.Target>`.
   Whether that's to map all VMDK files from a VMX or mapping the contents of a zip file to a virtual filesystem,
   if it's something that can be translated to a "disk", "volume" or "filesystem", you can write a loader that
   maps it into a target.

   You can do anything you want to manipulate the :class:`Target <dissect.target.target.Target>` object
   in your ``map`` function, but generally you do one of the following:

   * open a :class:`Container <dissect.target.container.Container>` and add it to ``target.disks``.
   * open a :class:`Volume <dissect.target.volume.Volume>` and add it to ``target.volumes``.
   * open a :class:`VirtualFilesystem <dissect.target.filesystem.VirtualFilesystem>`,    add your files into it and add it to ``target.filesystems``.

   You don't need to manually parse volumes or filesystems in your loader, just add the highest level object you have
   (e.g. a :class:`Container <dissect.target.container.Container>` of a VMDK file) to the target.
   However, sometimes you need to get creative.
   Take a look at the :class:`ITunesLoader <dissect.target.loaders.itunes.ITunesLoader>` and
   :class:`TarLoader <dissect.target.loaders.tar.TarLoader>` for some creative examples.

   :param path: The target path to load.

   .. py:method:: __repr__()

      Return repr(self).


   .. py:method:: detect(path: pathlib.Path) -> bool
      :staticmethod:
      :abstractmethod:

      Detects wether this ``Loader`` class can load this specific ``path``.

      :param path: The target path to check.

      :returns: ``True`` if the ``path`` can be loaded by a ``Loader`` instance. ``False`` otherwise.


   .. py:method:: find_all(path: pathlib.Path, **kwargs) -> Iterator[pathlib.Path]
      :staticmethod:

      Finds all targets to load from ``path``.

      This can be used to open multiple targets from a target path that doesn't necessarily map to files on a disk.
      For example, a wildcard in a hostname a loader that opens targets from an API or Unix socket,
      such as the Carbon Black loader.

      :param path: The location to a target to try and open multiple paths from.

      :returns: All the target paths found from the source path.


   .. py:method:: map(target: dissect.target.Target) -> None
      :abstractmethod:

      Maps the loaded path into a ``Target``.

      :param target: The target that we're mapping into.



.. py:function:: register(module_name: str, class_name: str, internal: bool = True) -> None

   Registers a ``Loader`` class inside ``LOADERS``.

   This function registers a loader using ``modname`` relative to the ``MODULE_PATH``.
   It lazily imports the module, and retrieves the specific class from it.

   :param module: The module where to find the loader.
   :param class_name: The class to load.
   :param internal: Whether it is an internal module or not.


.. py:function:: open(item: Union[str, pathlib.Path], *args, **kwargs) -> Loader

   Opens a :class:`Loader` for a specific ``item``.

   This instantiates a :class:`Loader` for a specific ``item``.
   The :class:`DirLoader <dissect.target.loaders.dir.DirLoader>` is used as the last entry
   due to how the detection methods function.

   :param item: The target path to load.

   :returns: A :class:`Loader` class for the specific target if one exists.