From 365f30766c64c2a509ccb83197b008e35d04189c Mon Sep 17 00:00:00 2001 From: Fokko Driesprong Date: Wed, 3 Aug 2022 00:33:03 +0200 Subject: [PATCH] Python: Cleanup catalog docstring (#5421) --- pyiceberg/catalog/base.py | 71 ++++++++++++++++++++------------------ pyiceberg/catalog/rest.py | 4 +-- pyiceberg/exceptions.py | 4 +-- tests/catalog/test_base.py | 11 +++--- tests/catalog/test_rest.py | 4 +-- 5 files changed, 49 insertions(+), 45 deletions(-) diff --git a/pyiceberg/catalog/base.py b/pyiceberg/catalog/base.py index d70fd7b57c..a0e2e6296c 100644 --- a/pyiceberg/catalog/base.py +++ b/pyiceberg/catalog/base.py @@ -44,8 +44,8 @@ class Catalog(ABC): or tuple of strings. Attributes: - name(str): Name of the catalog - properties(Properties): Catalog properties + name (str): Name of the catalog + properties (Properties): Catalog properties """ def __init__(self, name: str, properties: Properties): @@ -73,18 +73,18 @@ def create_table( """Create a table Args: - identifier: Table identifier. - schema: Table's schema. - location: Location for the table. Optional Argument. - partition_spec: PartitionSpec for the table. - sort_order: SortOrder for the table. - properties: Table properties that can be a string based dictionary. Optional Argument. + identifier (str | Identifier): Table identifier. + schema (Schema): Table's schema. + location (str): Location for the table. Optional Argument. + partition_spec (PartitionSpec): PartitionSpec for the table. + sort_order (SortOrder): SortOrder for the table. + properties (Properties | None): Table properties that can be a string based dictionary. Optional Argument. Returns: Table: the created table instance Raises: - AlreadyExistsError: If a table with the name already exists + TableAlreadyExistsError: If a table with the name already exists """ @abstractmethod @@ -95,13 +95,13 @@ def load_table(self, identifier: str | Identifier) -> Table: Note: This method doesn't scan data stored in the table. Args: - identifier: Table identifier. + identifier (str | Identifier): Table identifier. Returns: Table: the table instance with its metadata Raises: - TableNotFoundError: If a table with the name does not exist + NoSuchTableError: If a table with the name does not exist """ @abstractmethod @@ -109,10 +109,10 @@ def drop_table(self, identifier: str | Identifier) -> None: """Drop a table. Args: - identifier: Table identifier. + identifier (str | Identifier): Table identifier. Raises: - TableNotFoundError: If a table with the name does not exist + NoSuchTableError: If a table with the name does not exist """ @abstractmethod @@ -120,10 +120,10 @@ def purge_table(self, identifier: str | Identifier) -> None: """Drop a table and purge all data and metadata files. Args: - identifier: Table identifier. + identifier (str | Identifier): Table identifier. Raises: - TableNotFoundError: If a table with the name does not exist + NoSuchTableError: If a table with the name does not exist """ @abstractmethod @@ -131,14 +131,14 @@ def rename_table(self, from_identifier: str | Identifier, to_identifier: str | I """Rename a fully classified table name Args: - from_identifier: Existing table identifier. - to_identifier: New table identifier. + from_identifier (str | Identifier): Existing table identifier. + to_identifier (str | Identifier): New table identifier. Returns: Table: the updated table instance with its metadata Raises: - TableNotFoundError: If a table with the name does not exist + NoSuchTableError: If a table with the name does not exist """ @abstractmethod @@ -146,11 +146,11 @@ def create_namespace(self, namespace: str | Identifier, properties: Properties | """Create a namespace in the catalog. Args: - namespace: Namespace identifier - properties: A string dictionary of properties for the given namespace + namespace (str | Identifier): Namespace identifier + properties (Properties | None): A string dictionary of properties for the given namespace Raises: - AlreadyExistsError: If a namespace with the given name already exists + NamespaceAlreadyExistsError: If a namespace with the given name already exists """ @abstractmethod @@ -158,10 +158,10 @@ def drop_namespace(self, namespace: str | Identifier) -> None: """Drop a namespace. Args: - namespace: Namespace identifier + namespace (str | Identifier): Namespace identifier Raises: - NamespaceNotFoundError: If a namespace with the given name does not exist + NoSuchNamespaceError: If a namespace with the given name does not exist NamespaceNotEmptyError: If the namespace is not empty """ @@ -172,13 +172,13 @@ def list_tables(self, namespace: str | Identifier | None = None) -> list[Identif If namespace not provided, will list all tables in the catalog. Args: - namespace: Namespace identifier to search. + namespace (str | Identifier | None): Namespace identifier to search. Returns: List[Identifier]: list of table identifiers. Raises: - NamespaceNotFoundError: If a namespace with the given name does not exist + NoSuchNamespaceError: If a namespace with the given name does not exist """ @abstractmethod @@ -187,6 +187,9 @@ def list_namespaces(self) -> list[Identifier]: Returns: List[Identifier]: a List of namespace identifiers + + Raises: + NoSuchNamespaceError: If a namespace with the given name does not exist """ @abstractmethod @@ -194,13 +197,13 @@ def load_namespace_properties(self, namespace: str | Identifier) -> Properties: """Get properties for a namespace. Args: - namespace: Namespace identifier + namespace (str | Identifier): Namespace identifier Returns: Properties: Properties for the given namespace Raises: - NamespaceNotFoundError: If a namespace with the given name does not exist + NoSuchNamespaceError: If a namespace with the given name does not exist """ @abstractmethod @@ -210,12 +213,12 @@ def update_namespace_properties( """Removes provided property keys and updates properties for a namespace. Args: - namespace: Namespace identifier - removals: Set of property keys that need to be removed. Optional Argument. - updates: Properties to be updated for the given namespace. Optional Argument. + namespace (str | Identifier): Namespace identifier + removals (Set[str]): Set of property keys that need to be removed. Optional Argument. + updates (Properties | None): Properties to be updated for the given namespace. Optional Argument. Raises: - NamespaceNotFoundError: If a namespace with the given name does not exist + NoSuchNamespaceError: If a namespace with the given name does not exist ValueError: If removals and updates have overlapping keys. """ @@ -226,7 +229,7 @@ def identifier_to_tuple(identifier: str | Identifier) -> Identifier: If the identifier is a string, it is split into a tuple on '.'. If it is a tuple, it is used as-is. Args: - identifier: an identifier, either a string or tuple of strings + identifier (str | Identifier: an identifier, either a string or tuple of strings Returns: Identifier: a tuple of strings @@ -238,7 +241,7 @@ def table_name_from(identifier: str | Identifier) -> str: """Extracts table name from a table identifier Args: - identifier: a table identifier + identifier (str | Identifier: a table identifier Returns: str: Table name @@ -250,7 +253,7 @@ def namespace_from(identifier: str | Identifier) -> Identifier: """Extracts table namespace from a table identifier Args: - identifier: a table identifier + identifier (str | Identifier: a table identifier Returns: Identifier: Namespace identifier diff --git a/pyiceberg/catalog/rest.py b/pyiceberg/catalog/rest.py index 188f5a8a6d..b5938267ba 100644 --- a/pyiceberg/catalog/rest.py +++ b/pyiceberg/catalog/rest.py @@ -33,11 +33,11 @@ from pyiceberg.catalog import Identifier, Properties from pyiceberg.catalog.base import Catalog, PropertiesUpdateSummary from pyiceberg.exceptions import ( - AlreadyExistsError, AuthorizationExpiredError, BadCredentialsError, BadRequestError, ForbiddenError, + NamespaceAlreadyExistsError, NoSuchNamespaceError, NoSuchTableError, RESTError, @@ -386,7 +386,7 @@ def create_namespace(self, namespace: Union[str, Identifier], properties: Option try: response.raise_for_status() except HTTPError as exc: - self._handle_non_200_response(exc, {404: NoSuchNamespaceError, 409: AlreadyExistsError}) + self._handle_non_200_response(exc, {404: NoSuchNamespaceError, 409: NamespaceAlreadyExistsError}) def drop_namespace(self, namespace: Union[str, Identifier]) -> None: namespace = NAMESPACE_SEPARATOR.join(self.identifier_to_tuple(namespace)) diff --git a/pyiceberg/exceptions.py b/pyiceberg/exceptions.py index 517252f9a1..432c25675f 100644 --- a/pyiceberg/exceptions.py +++ b/pyiceberg/exceptions.py @@ -24,8 +24,8 @@ class NamespaceNotEmptyError(Exception): """Raised when a name-space being dropped is not empty""" -class AlreadyExistsError(Exception): - """Raised when a table or name-space being created already exists in the catalog""" +class NamespaceAlreadyExistsError(Exception): + """Raised when a name-space being created already exists in the catalog""" class ValidationError(Exception): diff --git a/tests/catalog/test_base.py b/tests/catalog/test_base.py index 49790ecbf3..3ca41da083 100644 --- a/tests/catalog/test_base.py +++ b/tests/catalog/test_base.py @@ -28,10 +28,11 @@ from pyiceberg.catalog import Identifier, Properties from pyiceberg.catalog.base import Catalog, PropertiesUpdateSummary from pyiceberg.exceptions import ( - AlreadyExistsError, + NamespaceAlreadyExistsError, NamespaceNotEmptyError, NoSuchNamespaceError, NoSuchTableError, + TableAlreadyExistsError, ) from pyiceberg.schema import Schema from pyiceberg.table.base import Table @@ -66,7 +67,7 @@ def create_table( namespace = Catalog.namespace_from(identifier) if identifier in self.__tables: - raise AlreadyExistsError(f"Table already exists: {identifier}") + raise TableAlreadyExistsError(f"Table already exists: {identifier}") else: if namespace not in self.__namespaces: self.__namespaces[namespace] = {} @@ -110,7 +111,7 @@ def rename_table(self, from_identifier: Union[str, Identifier], to_identifier: U def create_namespace(self, namespace: Union[str, Identifier], properties: Optional[Properties] = None) -> None: namespace = Catalog.identifier_to_tuple(namespace) if namespace in self.__namespaces: - raise AlreadyExistsError(f"Namespace already exists: {namespace}") + raise NamespaceAlreadyExistsError(f"Namespace already exists: {namespace}") else: self.__namespaces[namespace] = properties if properties else {} @@ -244,7 +245,7 @@ def test_create_table_raises_error_when_table_already_exists(catalog: InMemoryCa # Given given_catalog_has_a_table(catalog) # When - with pytest.raises(AlreadyExistsError, match=TABLE_ALREADY_EXISTS_ERROR): + with pytest.raises(TableAlreadyExistsError, match=TABLE_ALREADY_EXISTS_ERROR): catalog.create_table( identifier=TEST_TABLE_IDENTIFIER, schema=TEST_TABLE_SCHEMA, @@ -326,7 +327,7 @@ def test_create_namespace_raises_error_on_existing_namespace(catalog: InMemoryCa # Given catalog.create_namespace(TEST_TABLE_NAMESPACE, TEST_TABLE_PROPERTIES) # When - with pytest.raises(AlreadyExistsError, match=NAMESPACE_ALREADY_EXISTS_ERROR): + with pytest.raises(NamespaceAlreadyExistsError, match=NAMESPACE_ALREADY_EXISTS_ERROR): catalog.create_namespace(TEST_TABLE_NAMESPACE, TEST_TABLE_PROPERTIES) diff --git a/tests/catalog/test_rest.py b/tests/catalog/test_rest.py index cec2023035..b3c7b661f2 100644 --- a/tests/catalog/test_rest.py +++ b/tests/catalog/test_rest.py @@ -23,8 +23,8 @@ from pyiceberg.catalog.base import PropertiesUpdateSummary, Table from pyiceberg.catalog.rest import RestCatalog from pyiceberg.exceptions import ( - AlreadyExistsError, BadCredentialsError, + NamespaceAlreadyExistsError, NoSuchNamespaceError, NoSuchTableError, TableAlreadyExistsError, @@ -161,7 +161,7 @@ def test_create_namespace_409(rest_mock: Mocker): }, status_code=409, ) - with pytest.raises(AlreadyExistsError) as e: + with pytest.raises(NamespaceAlreadyExistsError) as e: RestCatalog("rest", {}, TEST_URI, token=TEST_TOKEN).create_namespace(namespace) assert "Namespace already exists" in str(e.value)