# Configuration

Pyresample allows certain functionality to be controlled at a global level. This allows users to quickly modify behavior at potentially very low levels of pyresample without having to specify new arguments throughout their code. Configuration is controlled through a central `config` object and allows setting parameters in one of three ways:

1. Environment variable

2. YAML file

3. At runtime with `pyresample.config`

This functionality is provided by the donfig library. The currently available settings are described below. Each option is available from all three methods. If specified as an environment variable or specified in the YAML file on disk, it must be set before Pyresample is imported.

YAML Configuration

YAML files that include these parameters can be in any of the following locations:

1. `<python environment prefix>/etc/pyresample/pyresample.yaml`

2. `<user_config_dir>/pyresample.yaml` (see below)

3. `~/.pyresample/pyresample.yaml`

The above `user_config_dir` is provided by the `platformdirs` package and differs by operating system. Typical user config directories are:

- Mac OSX: `~/Library/Preferences/pyresample`

- Unix/Linux: `~/.config/pyresample`

- Windows: `C:\\Users\\<username>\\AppData\\Local\\pytroll\\pyresample`

All YAML files found from the above paths will be merged into one configuration object (accessed via `pyresample.config`). The YAML contents should be a simple mapping of configuration key to its value. For example:

    some_key: "some_value"

In some cases, keys may be grouped into sub-dictionaries:

    features:
        future_geometries: true

Lastly, it is possible to specify an additional config path to the above options by setting the environment variable `PYRESAMPLE_CONFIG`. The file specified with this environment variable will be added last after all of the above paths have been merged together.

At runtime

After import, the values can be customized at runtime by doing:

    import pyresample
    pyresamle.config.set(some_key="some_value")
    # ... normal pyresample code ...

Or for specific blocks of code:

    import pyresample
    with pyresample.config.set(some_key="some_value):
        # ... some pyresample code ...
    # ... code using the original 'some_key' setting

Similarly, if you need to access one of the values you can use the `pyresample.config.get` method.

## Cache Directory

- Environment variable: `PYRESAMPLE_CACHE_DIR`

- YAML/Config Key: `cache_dir`

- Default: See below

Directory where any files cached by Pyresample will be stored. This directory is not necessarily cleared out by Pyresample, but is rarely used without explicitly being enabled by the user. This defaults to a different path depending on your operating system following the platformdirs “user cache dir”.

Note

Some resampling algorithms provide caching functionality when the user provides a directory to cache to. These resamplers do not currently use this configuration option.

## Cache Geometry Slices

- Environment variable: `PYRESAMPLE_CACHE_GEOMETRY_SLICES`

- YAML/Config Key: `cache_geometry_slices`

- Default: `False`

Whether or not generated slices for geometry objects are cached to disk. These slices are used in various parts of Pyresample like cropping or overlap calculations including those performed in some resampling algorithms. At the time of writing this is only performed on `AreaDefinition` objects through their `get_area_slices()` method. Slices are stored in `cache_dir` (see above). Unlike other caching performed in Pyresample where potentially large arrays are cached, this option saves a pair of `slice` objects that consist of only 3 integers each. This makes the amount of space used in the cache very small for many cached results.

The slicing operations in Pyresample typically involve finding the intersection between two geometries. This requires generating bounding polygons for the geometries and doing polygon intersection calculations that can handle projection anti-meridians. At the time of writing these calculations can take as long as 15 seconds depending on number of vertices used in the bounding polygons. One use case for these slices is reducing input data to only the overlap of the target area. This can be done before or during resampling as part of the algorithm or as part of a third-party resampling interface (ex. Satpy). In the future as optimizations are made to the polygon intersection logic this caching option should hopefully not be needed.

When setting this as an environment variable, this should be set with the string equivalent of the Python boolean values `="True"` or `="False"`.

Warning

This caching does not limit the number of entries nor does it expire old entries. It is up to the user to manage the contents of the cache directory.

### Feature Flags

The below configuration options control whether certain features are made available or used by default or overwrite existing behavior. In most cases these are used for future changes to pyresample or experimental functionality that may change later. These flags are all under the `features` sub-dictionary which requires some extra work to identify the substructure. For example:

    import pyresample
    pyresample.config.set({"features.future_geometries": True})

If using environment variables not the use of double underscores `__` in parts of the variable name.

## Future Geometries

- Environment variable: `PYRESAMPLE_FEATURES__FUTURE_GEOMETRIES`

- YAML/Config Key: `features: future_geometries`

- Default: False

Enable the use of future geometry objects (`AreaDefinition`, `SwathDefinition`, etc) and overwrite any internal use of the old geometry objects. This flag is meant to simplify the switch to future pyresample in user code when utility methods like `create_area_def` are used. When enabled the returned geometry instance will be of the future geometry class. These classes can be accessed from:

    from pyresample.future.geometry import AreaDefinition, SwathDefinition

Eventually these classes will be the default in Pyresample 2.0 and this flag will have no effect.