Skip to content

List

obspec.List

Bases: Protocol

list 

list(
    prefix: str | None = None, *, offset: str | None = None
) -> Iterator[Sequence[ObjectMeta]]

List all the objects with the given prefix.

Prefixes are evaluated on a path segment basis, i.e. foo/bar/ is a prefix of foo/bar/x but not of foo/bar_baz/x. List is recursive, i.e. foo/bar/more/x will be included.

Examples:

Synchronously iterate through list results:

import obspec

def upload_files(client: obspec.Put):
    for i in range(100):
        client.put(f"file{i}.txt", b"foo")

def list_files(client: obspec.List):
    stream = client.list()
    for list_result in stream:
        print(list_result[0])
        # {'path': 'file0.txt', 'last_modified': datetime.datetime(2024, 10, 23, 19, 19, 28, 781723, tzinfo=datetime.timezone.utc), 'size': 3, 'e_tag': '0', 'version': None}
        break

Note

The order of returned ObjectMeta is not guaranteed

Parameters:

  • prefix (str | None, default: None ) –

    The prefix within the store to use for listing. Defaults to None.

Other Parameters:

  • offset (str | None) –

    If provided, list all the objects with the given prefix and a location greater than offset. Defaults to None.

Returns:

obspec.ListAsync

Bases: Protocol

list_async 

list_async(
    prefix: str | None = None, *, offset: str | None = None
) -> AsyncIterator[Sequence[ObjectMeta]]

List all the objects with the given prefix.

Note that this method itself is not async. It's a synchronous method but returns an async iterator.

Refer to obspec.List for more information about list semantics.

Examples:

Asynchronously iterate through list results. Just change for to async for:

stream = obs.list_async(store)
async for list_result in stream:
    print(list_result[2])
    # {'path': 'file10.txt', 'last_modified': datetime.datetime(2024, 10, 23, 19, 21, 46, 224725, tzinfo=datetime.timezone.utc), 'size': 3, 'e_tag': '10', 'version': None}
    break

Note

The order of returned ObjectMeta is not guaranteed

Parameters:

  • prefix (str | None, default: None ) –

    The prefix within the store to use for listing. Defaults to None.

Other Parameters:

  • offset (str | None) –

    If provided, list all the objects with the given prefix and a location greater than offset. Defaults to None.

Returns:

obspec.ListWithDelimiter

Bases: Protocol

list_with_delimiter 

list_with_delimiter(
    prefix: str | None = None,
) -> ListResult[Sequence[ObjectMeta]]

List objects with the given prefix and an implementation specific delimiter.

Returns common prefixes (directories) in addition to object metadata.

Prefixes are evaluated on a path segment basis, i.e. foo/bar/ is a prefix of foo/bar/x but not of foo/bar_baz/x. This list is not recursive, i.e. foo/bar/more/x will not be included.

Note

Any prefix supplied to this prefix parameter will not be stripped off the paths in the result.

Parameters:

  • prefix (str | None, default: None ) –

    The prefix within the store to use for listing. Defaults to None.

Returns:

obspec.ListWithDelimiterAsync

Bases: Protocol

list_with_delimiter_async async 

list_with_delimiter_async(
    prefix: str | None = None,
) -> ListResult[Sequence[ObjectMeta]]

Call list_with_delimiter asynchronously.

Refer to the documentation for ListWithDelimiter.

obspec.ListResult

Bases: TypedDict, Generic[ListChunkType_co]

Result of a list_with_delimiter call.

Includes objects, prefixes (directories) and a token for the next set of results. Individual result sets may be limited to 1,000 objects based on the underlying object storage's limitations.

common_prefixes instance-attribute 

common_prefixes: Sequence[str]

Prefixes that are common (like directories)

objects instance-attribute 

objects: ListChunkType_co

Object metadata for the listing

obspec.ListChunkType_co module-attribute 

ListChunkType_co = TypeVar('ListChunkType_co', covariant=True)

The data structure used for holding list results.