chore(migration): Migrate code from googleapis/python-datastore into packages/google-cloud-datastore

[parthea]

See #11015.

This PR should be merged with a merge-commit, not a squash-commit, in order to preserve the git history.

[gemini-code-assist]

Code Review

This pull request migrates the google-cloud-datastore package into the monorepo structure. The changes primarily consist of adding new files for the package source, configuration, and CI/CD workflows. The migration appears to be comprehensive. I've identified a few areas for improvement, including a bare except clause that should be more specific, a potential enhancement to the ExplainMetrics API design for better usability, and an incorrect Python version warning that could confuse users, which relates to maintaining clear environment requirements.

[gemini-code-assist]

Using a bare except: can catch system-exiting exceptions like SystemExit or KeyboardInterrupt, which is generally not intended. It's better to catch Exception to handle application-level errors while allowing system-level exceptions to propagate.

Suggested change

	except: # noqa: E722 do not use bare except, specify exception instead
	self._status = self._ABORTED
	raise
	except Exception:
	self._status = self._ABORTED
	raise

[gemini-code-assist]

The current implementation for conditionally available execution_stats uses a subclass _ExplainAnalyzeMetrics and a base class property that always raises an exception. This can be unintuitive for users, who would need to use try...except or isinstance checks.

A more idiomatic Python approach would be to make execution_stats an optional attribute on ExplainMetrics. This would allow users to simply check if execution_stats is None.

For example:

from typing import Optional

@dataclass(frozen=True)
class ExplainMetrics:
    plan_summary: PlanSummary
    execution_stats: Optional[ExecutionStats] = None

    @staticmethod
    def _from_pb(metrics_pb):
        dict_repr = MessageToDict(metrics_pb._pb, preserving_proto_field_name=True)
        plan_summary = PlanSummary(
            indexes_used=dict_repr.get("plan_summary", {}).get("indexes_used", [])
        )
        execution_stats = None
        if "execution_stats" in dict_repr:
            stats_dict = dict_repr.get("execution_stats", {})
            execution_stats = ExecutionStats(
                results_returned=int(stats_dict.get("results_returned", 0)),
                execution_duration=metrics_pb.execution_stats.execution_duration,
                read_operations=int(stats_dict.get("read_operations", 0)),
                debug_stats=stats_dict.get("debug_stats", {}),
            )
        return ExplainMetrics(
            plan_summary=plan_summary, execution_stats=execution_stats
        )

This would remove the need for the _ExplainAnalyzeMetrics subclass and provide a cleaner API for consumers.

[gemini-code-assist]

This warning for Python versions < 3.9 seems incorrect. It states that these versions are non-supported, but setup.py specifies python_requires=">=3.7" and noxfile.py includes tests for Python 3.7 and 3.8. This could cause unnecessary concern for users on these supported versions. This check should probably be for versions older than 3.7.

References

1. When a release introduces breaking changes in environment requirements, such as dropping support for specific Python versions or major dependency versions (e.g., protobuf), prefer a minor version bump over a patch version bump. This maintains the ability to provide patches for the previous minor version for users still requiring the older environment. This comment highlights an inconsistency in stated Python version support, which relates to maintaining clear environment requirements.