gtristan commented on a change in pull request #1609: URL: https://github.com/apache/buildstream/pull/1609#discussion_r827688878
########## File path: src/buildstream/storage/directory.py ########## @@ -16,328 +17,499 @@ # # Authors: # Jim MacArthur <[email protected]> +# Tristan van Berkom <[email protected]> """ -Directory -========= - -This is a virtual Directory class to isolate the rest of BuildStream -from the backing store implementation. Sandboxes are allowed to read -from and write to the underlying storage, but all others must use this -Directory class to access files and directories in the sandbox. - -See also: :ref:`sandboxing`. - +Directory - Interfacing with files +================================== +The Directory class is given to plugins by way of the :class:`.Sandbox` +or in some other instances, and allows plugins to interface with files +and directory hierarchies owned by BuildStream. + + +.. _directory_path: + +Paths +----- +The path argument to directory functions depict a relative path. Path elements are +separated with the ``/`` character regardless of the platform. Both ``.`` and ``..`` entries +are permitted. Absolute paths are not permitted, as such it is illegal to specify a path +with a leading ``/`` character. + +Directory objects represent a directory entry within the context of a *directory tree*, +and the directory returned by +:func:`Sandbox.get_virtual_directory() <buildstream.sandbox.Sandbox.get_virtual_directory>` +is the root of the sandbox's *directory tree*. Attempts to escape the root of a *directory tree* +using ``..`` entries will not result in an error, instead ``..`` entries which cross the +root boundary will be evaluated as the root directory. Review comment: Appended to this paragraph: > This behavior matches POSIX behavior of filesystem root directories. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
