# How to use "gdal" CLI algorithms from Python

## Principles

"gdal" CLI algorithms are available as `osgeo.gdal.Algorithm` instances.

A convenient way to access an algorithm and run it is to use the `osgeo.gdal.Run()` function.

Run(*alg, arguments={}, progress=None, **kwargs)

  Run a GDAL algorithm and return it.

  Parameters:

    - alg (str, list[str], tuple[str], Algorithm) -- Path to the algorithm or algorithm instance itself. For example "raster info", or ["raster", "info"] or "raster", "info".

    - arguments (dict) -- Input arguments of the algorithm. For example {"format": "json", "input": "byte.tif"}

    - progress (callable) -- Progress function whose arguments are a progress ratio, a string and a user data

    - kwargs -- Instead of using the `arguments` parameter, it is possible to pass algorithm arguments directly as named parameters of gdal.Run(). If the named argument has dash characters in it, the corresponding parameter must replace them with an underscore character. For example `dst_crs` as a a parameter of gdal.Run(), instead of `dst-crs` which is the name to use on the command line.

  Return type:

    a `osgeo.gdal.Algorithm` instance

If you do not need to access output value(s) of the algorithm, you can call `Run` directly: `gdal.Run(["raster", "convert"], input="in.tif", output="out.tif")`

The name of algorithm arguments are the long names as documented in the documentation page of each algorithm. They can also be obtained with `osgeo.gdal.Algorithm.GetArgNames()`.

    >>> gdal.Algorithm("raster", "convert").GetArgNames()
    ['help', 'help-doc', 'version', 'json-usage', 'drivers', 'config', 'progress', 'output-format', 'open-option', 'input-format', 'input', 'output', 'creation-option', 'overwrite', 'append']

For a command such as gdal raster info that returns a JSON output, you can get the return value of `osgeo.gdal.Run()` and call the `osgeo.gdal.Algorithm.Output()` method.

    alg = gdal.Run("raster", "info", input="byte.tif")
    info_as_dict = alg.Output()

If the return value is a dataset, `osgeo.gdal.Run()` can be used within a context manager, in which case `osgeo.gdal.Algorithm.Finalize()` will be called at the exit of the context manager.

    with gdal.Run("raster reproject", input=src_ds, output_format="MEM",
                  dst_crs="EPSG:4326") as alg:
        values = alg.Output().ReadAsArray()

## Raster commands examples

### Example 1: Getting information on a raster dataset as JSON

    from osgeo import gdal

    gdal.UseExceptions()
    alg = gdal.Run("raster", "info", input="byte.tif")
    info_as_dict = alg.Output()

### Example 2: Converting a georeferenced netCDF file to cloud-optimized GeoTIFF

    from osgeo import gdal

    gdal.UseExceptions()
    gdal.Run("raster", "convert", input="in.tif", output="out.tif",
             output_format="COG", overwrite=True)

or

    from osgeo import gdal

    gdal.UseExceptions()
    gdal.Run(["raster", "convert"], {"input": "in.tif", "output": "out.tif", "output-format": "COG", "overwrite": True})

### Example 3: Reprojecting a GeoTIFF file to a Deflate-compressed tiled GeoTIFF file

    from osgeo import gdal

    gdal.UseExceptions()
    gdal.Run("raster", "reproject", input="in.tif", output="out.tif",
              dst_crs="EPSG:4326",
              creation_options={ "TILED": "YES", "COMPRESS": "DEFLATE"})

### Example 4: Reprojecting a (possibly in-memory) dataset to a in-memory dataset

    from osgeo import gdal

    gdal.UseExceptions()
    with gdal.Run("raster", "reproject", input=src_ds, output_format="MEM",
                  dst_crs="EPSG:4326") as alg:
        values = alg.Output().ReadAsArray()

## Vector commands examples

### Example 5: Getting information on a vector dataset as JSON

    from osgeo import gdal

    gdal.UseExceptions()
    alg = gdal.Run("vector", "info", input="poly.gpkg")
    info_as_dict = alg.Output()

### Example 6: Converting a shapefile to a GeoPackage

    from osgeo import gdal

    gdal.UseExceptions()
    gdal.Run("vector", "convert", input="in.shp", output="out.gpkg", overwrite=True)