General API

• Configuration Management

• Data Type Information

• Error Handling

• File Management

Configuration Management

osgeo.gdal.config_option(key, value, thread_local=True)

Temporarily define a configuration option.

Parameters:

• key (str) -- Name of the configuration option

• value (str) -- Value of the configuration option

• thread_local (bool, default=True) -- Whether the configuration option should be only set on the current thread.

Returns:

A context manager

Return type:

contextlib.contextmanager

Examples

>>> with gdal.config_option("GDAL_NUM_THREADS", "ALL_CPUS"):
...     gdal.Warp("out.tif", "in.tif", dstSRS="EPSG:4326")
<osgeo.gdal.Dataset; proxy of <Swig Object of type 'GDALDatasetShadow *' at 0x...> >

osgeo.gdal.config_options(options, thread_local=True)

Temporarily define a set of configuration options.

Parameters:

• options (dict) -- Dictionary of configuration options passed as key, value

• thread_local (bool, default=True) -- Whether the configuration options should be only set on the current thread.

Returns:

A context manager

Return type:

contextlib.contextmanager

Examples

>>> with gdal.config_options({"GDAL_NUM_THREADS": "ALL_CPUS"}):
...     gdal.Warp("out.tif", "in.tif", dstSRS="EPSG:4326")
<osgeo.gdal.Dataset; proxy of <Swig Object of type 'GDALDatasetShadow *' at 0x...> >

osgeo.gdal.ClearCredentials(char const * pszPathPrefix=None)

osgeo.gdal.ClearPathSpecificOptions(char const * pszPathPrefix=None)

osgeo.gdal.GetCacheMax() → GIntBig

Get the maximum size of the block cache. See GDALGetCacheMax().

Returns:

maximum cache size in bytes

Return type:

int

osgeo.gdal.GetCacheUsed() → GIntBig

Get the number of bytes in used by the block cache. See GDALGetCacheUsed().

Returns:

cache size in bytes

Return type:

int

osgeo.gdal.GetConfigOption(char const * pszKey, char const * pszDefault=None) → char const *

Return the value of a configuration option. See CPLGetConfigOption().

Parameters:

• pszKey (str) -- name of the configuration option

• pszDefault (str, optional) -- default value to return if the option has not been set

Return type:

str

See also

GetConfigOptions(), GetThreadLocalConfigOption()

osgeo.gdal.GetConfigOptions() → char **

Return a dictionary of currently set configuration options. See CPLGetConfigOptions().

Return type:

dict

Examples

>>> with gdal.config_options({'A': '3', 'B': '4'}):
...     gdal.SetConfigOption('C', '5')
...     gdal.GetConfigOptions()
...
{'C': '5', 'A': '3', 'B': '4'}

See also

GetConfigOption(), GetGlobalConfigOptions()

osgeo.gdal.GetCredential(char const * pszPathPrefix, char const * pszKey, char const * pszDefault=None) → char const *

osgeo.gdal.GetGlobalConfigOption(char const * pszKey, char const * pszDefault=None) → char const *

Return the value of a global (not thread-local) configuration option. See CPLGetGlobalConfigOption().

Parameters:

• pszKey (str) -- name of the configuration option

• pszDefault (str, optional) -- default value to return if the option has not been set

Return type:

str

osgeo.gdal.GetNumCPUs() → int

Return the number of processors detected by GDAL.

Return type:

int

osgeo.gdal.GetPathSpecificOption(char const * pszPathPrefix, char const * pszKey, char const * pszDefault=None) → char const *

osgeo.gdal.GetThreadLocalConfigOption(char const * pszKey, char const * pszDefault=None) → char const *

Return the value of a thread-local configuration option. See CPLGetThreadLocalConfigOption().

Parameters:

• pszKey (str) -- name of the configuration option

• pszDefault (str, optional) -- default value to return if the option has not been set

Return type:

str

osgeo.gdal.GetUsablePhysicalRAM() → GIntBig

osgeo.gdal.HasThreadSupport() → int

osgeo.gdal.SetCacheMax(GIntBig nBytes)

Set the maximum size of the block cache. See GDALSetCacheMax().

Parameters:

nBytes (int) -- Cache size in bytes

See also

GDAL_CACHEMAX

osgeo.gdal.SetConfigOption(char const * pszKey, char const * pszValue)

Set the value of a configuration option for all threads. See CPLSetConfigOption().

Parameters:

• pszKey (str) -- name of the configuration option

• pszValue (str) -- value of the configuration option

See also

SetThreadLocalConfigOption(), config_option(), config_options()

osgeo.gdal.SetCredential(char const * pszPathPrefix, char const * pszKey, char const * pszValue)

osgeo.gdal.SetPathSpecificOption(char const * pszPathPrefix, char const * pszKey, char const * pszValue)

osgeo.gdal.SetThreadLocalConfigOption(char const * pszKey, char const * pszValue)

Set the value of a configuration option for the current thread. See CPLSetThreadLocalConfigOption().

Parameters:

• pszKey (str) -- name of the configuration option

• pszValue (str) -- value of the configuration option

See also

SetConfigOption(), config_option(), config_options()

osgeo.gdal.VersionInfo(char const * request="VERSION_NUM") → char const *

Data Type Information

osgeo.gdal.DataTypeIsComplex(GDALDataType eDataType) → int

osgeo.gdal.DataTypeUnion(GDALDataType a, GDALDataType b) → GDALDataType

osgeo.gdal.DataTypeUnionWithValue(GDALDataType a, double val, bool isComplex) → GDALDataType

osgeo.gdal.GetDataTypeByName(char const * pszDataTypeName) → GDALDataType

Return the data type for a given name.

Parameters:

pszDataTypeName (str) -- data type name

Returns:

data type code

Return type:

int

Examples

>>> gdal.GetDataTypeByName('Int16') == gdal.GDT_Int16
True

osgeo.gdal.GetDataTypeName(GDALDataType eDataType) → char const *

Return the name of the data type.

Parameters:

eDataType (int) -- data type code

Return type:

str

Examples

>>> gdal.GetDataTypeName(gdal.GDT_Int16)
'Int16'
>>> gdal.GetDataTypeName(gdal.GDT_Float64)
'Float64'

osgeo.gdal.GetDataTypeSize(GDALDataType eDataType) → int

osgeo.gdal.GetDataTypeSizeBits(GDALDataType eDataType) → int

osgeo.gdal.GetDataTypeSizeBytes(GDALDataType eDataType) → int

Error Handling

osgeo.gdal.ConfigurePythonLogging(logger_name='gdal', enable_debug=False)

Configure GDAL to use Python's logging framework

osgeo.gdal.Debug(char const * msg_class, char const * message)

osgeo.gdal.DontUseExceptions()

Disable exceptions in all GDAL related modules (osgeo.gdal, osgeo.ogr, osgeo.osr, osgeo.gnm). Note: prior to GDAL 3.7, this only affected the calling module

osgeo.gdal.Error(CPLErr msg_class=CE_Failure, int err_code=0, char const * msg="error")

osgeo.gdal.ErrorReset()

class osgeo.gdal.ExceptionMgr(useExceptions=True)

Context manager to manage Python Exception state for GDAL/OGR/OSR/GNM.

Separate exception state is maintained for each module (gdal, ogr, etc), and this class appears independently in all of them. This is built in top of calls to the older UseExceptions()/DontUseExceptions() functions.

Example:

>>> print(gdal.GetUseExceptions())
0
>>> with gdal.ExceptionMgr():
...     # Exceptions are now in use
...     print(gdal.GetUseExceptions())
1
>>>
>>> # Exception state has now been restored
>>> print(gdal.GetUseExceptions())
0

osgeo.gdal.GetErrorCounter() → unsigned int

osgeo.gdal.GetLastErrorMsg() → char const *

osgeo.gdal.GetLastErrorNo() → int

osgeo.gdal.GetLastErrorType() → int

osgeo.gdal.GetUseExceptions() → int

osgeo.gdal.PopErrorHandler()

osgeo.gdal.PushErrorHandler(CPLErrorHandler pfnErrorHandler=0) → CPLErr

osgeo.gdal.quiet_errors()

Temporarily install an error handler that silences all warnings and errors.

Returns:

A context manager

Return type:

contextlib.contextmanager

Examples

>>> with gdal.ExceptionMgr(useExceptions=False), gdal.quiet_errors():
...     gdal.Error(gdal.CE_Failure, gdal.CPLE_AppDefined, "you will never see me")

osgeo.gdal.quiet_warnings()

Temporarily install an error handler that silences all warnings.

Added in version 3.11.

Returns:

A context manager

Return type:

contextlib.contextmanager

Examples

>>> with gdal.ExceptionMgr(useExceptions=False), gdal.quiet_warnings():
...     gdal.Error(gdal.CE_Warning, gdal.CPLE_AppDefined, "you will never see me")

osgeo.gdal.SetCurrentErrorHandlerCatchDebug(int bCatchDebug)

osgeo.gdal.SetErrorHandler(CPLErrorHandler pfnErrorHandler=0) → CPLErr

osgeo.gdal.UseExceptions()

Enable exceptions in all GDAL related modules (osgeo.gdal, osgeo.ogr, osgeo.osr, osgeo.gnm). Note: prior to GDAL 3.7, this only affected the calling module

File Management

osgeo.gdal_fsspec module

Module exposing GDAL Virtual File Systems (VSI) as a "gdalvsi" fsspec implementation.

Importing "osgeo.gdal_fsspec" requires the Python "fsspec" (https://filesystem-spec.readthedocs.io/en/latest/) module to be available.

A generic "gdalvsi" fsspec protocol is available. All GDAL VSI file names must be simply prefixed with "gdalvsi://". For example:

• "gdalvsi://data/byte.tif" to access relative file "data/byte.tif"

• "gdalvsi:///home/user/byte.tif" to access absolute file "/home/user/byte.tif"

• "gdalvsi:///vsimem/byte.tif" (note the 3 slashes) to access VSIMem file "/vsimem/byte.tif"

• "gdalvsi:///vsicurl/https://example.com/byte.tif (note the 3 slashes) to access "https://example.com/byte.tif" through /vsicurl/

since:

GDAL 3.11

class osgeo.gdal_fsspec.VSIFileSystem(*args, **kwargs)

Bases: AbstractFileSystem

Implementation of AbstractFileSystem for a GDAL Virtual File System

copy(path1, path2, recursive=False, maxdepth=None, on_error=None, **kwargs)

Implements AbstractFileSystem.copy()

info(path, **kwargs)

Implements AbstractFileSystem.info()

ls(path, detail=True, **kwargs)

Implements AbstractFileSystem.ls()

makedirs(path, exist_ok=False)

Implements AbstractFileSystem.makedirs()

mkdir(path, create_parents=True, **kwargs)

Implements AbstractFileSystem.mkdir()

modified(path)

Implements AbstractFileSystem.modified()

mv(path1, path2, recursive=False, maxdepth=None, **kwargs)

Implements AbstractFileSystem.mv()

rmdir(path)

Implements AbstractFileSystem.rmdir()

osgeo.gdal_fsspec.register_vsi_implementations()

Register a generic "gdalvsi" protocol. This method is automatically called on osgeo.gdal_fsspec import.

osgeo.gdal.VSIFile class

class osgeo.gdal.VSIFile(path, mode, encoding='utf-8', options={})

Class wrapping a GDAL VSILFILE instance as a Python BytesIO instance

Since:

GDAL 3.11

close()

Disable all I/O operations.

read(size=-1)

Read at most size bytes, returned as a bytes object.

If the size argument is negative, read until EOF is reached. Return an empty bytes object at EOF.

seek(offset, whence=0)

Change stream position.

Seek to byte offset pos relative to position indicated by whence:

• 0: Start of stream (the default). pos should be >= 0;

• 1: Current position - pos may be negative;

• 2: End of stream - pos usually negative.

Returns the new absolute position.

tell()

Current file position, an integer.

write(x)

Write bytes to file.

Return the number of bytes written.

Low level functions

osgeo.gdal.CloseDir(VSIDIR * dir)

osgeo.gdal.CopyFile(char const * pszSource, char const * pszTarget, VSILFILE fpSource=None, GIntBig nSourceSize=-1, char ** options=None, GDALProgressFunc callback=0, void * callback_data=None) → int

osgeo.gdal.CopyFileRestartable(char const * pszSource, char const * pszTarget, char const * pszInputPayload, char ** options=None, GDALProgressFunc callback=0, void * callback_data=None)

class osgeo.gdal.DirEntry(*args)

Proxy of C++ DirEntry class.

IsDirectory(DirEntry self) → bool

property extra

p.p.char

Type:

extra

property mode

int

Type:

mode

property modeKnown

bool

Type:

modeKnown

property mtime

GIntBig

Type:

mtime

property mtimeKnown

bool

Type:

mtimeKnown

property name

p.char

Type:

name

property size

GIntBig

Type:

size

property sizeKnown

bool

Type:

sizeKnown

property thisown

The membership flag

osgeo.gdal.FileFromMemBuffer(char const * utf8_path, GIntBig nBytes) → VSI_RETVAL

osgeo.gdal.FindFile(char const * pszClass, char const * utf8_path) → char const *

osgeo.gdal.GetFileMetadata(char const * utf8_path, char const * domain, char ** options=None) → char **

osgeo.gdal.GetFileSystemOptions(char const * utf8_path) → char const *

osgeo.gdal.GetFileSystemsPrefixes() → char **

osgeo.gdal.Mkdir(char const * utf8_path, int mode) → VSI_RETVAL

osgeo.gdal.MkdirRecursive(char const * utf8_path, int mode) → VSI_RETVAL

osgeo.gdal.Move(char const * old_path, char const * new_path, char ** options=None, GDALProgressFunc callback=0, void * callback_data=None) → VSI_RETVAL

osgeo.gdal.MoveFile(char const * pszSource, char const * pszTarget) → int

osgeo.gdal.OpenDir(char const * utf8_path, int nRecurseDepth=-1, char ** options=None) → VSIDIR *

osgeo.gdal.ReadDir(char const * utf8_path, int nMaxFiles=0) → char **

osgeo.gdal.ReadDirRecursive(char const * utf8_path) → char **

osgeo.gdal.Rename(char const * old_path, char const * new_path) → VSI_RETVAL

osgeo.gdal.Rmdir(char const * utf8_path) → VSI_RETVAL

osgeo.gdal.RmdirRecursive(char const * utf8_path) → VSI_RETVAL

osgeo.gdal.SetFileMetadata(char const * utf8_path, char ** metadata, char const * domain, char ** options=None) → bool

osgeo.gdal.Sync(char const * pszSource, char const * pszTarget, char ** options=None, GDALProgressFunc callback=0, void * callback_data=None) → bool

osgeo.gdal.Unlink(char const * utf8_path) → VSI_RETVAL

osgeo.gdal.UnlinkBatch(char ** files) → bool