simfile.dir
===========

.. py:module:: simfile.dir


Exceptions
----------

.. autoapisummary::

   simfile.dir.DuplicateSimfileError


Classes
-------

.. autoapisummary::

   simfile.dir.SimfileDirectory
   simfile.dir.SimfilePack


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

.. py:exception:: DuplicateSimfileError

   Bases: :py:obj:`Exception`


   Raised when a simfile directory contains multiple simfiles of the same
   type (e.g. two SM files).


.. py:class:: SimfileDirectory(simfile_dir: str, *, filesystem: simfile._private.fs.FS = NativeOSFS(), ignore_duplicate=False)

   A simfile directory, containing an SM and/or SSC file, or neither.

   Raises :class:`DuplicateSimfileError` if the directory contains
   multiple simfiles of the same type (e.g. two SM files).


   .. py:attribute:: sm_path
      :type:  Optional[str]
      :value: None


      Absolute path to the SM file, if present.



   .. py:attribute:: ssc_path
      :type:  Optional[str]
      :value: None


      Absolute path to the SSC file, if present.



   .. py:attribute:: simfile_dir
      :value: b'.'



   .. py:attribute:: filesystem


   .. py:property:: simfile_path

      The SSC path if present, otherwise the SM path.



   .. py:method:: open(**kwargs) -> simfile.types.Simfile

      Open the simfile in this directory.

      If both SSC and SM are present, SSC is preferred. Keyword arguments
      are passed down to :func:`simfile.open`.

      Raises :code:`FileNotFoundError` if there is no SM or SSC file in
      the directory.



   .. py:method:: assets() -> simfile.assets.Assets

      Get the file assets for this simfile.



.. py:class:: SimfilePack(pack_dir: str, *, filesystem: simfile._private.fs.FS = NativeOSFS(), ignore_duplicate: bool = False)

   A simfile pack directory, containing any number of simfile directories.

   Only immediate subdirectories of :code:`pack_dir` containing an SM or
   SSC file are included. Simfiles aren't guaranteed to appear in any
   particular order.


   .. py:attribute:: simfile_dir_paths
      :type:  Tuple[str, Ellipsis]

      Absolute paths to the simfile directories in this pack.



   .. py:attribute:: pack_dir
      :value: b'.'



   .. py:attribute:: filesystem


   .. py:method:: simfile_dirs() -> Iterator[SimfileDirectory]

      Iterator over the simfile directories in the pack.



   .. py:method:: simfiles(**kwargs) -> Iterator[simfile.types.Simfile]

      Iterator over the simfiles in the pack.

      If both SSC and SM are present in a simfile directory, SSC is
      preferred. Keyword arguments are passed down to
      :func:`simfile.open`.



   .. py:property:: name

      Get the name of the pack (the directory name by itself).



   .. py:method:: banner() -> Optional[str]

      Get the pack's banner image, if present, as an absolute path.

      Follows the same logic as StepMania:

      * When there are multiple images in the pack directory, the banner
        is chosen first by extension priority (PNG is highest, then JPG,
        JPEG, GIF, BMP), then alphabetically.
      * If there are no images in the pack directory, checks for a banner
        *alongside* the pack with the same base name, using the same
        extension priority as before.