How to use "context" in rasterio?

Question

Another rasterio follow-up question, after questions on reading and writing rasters. I've successfully made and reprojected an output layer, but while trying to use the overview module to build pyramids, I found I don't understand something fundamental: the ctx parameter of the function.

def overview(ctx, input, build, ls, rebuild, resampling):

By a Google search, I found that ctx means "context" and that there's a module named context in click library used by rasterio. I got stuck here: further searching shows "context" only in other contexts. The only useful hints I found here: info.py and test_rio_info.py files in the rasterio repository. I'm not good enough to be able to reverse engineer the ctx format expected by the overview function from these libraries (not sure whether it is possible).

So I need a good manual explaining contexts as used in rasterio, either as an answer or as a link with some summary. How to produce/get them, what exactly do they mean (do they have any use besides passing data into functions?), what are their components (if any) etc.

EDIT: I've found the Context class in the click library in the core.py file on my disk (/usr/local/lib/python2.7/dist-packages/click/core.py on my Ubuntu machine). I didn't manage to explicitely initialize this class object (I didn't understand the params), but after reading Kersten's answer I think it is not needed while using Rasterio through Python API. The class documentation seems to agree:

The context is a special internal object that holds state relevant for the script execution at every single level. It's normally invisible to commands unless they opt-in to getting access to it.

The context is useful as it can pass internal objects around and can control special execution features such as reading data from environment variables.

Answer 1

The function overview is from rasterios command line interface rio.

What you are looking for is the function build_overviews inside the standard I/O class of rasterio.

How to use that? I have absolutely no idea since I never needed it so far.

Luckily rasterio includes an extensive test suite which also includes one called test_overviews.py. If you look at the code inside the test the usage is actually pretty straightforward. When you write a dataset, or open a dataset in read/write mode, you can define the overview levels you want as a list.

with rasterio.open('rasterio-test.tif', 'r+') as dst:
    # dst.write() if your dataset has not yet been written to disk
    dst.build_overviews([2,4])

On my 4800x4800 pixel test dataset this creates overviews with pyramids of the size 2400x2400 as well as 1200x1200.

>> gdalinfo rasterio-test.tif
...
Overviews: 2400x2400, 1200x1200