Restore python type-only constructs for simplicity (#327)

Author: kylebarron

obstore/python/obstore/__get.py

@@ -1,9 +1,5 @@
 from typing import TYPE_CHECKING
 
-from .__get import GetOptions, OffsetRange, SuffixRange
-from .__put import PutMode, PutResult, UpdateVersion
-from .__sign import HTTP_METHOD
-from ._attributes import Attribute, Attributes
 from ._obstore import *
 from ._obstore import ___version
 

obstore/python/obstore/__init__.py

@@ -1,11 +1,119 @@
 from collections.abc import Sequence
+from datetime import datetime
+from typing import TypedDict
 
-from .__get import GetOptions
 from ._attributes import Attributes
 from ._bytes import Bytes
 from ._list import ObjectMeta
 from .store import ObjectStore
 
+class OffsetRange(TypedDict):
+    """Request all bytes starting from a given byte offset."""
+
+    offset: int
+    """The byte offset for the offset range request."""
+
+class SuffixRange(TypedDict):
+    """Request up to the last `n` bytes."""
+
+    suffix: int
+    """The number of bytes from the suffix to request."""
+
+class GetOptions(TypedDict, total=False):
+    """Options for a get request.
+
+    All options are optional.
+    """
+
+    if_match: str | None
+    """
+    Request will succeed if the `ObjectMeta::e_tag` matches
+    otherwise returning [`PreconditionError`][obstore.exceptions.PreconditionError].
+
+    See <https://datatracker.ietf.org/doc/html/rfc9110#name-if-match>
+
+    Examples:
+
+    ```text
+    If-Match: "xyzzy"
+    If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+    If-Match: *
+    ```
+    """
+
+    if_none_match: str | None
+    """
+    Request will succeed if the `ObjectMeta::e_tag` does not match
+    otherwise returning [`NotModifiedError`][obstore.exceptions.NotModifiedError].
+
+    See <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.2>
+
+    Examples:
+
+    ```text
+    If-None-Match: "xyzzy"
+    If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+    If-None-Match: *
+    ```
+    """
+
+    if_unmodified_since: datetime | None
+    """
+    Request will succeed if the object has been modified since
+
+    <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.3>
+    """
+
+    if_modified_since: datetime | None
+    """
+    Request will succeed if the object has not been modified since
+    otherwise returning [`PreconditionError`][obstore.exceptions.PreconditionError].
+
+    Some stores, such as S3, will only return `NotModified` for exact
+    timestamp matches, instead of for any timestamp greater than or equal.
+
+    <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.4>
+    """
+
+    range: tuple[int, int] | list[int] | OffsetRange | SuffixRange
+    """
+    Request transfer of only the specified range of bytes
+    otherwise returning [`NotModifiedError`][obstore.exceptions.NotModifiedError].
+
+    The semantics of this tuple are:
+
+    - `(int, int)`: Request a specific range of bytes `(start, end)`.
+
+        If the given range is zero-length or starts after the end of the object, an
+        error will be returned. Additionally, if the range ends after the end of the
+        object, the entire remainder of the object will be returned. Otherwise, the
+        exact requested range will be returned.
+
+        The `end` offset is _exclusive_.
+
+    - `{"offset": int}`: Request all bytes starting from a given byte offset.
+
+        This is equivalent to `bytes={int}-` as an HTTP header.
+
+    - `{"suffix": int}`: Request the last `int` bytes. Note that here, `int` is _the
+        size of the request_, not the byte offset. This is equivalent to `bytes=-{int}`
+        as an HTTP header.
+
+    <https://datatracker.ietf.org/doc/html/rfc9110#name-range>
+    """
+
+    version: str | None
+    """
+    Request a particular object version
+    """
+
+    head: bool
+    """
+    Request transfer of no content
+
+    <https://datatracker.ietf.org/doc/html/rfc9110#name-head>
+    """
+
 class GetResult:
     """Result for a get request.
 

obstore/python/obstore/__put.py

@@ -1,3 +1,5 @@
+from ._attributes import Attribute as Attribute
+from ._attributes import Attributes as Attributes
 from ._buffered import AsyncReadableFile as AsyncReadableFile
 from ._buffered import AsyncWritableFile as AsyncWritableFile
 from ._buffered import ReadableFile as ReadableFile
@@ -12,7 +14,10 @@ from ._copy import copy_async as copy_async
 from ._delete import delete as delete
 from ._delete import delete_async as delete_async
 from ._get import BytesStream as BytesStream
+from ._get import GetOptions as GetOptions
 from ._get import GetResult as GetResult
+from ._get import OffsetRange as OffsetRange
+from ._get import SuffixRange as SuffixRange
 from ._get import get as get
 from ._get import get_async as get_async
 from ._get import get_range as get_range
@@ -28,10 +33,14 @@ from ._list import ObjectMeta as ObjectMeta
 from ._list import list as list  # noqa: A004
 from ._list import list_with_delimiter as list_with_delimiter
 from ._list import list_with_delimiter_async as list_with_delimiter_async
+from ._put import PutMode as PutMode
+from ._put import PutResult as PutResult
+from ._put import UpdateVersion as UpdateVersion
 from ._put import put as put
 from ._put import put_async as put_async
 from ._rename import rename as rename
 from ._rename import rename_async as rename_async
+from ._sign import HTTP_METHOD as HTTP_METHOD
 from ._sign import SignCapableStore as SignCapableStore
 from ._sign import sign as sign
 from ._sign import sign_async as sign_async