{"id":5625,"library":"fatfs-ng","title":"fatfs-ng (Python FatFS Wrapper)","description":"fatfs-ng is an enhanced Python wrapper around ChaN's FatFS C library, building upon the `fatfs-python` project. It provides Pythonic access to FAT12, FAT16, and FAT32 filesystems, including VFAT (long file name) support. The library is currently at version 0.1.15 and appears to have a relatively active release cadence, albeit with minor version bumps.","status":"active","version":"0.1.15","language":"en","source_language":"en","source_url":"https://github.com/Jason2866/pyfatfs","tags":["filesystem","fat","fat12","fat16","fat32","vfat","embedded","wrapper"],"install":[{"cmd":"pip install fatfs-ng","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Often used for higher-level file system abstraction, though fatfs-ng (and its upstream pyfatfs) can also be used with a low-level API.","package":"PyFilesystem2","optional":true}],"imports":[{"note":"Based on the likely upstream 'pyfatfs' by nathanhi, which provides the core FAT filesystem implementation that 'fatfs-ng' is expected to wrap or extend. Direct import for 'fatfs-ng' specific classes is not documented under the provided GitHub link, which points to a different project.","symbol":"PyFatFS","correct":"from pyfatfs import PyFatFS"},{"note":"Used for creating an in-memory FAT filesystem, often found in examples for pyfatfs, the presumed upstream or closely related project.","symbol":"PyFatBytesIOFS","correct":"from pyfatfs import PyFatBytesIOFS"}],"quickstart":{"code":"from pyfatfs import PyFatBytesIOFS\nfrom fs.opener import open_fs\n\n# Create an in-memory FAT12 filesystem image (default size is 1.44MB floppy)\n# This uses PyFilesystem2's 'memfs' which is then formatted as FAT\n# For fatfs-ng specific usage, it might involve direct class instantiation or a different opener.\n# This example is adapted from pyfatfs documentation.\n\n# Initialize a PyFatBytesIOFS for an in-memory FAT filesystem\nfat_fs = PyFatBytesIOFS(size=1474560) # 1.44MB floppy size\n\n# Create a file and write to it\nwith fat_fs.open('test.txt', 'w') as f:\n    f.write('Hello, fatfs-ng!')\n\n# Read the file\nwith fat_fs.open('test.txt', 'r') as f:\n    content = f.read()\n    print(f\"Read from FAT filesystem: {content}\")\n\n# List directory contents\nprint(f\"Files in root directory: {fat_fs.listdir('/')}\")\n\n# Close the filesystem (important for releasing resources/flushing changes)\nfat_fs.close()\n\n# Example using PyFilesystem2 opener with a FAT image (conceptual, actual opener URI might vary)\n# with open_fs('fat://my_fat_image.bin') as fat_disk:\n#     fat_disk.writetext('another_file.txt', 'Content via PyFilesystem2')\n#     print(fat_disk.listdir('/'))","lang":"python","description":"This quickstart demonstrates creating a simple in-memory FAT filesystem, writing a file, reading it back, and listing directory contents using the `PyFatBytesIOFS` class from the `pyfatfs` library. This approach is commonly seen in related Python FAT wrappers like `pyfatfs`, as direct `fatfs-ng` specific examples were not readily available under the provided GitHub link."},"warnings":[{"fix":"Users should verify the correct GitHub repository for 'fatfs-ng' if they encounter import errors with 'pyfatfs', or consider using 'pyfatfs' directly if the API is compatible.","message":"The GitHub repository link provided in the PyPI metadata for 'fatfs-ng' (https://github.com/Jason2866/pyfatfs) appears to point to a user profile 'Jason2866' which does not contain a Python FAT filesystem wrapper. The examples and imports in this registry entry are therefore based on the commonly used 'pyfatfs' library (by nathanhi) which is a prominent Python wrapper for ChaN's FatFS and likely the intended upstream or a very similar project.","severity":"gotcha","affected_versions":"All"},{"fix":"Explicitly specify the `encoding` parameter when creating or opening a FAT filesystem if non-standard characters are used or if interoperability with different systems is critical. For VFAT, long file names are typically handled internally as UTF-16-LE.","message":"When manipulating FAT filesystems, especially those intended for embedded systems or specific hardware, ensure correct encoding is used for filenames. FAT typically uses IBM437, but VFAT (long file names) uses UTF-16-LE. Incorrect encoding can lead to unreadable filenames or data corruption.","severity":"gotcha","affected_versions":"All"},{"fix":"Always review the release notes and migration guides when upgrading `fatfs-ng` to a new major version, as internal changes to the wrapped C library might necessitate Python API adjustments.","message":"The underlying ChaN's FatFS C library has undergone various revisions (e.g., R0.15, R0.16) with breaking changes in its C API, especially regarding synchronization functions, argument changes for `f_read`/`f_write`, and `f_mkfs`. While `fatfs-ng` is a Python wrapper, internal updates to the wrapped C library might introduce breaking changes that propagate to the Python API in future major versions.","severity":"breaking","affected_versions":"Future major versions of fatfs-ng, or significant updates to its wrapped C FatFS version."},{"fix":"Consider using the `utc` parameter (if exposed by `fatfs-ng` or its underlying Python layer, as seen in `pyfatfs`) to create all timestamps in UTC to ensure better interoperability.","message":"Handling timestamps on FAT filesystems can be tricky. By default, timestamps might be created in local time, which can cause issues with systems expecting UTC.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}