Metadata-Version: 2.1
Name: pyfatfs
Version: 1.1.0
Summary: FAT12/FAT16/FAT32 implementation with VFAT support
Author-email: "Nathan-J. Hirschauer" <nathanhi@deepserve.info>
License: MIT License
        
        Copyright (c) 2018-2024 pyfatfs contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/nathanhi/pyfatfs
Project-URL: Documentation, https://pyfatfs.readthedocs.io
Project-URL: Changelog, https://github.com/nathanhi/pyfatfs/blob/master/CHANGELOG.rst
Project-URL: Issues, https://github.com/nathanhi/pyfatfs/issues
Project-URL: Source, https://github.com/nathanhi/pyfatfs
Keywords: filesystem,PyFilesystem2,FAT12,FAT16,FAT32,VFAT,LFN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
Requires-Python: ~=3.8
Description-Content-Type: text/x-rst
Provides-Extra: development
License-File: LICENSE

.. image:: https://img.shields.io/github/actions/workflow/status/nathanhi/pyfatfs/test.yml?style=flat-square
    :target: https://github.com/nathanhi/pyfatfs/actions/workflows/test.yml
    :alt: CI build status
.. image:: https://img.shields.io/readthedocs/pyfatfs?style=flat-square
    :target: https://pyfatfs.readthedocs.io/
    :alt: Read the Docs
.. image:: https://img.shields.io/coveralls/github/nathanhi/pyfatfs?style=flat-square
    :target: https://coveralls.io/github/nathanhi/pyfatfs
    :alt: Test coverage overview
.. image:: https://img.shields.io/codacy/grade/3def4d7b0bcd4b6f9aa4bb64e0338540?style=flat-square
    :target: https://app.codacy.com/gh/nathanhi/pyfatfs
    :alt: Codacy Code Quality
.. image:: https://img.shields.io/pypi/pyversions/pyfatfs?style=flat-square
    :target: https://github.com/nathanhi/pyfatfs
    :alt: PyPI - Python Version
.. image:: https://img.shields.io/pypi/v/pyfatfs?style=flat-square
    :target: https://pypi.org/project/pyfatfs
    :alt: PyPI
.. image:: https://img.shields.io/github/license/nathanhi/pyfatfs.svg?style=flat-square
    :target: https://github.com/nathanhi/pyfatfs/blob/HEAD/LICENSE
    :alt: MIT License

pyfatfs
=======

pyfatfs is a filesystem module for use with `PyFilesystem2 <https://pypi.org/project/fs/>`_
for anyone who needs to access or modify files on a FAT filesystem. It also
provides a low-level API that allows direct interaction with a FAT filesystem
without PyFilesystem2 abstraction.

pyfatfs supports FAT12/FAT16/FAT32 as well as the VFAT extension (long file names).

Installation
------------

pyfatfs is available via PyPI as ``pyfatfs``, so just execute the following
command to install the package for your project:

.. code-block:: bash

   $ pip install pyfatfs


Usage
=====

The easiest way to get started with pyfatfs is to use it in conjunction
with PyFilesystem2:

PyFilesystem2
-------------

.. pyfilesystem-quickstart-begin

Use fs.open_fs to open a filesystem with a FAT `FS URL <https://pyfilesystem2.readthedocs.io/en/latest/openers.html>`_:

.. code-block:: python

   import fs
   my_fs = fs.open_fs("fat:///dev/sda1")


Parameters
''''''''''

It is possible to supply query parameters to the URI of the
PyFilesystem2 opener to influence certain behavior; it can
be compared to mount options. Multiple parameters can be
supplied by separating them via ``ampersand (&)``.

encoding
^^^^^^^^

pyfatfs offers an encoding parameter to allow overriding the
default encoding of ibm437 for file names, which was mainly
used by DOS and still is the `default on Linux <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/fs/fat/Kconfig?h=v5.10#n81>`_.

Any encoding known by Python can be used as value for this
parameter, but keep in mind that this might affect interoperability
with other systems, especially when the selected encoding/codepage
is not native or supported.

Please note that this only affects encoding of the 8DOT3 short file names, not
long file names of the VFAT extension, as LFN are always stored as UTF-16-LE.

.. code-block:: python

   import fs
   my_fs = fs.open_fs("fat:///dev/sda1?encoding=cp1252")


offset
^^^^^^

Specify an offset in bytes to skip when accessing the file. That way even
complete disk images can be read if the location of the partition is known:

.. code-block:: python

   import fs
   my_fs = fs.open_fs("fat:///dev/sda?offset=32256")


preserve_case
^^^^^^^^^^^^^

Preserve case when creating files. This will force LFN entries for all
created files that do not match the 8DOT3 rules. This defaults to ``true``
but can be disabled by setting preserve_case to ``false``:

.. code-block:: python

   import fs
   my_fs = fs.open_fs("fat:///dev/sda1?preserve_case=false")


read_only
^^^^^^^^^

Open filesystem in read-only mode and thus don't allow writes/modifications.
This defaults to false but can be enabled by setting read_only to ``true``:

.. code-block:: python

   import fs
   my_fs = fs.open_fs("fat:///dev/sda1?read_only=true")


utc
^^^

Create all timestamps on the filesystem in UTC time rather than local time.
Affects all directory entries' creation, modification and access times.

.. code-block:: python

    import fs
    my_fs = fs.open_fs("fat:///dev/sda1?utc=true")


lazy_load
^^^^^^^^^

If set to ``true`` (default), the directory entries are loaded only when accessed
to increase performance with larger filesystems and resilience against
recursion / directory loops.

.. code-block:: python

    import fs
    my_fs = fs.open_fs("fat:///dev/sda1?lazy_load=false")
.. pyfilesystem-quickstart-end

Testing
-------

Tests are located at the `tests` directory. In order to test your new
contribution to pyfatfs just run

.. code-block:: bash

    $ python setup.py test

from your shell.
