Trait System 

pub trait System:
    Debug
    + Sync
    + Send {
    // Required methods
    fn path_metadata(&self, path: &SystemPath) -> Result<Metadata>;
    fn canonicalize_path(&self, path: &SystemPath) -> Result<SystemPathBuf>;
    fn is_same_file(
        &self,
        first: &SystemPath,
        second: &SystemPath,
    ) -> Result<bool>;
    fn which(&self, binary_name: &str) -> WhichResult;
    fn read_to_string(&self, path: &SystemPath) -> Result<String>;
    fn read_to_notebook(
        &self,
        path: &SystemPath,
    ) -> Result<Notebook, NotebookError>;
    fn read_virtual_path_to_string(
        &self,
        path: &SystemVirtualPath,
    ) -> Result<String>;
    fn read_virtual_path_to_notebook(
        &self,
        path: &SystemVirtualPath,
    ) -> Result<Notebook, NotebookError>;
    fn current_directory(&self) -> &SystemPath;
    fn user_config_directory(&self) -> Option<SystemPathBuf>;
    fn cache_dir(&self) -> Option<SystemPathBuf>;
    fn read_directory<'a>(
        &'a self,
        path: &SystemPath,
    ) -> Result<Box<dyn Iterator<Item = Result<DirectoryEntry>> + 'a>>;
    fn walk_directory(&self, path: &SystemPath) -> WalkDirectoryBuilder;
    fn as_writable(&self) -> Option<&dyn WritableSystem>;
    fn as_any(&self) -> &dyn Any;
    fn as_any_mut(&mut self) -> &mut dyn Any;
    fn dyn_clone(&self) -> Box<dyn System>;

    // Provided methods
    fn source_type(&self, path: &SystemPath) -> Option<PySourceType> { ... }
    fn virtual_path_source_type(
        &self,
        path: &SystemVirtualPath,
    ) -> Option<PySourceType> { ... }
    fn run_command(&self, command: Command) -> Result<Output> { ... }
    fn command_executor(&self) -> Option<&dyn CommandExecutor> { ... }
    fn path_exists(&self, path: &SystemPath) -> bool { ... }
    fn is_directory(&self, path: &SystemPath) -> bool { ... }
    fn is_file(&self, path: &SystemPath) -> bool { ... }
    fn env_var(&self, name: &str) -> Result<String, VarError> { ... }
}

The system on which Ruff runs.

Ruff supports running on the CLI, in a language server, and in a browser (WASM). Each of these host-systems differ in what system operations they support and how they interact with the file system:

• Language server:
  • Reading a file’s content should take into account that it might have unsaved changes because it’s open in the editor.
  • Use structured representations for notebooks, making deserializing a notebook from a string unnecessary.
  • Use their own file watching infrastructure.
• WASM (Browser):
  • There are ways to emulate a file system in WASM but a native memory-filesystem is more efficient.
  • Doesn’t support a current working directory
  • File watching isn’t supported.

Abstracting the system also enables tests to use a more efficient in-memory file system.

Required Methods

fn path_metadata(&self, path: &SystemPath) -> Result<Metadata>

Reads the metadata of the file or directory at path.

This function will traverse symbolic links to query information about the destination file.

fn canonicalize_path(&self, path: &SystemPath) -> Result<SystemPathBuf>

Returns the canonical, absolute form of a path with all intermediate components normalized and symbolic links resolved.

Errors

This function will return an error in the following situations, but is not limited to just these cases:

• path does not exist.
• A non-final component in path is not a directory.
• the symlink target path is not valid Unicode.

Windows long-paths

Unlike std::fs::canonicalize, this function does remove UNC prefixes if possible. See dunce::canonicalize for more information.

fn is_same_file(&self, first: &SystemPath, second: &SystemPath) -> Result<bool>

Returns true if both paths refer to the same file.

fn which(&self, binary_name: &str) -> WhichResult

Find an executable binary’s path by name.

fn read_to_string(&self, path: &SystemPath) -> Result<String>

Reads the content of the file at path into a String.

fn read_to_notebook(&self, path: &SystemPath) -> Result<Notebook, NotebookError>

Reads the content of the file at path as a Notebook.

This method optimizes for the case where the system holds a structured representation of a Notebook, allowing to skip the notebook deserialization. Systems that don’t use a structured representation fall-back to deserializing the notebook from a string.

fn read_virtual_path_to_string( &self, path: &SystemVirtualPath, ) -> Result<String>

Reads the content of the virtual file at path into a String.

fn read_virtual_path_to_notebook( &self, path: &SystemVirtualPath, ) -> Result<Notebook, NotebookError>

Reads the content of the virtual file at path as a Notebook.

fn current_directory(&self) -> &SystemPath

Returns the current working directory

fn user_config_directory(&self) -> Option<SystemPathBuf>

Returns the directory path where user configurations are stored.

Returns None if no such convention exists for the system.

fn cache_dir(&self) -> Option<SystemPathBuf>

Returns the directory path where cached files are stored.

Returns None if no such convention exists for the system.

fn read_directory<'a>( &'a self, path: &SystemPath, ) -> Result<Box<dyn Iterator<Item = Result<DirectoryEntry>> + 'a>>

Iterate over the contents of the directory at path.

The returned iterator must have the following properties:

• It only iterates over the top level of the directory, i.e., it does not recurse into subdirectories.
• It skips the current and parent directories (. and .. respectively).
• The iterator yields std::io::Result<DirEntry> instances. For each instance, an Err variant may signify that the path of the entry was not valid UTF8, in which case it should be an std::io::Error with the ErrorKind set to std::io::ErrorKind::InvalidData and the payload set to a camino::FromPathBufError. It may also indicate that “some sort of intermittent IO error occurred during iteration” (language taken from the std::fs::read_dir documentation).

Errors

Returns an error:

• if path does not exist in the system,
• if path does not point to a directory,
• if the process does not have sufficient permissions to view the contents of the directory at path
• May also return an error in some other situations as well.

fn walk_directory(&self, path: &SystemPath) -> WalkDirectoryBuilder

Recursively walks the content of path.

It is allowed to pass a path that points to a file. In this case, the walker yields a single entry for that file.

fn as_writable(&self) -> Option<&dyn WritableSystem>

Returns a handle to a WritableSystem if this system is writable.

fn as_any(&self) -> &dyn Any

fn as_any_mut(&mut self) -> &mut dyn Any

fn dyn_clone(&self) -> Box<dyn System>

Provided Methods

fn source_type(&self, path: &SystemPath) -> Option<PySourceType>

Returns the source type for path if known or None.

The default is to always return None, assuming the system has no additional information and that the caller should rely on the file extension instead.

This is primarily used for the LSP integration to respect the chosen language (or the fact that it is a notebook) in the editor.

fn virtual_path_source_type( &self, path: &SystemVirtualPath, ) -> Option<PySourceType>

Returns the source type for path if known or None.

The default is to always return None, assuming the system has no additional information and that the caller should rely on the file extension instead.

This is primarily used for the LSP integration to respect the chosen language (or the fact that it is a notebook) in the editor.

fn run_command(&self, command: Command) -> Result<Output>

Runs command and captures its standard output and standard error.

fn command_executor(&self) -> Option<&dyn CommandExecutor>

Returns the system’s command executor, if it supports running commands.

fn path_exists(&self, path: &SystemPath) -> bool

Returns true if path exists.

fn is_directory(&self, path: &SystemPath) -> bool

Returns true if path exists and is a directory.

fn is_file(&self, path: &SystemPath) -> bool

Returns true if path exists and is a file.

fn env_var(&self, name: &str) -> Result<String, VarError>

Fetches the environment variable key from the current process.

Errors

Returns std::env::VarError::NotPresent if:

• The variable is not set.
• The variable’s name contains an equal sign or NUL ('=' or '\0').

Returns std::env::VarError::NotUnicode if the variable’s value is not valid Unicode.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl System for InMemorySystem

impl System for TestSystem