Error Handling
==============

.. todo::

    error enums, context managers, converting GDAL errors to python exceptions


Debugging internal GDAL functions
----------------------------------

To get more debugging information from the internal GDAL/PROJ code:

1. Enable the `CPL_DEBUG` config option.

    .. note:: If setting the :envvar:`PROJ_DEBUG` environment variable
              inside a Python script, make sure that it is set before
              importing rasterio.

    .. code-block:: python

        import os
        os.environ["PROJ_DEBUG"] = "2"

        import rasterio

        with rasterio.Env(CPL_DEBUG=True):
            ...


2. Activate logging in `rasterio` with the devel `DEBUG`:

    More information available here: https://docs.python.org/3/howto/logging.html

    Here are examples to get started.

    Example - Add handler to the `rasterio` logger:

    .. code-block:: python

        import logging

        console_handler = logging.StreamHandler()
        formatter = logging.Formatter("%(levelname)s:%(message)s")
        console_handler.setFormatter(formatter)
        logger = logging.getLogger("rasterio")
        logger.addHandler(console_handler)
        logger.setLevel(logging.DEBUG)


    Example - Activate default logging config:

    .. code-block:: python

        import logging

        logging.basicConfig(format="%(levelname)s:%(message)s", level=logging.DEBUG)