# Python General API

## 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.

  Return type:

    A context manager

  Example

      >>> with gdal.config_option("GDAL_NUM_THREADS", "ALL_CPUS"):
      ...     gdal.Warp("out.tif", "in.tif", dstSRS="EPSG:4326")

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.

  Return type:

    A context manager

  Example

      >>> with gdal.config_options({"GDAL_NUM_THREADS": "ALL_CPUS"}):
      ...     gdal.Warp("out.tif", "in.tif", dstSRS="EPSG:4326")

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 *

## 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 silents all warnings and errors.

  Return type:

    A context manager

  Example

      >>> with gdal.ExceptionMgr(useExceptions=False), gdal.quiet_errors():
      ...     gdal.Error(gdal.CE_Failure, 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.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

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.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 * pszOld, char const * pszNew) → 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.Unlink(char const * utf8_path) → VSI_RETVAL

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