sidescanpy.datasets#

Openly licensed sidescan recordings for examples and tests.

Each registered file is one raw recording, or one published product made from recordings, in a public agency archive. Most archives are multi-gigabyte zips: fetch() pulls just the one member out with HTTP range requests, so an example needs a few tens of megabytes instead of the whole archive. A few archives serve each file on its own URL; those are downloaded directly. Either way the SHA-256 is checked and the file cached.

>>> from sidescanpy import datasets
>>> path = datasets.fetch("jncc_wight_barfleur_20130321174522.jsf")
>>> print(datasets.citation("jncc_wight_barfleur_20130321174522.jsf"))

The cache is SIDESCANPY_DATA_DIR when set, otherwise ~/.cache/sidescanpy ($XDG_CACHE_HOME/sidescanpy if that is set). A file already in the cache with the right checksum is used as is, so a directory of pre-downloaded files works offline.

Only standard-library modules are used. Downloads log at DEBUG; call sidescanpy.log.configure_logging() with "DEBUG" to see them.

2026 rshomberg@uri.edu

Contents

`Source`	A public archive and the terms its files come under.
`RemoteFile`	One file in a source archive.
`SOURCES`
`REGISTRY`
`BGS_LONDON_GATEWAY_WRECKS`	Catalogued wreck centres of the London Gateway survey, as given in the BGS record (UTM zone 31N, WGS84; easting, northing in meters).
`list_datasets`	Names `fetch()` accepts, sorted.
`data_dir`	The cache directory `fetch()` uses when none is given.
`citation`	Source, licence and attribution text for a registered file.
`fetch`	Return a local path to a registered recording, downloading it if needed.

class sidescanpy.datasets.Source(title, url, licence, attribution)#

Bases: object

A public archive and the terms its files come under.

class sidescanpy.datasets.RemoteFile(source, archive_url, member, size, sha256, description)#

Bases: object

One file in a source archive.

member is the file’s path inside the zip at archive_url; when it is None, archive_url is the file itself.

sidescanpy.datasets.SOURCES#

sidescanpy.datasets.REGISTRY#

sidescanpy.datasets.BGS_LONDON_GATEWAY_WRECKS#: Catalogued wreck centres of the London Gateway survey, as given in the BGS record (UTM zone 31N, WGS84; easting, northing in meters). Centres only: a line can show its wreck tens of meters away along track, so treat them as approximate positions, not boxes.

sidescanpy.datasets.list_datasets()#: Names fetch() accepts, sorted.

sidescanpy.datasets.data_dir()#: The cache directory fetch() uses when none is given.

sidescanpy.datasets.citation(name)#: Source, licence and attribution text for a registered file.

sidescanpy.datasets.fetch(name, *, directory=None)#

Return a local path to a registered recording, downloading it if needed.

Parameters:

namestr: A name from list_datasets().
directorystr or Path, optional: Where to look for and store the file. Defaults to data_dir().

Returns:

Path: The verified local file.

Raises:

KeyError: If name is not registered.
OSError: If the download fails or the downloaded file’s size or SHA-256 does not match the registry, after two retries (5 s and 20 s apart, each logged as a WARNING). The partial file is removed.