Class: QgsFileUtils¶
Contains utilities for working with files.
Static Methods
Ensures that a fileName ends with an extension from the specified filter string. |
|
Returns the drive type for the given path. |
|
Ensures that a fileName ends with an extension from the provided list of extensions. |
|
Returns a list of the extensions contained within a file filter string. |
|
Returns |
|
Returns the top-most existing folder from path. |
|
Will check basepath in an outward spiral up to maxClimbs levels to check if file exists. |
|
Returns |
|
Renames the dataset at oldPath to newPath, renaming both the file at oldPath and all associated sidecar files which exist for it. |
|
Returns the human size from bytes |
|
Returns a list of the sidecar files which exist for the dataset a the specified path. |
|
Given a file path, returns a list of all the components leading to that path. |
|
Converts a string to a safe filename, replacing characters which are not safe for filenames with an '_' character. |
|
Creates a unique file path name from a desired path by appending |
|
Given a filter string like |
- class qgis.core.QgsFileUtils[source]¶
Bases:
object
- static addExtensionFromFilter(fileName: str | None, filter: str | None) str [source]¶
Ensures that a
fileName
ends with an extension from the specifiedfilter
string.E.g. a
fileName
ofd:/my_file
with a filter ofGeoTIFF Files (*.tiff *.tif)
will returnd:/my_file.tif
, where asfileName
ofd:/my_file.TIFF
ord:/my_file.TIF
will be returned unchanged.See also
See also
- Parameters:
fileName (Optional[str])
filter (Optional[str])
- Return type:
str
- static driveType(path: str | None) Qgis.DriveType [source]¶
Returns the drive type for the given
path
.- Raises:
QgsNotSupportedException – if determining the drive type is not supported on the current platform.
Added in version 3.20.
- Parameters:
path (Optional[str])
- Return type:
- static ensureFileNameHasExtension(fileName: str | None, extensions: Iterable[str | None]) str [source]¶
Ensures that a
fileName
ends with an extension from the provided list ofextensions
.E.g. if extensions contains
tif
andtiff
, then afileName
ofd:/my_file
will returnd:/my_file.tif
. AfileName
ofd:/my_file.TIFF
ord:/my_file.TIF
will be returned unchanged.See also
See also
- Parameters:
fileName (Optional[str])
extensions (Iterable[Optional[str]])
- Return type:
str
- static extensionsFromFilter(filter: str | None) List[str] [source]¶
Returns a list of the extensions contained within a file
filter
string. E.g. afilter
ofGeoTIFF Files (*.tiff *.tif)
would return a list containingtiff
,tif
. The initial ‘.’ is stripped off the extension.See also
See also
- Parameters:
filter (Optional[str])
- Return type:
List[str]
- static fileMatchesFilter(fileName: str | None, filter: str | None) bool [source]¶
Returns
True
if the givenfileName
matches a filefilter
string.E.g a filter of
GeoTIFF Files (*.tiff *.tif)
would returnTrue
for afileName
of/home/test.tif
, orFalse
for/home/test.jpg
.Added in version 3.18.
- Parameters:
fileName (Optional[str])
filter (Optional[str])
- Return type:
bool
- static findClosestExistingPath(path: str | None) str [source]¶
Returns the top-most existing folder from
path
. E.g. ifpath
is/home/user/projects/2018/P4343
and/home/user/projects
exists but no2018
subfolder exists, then the function will return/home/user/projects
.Added in version 3.2.
- Parameters:
path (Optional[str])
- Return type:
str
- static findFile(file: str | None, basepath: str | None = '', maxClimbs: int = 4, searchCeiling: int = 4, currentDir: str | None = '') List[str] [source]¶
Will check
basepath
in an outward spiral up tomaxClimbs
levels to check iffile
exists.- Parameters:
file (Optional[str]) – Name or full path of the file to find
basepath (Optional[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 (Optional[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.
Added in version 3.12.
- static pathIsSlowDevice(path: str | None) bool [source]¶
Returns
True
if the specifiedpath
is assumed to reside on a slow device, e.g. a remote network drive or other non-fixed device.Added in version 3.20.
- Parameters:
path (Optional[str])
- Return type:
bool
- static renameDataset(oldPath: str | None, newPath: str | None, flags: Qgis.FileOperationFlags | Qgis.FileOperationFlag = Qgis.FileOperationFlag.IncludeMetadataFile | Qgis.FileOperationFlag.IncludeStyleFile)[source]¶
Renames the dataset at
oldPath
tonewPath
, renaming both the file atoldPath
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 (Optional[str]) – original path to dataset
newPath (Optional[str]) – new path for dataset
flags (Union[Qgis.FileOperationFlags, Qgis.FileOperationFlag] = Qgis.FileOperationFlag.IncludeMetadataFile|Qgis.FileOperationFlag.IncludeStyleFile) -> (bool) – optional flags to control file operation behavior
- Returns:
True
if the dataset was successfully renamed, orFalse
if an error occurrederror: a descriptive error message if the rename operation fails
Added in version 3.22.
- static representFileSize(bytes: int) str [source]¶
Returns the human size from bytes
- Parameters:
bytes (int)
- Return type:
str
- static sidecarFilesForPath(path: str | None) 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.
Added in version 3.22.
- Parameters:
path (Optional[str])
- Return type:
Set[str]
- static splitPathToComponents(path: str | None) List[str] [source]¶
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
.Added in version 3.28.
- Parameters:
path (Optional[str])
- Return type:
List[str]
- static stringToSafeFilename(string: str | None) str [source]¶
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 (Optional[str])
- Return type:
str
- static uniquePath(path: str | None) str [source]¶
Creates a unique file path name from a desired path by appending
_<n>
(where<n>
is an integer number) before the file suffix.E.g. if
/path/my_image.png
already exists/path/my_image_2.png
(and_3`, ``_4
etc.) will be checked until a file path that does not already exist is found.- Parameters:
path (Optional[str]) – the desired path.
- Return type:
str
- Returns:
the unmodified path if path is already unique or the new path with
_<n>
(where<n>
is an integer number) appended to the file name before the suffix.
Note
This function does not make any check on path validity and write permissions.
Added in version 3.30.