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

.. py:module:: os.windows.fs

.. autoapi-nested-parse::

   Windows filesystem operations using native API.



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

Classes
~~~~~~~

.. autoapisummary::

   os.windows.fs.WithOpenFile
   os.windows.fs.NTFile




Attributes
~~~~~~~~~~

.. autoapisummary::

   os.windows.fs.logger


.. py:data:: logger

   

.. py:class:: WithOpenFile(desired_access: int | None = None, shared_access: int | None = None, open_options: int | None = None)


   Decorator to manage Windows file opening with specific access modes.

   .. py:method:: __call__(f: collections.abc.Callable) -> Any

      Decorate function to open file if needed.

      :param f: function to wrap



.. py:class:: NTFile(filename: str | pathlib.Path, parent: NTFile | None = None)


   Class to manipulate Win32 paths.

   :ivar path: the full pathname
   :ivar nt_filename: UnicodeString object representing either the full path
       or the basename of the file (when inititialized using a parent object)
   :ivar handle: handle to the file. It is set to None if no call to open
       has been done
   :ivar io_status: structure returned by most of low level API call
   :ivar basic_info: ObjectAttributes object associated with the file

   .. py:property:: volume_path
      :type: str

      Retrieve path to the volume containing the file.

      :return: path to a windows volume after junction resolution
      :raise: NTException


   .. py:property:: uid
      :type: int

      Retrieve the ID of the file.

      On NTFS system we are sure that this ID is unique on the given volume

      :return: the uid
      :raise: NTException


   .. py:property:: reparse_tag
      :type: int

      Find the reparse point tag for a given file.

      :return: the tag as int. 0 is returned if not a reparse point


   .. py:property:: is_dir
      :type: bool

      Check if file is a directory.

      Note that read_attributes methods should be called at least once
      otherwise the function will return False.

      :return: True if the file is a directory, False otherwise


   .. py:property:: is_readonly
      :type: bool

      Check if file is readonly.

      Note that read_attributes methods should be called at least once
      otherwise the function will return False.

      :return: True if readonly, False otherwise


   .. py:property:: is_reparse_point
      :type: bool

      Check if a given file is a reparse point.

      :return: True if the file is a reparse point, False otherwise


   .. py:property:: is_symlink
      :type: bool

      Check whether a given file is a symlink or not.

      :return: return True for all kind of symlinks (native and WSL).


   .. py:property:: trash_path
      :type: str

      Return path in which the file can move safely for deletion.

      On NTFS filesystem we are sure that the path is unique and thus
      that no existing file can exist at that location.

      :return: a path


   .. py:property:: is_dir_empty
      :type: bool

      Check if dir is empty.

      :return: True if the directory is empty. If not empty return False and set
          is_dir_empty_last_seen_file attribute to the first file found in the
          directory.
      :raise: NTException


   .. py:method:: __str__() -> str

      Return string representation of NT file info.


   .. py:method:: open(desired_access: int | None = None, shared_access: int | None = None, open_options: int | None = None) -> None

      Open file.

      :param desired_access: desired access
          (see e3.os.windows.native_api.Access)
      :param shared_access: sharing parameters
          (see e3.os.windows.native_api.Shared)
      :param open_options: open options
          (see e3.os.windows.native_api.OpenOptions)


   .. py:method:: close() -> None

      Close file.

      If a call has been done to open, close the handle associated
      with the file and reset the handle to None.


   .. py:method:: wsl_reparse_link_target() -> str | None

      Get target of a WSL link (also used by Cygwin).

      :return: the link target


   .. py:method:: read_attributes_internal() -> None

      Retrieve file basic attributes (internal function).

      The function is used internally to check file basic attributes
      (kind of entry and windows attributes such as readonly). Retrieved
      attributes are stored in basic_info Python attribute. It requires
      less rights than the read_attributes method.


   .. py:method:: read_attributes() -> e3.os.windows.native_api.FileInfo.Basic

      Retrieve file basic information.

      It updates the basic_info attribute including timestamp information

      :raise: NTException


   .. py:method:: write_attributes() -> None

      Update file attributes.

      :raise: NTException


   .. py:method:: rename(filename: str, replace: bool = False) -> None

      Move file.

      :param filename: target location
      :param replace: if True replace the target file if it exists
      :raise: NTException


   .. py:method:: move_to_trash() -> None

      Move file to trash location.

      :raise: NTException


   .. py:method:: dispose() -> None

      Remove the file (low level).

      The remove is effective on call to close method


   .. py:method:: iterate_on_dir(fun: collections.abc.Callable, default_result: Any = None) -> Any

      Iterate on directory.

      :param fun: function called on each entry (. are .. are skipped)
      :param default_result: default return value
      :return: last return value or fun or default_result


   .. py:method:: unlink() -> None

      Remove file safely.

      :raise: NTException