fs_irods ======== .. py:module:: fs_irods .. autoapi-nested-parse:: Documentation about fs_irods. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/fs_irods/iRODSFS/index /autoapi/fs_irods/utils/index Classes ------- .. autoapisummary:: fs_irods.iRODSFS Functions --------- .. autoapisummary:: fs_irods.can_create Package Contents ---------------- .. py:class:: iRODSFS(session: irods.session.iRODSSession, root: str | None = None) Bases: :py:obj:`fs.base.FS` iRODS PyFilesystem2 implementation. The filesystem needs to be connected to an iRODS server via a sesseion, using valid login information. .. py:attribute:: _meta .. py:attribute:: _lock .. py:attribute:: _host .. py:attribute:: _port .. py:attribute:: _zone .. py:attribute:: _session .. py:attribute:: _finalizing :value: False .. py:attribute:: files .. py:attribute:: _root .. py:method:: wrap(path: str) -> str Transform path into iRODSPath. :param path: Path to transform. :type path: str :returns: Equivalent iRODSPath. :rtype: str .. py:method:: parent(path: str) -> str Get the parent directory of specified path. :param path: Path to retrieve parent for. :type path: str :returns: Parent directory of the path. :rtype: str .. py:method:: getinfo(path: str, namespaces: list | None = None) -> fs.info.Info Get information about a resource on the filesystem. :param path: A path to a resource on the filesystem. :type path: str :param namespaces: Info namespaces to query. If namespaces is None, then all available namespaces are queried. Defaults to None. :type namespaces: list, optional :returns: An Info object containing information about the resource. :rtype: Info :raises ResourceNotFound: If the path does not exist. .. py:method:: listdir(path: str) -> list List a directory on the filesystem. :param path: A path to a directory on the filesystem. :type path: str :returns: A list of resources in the directory. :rtype: list :raises ResourceNotFound: If the path does not exist. :raises DirectoryExpected: If the path is not a directory. .. py:method:: makedir(path: str, permissions: fs.permissions.Permissions | None = None, recreate: bool = False) Make a directory on the filesystem. :param path: A path to a directory on the filesystem. :type path: str :param permissions: A Permissions instance, or None to use default permissions. Defaults to None. :type permissions: Permissions, optional :param recreate: If False (the default) raise an error if the directory already exists, if True do not raise an error. Defaults to False. :type recreate: bool, optional :raises DirectoryExists: If the directory already exists and recreate is False. :raises ResourceNotFound: If the path does not exist. .. py:method:: _finalize_files() Helper function to close file handles. .. py:method:: __del__() Deconstructor to close all dangling file handles. .. py:method:: open(path: str, mode: str = 'r', buffering: int = -1, encoding: str | None = None, errors: str | None = None, newline: str = '', **options) Open a file. Stores weak references to open file handles that maintain a hard reference to the iRODSFS object. In this way, the iRODSFS can only be destructed once these file handles are gone. :param path: A path to a file on the filesystem. :type path: str :param mode: Mode to open the file object with (defaults to *r*). :type mode: str :param buffering: Buffering policy (-1 to use default buffering, 0 to disable buffering, 1 to select line buffering, of any positive integer to indicate a buffer size). :type buffering: int :param encoding: Encoding for text files (defaults to ``utf-8``) :type encoding: str :param errors: What to do with unicode decode errors (see `codecs` module for more information). :type errors: str, optional :param newline: Newline parameter. :type newline: str :param \*\*options: keyword arguments for any additional information required by the filesystem (if any). :returns: a *file-like* object. :rtype: io.IOBase :raises fs.errors.FileExpected: If the path is not a file. :raises fs.errors.FileExists: If the file exists, and *exclusive mode* is specified (``x`` in the mode). :raises fs.errors.ResourceNotFound: If the path does not exist. .. py:method:: openbin(path: str, mode: str = 'r', buffering: int = -1, **options) -> io.BufferedRandom Open a binary file-like object on the filesystem. :param path: A path to a file on the filesystem. :type path: str :param mode: The mode to open the file in, see the built-in open() function for details. Defaults to "r". :type mode: str, optional :param buffering: The buffer size to use for the file, see the built-in open() function for details. Defaults to -1. :type buffering: int, optional :param \*\*options: Additional options to pass to the open() function. :returns: A file-like object representing the file. :rtype: IO :raises ResourceNotFound: If the path does not exist and mode does not imply creating the file, or if any ancestor of path does not exist. :raises FileExpected: If the path is not a file. :raises FileExists: If the path exists, and exclusive mode is specified (x in the mode). .. py:method:: remove(path: str) Remove a file from the filesystem. :param path: A path to a file on the filesystem. :type path: str :raises ResourceNotFound: If the path does not exist. :raises FileExpected: If the path is not a file. .. py:method:: _check_isfile(path: str) Check if a path points to a file and raise an FileExpected error if not. :param path: A path to a file on the filesystem. :type path: str :raises ResourceNotFound: If the path does not exist. :raises FileExpected: If the path is not a file. .. py:method:: removedir(path: str) Remove a directory from the filesystem. :param path: A path to a directory on the filesystem. :type path: str :raises ResourceNotFound: If the path does not exist. :raises DirectoryExpected: If the path is not a directory. :raises RemoveRootError: If the path is the root directory. :raises DirectoryNotEmpty: If the directory is not empty. .. py:method:: _is_root(path: str) -> bool Check if path points to root of the filesystem. :param path: Path to a directory. :type path: str :returns: True if path points to root. :rtype: bool .. py:method:: removetree(path: str) Recursively remove a directory and all its contents. This method is similar to removedir, but will remove the contents of the directory if it is not empty. :param path: A path to a directory on the filesystem. :type path: str :raises ResourceNotFound: If the path does not exist. :raises DirectoryExpected: If the path is not a directory. .. py:method:: _check_isdir(path: str) Check if a path is a directory. :param path: A path to a resource on the filesystem. :type path: str :raises ResourceNotFound: If the path does not exist. :raises DirectoryExpected: If the path is not a directory. .. py:method:: setinfo(path: str, info: dict) -> None Set metadata for a file or directory. :param path: Path to a file or directory on the filesystem. :type path: str :param info: Dictionary with metadata. Format: :type info: dict :param {"details": {"modified": , "created": , "expiry": , "comments": }} :raises ResourceNotFound: If the path does not exist. :raises ValueError: If field values are invalid. .. py:method:: _validate_and_format_timestamp(value, field_name: str) -> int Validate that `value` can be parsed as a non-negative int timestamp. :param value: The value to validate and format. :type value: dict :param field_name: The name of the field being validated (for error messages). :type field_name: str :returns: The integer timestamp. :rtype: int :raises ValueError: If `value` is not an integer or is negative. .. py:method:: _check_exists(path: str) Check if a resource exists. :param path: A path to a resource on the filesystem. :type path: str :raises ResourceNotFound: If the path does not exist. .. py:method:: isfile(path: str) -> bool Check if a path is a file. :param path: A path to a resource on the filesystem. :type path: str :returns: True if the path is a file, False otherwise. :rtype: bool .. py:method:: isdir(path: str) -> bool Check if a path is a directory. :param path: A path to a resource on the filesystem. :type path: str :returns: True if the path is a directory, False otherwise. :rtype: bool .. py:method:: create(path: str) Create a file on the filesystem. :param path: A path to a file on the filesystem. :type path: str :raises ResourceNotFound: If any ancestor of path does not exist. :raises FileExists: If the path exists. .. py:method:: _check_points_into_collection(path: str) Check if a path points to a location inside a collection. :param path: Path to check. :type path: str :raises ResourceNotFound: If the path does not point to a location inside a collection. .. py:method:: points_into_collection(path: str) -> bool Return true if the path is located inside a collection, aka the parent is a collection. :param path: Path to check :type path: str :returns: True if the parent of path is a collection. :rtype: bool .. py:method:: exists(path: str) -> bool Check if a resource exists. :param path: A path to a resource on the filesystem. :type path: str :returns: True if the path exists, False otherwise. :rtype: bool .. py:method:: move(src_path: str, dst_path: str, overwrite: bool = False, preserve_time: bool = False) -> None Move a file to the specified location. :param src_path: Path to the current location of the file :type src_path: str :param dst_path: Path to the target location of the file :type dst_path: str :param overwrite: Set to True to overwrite an existing destination file. Defaults to False. :type overwrite: bool, optional :param preserve_time: Set to True to preserve the original modification time. Defaults to False. :type preserve_time: bool, optional :raises ResourceNotFound: If the source path does not exist, or if a parent directory of dst_path does not exist. :raises FileExpected: If the source path is not a file. :raises DestinationExists: If destination path exists and overwrite is False. .. py:method:: _preserve_modified_time(src_path: str, dst_path: str) -> None Copy the modified time field from src to dst if present. :param src_path: Source path to copy modified time from :type src_path: str :param dst_path: Destination path to copy modified time to :type dst_path: str .. py:method:: movedir(src_path: str, dst_path: str, overwrite: bool = False, preserve_time: bool = False) -> None Move a directory to the specified location. :param src_path: Path to the current location of the directory :type src_path: str :param dst_path: Path to the target location of the directory :type dst_path: str :param overwrite: Set to True to overwrite an existing destination directory. Defaults to False. :type overwrite: bool, optional :param preserve_time: Set to True to preserve the original modification time. Defaults to False. :type preserve_time: bool, optional :raises ResourceNotFound: If the source path does not exist. :raises DirectoryExpected: If the source path is not a directory. :raises DestinationExists: If destination path exists and overwrite is False. .. py:method:: _init_directory_tree_metadata(src_path: str) -> dict Recursively collect modification time metadata for all files and directories in a directory tree. :param src_path: Root directory to collect metadata from :type src_path: str :returns: Dictionary mapping relative paths to their modification times :rtype: dict .. py:method:: _collect_entry_metadata(path: str, rel: str, entry) -> dict Collect metadata for a file or directory entry. :param path: Current path during traversal :type path: str :param rel: Path relative to source root :type rel: str :param entry: Entry object (file or directory) :returns: Dictionary containing the entry's metadata, or empty dict if no modified time :rtype: dict .. py:method:: _apply_directory_tree_metadata(dst_path: str, metadata: dict) -> None Apply collected metadata to a directory tree at the destination. :param dst_path: Root destination path where metadata should be applied :type dst_path: str :param metadata: Dictionary mapping relative paths to their modification times :type metadata: dict .. py:method:: copy(src_path: str, dst_path: str, overwrite: bool = False, preserve_time: bool = False) Copy a file from one position to another. :param src_path: Path to source file to copy :type src_path: str :param dst_path: Destination :type dst_path: str :param overwrite: Whether to overwrite if the destination exists. Defaults to False. :type overwrite: bool, optional :param preserve_time: Whether to preserve the original modification time. Defaults to False. :type preserve_time: bool, optional :raises DestinationExists: If ``dst_path`` exists and ``overwrite`` is `False`. :raises ResourceNotFound: If a parent directory of ``dst_path`` does not exist. :raises FileExpected: If ``src_path`` is not a file. .. py:method:: copydir(src_path: str, dst_path: str, create: bool = False, preserve_time: bool = False) Copy the contents of the folder src_path to dst_path. :param src_path: Source directory to copy. :type src_path: str :param dst_path: Where to copy the folder to. :type dst_path: str :param create: Create the target directory if it does not exist. Defaults to False. :type create: bool, optional :param preserve_time: Preserve the modification time. Defaults to False. :type preserve_time: bool, optional :raises ResourceNotFound: If the ``dst_path`` does not exist, and ``create`` is not `True`. :raises DirectoryExpected: If ``src_path`` is not a directory. .. py:method:: upload(path: str, file: io.IOBase | str, chunk_size: int | None = None, **options) Set a file to the contents of a binary file object. This method copies bytes from an open binary file to a file on the filesystem. If the destination exists, it will first be truncated. :param path: A path on the filesystem. :type path: str :param file: a file object open for reading in binary mode or a path to a local file to upload. :type file: io.IOBase or str :param chunk_size: Number of bytes to read at a time, if a simple copy is used, or `None` to use sensible default. :type chunk_size: int, optional :param \*\*options: Implementation specific options required to open the source file. :raises ResourceNotFound: If a parent directory of ``path`` does not exist. Note that the file object ``file`` will *not* be closed by this method. Take care to close it after this method completes (ideally with a context manager). .. rubric:: Example >>> with open('~/movies/starwars.mov', 'rb') as read_file: ... my_fs.upload('starwars.mov', read_file) .. py:method:: download(path: str, file: io.IOBase | str, chunk_size=None, **options) Copy a file from the filesystem to a file-like object. This may be more efficient that opening and copying files manually if the filesystem supplies an optimized method. Note that the file object ``file`` will *not* be closed by this method. Take care to close it after this method completes (ideally with a context manager). :param path: Path to a resource. :type path: str :param file: A file-like object open for writing in binary mode. :type file: file-like :param chunk_size: Number of bytes to read at a time, if a simple copy is used, or `None` to use sensible default. :type chunk_size: int, optional :param \*\*options: Implementation specific options required to open the source file. .. rubric:: Example >>> with open('starwars.mov', 'wb') as write_file: ... my_fs.download('/Videos/starwars.mov', write_file) :raises ResourceNotFound: if ``path`` does not exist. .. py:function:: can_create(mode: str) -> bool Check if the mode implies creating a file.