Differential D8029 Diff 28925 swh/objstorage/interface.py

Changeset View

Standalone View

swh/objstorage/interface.py

# Copyright (C) 2015-2022 The Software Heritage developers		# Copyright (C) 2015-2022 The Software Heritage developers
# See the AUTHORS file at the top-level directory of this distribution		# See the AUTHORS file at the top-level directory of this distribution
# License: GNU General Public License version 3, or any later version		# License: GNU General Public License version 3, or any later version
# See top-level LICENSE file for more information		# See top-level LICENSE file for more information

from typing import Dict, Iterator, List, Optional		from typing import Dict, Iterator, List, Optional, Union

from typing_extensions import Protocol, runtime_checkable		from typing_extensions import Protocol, TypedDict, runtime_checkable

from swh.core.api import remote_api_endpoint		from swh.core.api import remote_api_endpoint
from swh.objstorage.constants import DEFAULT_LIMIT		from swh.objstorage.constants import DEFAULT_LIMIT

ObjId = bytes
"""Type of object ids, which should be a sha1 hash."""		class CompositeObjId(TypedDict, total=False):
		sha1: bytes
		sha1_git: bytes
		sha256: bytes
		blake2s256: bytes


		ObjId = Union[bytes, CompositeObjId]
		"""Type of object ids, which should be ``{hash: value for hash in SUPPORTED_HASHES}``;
		but single sha1 hashes are supported for legacy clients"""


@runtime_checkable		@runtime_checkable
class ObjStorageInterface(Protocol):		class ObjStorageInterface(Protocol):
"""High-level API to manipulate the Software Heritage object storage.		"""High-level API to manipulate the Software Heritage object storage.

Conceptually, the object storage offers the following methods:		Conceptually, the object storage offers the following methods:

Show All 37 Lines	def __contains__(self, obj_id: ObjId) -> bool:
...		...

@remote_api_endpoint("content/add")		@remote_api_endpoint("content/add")
def add(self, content: bytes, obj_id: ObjId, check_presence: bool = True) -> None:		def add(self, content: bytes, obj_id: ObjId, check_presence: bool = True) -> None:
"""Add a new object to the object storage.		"""Add a new object to the object storage.

Args:		Args:
content: object's raw content to add in storage.		content: object's raw content to add in storage.
obj_id: checksum of [bytes] using [ID_HASH_ALGO]		obj_id (bytes): checksum of [bytes] using [ID_HASH_ALGO]
		ardumontUnsubmitted Done Inline Actions no need, it's already typed in the signature. ardumont: no need, it's already typed in the signature.
		vlorentzAuthorUnsubmitted Done Inline Actions it's also incorrect; looks like I accidentally reverted a previous diff. vlorentz: it's also incorrect; looks like I accidentally reverted a previous diff.
algorithm. It is trusted to match the bytes.		algorithm. It is trusted to match the bytes.
check_presence (bool): indicate if the presence of the		check_presence (bool): indicate if the presence of the
content should be verified before adding the file.		content should be verified before adding the file.

Returns:		Returns:
the id (bytes) of the object into the storage.		the id (bytes) of the object into the storage.

"""		"""
▲ Show 20 Lines • Show All 90 Lines • ▼ Show 20 Lines	def delete(self, obj_id: ObjId):
obj_id: object identifier.		obj_id: object identifier.

Raises:		Raises:
ObjNotFoundError: if the requested object is missing.		ObjNotFoundError: if the requested object is missing.

"""		"""
...		...

def __iter__(self) -> Iterator[ObjId]:		def __iter__(self) -> Iterator[CompositeObjId]:
...		...

def list_content(		def list_content(
self, last_obj_id: Optional[ObjId] = None, limit: int = DEFAULT_LIMIT		self, last_obj_id: Optional[ObjId] = None, limit: int = DEFAULT_LIMIT
) -> Iterator[ObjId]:		) -> Iterator[CompositeObjId]:
"""Generates known object ids.		"""Generates known object ids.

Args:		Args:
last_obj_id: object id from which to iterate from		last_obj_id: object id from which to iterate from
(excluded).		(excluded).
limit (int): max number of object ids to generate.		limit (int): max number of object ids to generate.

Generates:		Generates:
obj_id: object ids.		obj_id: object ids.
"""		"""
...		...