SciTools/cartopy — pull request #468 by snorfalorpagus (2014-08-18 09:22:18+00:00)
Title: Implementation of GADM shapereader / feature interface

This pull request is the beginning of an interface to the GADM dataset, initially proposed in https://github.com/SciTools/cartopy/issues/466

The current code is function, but has issues where regions don't have exactly 3 levels (0, 1 and 2). We need to agree on what is the correct behaviour in this instance.

The GADM (version 2) dataset is a little different from the Natural Earth and GSHHS data, in that the downloadable archives contain multiple levels. e.g.

```
~/Downloads> unzip -l GBR_adm.zip
Archive: GBR_adm.zip
Length Date Time Name
--------- ---------- ----- ----
1022 2011-12-20 14:44 GBR_adm0.csv
1895 2011-12-20 12:03 GBR_adm0.dbf
145 2011-12-20 12:03 GBR_adm0.prj
6585600 2011-12-20 12:03 GBR_adm0.shp
108 2011-12-20 12:03 GBR_adm0.shx
499 2011-12-20 14:56 GBR_adm1.csv
2210 2011-12-20 12:51 GBR_adm1.dbf
145 2011-12-20 12:51 GBR_adm1.prj
6592228 2011-12-20 12:51 GBR_adm1.shp
132 2011-12-20 12:51 GBR_adm1.shx
22048 2011-12-20 15:07 GBR_adm2.csv
111938 2011-12-20 13:22 GBR_adm2.dbf
145 2011-12-20 13:22 GBR_adm2.prj
6852052 2011-12-20 13:22 GBR_adm2.shp
1636 2011-12-20 13:22 GBR_adm2.shx
212369 2011-12-20 15:49 read_me.pdf
--------- -------
20384172 16 files
```

This isn't a problem in itself. Requests for level 0 will download levels 0, 1 and 2. If those other levels are requested later, they don't need to be downloaded again.

The issue lies in that not all countries have the same number of levels. For example, GBR has 0, 1, and 2, while FRA has 0, 1, 2, 3, and 4. What should happen when a level is requested that doesn't exist? e.g. GBR level 3 would trigger a download, but the archive wouldn't contain the requested data. What's the correct way to handle this? Raise an error when it's found the data isn't available (and if so, what error)? Or keep some sort of dictionary in the module that gives clues as to which levels are available for which codes?