.. nobodd: a boot configuration tool for the Raspberry Pi
..
.. Copyright (c) 2023-2026 Dave Jones <dave.jones@canonical.com>
.. Copyright (c) 2023-2026 Canonical Ltd.
..
.. SPDX-License-Identifier: GPL-3.0

===============
nobodd.fs
===============

.. module:: nobodd.fs

The :mod:`nobodd.fs` module contains the :class:`FatFileSystem` class which is
the primary entry point for reading FAT file-systems. Constructed with a buffer
object representing a memory mapping of the file-system, the class will
determine whether the format is FAT12, FAT16, or FAT32. The
:attr:`~FatFileSystem.root` attribute provides a Path-like object representing
the root directory of the file-system.

.. code-block:: pycon

    >>> from nobodd.disk import DiskImage
    >>> from nobodd.fs import FatFileSystem
    >>> img = DiskImage('test-gpt.img')
    >>> fs = FatFileSystem(img.partitions[1].data)
    >>> fs.fat_type
    'fat16'
    >>> fs.root
    FatPath(<FatFileSystem label='TEST' fat_type='fat16'>, '/')

.. warning::

    The implementation will *not* handle certain "obscure" extensions to FAT,
    such as sub-directory style roots on FAT-12/16. It will attempt to warn
    about these and abort if they are found.


FatFileSystem
=============

.. autoclass:: FatFileSystem


FatFile
=======

.. autoclass:: FatFile


Exceptions and warnings
=======================

.. autoexception:: FatWarning

.. autoexception:: DirtyFileSystem

.. autoexception:: DamagedFileSystem

.. autoexception:: OrphanedLongFilename

.. autoexception:: BadLongFilename


Support classes and functions
==============================

You should never need to interact with these classes directly; use
:class:`FatFileSystem` instead. These classes exist to enumerate and manipulate
the FAT, and different types of root directory under FAT-12, FAT-16, and
FAT-32, and sub-directories (which are common across FAT types).

.. autoclass:: FatTable

.. autoclass:: Fat12Table

.. autoclass:: Fat16Table

.. autoclass:: Fat32Table

.. autoclass:: FatClusters

.. autoclass:: FatDirectory
   :members:
   :private-members:

.. autoclass:: FatRoot

.. autoclass:: FatSubDirectory

.. autoclass:: Fat12Root

.. autoclass:: Fat16Root

.. autoclass:: Fat32Root

.. autofunction:: fat_type

.. autofunction:: fat_type_from_count