Skip to content

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 the store to retrieve.

  • options (GetOptions | None, default: None ) –

    options for accessing the file. Defaults to None.

Returns:

obspec.GetAsync

Bases: Protocol

get_async async 

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

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 the store 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.

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,
) -> Sequence[Buffer]

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

The choice of how to implement multiple range requests is implementation specific.

Parameters:

  • path (str) –

    The path within the store 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:

  • Sequence[Buffer] –

    A sequence of Buffer, one for each range, each implementing the Python

  • Sequence[Buffer] –

    buffer protocol.

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,
) -> Sequence[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] | Sequence[int] | OffsetRange | SuffixRange

Request transfer of only the specified range of bytes.

The semantics of this attribute 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: Iterable[Buffer], Protocol

Result for a get request.

You can materialize the entire buffer by calling the bytes method or you can stream the result by iterating over it .

Example:

from obspec import Get

def streaming_download(client: Get, path: str):
    resp = client.get(path)
    for buffer in resp:
        print(len(buffer))

attributes property 

attributes: Attributes

Additional object attributes.

meta property 

meta: ObjectMeta

The ObjectMeta for this object.

range property 

range: tuple[int, int]

The range of bytes returned by this request.

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

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.

obspec.GetResultAsync

Bases: AsyncIterable[Buffer], Protocol

Result for an async get request.

You can materialize the entire buffer by calling the bytes_async method or you can stream the result by asynchronously iterating over it.

Example:

from obspec import GetAsync

async def streaming_download(obs: GetAsync, path: str):
    resp = await client.get_async(path)
    async for buffer in resp:
        print(len(buffer))

attributes property 

attributes: Attributes

Additional object attributes.

meta property 

meta: ObjectMeta

The ObjectMeta for this object.

range property 

range: tuple[int, int]

The range of bytes returned by this request.

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

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.

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.