Add @typing.override to catalog and FileIO implementations (#3360)

Adds `@override` from `typing_extensions` to all concrete
implementations of `Catalog`, `MetastoreCatalog`, `FileIO`, `InputFile`,
and `OutputFile` so overridden base-class methods are explicit and can
be verified by static type checkers.

Uses `from typing_extensions import override` (same pattern already used
for `Self` in `typedef.py`) instead of `from typing import override`
which requires Python 3.12+ and would break the supported 3.10/3.11
versions.

Closes #1310

# Rationale for this change

`@typing.override` (PEP 698) makes it explicit which methods
intentionally override a parent class method, helping static type
checkers catch mistakes early. The previous attempt (#1312) and the
currently open PR (#3359) both use `from typing import override` which
only exists in Python 3.12+. This PR uses `typing_extensions` to support
all versions from 3.10+.

## Are these changes tested?

No new tests are needed — `@override` is a static analysis marker with
zero runtime effect. `make lint` and `make test` (3625 passed) both pass
cleanly.

## Are there any user-facing changes?

No.

Author: vishnuprakaz

pyiceberg/catalog/__init__.py

@@ -31,6 +31,8 @@
     cast,
 )
 
+from typing_extensions import override
+
 from pyiceberg.exceptions import (
     NamespaceAlreadyExistsError,
     NoSuchNamespaceError,
@@ -904,9 +906,11 @@ class MetastoreCatalog(Catalog, ABC):
     def __init__(self, name: str, **properties: str):
         super().__init__(name, **properties)
 
+    @override
     def supports_server_side_planning(self) -> bool:
         return False
 
+    @override
     def create_table_transaction(
         self,
         identifier: str | Identifier,
@@ -920,13 +924,15 @@ def create_table_transaction(
             self._create_staged_table(identifier, schema, location, partition_spec, sort_order, properties)
         )
 
+    @override
     def table_exists(self, identifier: str | Identifier) -> bool:
         try:
             self.load_table(identifier)
             return True
         except NoSuchTableError:
             return False
 
+    @override
     def namespace_exists(self, namespace: str | Identifier) -> bool:
         """Check if a namespace exists.
 
@@ -942,6 +948,7 @@ def namespace_exists(self, namespace: str | Identifier) -> bool:
         except NoSuchNamespaceError:
             return False
 
+    @override
     def purge_table(self, identifier: str | Identifier) -> None:
         table = self.load_table(identifier)
         self.drop_table(identifier)
@@ -962,6 +969,7 @@ def purge_table(self, identifier: str | Identifier) -> None:
         delete_files(io, prev_metadata_files, PREVIOUS_METADATA)
         delete_files(io, {table.metadata_location}, METADATA)
 
+    @override
     def create_view(
         self,
         identifier: str | Identifier,

pyiceberg/catalog/bigquery_metastore.py

@@ -26,6 +26,7 @@
 from google.cloud.bigquery.schema import SerDeInfo, StorageDescriptor
 from google.cloud.exceptions import Conflict
 from google.oauth2 import service_account
+from typing_extensions import override
 
 from pyiceberg.catalog import WAREHOUSE_LOCATION, MetastoreCatalog, PropertiesUpdateSummary
 from pyiceberg.exceptions import NamespaceAlreadyExistsError, NoSuchNamespaceError, NoSuchTableError, TableAlreadyExistsError
@@ -101,6 +102,7 @@ def __init__(self, name: str, **properties: str):
         self.location = location
         self.project_id = project_id
 
+    @override
     def create_table(
         self,
         identifier: str | Identifier,
@@ -156,6 +158,7 @@ def create_table(
 
         return self.load_table(identifier=identifier)
 
+    @override
     def create_namespace(self, namespace: str | Identifier, properties: Properties = EMPTY_DICT) -> None:
         """Create a namespace in the catalog.
 
@@ -177,6 +180,7 @@ def create_namespace(self, namespace: str | Identifier, properties: Properties =
         except Conflict as e:
             raise NamespaceAlreadyExistsError("Namespace {database_name} already exists") from e
 
+    @override
     def load_table(self, identifier: str | Identifier) -> Table:
         """
         Load the table's metadata and returns the table instance.
@@ -205,6 +209,7 @@ def load_table(self, identifier: str | Identifier) -> Table:
         except NotFound as e:
             raise NoSuchTableError(f"Table does not exist: {dataset_name}.{table_name}") from e
 
+    @override
     def drop_table(self, identifier: str | Identifier) -> None:
         """Drop a table.
 
@@ -225,14 +230,17 @@ def drop_table(self, identifier: str | Identifier) -> None:
         except NoSuchTableError as e:
             raise NoSuchTableError(f"Table does not exist: {dataset_name}.{table_name}") from e
 
+    @override
     def commit_table(
         self, table: Table, requirements: tuple[TableRequirement, ...], updates: tuple[TableUpdate, ...]
     ) -> CommitTableResponse:
         raise NotImplementedError
 
+    @override
     def rename_table(self, from_identifier: str | Identifier, to_identifier: str | Identifier) -> Table:
         raise NotImplementedError
 
+    @override
     def drop_namespace(self, namespace: str | Identifier) -> None:
         database_name = self.identifier_to_database(namespace)
 
@@ -243,6 +251,7 @@ def drop_namespace(self, namespace: str | Identifier) -> None:
         except NotFound as e:
             raise NoSuchNamespaceError(f"Namespace {namespace} does not exist.") from e
 
+    @override
     def list_tables(self, namespace: str | Identifier) -> list[Identifier]:
         database_name = self.identifier_to_database(namespace)
         iceberg_tables: list[Identifier] = []
@@ -257,6 +266,7 @@ def list_tables(self, namespace: str | Identifier) -> list[Identifier]:
             raise NoSuchNamespaceError(f"Namespace (dataset) '{database_name}' not found.") from None
         return iceberg_tables
 
+    @override
     def list_namespaces(self, namespace: str | Identifier = ()) -> list[Identifier]:
         # Since this catalog only supports one-level namespaces, it always returns an empty list unless
         # passed an empty namespace to list all namespaces within the catalog.
@@ -267,6 +277,7 @@ def list_namespaces(self, namespace: str | Identifier = ()) -> list[Identifier]:
         datasets_iterator = self.client.list_datasets()
         return [(dataset.dataset_id,) for dataset in datasets_iterator]
 
+    @override
     def register_table(self, identifier: str | Identifier, metadata_location: str, overwrite: bool = False) -> Table:
         """Register a new table using existing metadata.
 
@@ -302,21 +313,27 @@ def register_table(self, identifier: str | Identifier, metadata_location: str, o
 
         return self.load_table(identifier=identifier)
 
+    @override
     def list_views(self, namespace: str | Identifier) -> list[Identifier]:
         raise NotImplementedError
 
+    @override
     def register_view(self, identifier: str | Identifier, metadata_location: str) -> View:
         raise NotImplementedError
 
+    @override
     def drop_view(self, identifier: str | Identifier) -> None:
         raise NotImplementedError
 
+    @override
     def view_exists(self, identifier: str | Identifier) -> bool:
         raise NotImplementedError
 
+    @override
     def load_view(self, identifier: str | Identifier) -> View:
         raise NotImplementedError
 
+    @override
     def load_namespace_properties(self, namespace: str | Identifier) -> Properties:
         dataset_name = self.identifier_to_database(namespace)
 
@@ -329,6 +346,7 @@ def load_namespace_properties(self, namespace: str | Identifier) -> Properties:
             raise NoSuchNamespaceError(f"Namespace {namespace} not found") from e
         return {}
 
+    @override
     def update_namespace_properties(
         self, namespace: str | Identifier, removals: set[str] | None = None, updates: Properties = EMPTY_DICT
     ) -> PropertiesUpdateSummary:

pyiceberg/catalog/dynamodb.py

@@ -24,6 +24,7 @@
 )
 
 import boto3
+from typing_extensions import override
 
 from pyiceberg.catalog import (
     BOTOCORE_SESSION,
@@ -151,6 +152,7 @@ def _dynamodb_table_exists(self) -> bool:
         else:
             return True
 
+    @override
     def create_table(
         self,
         identifier: str | Identifier,
@@ -210,6 +212,7 @@ def create_table(
 
         return self.load_table(identifier=identifier)
 
+    @override
     def register_table(self, identifier: str | Identifier, metadata_location: str, overwrite: bool = False) -> Table:
         """Register a new table using existing metadata.
 
@@ -226,6 +229,7 @@ def register_table(self, identifier: str | Identifier, metadata_location: str, o
         """
         raise NotImplementedError
 
+    @override
     def commit_table(
         self, table: Table, requirements: tuple[TableRequirement, ...], updates: tuple[TableUpdate, ...]
     ) -> CommitTableResponse:
@@ -245,6 +249,7 @@ def commit_table(
         """
         raise NotImplementedError
 
+    @override
     def load_table(self, identifier: str | Identifier) -> Table:
         """
         Load the table's metadata and returns the table instance.
@@ -265,6 +270,7 @@ def load_table(self, identifier: str | Identifier) -> Table:
         dynamo_table_item = self._get_iceberg_table_item(database_name=database_name, table_name=table_name)
         return self._convert_dynamo_table_item_to_iceberg_table(dynamo_table_item=dynamo_table_item)
 
+    @override
     def drop_table(self, identifier: str | Identifier) -> None:
         """Drop a table.
 
@@ -285,6 +291,7 @@ def drop_table(self, identifier: str | Identifier) -> None:
         except ConditionalCheckFailedException as e:
             raise NoSuchTableError(f"Table does not exist: {database_name}.{table_name}") from e
 
+    @override
     def rename_table(self, from_identifier: str | Identifier, to_identifier: str | Identifier) -> Table:
         """Rename a fully classified table name.
 
@@ -351,6 +358,7 @@ def rename_table(self, from_identifier: str | Identifier, to_identifier: str | I
 
         return self.load_table(to_identifier)
 
+    @override
     def create_namespace(self, namespace: str | Identifier, properties: Properties = EMPTY_DICT) -> None:
         """Create a namespace in the catalog.
 
@@ -372,6 +380,7 @@ def create_namespace(self, namespace: str | Identifier, properties: Properties =
         except ConditionalCheckFailedException as e:
             raise NamespaceAlreadyExistsError(f"Database {database_name} already exists") from e
 
+    @override
     def drop_namespace(self, namespace: str | Identifier) -> None:
         """Drop a namespace.
 
@@ -399,6 +408,7 @@ def drop_namespace(self, namespace: str | Identifier) -> None:
         except ConditionalCheckFailedException as e:
             raise NoSuchNamespaceError(f"Database does not exist: {database_name}") from e
 
+    @override
     def list_tables(self, namespace: str | Identifier) -> list[Identifier]:
         """List Iceberg tables under the given namespace in the catalog.
 
@@ -443,6 +453,7 @@ def list_tables(self, namespace: str | Identifier) -> list[Identifier]:
 
         return table_identifiers
 
+    @override
     def list_namespaces(self, namespace: str | Identifier = ()) -> list[Identifier]:
         """List top-level namespaces from the catalog.
 
@@ -485,6 +496,7 @@ def list_namespaces(self, namespace: str | Identifier = ()) -> list[Identifier]:
 
         return database_identifiers
 
+    @override
     def load_namespace_properties(self, namespace: str | Identifier) -> Properties:
         """
         Get properties for a namespace.
@@ -503,6 +515,7 @@ def load_namespace_properties(self, namespace: str | Identifier) -> Properties:
         namespace_dict = _convert_dynamo_item_to_regular_dict(namespace_item)
         return _get_namespace_properties(namespace_dict=namespace_dict)
 
+    @override
     def update_namespace_properties(
         self, namespace: str | Identifier, removals: set[str] | None = None, updates: Properties = EMPTY_DICT
     ) -> PropertiesUpdateSummary:
@@ -540,6 +553,7 @@ def update_namespace_properties(
 
         return properties_update_summary
 
+    @override
     def create_view(
         self,
         identifier: str | Identifier,
@@ -550,18 +564,23 @@ def create_view(
     ) -> View:
         raise NotImplementedError
 
+    @override
     def list_views(self, namespace: str | Identifier) -> list[Identifier]:
         raise NotImplementedError
 
+    @override
     def register_view(self, identifier: str | Identifier, metadata_location: str) -> View:
         raise NotImplementedError
 
+    @override
     def drop_view(self, identifier: str | Identifier) -> None:
         raise NotImplementedError
 
+    @override
     def view_exists(self, identifier: str | Identifier) -> bool:
         raise NotImplementedError
 
+    @override
     def load_view(self, identifier: str | Identifier) -> View:
         raise NotImplementedError