Skip to content

User-guide page: safe GeoTIFF IO usage (#2345 PR 1) #2379

@brendancol

Description

@brendancol

Part of epic #2345.

Goal

Add a user-guide page that explains how to use the GeoTIFF IO surface safely without reading source code or SUPPORTED_FEATURES directly.

Scope

Create docs/source/user_guide/geotiff_safe_io.rst and add it to docs/source/user_guide/index.rst.

Sections to cover:

  • Which entry points to prefer (open_geotiff, to_geotiff, dask variants) and what each one expects.
  • How to read SUPPORTED_FEATURES and the tier vocabulary (stable / advanced / experimental / internal-only).
  • Recommended codec choices for the stable contract and what disqualifies a file from the stable subset.
  • COG output: when to pass cog=True, the layout it produces, and which combinations fall outside the stable contract.
  • Fail-closed errors users will hit, what each one means, and how to opt in where an opt-in exists.
  • Remote-read safety limits: env vars and parameters that govern byte budgets, range behavior, and private-host rejection.
  • Pointers to the reference page and the release gate.

Out of scope

  • Rewriting attrs_contract.rst. Cross-link instead.
  • Adding new code or new public APIs. This is documentation only.

Acceptance

  • New docs/source/user_guide/geotiff_safe_io.rst builds without warnings.
  • It is referenced from docs/source/user_guide/index.rst.
  • It does not claim full GDAL / VRT / GPU parity anywhere.
  • A user can answer "is this safe to rely on" from the page alone.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions