:py:mod:`os.fs`
===============

.. py:module:: os.fs

.. autoapi-nested-parse::

   Low-level file manipulation.

   All function here should be platform independent, should not involve globbing or
   logging (unless in case of unexpected failure).



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


Functions
~~~~~~~~~

.. autoapisummary::

   os.fs.cd
   os.fs.chmod
   os.fs.df
   os.fs.__safe_unlink_func
   os.fs.force_remove_file
   os.fs.ldd_output_to_posix
   os.fs.max_path
   os.fs.mv
   os.fs.readlink
   os.fs.touch
   os.fs.unixpath
   os.fs.which



Attributes
~~~~~~~~~~

.. autoapisummary::

   os.fs.CYGPATH_MATCH
   os.fs.logger


.. py:data:: CYGPATH_MATCH
   :type: re.Pattern[str]

   

.. py:exception:: OSFSError(message: str | list[str], origin: str | None = None)


   Bases: :py:obj:`e3.error.E3Error`

   Exception raised for OS file system operations errors.


.. py:data:: logger

   

.. py:function:: cd(path: str | pathlib.Path) -> None

   Change current directory.

   :param path: directory name
   :raise OSFSError: in case of error


.. py:function:: chmod(mode: str, filename: str | pathlib.Path) -> int

   Chmod with interface similar to Unix tool.

   :param mode: should conform with posix specification for
       chmod utility (ex: +wx). See chmod man page for more information
   :param filename: the target file
   :return: the mode that has been set


.. py:function:: df(path: str | pathlib.Path) -> int
                 df(path: str | pathlib.Path, full: Literal[True]) -> tuple

   Disk space available on the filesystem containing the given path.

   :param path: path to check disk space for
   :param full: if True return full disk information otherwise only
       space left

   :return: either space left in Mo or a py:meth:`collections.namedtuple`
       with ``total``, ``used`` and ``free`` attributes. Each attribute is
       an int representing Mo.


.. py:function:: __safe_unlink_func() -> tuple[collections.abc.Callable[[str | pathlib.Path], None], collections.abc.Callable[[str | pathlib.Path], None]]

   Provide a safe unlink function on windows.

   Note that all this is done to ensure that rm is working fine on Windows 7
   and 2008R2. Indeed very often, deletion will fail with access denied
   error. The typical scenario is when you spawn an executable and try to
   delete it just afterward.


.. py:function:: force_remove_file(path: str | pathlib.Path) -> None

   Force file removing, changing permissions if first attempt failed.

   :param path: path of the file to remove


.. py:function:: ldd_output_to_posix(ldd_output: str) -> str

   Transform an ``ldd`` output to POSIX paths only.

   This method does not have any impact when the ``ldd`` output has
   been executed on a Unix host, because paths are already POSIX there.

   It applies only to ``ldd`` outputs on Windows, where the paths starting
   with `/c/`, `/mnt/c/` or `/cygdrive/c/` are modified to `C:/`.

   For instance, ``/c/WINDOWS/System32/ntdll.dll`` is transformed to
   ``C:/WINDOWS/System32/ntdll.dll``.

   .. note:: The transformation is made on strings only to minimize the
       call the ``cygpath``. If a file path is found, all its occurrences
       are replaced by its POSIX value.

   :param ldd_output: The output of an ``ldd`` call to transform to contain
       only POSIX paths.

   :return: An ``ldd`` output with POSIX paths only.


.. py:function:: max_path() -> int

   Return the maximum length for a path.

   :return: the maximum length


.. py:function:: mv(source: str | pathlib.Path, target: str | pathlib.Path) -> None

   Move a file.

   :param target: file to move
   :param source: target file or directory


.. py:function:: readlink(filename: str | pathlib.Path) -> str

   Get target path of a symlink.

   Equivalent of os.readlink with support for WSL Windows links.

   :param filename: path containing a symlink
   :return: target of the symlink


.. py:function:: touch(filename: str | pathlib.Path) -> None

   Update file access and modification times. Create the file if needed.

   :param filename: file to update


.. py:function:: unixpath(path: str | pathlib.Path) -> str

   Convert path to Unix/Cygwin format.

   :param path: path string to convert
   :return: the converted path

   On Unix systems this function is identity. On Win32 systems it removes
   drive letter information and replace \\ by /.


.. py:function:: which(prog: str | pathlib.Path, paths: str | None = None, default: Any = '') -> Any

   Locate executable.

   :param prog: program to find
   :param paths: if not None then we use this value instead of PATH to look
       for the executable.
   :param default: default value to return if not found

   :return: absolute path to the program on success, found by searching for an
     executable in the directories listed in the environment variable PATH
     or default value if not found