docs: Use vfs module instead of os.

dpgeorge · dpgeorge · commit 4c56b39051b4 · 2024-02-07T13:25:10.000+11:00
Signed-off-by: Damien George &lt;damien@micropython.org&gt;
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
@@ -650,15 +650,15 @@ SD card
 
 See :ref:`machine.SDCard <machine.SDCard>`. ::
 
-    import machine, os
+    import machine, os, vfs
 
     # Slot 2 uses pins sck=18, cs=5, miso=19, mosi=23
     sd = machine.SDCard(slot=2)
-    os.mount(sd, '/sd')  # mount
+    vfs.mount(sd, '/sd') # mount
 
     os.listdir('/sd')    # list directory contents
 
-    os.umount('/sd')     # eject
+    vfs.umount('/sd')    # eject
 
 RMT
 ---
diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst
@@ -20,11 +20,11 @@ more info regarding the pins which can be remapped to be used with a SD card.
 Example usage::
 
     from machine import SD
-    import os
+    import vfs
     # clk cmd and dat0 pins must be passed along with
     # their respective alternate functions
     sd = machine.SD(pins=('GP10', 'GP11', 'GP15'))
-    os.mount(sd, '/sd')
+    vfs.mount(sd, '/sd')
     # do normal file operations
 
 Constructors
diff --git a/docs/library/machine.SDCard.rst b/docs/library/machine.SDCard.rst
@@ -30,7 +30,7 @@ vary from platform to platform.
     The class implements the block protocol defined by :class:`vfs.AbstractBlockDev`.
     This allows the mounting of an SD card to be as simple as::
 
-      os.mount(machine.SDCard(), "/sd")
+      vfs.mount(machine.SDCard(), "/sd")
 
     The constructor takes the following parameters:
 
diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst
@@ -213,7 +213,7 @@ Miscellaneous functions
 .. function:: mount(device, mountpoint, *, readonly=False, mkfs=False)
 
    .. note:: This function is deprecated. Mounting and unmounting devices should
-      be performed by :meth:`os.mount` and :meth:`os.umount` instead.
+      be performed by :meth:`vfs.mount` and :meth:`vfs.umount` instead.
 
    Mount a block device and make it available as part of the filesystem.
    ``device`` must be an object that provides the block protocol. (The
diff --git a/docs/mimxrt/quickref.rst b/docs/mimxrt/quickref.rst
@@ -443,27 +443,27 @@ SD card
 
 See :ref:`machine.SDCard <machine.SDCard>`::
 
-    import machine, os
+    import machine, os, vfs
 
     sd = machine.SDCard()
-    fs = os.VfsFat(sd)
-    os.mount(fs, "/sd")  # mount
+    fs = vfs.VfsFat(sd)
+    vfs.mount(fs, "/sd") # mount
     os.listdir('/sd')    # list directory contents
-    os.umount('/sd')     # eject
+    vfs.umount('/sd')    # eject
 
 Note: The i.mx-rt 1011 and 1015 based boards do not support the ``machine.SDCard``
 class.  For these, the SPI based driver ``sdcard.py`` from the MicroPython drivers
 can be used.  When using it, you have to overdrive the CS pin of the SPI hardware
 module.  Example::
 
-    import os, sdcard, machine
+    import vfs, sdcard, machine
 
     cs_pin = "D10"
     spi = machine.SPI(0) # SPI0 with cs at Pin "D10" used for SDCARD
     cs = machine.Pin(cs_pin, machine.Pin.OUT, value=1)
     sd = sdcard.SDCard(spi, cs)
-    vfs = os.VfsFat(sd)
-    os.mount(vfs, "/sdcard")
+    fs = vfs.VfsFat(sd)
+    vfs.mount(fs, "/sdcard")
 
 OneWire driver
 --------------
diff --git a/docs/pyboard/general.rst b/docs/pyboard/general.rst
@@ -21,7 +21,7 @@ If needed, you can prevent the use of the SD card by creating an empty file
 called ``/flash/SKIPSD``.  If this file exists when the pyboard boots
 up then the SD card will be skipped and the pyboard will always boot from the
 internal filesystem (in this case the SD card won't be mounted but you can still
-mount and use it later in your program using ``os.mount``).
+mount and use it later in your program using ``vfs.mount``).
 
 (Note that on older versions of the board, ``/flash`` is called ``0:/`` and ``/sd``
 is called ``1:/``).
diff --git a/docs/reference/filesystem.rst b/docs/reference/filesystem.rst
@@ -108,11 +108,11 @@ RAM using a ``bytearray``::
 
 It can be used as follows::
 
-    import os
+    import vfs
 
     bdev = RAMBlockDev(512, 50)
-    os.VfsFat.mkfs(bdev)
-    os.mount(bdev, '/ramdisk')
+    vfs.VfsFat.mkfs(bdev)
+    vfs.mount(bdev, '/ramdisk')
 
 An example of a block device that supports both the simple and extended
 interface (i.e. both signatures and behaviours of the
@@ -150,11 +150,11 @@ interface (i.e. both signatures and behaviours of the
 As it supports the extended interface, it can be used with :class:`littlefs
 <vfs.VfsLfs2>`::
 
-    import os
+    import vfs
 
     bdev = RAMBlockDev(512, 50)
-    os.VfsLfs2.mkfs(bdev)
-    os.mount(bdev, '/ramdisk')
+    vfs.VfsLfs2.mkfs(bdev)
+    vfs.mount(bdev, '/ramdisk')
 
 Once mounted, the filesystem (regardless of its type) can be used as it
 normally would be used from Python code, for example::
@@ -197,16 +197,16 @@ recommended to use littlefs instead.
 To format the entire flash using FAT::
 
     # ESP8266 and ESP32
-    import os
-    os.umount('/')
-    os.VfsFat.mkfs(bdev)
-    os.mount(bdev, '/')
+    import vfs
+    vfs.umount('/')
+    vfs.VfsFat.mkfs(bdev)
+    vfs.mount(bdev, '/')
 
     # STM32
-    import os, pyb
-    os.umount('/flash')
-    os.VfsFat.mkfs(pyb.Flash(start=0))
-    os.mount(pyb.Flash(start=0), '/flash')
+    import os, vfs, pyb
+    vfs.umount('/flash')
+    vfs.VfsFat.mkfs(pyb.Flash(start=0))
+    vfs.mount(pyb.Flash(start=0), '/flash')
     os.chdir('/flash')
 
 Littlefs
@@ -222,16 +222,16 @@ resistant to filesystem corruption.
 To format the entire flash using littlefs v2::
 
     # ESP8266 and ESP32
-    import os
-    os.umount('/')
-    os.VfsLfs2.mkfs(bdev)
-    os.mount(bdev, '/')
+    import vfs
+    vfs.umount('/')
+    vfs.VfsLfs2.mkfs(bdev)
+    vfs.mount(bdev, '/')
 
     # STM32
-    import os, pyb
-    os.umount('/flash')
-    os.VfsLfs2.mkfs(pyb.Flash(start=0))
-    os.mount(pyb.Flash(start=0), '/flash')
+    import os, vfs, pyb
+    vfs.umount('/flash')
+    vfs.VfsLfs2.mkfs(pyb.Flash(start=0))
+    vfs.mount(pyb.Flash(start=0), '/flash')
     os.chdir('/flash')
 
 A littlefs filesystem can be still be accessed on a PC over USB MSC using the
@@ -264,14 +264,14 @@ block devices spanning a subset of the flash device.
 For example, to configure the first 256kiB as FAT (and available over USB MSC),
 and the remainder as littlefs::
 
-    import os, pyb
-    os.umount('/flash')
+    import os, vfs, pyb
+    vfs.umount('/flash')
     p1 = pyb.Flash(start=0, len=256*1024)
     p2 = pyb.Flash(start=256*1024)
-    os.VfsFat.mkfs(p1)
-    os.VfsLfs2.mkfs(p2)
-    os.mount(p1, '/flash')
-    os.mount(p2, '/data')
+    vfs.VfsFat.mkfs(p1)
+    vfs.VfsLfs2.mkfs(p2)
+    vfs.mount(p1, '/flash')
+    vfs.mount(p2, '/data')
     os.chdir('/flash')
 
 This might be useful to make your Python files, configuration and other
@@ -282,9 +282,9 @@ failure, etc.
 The partition at offset ``0`` will be mounted automatically (and the filesystem
 type automatically detected), but you can add::
 
-    import os, pyb
+    import vfs, pyb
     p2 = pyb.Flash(start=256*1024)
-    os.mount(p2, '/data')
+    vfs.mount(p2, '/data')
 
 to ``boot.py`` to mount the data partition.
 
@@ -297,7 +297,7 @@ define an arbitrary partition layout.
 At boot, the partition named "vfs" will be mounted at ``/`` by default, but any
 additional partitions can be mounted in your ``boot.py`` using::
 
-    import esp32, os
+    import esp32, vfs
     p = esp32.Partition.find(esp32.Partition.TYPE_DATA, label='foo')
-    os.mount(p, '/foo')
+    vfs.mount(p, '/foo')
 
diff --git a/docs/renesas-ra/quickref.rst b/docs/renesas-ra/quickref.rst
@@ -387,15 +387,15 @@ SDCard
 The frozen sdcard driver (drivers/sdcard/sdcard.py) is available by connecting microSD card device to hardware SPI0 pins.::
 
     from machine import Pin, SPI
-    import os, sdcard
+    import os, vfs, sdcard
 
     spi = SPI(0, baudrate=500000)
     cs = Pin.cpu.P103
     sd = sdcard.SDCard(spi, cs)
-    os.mount(sd, '/sd')
+    vfs.mount(sd, '/sd')
     os.listdir('/')
     os.chdir('/sd')
-    os.umount('/sd')
+    vfs.umount('/sd')
 
 OneWire driver
 --------------
diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst
@@ -373,7 +373,7 @@ functions are defined in ``os`` module:
    Mounts a block device (like an ``SD`` object) in the specified mount
    point. Example::
 
-      os.mount(sd, '/sd')
+      vfs.mount(sd, '/sd')
 
 .. function:: unmount(path)
 
diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst
@@ -171,13 +171,13 @@ SD card
 See :ref:`machine.SD <machine.SD>`. ::
 
     from machine import SD
-    import os
+    import vfs
 
     # clock pin, cmd pin, data0 pin
     sd = SD(pins=('GP10', 'GP11', 'GP15'))
     # or use default ones for the expansion board
     sd = SD()
-    os.mount(sd, '/sd')
+    vfs.mount(sd, '/sd')
 
 WLAN (WiFi)
 -----------
diff --git a/docs/zephyr/quickref.rst b/docs/zephyr/quickref.rst
@@ -109,12 +109,12 @@ Disk Access
 
 Use the :ref:`zephyr.DiskAccess <zephyr.DiskAccess>` class to support filesystem::
 
-    import os
+    import vfs
     from zephyr import DiskAccess
 
     block_dev = DiskAccess('SDHC')      # create a block device object for an SD card
-    os.VfsFat.mkfs(block_dev)           # create FAT filesystem object using the disk storage block
-    os.mount(block_dev, '/sd')          # mount the filesystem at the SD card subdirectory
+    vfs.VfsFat.mkfs(block_dev)          # create FAT filesystem object using the disk storage block
+    vfs.mount(block_dev, '/sd')         # mount the filesystem at the SD card subdirectory
 
     # with the filesystem mounted, files can be manipulated as normal
     with open('/sd/hello.txt','w') as f:     # open a new file in the directory
@@ -126,12 +126,12 @@ Flash Area
 
 Use the :ref:`zephyr.FlashArea <zephyr.FlashArea>` class to support filesystem::
 
-    import os
+    import vfs
     from zephyr import FlashArea
 
     block_dev = FlashArea(4, 4096)      # creates a block device object in the frdm-k64f flash scratch partition
-    os.VfsLfs2.mkfs(block_dev)          # create filesystem in lfs2 format using the flash block device
-    os.mount(block_dev, '/flash')       # mount the filesystem at the flash subdirectory
+    vfs.VfsLfs2.mkfs(block_dev)         # create filesystem in lfs2 format using the flash block device
+    vfs.mount(block_dev, '/flash')      # mount the filesystem at the flash subdirectory
 
     # with the filesystem mounted, files can be manipulated as normal
     with open('/flash/hello.txt','w') as f:     # open a new file in the directory
diff --git a/docs/zephyr/tutorial/storage.rst b/docs/zephyr/tutorial/storage.rst
@@ -21,11 +21,11 @@ file system to access SD cards via disk access (see below).
 
 Example usage of FatFS with an SD card on the mimxrt1050_evk board::
 
-    import os
+    import vfs
     from zephyr import DiskAccess
     bdev = zephyr.DiskAccess('SDHC')        # create block device object using DiskAccess
-    os.VfsFat.mkfs(bdev)                    # create FAT filesystem object using the disk storage block
-    os.mount(bdev, '/sd')                   # mount the filesystem at the SD card subdirectory
+    vfs.VfsFat.mkfs(bdev)                   # create FAT filesystem object using the disk storage block
+    vfs.mount(bdev, '/sd')                  # mount the filesystem at the SD card subdirectory
     with open('/sd/hello.txt','w') as f:    # open a new file in the directory
         f.write('Hello world')              # write to the file
     print(open('/sd/hello.txt').read())     # print contents of the file
@@ -43,11 +43,11 @@ implements the `vfs.AbstractBlockDev` protocol.
 
 Example usage with the internal flash on the reel_board or the rv32m1_vega_ri5cy board::
 
-    import os
+    import vfs
     from zephyr import FlashArea
     bdev = FlashArea(FlashArea.STORAGE, 4096)   # create block device object using FlashArea
-    os.VfsLfs2.mkfs(bdev)                       # create Little filesystem object using the flash area block
-    os.mount(bdev, '/flash')                    # mount the filesystem at the flash storage subdirectory
+    vfs.VfsLfs2.mkfs(bdev)                      # create Little filesystem object using the flash area block
+    vfs.mount(bdev, '/flash')                   # mount the filesystem at the flash storage subdirectory
     with open('/flash/hello.txt','w') as f:     # open a new file in the directory
         f.write('Hello world')                  # write to the file
     print(open('/flash/hello.txt').read())      # print contents of the file
