stac-hash 0.0.2

Sortable spatio-temporal hashes for STAC items
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

from collections.abc import Sequence
from datetime import datetime
from typing import Literal, overload

__version__: str

class Hasher:
    """Creates sortable spatio-temporal hashes.

    The hasher is built from a datetime range and, optionally, a bounding box.
    Without a `bbox` the hasher covers the whole world.
    """

    def __init__(
        self,
        start_datetime: datetime,
        end_datetime: datetime,
        bbox: tuple[float, float, float, float] | None = None,
    ) -> None: ...
    def hash(self, datetime: datetime, longitude: float, latitude: float) -> int:
        """Hashes a datetime and a point into an `int`."""

    def hash_clamped(
        self, datetime: datetime, longitude: float, latitude: float
    ) -> int:
        """Hashes a datetime and a point, clamping onto the hasher's boundary.

        Unlike `hash`, this never raises for out-of-extent input. A datetime
        before the hasher's start hashes as that start, a longitude west of
        the minimum hashes as that minimum, and so on.
        """

    @overload
    def hash_all(
        self,
        datetimes: Sequence[datetime],
        longitudes: Sequence[float],
        latitudes: Sequence[float],
        skip_invalid: Literal[False] = False,
    ) -> list[int]:
        """Hashes parallel sequences of datetimes, longitudes, and latitudes."""

    @overload
    def hash_all(
        self,
        datetimes: Sequence[datetime],
        longitudes: Sequence[float],
        latitudes: Sequence[float],
        skip_invalid: Literal[True],
    ) -> list[int | None]:
        """Hashes parallel sequences of datetimes, longitudes, and latitudes.

        Every item is checked independently; out-of-extent items become
        `None` in the result instead of raising.
        """

    @overload
    def hash_all(
        self,
        datetimes: Sequence[datetime],
        longitudes: Sequence[float],
        latitudes: Sequence[float],
        skip_invalid: bool,
    ) -> list[int | None]:
        """Hashes parallel sequences of datetimes, longitudes, and latitudes.

        Raises a `ValueError` if the sequences are not the same length, or if
        any item falls outside the hasher's extent. Pass `skip_invalid=True`
        to get `None` for out-of-extent items instead of raising.
        """

    def hash_all(
        self,
        datetimes: Sequence[datetime],
        longitudes: Sequence[float],
        latitudes: Sequence[float],
        skip_invalid: bool = False,
    ) -> list[int] | list[int | None]:
        """Hashes parallel sequences of datetimes, longitudes, and latitudes.

        Raises a `ValueError` if the sequences are not the same length, or if
        any item falls outside the hasher's extent. Pass `skip_invalid=True`
        to get `None` for out-of-extent items instead of raising.
        """

    def hash_all_clamped(
        self,
        datetimes: Sequence[datetime],
        longitudes: Sequence[float],
        latitudes: Sequence[float],
    ) -> list[int]:
        """Hashes parallel sequences, clamping onto the hasher's boundary.

        Raises a `ValueError` only if the sequences are not the same length.
        No item can fall outside the extent, so there is no `skip_invalid`.
        """