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

.. py:module:: dissect.target.container


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

Classes
~~~~~~~

.. autoapisummary::

   dissect.target.container.Container



Functions
~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   dissect.target.container.register
   dissect.target.container.open



Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.target.container.CONTAINERS
   dissect.target.container.MODULE_PATH
   dissect.target.container.RawContainer
   dissect.target.container.log


.. py:data:: CONTAINERS
   :type: list[Type[Container]]
   :value: []

   

.. py:data:: MODULE_PATH
   :value: 'dissect.target.containers'

   

.. py:data:: RawContainer

   A lazy import of :mod:`dissect.target.containers.raw`

.. py:data:: log

   

.. py:class:: Container(fh: Union[BinaryIO, pathlib.Path], size: int, vs: dissect.target.volume.VolumeSystem = None)


   Bases: :py:obj:`io.IOBase`

   Base class that acts as a file-like object wrapper around anything that can behave like a "raw disk".

   Containers are anything from raw disk images and virtual disks, to evidence containers and made-up binary formats.
   Consumers of the ``Container`` class only need to implement ``seek``, ``tell`` and ``read``.
   Override ``__init__`` for any opening that you may need to do, but don't forget to initialize the super class.

   :param fh: The source file-like object of the container or a ``Path`` object to the file.
   :param size: The size of the container.
   :param vs: An optional shorthand to set the underlying volume system, usually set later.

   .. py:attribute:: __type__
      :type: str

      A short string identifying the type of container.

   .. py:method:: __repr__() -> str

      Return repr(self).


   .. py:method:: detect(item: Union[list, BinaryIO, pathlib.Path]) -> bool
      :classmethod:

      Detect if this ``Container`` can handle this file format.

      :param item: The object we want to see if it can be handled by this ``Container``.

      :returns: ``True`` if this ``Container`` can be used, ``False`` otherwise.


   .. py:method:: detect_fh(fh: BinaryIO, original: Union[list, BinaryIO]) -> bool
      :classmethod:

      Detect if this ``Container`` can be used to open the file-like object ``fh``.

      The function checks whether the raw data contains any magic information that corresponds to this
      specific container.

      :param fh: A file-like object that we want to open a ``Container`` on.
      :param original: The original argument passed to ``detect()``.

      :returns: ``True`` if this ``Container`` can be used for this file-like object, ``False`` otherwise.


   .. py:method:: detect_path(path: pathlib.Path, original: Union[list, pathlib.Path]) -> bool
      :staticmethod:
      :abstractmethod:

      Detect if this ``Container`` can be used to open ``path``.

      The function checks wether file inside ``path`` is formatted in such a way that
      this ``Container`` can be used to read it. For example, it validates against the
      file extension.

      :param path: A location to a file.
      :param original: The original argument passed to ``detect()``.

      :returns: ``True`` if this ``Container`` can be used for this path, ``False`` otherwise.


   .. py:method:: read(length: int = -1) -> bytes
      :abstractmethod:

      Read a ``length`` of bytes from this ``Container``.


   .. py:method:: readinto(b: bytearray) -> int

      Uses :func:`dissect.target.helpers.utils.readinto`.


   .. py:method:: seek(offset: int, whence: int = io.SEEK_SET) -> int
      :abstractmethod:

      Change the stream position to ``offset``.

      ``whence`` determines where to seek from:

      * ``io.SEEK_SET`` (``0``):: absolute offset in the stream.
      * ``io.SEEK_CUR`` (``1``):: current position in the stream.
      * ``io.SEEK_END`` (``2``):: end of stream.

      :param offset: The offset relative to the position indicated by ``whence``.
      :param whence: Where to start the seek from.


   .. py:method:: seekable() -> bool

      Returns whether ``seek`` can be used by this ``Container``. Always ``True``.


   .. py:method:: tell() -> int
      :abstractmethod:

      Returns the current seek position of the ``Container``.


   .. py:method:: close() -> None
      :abstractmethod:

      Close the container.

      Override this if you need to clean-up anything.



.. py:function:: register(module: str, class_name: str, internal: bool = True)

   Register a container implementation to use when opening a container.

   This function registers a container using ``module`` 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 container.
   :param class_name: The class to load.
   :param internal: Whether it is an internal module or not.


.. py:function:: open(item: Union[list, str, BinaryIO, pathlib.Path], *args, **kwargs)

   Open a :class:`Container` from the given object.

   All currently supported containers are checked to find a compatible one.
   :class:`RawContainer <dissect.target.containers.raw.RawContainer>` must always be checked last
   since it always succeeds!

   :param item: The object we want to open a :class`Container` from.

   :raises ContainerError: When a compatible :class`Container` was found but it failed to open.
   :raises ContainerError: When no compatible :class`Container` implementations were found.