os.windows.fs
=============

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


Attributes
----------

.. autoapisummary::

   os.windows.fs.logger


Classes
-------

.. autoapisummary::

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


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

.. py:data:: logger

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

   .. py:attribute:: desired_access
      :value: None



   .. py:attribute:: shared_access
      :value: None



   .. py:attribute:: open_options
      :value: None



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


.. 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:attribute:: handle
      :type:  ctypes.wintypes.HANDLE | None
      :value: None



   .. py:attribute:: io_status


   .. py:attribute:: basic_info


   .. py:attribute:: attr


   .. py:attribute:: desired_access


   .. py:attribute:: shared_access


   .. py:attribute:: open_options


   .. py:attribute:: is_dir_empty_last_seen_file
      :type:  str | None
      :value: None



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


   .. 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: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: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: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: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: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:: unlink() -> None

      Remove file safely.

      :raise: NTException



