2.16.3.4. pycsamt.geology.rock_providers#

Pluggable rock-property sources for RockDatabase.

No public, machine-readable service currently maps a rock or lithology name directly to a resistivity range (see pycsamt.geology.rock_library for why the built-in table is a literature compilation rather than a live fetch). This module instead gives from_url() and from_provider() a small, source-agnostic contract, so a project- or organisation-controlled endpoint – an internal REST API, a JSON file on a shared drive or object store, or a public service, should one appear – can be plugged in without touching pycsamt.geology.lithology.

Every provider implements RockPropertyProvider: a zero-argument fetch() returning (entries, metadata), a list of RockEntry plus a small provenance dictionary recording where they came from. RemoteRockPropertyProvider caches successful fetches under ~/.pycsamt/rock_db (override with the PYCSAMT_ROCKDB_CACHE environment variable or the cache_dir argument, matching the convention already used by pycsamt.ai._zoo’s model cache) and, on any failure – network error, timeout, or a response that does not match the expected schema – falls back first to a stale cache entry and then to LocalRockPropertyProvider, rather than raising, unless fallback=False.

Classes

LocalRockPropertyProvider([csv_path])

Provider wrapping the bundled table or a local CSV file.

RemoteRockPropertyProvider(url, *[, ...])

Fetch rock entries as JSON from url, with caching and fallback.

RockPropertyProvider(*args, **kwargs)

Minimal contract every rock-property source must satisfy.

Exceptions

RockProviderFetchError

Raised by a provider when a fetch fails and fallback=False.
class pycsamt.geology.rock_providers.RockPropertyProvider(*args, **kwargs)[source]

Bases: Protocol

Minimal contract every rock-property source must satisfy.

fetch()[source]

Return (entries, metadata) for a RockDatabase.

Return type:

tuple[list[RockEntry], dict[str, Any]]

class pycsamt.geology.rock_providers.LocalRockPropertyProvider(csv_path=None)[source]

Bases: object

Provider wrapping the bundled table or a local CSV file.

This is what RemoteRockPropertyProvider falls back to, and is also usable directly wherever a RockPropertyProvider is expected but no remote source is involved.

Parameters:

csv_path (path-like, optional) – When given, entries come from from_csv(). When omitted, entries come from default().

fetch()[source]
Return type:

tuple[list[RockEntry], dict[str, Any]]

class pycsamt.geology.rock_providers.RemoteRockPropertyProvider(url, *, cache_dir=None, ttl_seconds=86400.0, timeout=10.0, force=False, fallback=True)[source]

Bases: object

Fetch rock entries as JSON from url, with caching and fallback.

Parameters:

  • url (str) – Any URL urllib.request.urlopen() can open (http(s)://, file://, …), serving a JSON array of objects with at least name, rho_min, rho_max.

  • cache_dir (path-like, optional) – Override the local cache location. Defaults to $PYCSAMT_ROCKDB_CACHE or ~/.pycsamt/rock_db.

  • ttl_seconds (float) – Reuse a cached response younger than this many seconds instead of re-fetching.

  • timeout (float) – Network timeout in seconds for the fetch itself.

  • force (bool) – Re-fetch even if a fresh cache entry exists.

  • fallback (bool) – On failure, fall back to a stale cache entry (if any) and then to LocalRockPropertyProvider, instead of raising RockProviderFetchError.

fetch()[source]
Return type:

tuple[list[RockEntry], dict[str, Any]]

exception pycsamt.geology.rock_providers.RockProviderFetchError[source]

Bases: RuntimeError

Raised by a provider when a fetch fails and fallback=False.

Examples

>>> isinstance(RockProviderFetchError("network down"), RuntimeError)
True