Class: QgsFileUtils

class qgis.core.QgsFileUtils

Bases: sip.wrapper

Class for file utilities.

New in version 3.0:

Methods

addExtensionFromFilter

Ensures that a fileName ends with an extension from the specified filter string.

driveType

Returns the drive type for the given path.

ensureFileNameHasExtension

Ensures that a fileName ends with an extension from the provided list of extensions.

extensionsFromFilter

Returns a list of the extensions contained within a file filter string. E.g. a filter of "GeoTIFF Files (*.tiff *.tif)" would return a list containing "tiff", "tif". The initial '.' is stripped off the extension.

fileMatchesFilter

Returns True if the given fileName matches a file filter string.

findClosestExistingPath

Returns the top-most existing folder from path.

findFile

Will check basepath in an outward spiral up to maxClimbs levels to check if file exists.

pathIsSlowDevice

Returns True if the specified path is assumed to reside on a slow device, e.g. a remote network drive or other non-fixed device.

renameDataset

Renames the dataset at oldPath to newPath, renaming both the file at oldPath and all associated sidecar files which exist for it.

representFileSize

Returns the human size from bytes

sidecarFilesForPath

Returns a list of the sidecar files which exist for the dataset a the specified path.

splitPathToComponents

Given a file path, returns a list of all the components leading to that path.

stringToSafeFilename

Converts a string to a safe filename, replacing characters which are not safe for filenames with an '_' character.

wildcardsFromFilter

Given a filter string like "GeoTIFF Files (.tiff *.tif)", extracts the wildcard portion of this filter (i.e. ".tiff *.tif").

addExtensionFromFilter(fileName: str, filter: str) str

Ensures that a fileName ends with an extension from the specified filter string.

E.g. a fileName of “d:/my_file” with a filter of “GeoTIFF Files (*.tiff *.tif)” will return “d:/my_file.tif”, where as fileName of “d:/my_file.TIFF” or “d:/my_file.TIF” will be returned unchanged.

Parameters:
  • fileName (str) –

  • filter (str) –

Return type:

str

driveType(path: str) Qgis.DriveType

Returns the drive type for the given path.

Raises:

QgsNotSupportedException – if determining the drive type is not supported on the current platform.

New in version 3.20.

Parameters:

path (str) –

Return type:

Qgis.DriveType

ensureFileNameHasExtension(fileName: str, extensions: Iterable[str]) str

Ensures that a fileName ends with an extension from the provided list of extensions.

E.g. if extensions contains “tif” and “tiff”, then a fileName of “d:/my_file” will return “d:/my_file.tif”. A fileName of “d:/my_file.TIFF” or “d:/my_file.TIF” will be returned unchanged.

Parameters:
  • fileName (str) –

  • extensions (Iterable[str]) –

Return type:

str

extensionsFromFilter(filter: str) List[str]

Returns a list of the extensions contained within a file filter string. E.g. a filter of “GeoTIFF Files (*.tiff *.tif)” would return a list containing “tiff”, “tif”. The initial ‘.’ is stripped off the extension.

Parameters:

filter (str) –

Return type:

List[str]

fileMatchesFilter(fileName: str, filter: str) bool

Returns True if the given fileName matches a file filter string.

E.g a filter of “GeoTIFF Files (*.tiff *.tif)” would return True for a fileName of “/home/test.tif”, or False for “/home/test.jpg”.

New in version 3.18.

Parameters:
  • fileName (str) –

  • filter (str) –

Return type:

bool

findClosestExistingPath(path: str) str

Returns the top-most existing folder from path. E.g. if path is “/home/user/projects/2018/P4343” and “/home/user/projects” exists but no “2018” subfolder exists, then the function will return “/home/user/projects”.

New in version 3.2.

Parameters:

path (str) –

Return type:

str

findFile(file: str, basepath: str = '', maxClimbs: int = 4, searchCeiling: int = 4, currentDir: str = '') List[str]

Will check basepath in an outward spiral up to maxClimbs levels to check if file exists.

Parameters:
  • file (str) – Name or full path of the file to find

  • basepath (str = '') – current basepath of the file, needed if only the name is specified in file

  • maxClimbs (int = 4) – limit the number of time the search can move up from the basepath

  • searchCeiling (int = 4) – limits where in the folder hierarchy the search can be performed, 1 = root/drive, 2 = first folder level, 3 = sub folders ( Unix: /usr/bin, Win: C:/Users/Admin ), etc.

  • currentDir (str = '') – alternative default directory to override the actual current directory during the search

Return type:

List[str]

Returns:

List of strings of the first matching path in unix format.

New in version 3.12.

pathIsSlowDevice(path: str) bool

Returns True if the specified path is assumed to reside on a slow device, e.g. a remote network drive or other non-fixed device.

New in version 3.20.

Parameters:

path (str) –

Return type:

bool

renameDataset(oldPath: str, newPath: str, flags: Qgis.FileOperationFlags | Qgis.FileOperationFlag = Qgis.FileOperationFlag.IncludeMetadataFile | Qgis.FileOperationFlag.IncludeStyleFile) Tuple[bool, str]

Renames the dataset at oldPath to newPath, renaming both the file at oldPath and all associated sidecar files which exist for it.

For instance, if oldPath specified a .shp file then the corresponding .dbf, .idx and .prj files would be renamed (amongst others).

The destination directory must already exist.

The optional flags argument can be used to control whether QMD metadata files and QML styling files should also be renamed accordingly. By default these will be renamed, but manually specifying a different set of flags allows callers to avoid this when desired.

Parameters:
  • oldPath (str) – original path to dataset

  • newPath (str) – new path for dataset

  • flags (Union[Qgis.FileOperationFlags) – optional flags to control file operation behavior

Return type:

Tuple[bool, str]

Returns:

  • True if the dataset was successfully renamed, or False if an error occurred

  • error: will be set to a descriptive error message if the rename operation fails

New in version 3.22.

representFileSize(bytes: int) str

Returns the human size from bytes

Parameters:

bytes (int) –

Return type:

str

sidecarFilesForPath(path: str) Set[str]

Returns a list of the sidecar files which exist for the dataset a the specified path.

In this context a sidecar file is defined as a file which shares the same base filename as a dataset, but which differs in file extension. It defines the list of additional files which must be renamed or deleted alongside the main file associated with the dataset in order to completely rename/delete the dataset.

For instance, if path specified a .shp file then the corresponding .dbf, .idx and .prj files would be returned (amongst others).

Note

QGIS metadata files (.qmd) and map layer styling files (.qml) are NOT included in the returned list.

New in version 3.22.

Parameters:

path (str) –

Return type:

Set[str]

splitPathToComponents(path: str) List[str]

Given a file path, returns a list of all the components leading to that path.

E.g. if path is “/home/user/Pictures/test.png”, the returned list will contain “/” , “home”, “user”, “Pictures”, “test.png”.

New in version 3.28.

Parameters:

path (str) –

Return type:

List[str]

stringToSafeFilename(string: str) str

Converts a string to a safe filename, replacing characters which are not safe for filenames with an ‘_’ character.

Warning

This method strips slashes from the filename, so it is safe to call with file names only, not complete paths.

Parameters:

string (str) –

Return type:

str

wildcardsFromFilter(filter: str) str

Given a filter string like “GeoTIFF Files (.tiff *.tif)”, extracts the wildcard portion of this filter (i.e. “.tiff *.tif”).

New in version 3.18.

Parameters:

filter (str) –

Return type:

str