feat(firestore): add BSONInt32 support

[ohmayr]

This PR adds support for BSONInt32 in the Firestore Python SDK. BSONInt32 allows developers to explicitly store 32-bit signed integer values in Firestore documents according to the official Firestore BSON specification.

Added BSONInt32 class: Introduces a container class that holds 32-bit signed integers between $-2,147,483,648$ and $2,147,483,647$.
Input Validation: Automatically rejects booleans and non-integer types with a TypeError, and raises a ValueError if a number is outside 32-bit signed integer bounds.
Wire Format: Serializes to {"__int__": value} for Firestore BSON document writes.
Package Exports: Exported BSONInt32 in google.cloud.firestore and google.cloud.firestore_v1, and updated post-processing generator rules to preserve exports during regeneration.
Testing: Added unit tests covering validation, equality, hashing, copying, and pickling, plus verified sync and async document writes on Firestore Enterprise DB.

Fixes b/562163919 🦕

[gemini-code-assist]

Code Review

This pull request introduces the BSONInt32 class to represent 32-bit signed integers in Firestore BSON, updating the package exports and adding system and unit tests. The feedback suggests improving the __hash__ method of BSONInt32 to include the class type in the hash tuple, which prevents hash collisions with plain integers since they are not considered equal.

[gemini-code-assist]

The current implementation of __hash__ returns hash(self._value). Since BSONInt32(42) != 42 (as verified in the unit tests), having the same hash value for both BSONInt32(42) and 42 violates the best practice of minimizing hash collisions for unequal objects of different types. If both are stored in the same dictionary or set, it will cause a hash collision and degrade lookup performance.

Consider incorporating the class type into the hash to ensure distinct hash values for BSONInt32 instances compared to plain integers.

Suggested change

	def __hash__(self) -> int:
	return hash(self._value)
	def __hash__(self) -> int:
	return hash((BSONInt32, self._value))

[daniel-sanche]

LGTM

[daniel-sanche]

nit: we can probably rely on the backend for this kind of validation. But this is fine too