cartopy.io.shapereader.GSHHSShpDownloader

class cartopy.io.shapereader.GSHHSShpDownloader(url_template='https://www.ngdc.noaa.gov/mgg/shorelines/data/gshhs/latest/gshhg-shp-2.3.7.zip', target_path_template=None, pre_downloaded_path_template='')

Specialise cartopy.io.Downloader to download the zipped GSHHS shapefiles and extract them to the defined location.

The keys which should be passed through when using the format_dict are scale (a single character indicating the resolution) and level (a number indicating the type of feature).

FORMAT_KEYS = ('config', 'scale', 'level')

The minimum keys which should be provided in the format_dict argument for the path, url, target_path, pre_downloaded_path and acquire_resource methods.

acquire_resource(target_path, format_dict)

Download the zip file and extracts the files listed in zip_file_contents() to the target path.

Note

Because some of the GSHSS data is available with the cartopy repository, scales of “l” or “c” will not be downloaded if they exist in the cartopy.config['repo_data_dir'] directory.

static default_downloader()

Return a GSHHSShpDownloader instance that expects (and if necessary downloads and installs) shapefiles in the data directory of the cartopy installation.

Typically, a user will not need to call this staticmethod.

To find the path template of the GSHHSShpDownloader:

>>> gshhs_dnldr = GSHHSShpDownloader.default_downloader()
>>> print(gshhs_dnldr.target_path_template)
{config[data_dir]}/shapefiles/gshhs/{scale}/GSHHS_{scale}_L{level}.shp

static from_config(specification, config_dict=None)

The from_config static method implements the logic for acquiring a Downloader (sub)class instance from the config dictionary.

Parameters:

• specification – Should be iterable, as it will be traversed in reverse order to find the most appropriate Downloader instance for this specification. An example specification is ('shapefiles', 'natural_earth') for the Natural Earth shapefiles.

• config_dict (optional) – typically this is left as None to use the default cartopy.config “downloaders” dictionary.

Examples

>>> from cartopy.io import Downloader
>>>
>>> dnldr = Downloader('https://example.com/{name}', './{name}.txt')
>>> config = {('level_1', 'level_2'): dnldr}
>>> d1 = Downloader.from_config(('level_1', 'level_2', 'level_3'),
...                             config_dict=config)
>>> print(d1.url_template)
https://example.com/{name}
>>> print(d1.url({'name': 'item_name'}))
https://example.com/item_name

path(format_dict)

Returns the path to a file on disk that this resource represents.

If the file doesn’t exist in pre_downloaded_path() then it will check whether it exists in target_path(), otherwise the resource will be downloaded via acquire_resouce() from url() to target_path().

Typically, this is the method that most applications will call, allowing implementers of new Downloaders to specialise acquire_resource().

Parameters:

format_dict – The dictionary which is used to replace certain template variables. Subclasses should document which keys are expected as a minimum in their FORMAT_KEYS class attribute.

pre_downloaded_path(format_dict)

The path on disk of the file that this resource represents, if it does not exist, then no further action will be taken with this path, and all further processing will be done using target_path() instead.

Parameters:

format_dict – The dictionary which is used to replace certain template variables. Subclasses should document which keys are expected as a minimum in their FORMAT_KEYS class attribute.

target_path(format_dict)

The path on disk of the file that this resource represents, must either exist, or be writable by the current user. This method does not check either of these conditions.

Parameters:

format_dict – The dictionary which is used to replace certain template variables. Subclasses should document which keys are expected as a minimum in their FORMAT_KEYS class attribute.

url(format_dict)

The full URL that this resource represents.

Parameters:

format_dict – The dictionary which is used to replace certain template variables. Subclasses should document which keys are expected as a minimum in their FORMAT_KEYS class attribute.

zip_file_contents(format_dict)

Return a generator of the filenames to be found in the downloaded GSHHS zip file for the specified resource.