Get¶

obspec.Get ¶

Bases: Protocol

get ¶

get(path: str, *, options: GetOptions | None = None) -> GetResult

Return the bytes that are stored at the specified location.

Parameters:

path (str) –

The path within ObjectStore to retrieve.
options (GetOptions | None, default: None ) –

options for accessing the file. Defaults to None.

Returns:

GetResult –

GetResult

obspec.GetAsync ¶

Bases: Protocol

get_async `async` ¶

get_async(path: str, *, options: GetOptions | None = None) -> GetResult

Call get asynchronously.

Refer to the documentation for Get.

obspec.GetRange ¶

Bases: Protocol

get_range ¶

get_range(
    path: str, *, start: int, end: int | None = None, length: int | None = None
) -> Buffer

Return the bytes stored at the specified location in the given byte range.

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.

Parameters:

path (str) –

The path within ObjectStore to retrieve.

Other Parameters:

start (int) –

The start of the byte range.
end (int | None) –

The end of the byte range (exclusive). Either end or length must be non-None.
length (int | None) –

The number of bytes of the byte range. Either end or length must be non-None.

Returns:

Buffer –

A Buffer object implementing the Python buffer protocol, allowing zero-copy access to the underlying memory provided by Rust.

obspec.GetRangeAsync ¶

Bases: Protocol

get_range_async `async` ¶

get_range_async(
    path: str, *, start: int, end: int | None = None, length: int | None = None
) -> Buffer

Call get_range asynchronously.

Refer to the documentation for GetRange.

obspec.GetRanges ¶

Bases: Protocol

get_ranges ¶

get_ranges(
    path: str,
    *,
    starts: Sequence[int],
    ends: Sequence[int] | None = None,
    lengths: Sequence[int] | None = None,
) -> list[Buffer]

Return the bytes stored at the specified location in the given byte ranges.

To improve performance this will:

Transparently combine ranges less than 1MB apart into a single underlying request
Make multiple fetch requests in parallel (up to maximum of 10)

Parameters:

path (str) –

The path within ObjectStore to retrieve.

Other Parameters:

starts (Sequence[int]) –

A sequence of int where each offset starts.
ends (Sequence[int] | None) –

A sequence of int where each offset ends (exclusive). Either ends or lengths must be non-None.
lengths (Sequence[int] | None) –

A sequence of int with the number of bytes of each byte range. Either ends or lengths must be non-None.

Returns:

list[Buffer] –

A sequence of Buffer, one for each range. This Buffer object implements
list[Buffer] –

the Python buffer protocol, allowing zero-copy access to the underlying
list[Buffer] –

memory provided by Rust.

obspec.GetRangesAsync ¶

Bases: Protocol

get_ranges_async `async` ¶

get_ranges_async(
    path: str,
    *,
    starts: Sequence[int],
    ends: Sequence[int] | None = None,
    lengths: Sequence[int] | None = None,
) -> list[Buffer]

Call get_ranges asynchronously.

Refer to the documentation for GetRanges.

obspec.GetOptions ¶

Bases: TypedDict

Options for a get request.

All options are optional.

head `instance-attribute` ¶

head: bool

Request transfer of no content

datatracker.ietf.org/doc/html/rfc9110#name-head

if_match `instance-attribute` ¶

if_match: str | None

Request will succeed if the ObjectMeta::e_tag matches.

See datatracker.ietf.org/doc/html/rfc9110#name-if-match

Examples:

If-Match: "xyzzy"
If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
If-Match: *

if_modified_since `instance-attribute` ¶

if_modified_since: datetime | None

Request will succeed if the object has not been modified since.

Some stores, such as S3, will only return NotModified for exact timestamp matches, instead of for any timestamp greater than or equal.

datatracker.ietf.org/doc/html/rfc9110#section-13.1.4

if_none_match `instance-attribute` ¶

if_none_match: str | None

Request will succeed if the ObjectMeta::e_tag does not match.

See datatracker.ietf.org/doc/html/rfc9110#section-13.1.2

Examples:

If-None-Match: "xyzzy"
If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
If-None-Match: *

if_unmodified_since `instance-attribute` ¶

if_unmodified_since: datetime | None

Request will succeed if the object has been modified since

datatracker.ietf.org/doc/html/rfc9110#section-13.1.3

range `instance-attribute` ¶

range: tuple[int, int] | list[int] | OffsetRange | SuffixRange

Request transfer of only the specified range of bytes.

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.

datatracker.ietf.org/doc/html/rfc9110#name-range

version `instance-attribute` ¶

version: str | None

Request a particular object version

obspec.GetResult ¶

Bases: Protocol

Result for a get request.

You can materialize the entire buffer by using either bytes or bytes_async, or you can stream the result using stream. __iter__ and __aiter__ are implemented as aliases to stream, so you can alternatively call iter() or aiter() on GetResult to start an iterator.

Using as an async iterator:

resp = await obs.get_async(store, path)
# 5MB chunk size in stream
stream = resp.stream(min_chunk_size=5 * 1024 * 1024)
async for buf in stream:
    print(len(buf))

Using as a sync iterator:

resp = obs.get(store, path)
# 20MB chunk size in stream
stream = resp.stream(min_chunk_size=20 * 1024 * 1024)
for buf in stream:
    print(len(buf))

Note that after calling bytes, bytes_async, or stream, you will no longer be able to call other methods on this object, such as the meta attribute.

attributes `property` ¶

attributes: Attributes

Additional object attributes.

This must be accessed before calling stream, bytes, or bytes_async.

meta `property` ¶

meta: ObjectMeta

The ObjectMeta for this object.

This must be accessed before calling stream, bytes, or bytes_async.

range `property` ¶

range: tuple[int, int]

The range of bytes returned by this request.

Note that this is (start, stop) not (start, length).

This must be accessed before calling stream, bytes, or bytes_async.

aiter ¶

__aiter__() -> BufferStream

Return a chunked stream over the result's bytes.

Uses the default (10MB) chunk size.

iter ¶

__iter__() -> BufferStream

Return a chunked stream over the result's bytes.

Uses the default (10MB) chunk size.

bytes ¶

bytes() -> Buffer

Collect the data into a Buffer object.

This implements the Python buffer protocol. You can copy the buffer to Python memory by passing to bytes.

bytes_async `async` ¶

bytes_async() -> Buffer

Collect the data into a Buffer object.

This implements the Python buffer protocol. You can copy the buffer to Python memory by passing to bytes.

stream ¶

stream(min_chunk_size: int = 10 * 1024 * 1024) -> BufferStream

Return a chunked stream over the result's bytes.

Parameters:

min_chunk_size (int, default: 10 * 1024 * 1024 ) –

The minimum size in bytes for each chunk in the returned BufferStream. All chunks except for the last chunk will be at least this size. Defaults to 10*1024*1024 (10MB).

Returns:

BufferStream –

A chunked stream

obspec.BufferStream ¶

Bases: Protocol

An async stream of bytes.

aiter ¶

__aiter__() -> Self

Return Self as an async iterator.

anext `async` ¶

__anext__() -> Buffer

Return the next Buffer chunk in the stream.

iter ¶

__iter__() -> Self

Return Self as an async iterator.

next ¶

__next__() -> Buffer

Return the next Buffer chunk in the stream.

obspec.OffsetRange ¶

Bases: TypedDict

Request all bytes starting from a given byte offset.

offset `instance-attribute` ¶

offset: int

The byte offset for the offset range request.

obspec.SuffixRange ¶

Bases: TypedDict

Request up to the last n bytes.

suffix `instance-attribute` ¶

suffix: int

The number of bytes from the suffix to request.

Get¶

obspec.Get ¶

get ¶

obspec.GetAsync ¶

get_async async ¶

obspec.GetRange ¶

get_range ¶

obspec.GetRangeAsync ¶

get_range_async async ¶

obspec.GetRanges ¶

get_ranges ¶

obspec.GetRangesAsync ¶

get_ranges_async async ¶

obspec.GetOptions ¶

head instance-attribute ¶

if_match instance-attribute ¶

if_modified_since instance-attribute ¶

if_none_match instance-attribute ¶

if_unmodified_since instance-attribute ¶

range instance-attribute ¶

version instance-attribute ¶

obspec.GetResult ¶

attributes property ¶

meta property ¶

range property ¶

__aiter__ ¶

__iter__ ¶

bytes ¶

bytes_async async ¶

stream ¶

obspec.BufferStream ¶

__aiter__ ¶

__anext__ async ¶

__iter__ ¶

__next__ ¶

obspec.OffsetRange ¶

offset instance-attribute ¶

obspec.SuffixRange ¶

suffix instance-attribute ¶

get_async `async` ¶

get_range_async `async` ¶

get_ranges_async `async` ¶

head `instance-attribute` ¶

if_match `instance-attribute` ¶

if_modified_since `instance-attribute` ¶

if_none_match `instance-attribute` ¶

if_unmodified_since `instance-attribute` ¶

range `instance-attribute` ¶

version `instance-attribute` ¶

attributes `property` ¶

meta `property` ¶

range `property` ¶

aiter ¶

iter ¶

bytes_async `async` ¶

aiter ¶

anext `async` ¶

iter ¶

next ¶

offset `instance-attribute` ¶

suffix `instance-attribute` ¶