feat: Add Geometry & Geography Types (#2859)

Closes #1820

# Rationale for this change

Apache Iceberg v3 introduces native `geometry` and `geography` primitive
types.
This PR adds spec-compliant support for those types in PyIceberg,
including:

- New primitive types with parameter handling and format-version
enforcement
- Schema parsing and round-trip serialization
- Avro mapping using WKB bytes
- PyArrow / Parquet integration with version-aware fallbacks
- Unit test coverage for type behavior and compatibility constraints

A full design and scope discussion is available in the accompanying RFC:
📄 **RFC: [Iceberg v3 Geospatial Primitive
Types](https://github.com/apache/iceberg-python/issues/3004)**
The RFC documents scope, non-goals, compatibility constraints, and known
limitations.

# Are these changes tested?

Yes.

- Unit tests cover:
  - Type creation (default and custom parameters)
  - `__str__` / `__repr__` round-tripping
  - Equality, hashing, and pickling
  - Format version enforcement (v3-only)
- PyArrow-dependent behavior is version-gated and conditionally tested

# Are there any user-facing changes?

Yes.

- Users may now declare `geometry` and `geography` columns in Iceberg v3
schemas
- Parquet files written with PyArrow ≥ 21 preserve GEO logical types
when available
- Limitations (e.g. no WKB↔WKT conversion, no spatial predicates) are
documented

<!-- Changelog label added -->
11 files changed
tree: c80b7f3cd0f3ac0823a7e0d228dd4083ebaa2318
  1. .github/
  2. dev/
  3. mkdocs/
  4. notebooks/
  5. pyiceberg/
  6. tests/
  7. vendor/
  8. .asf.yaml
  9. .codespellrc
  10. .gitignore
  11. .markdownlint.yaml
  12. .pre-commit-config.yaml
  13. LICENSE
  14. Makefile
  15. MANIFEST.in
  16. NOTICE
  17. pyproject.toml
  18. README.md
  19. ruff.toml
  20. setup.py
  21. uv.lock
README.md

Iceberg Python

PyIceberg is a Python library for programmatic access to Iceberg table metadata as well as to table data in Iceberg format. It is a Python implementation of the Iceberg table spec.

The documentation is available at https://py.iceberg.apache.org/.

Get in Touch