googleapis / googleapis/google-cloud-python
Docs say RouteMatrixElement.duration is Duration, but runtime returns datetime.timedelta
- Linguagem predominante
- Python
- Estrelas
- 5.4k
- Forks
- 1.8k
- Merge médio
- 2d 23h
- PRs com merge (30d)
- 123
Descrição
### Determine this is the right repository
- [x] I determined this is the correct repository in which to report this bug.
### Summary of the issue
**Context**
I was using `google-maps-routing` and inspecting `RouteMatrixElement.duration` from a `compute_route_matrix` response.
**Expected Behavior:**
The documentation indicates that `RouteMatrixElement.duration` is a `google.protobuf.duration_pb2.Duration`.
**Actual Behavior:**
At runtime, `RouteMatrixElement.duration` is returned as a `datetime.timedelta` object.
This appears to be a documentation or generated type-surface mismatch rather than a server-side API problem. The underlying protobuf field may be `Duration`, but the Python client returns the marshaled native Python type.
### API client name and version
google-maps-routing 0.10.0
### Reproduction steps: code
file: main.py
```python
from datetime import timedelta
from google.maps import routing_v2
def main():
client = routing_v2.RoutesClient()
request = routing_v2.ComputeRouteMatrixRequest(
origins=[
routing_v2.RouteMatrixOrigin(
waypoint=routing_v2.Waypoint(
address="1600 Amphitheatre Parkway, Mountain View, CA"
)
)
],
destinations=[
routing_v2.RouteMatrixDestination(
waypoint=routing_v2.Waypoint(
address="1 Infinite Loop, Cupertino, CA"
)
)
],
travel_mode=routing_v2.RouteTravelMode.DRIVE,
)
stream = client.compute_route_matrix(
request=request,
metadata=[(
"x-goog-fieldmask",
"originIndex,destinationIndex,status,condition,distanceMeters,duration"
)],
)
element = next(iter(stream))
print("type:", type(element.duration))
print("is timedelta:", isinstance(element.duration, timedelta))
if __name__ == "__main__":
main()
```
### Reproduction steps: supporting files
### Reproduction steps: actual results
```
type:
is timedelta: True
```
### Reproduction steps: expected results
```
type:
is timedelta: False
```
### OS & version + platform
Window 11 25H2
### Python environment
Python 3.11.9
### Python dependencies
pip list
| Package | Version |
|---------------------------|--------------|
| altgraph | 0.17.5 |
| certifi | 2026.2.25 |
| cffi | 2.0.0 |
| charset-normalizer | 3.4.6 |
| cryptography | 46.0.6 |
| google-api-core | 2.30.1 |
| google-auth | 2.49.1 |
| google-geo-type | 0.6.0 |
| google-maps-routing | 0.10.0 |
| googleapis-common-protos | 1.73.1 |
| greenlet | 3.3.2 |
| grpcio | 1.80.0 |
| grpcio-status | 1.80.0 |
| idna | 3.11 |
| jellyfish | 1.2.1 |
| packaging | 26.0 |
| pefile | 2024.8.26 |
| pip | 24.2 |
| proto-plus | 1.27.2 |
| protobuf | 6.33.6 |
| pyasn1 | 0.6.3 |
| pyasn1_modules | 0.4.2 |
| pycparser | 3.0 |
| pyinstaller | 6.19.0 |
| pyinstaller-hooks-contrib | 2026.4 |
| pyodbc | 5.3.0 |
| python-dateutil | 2.9.0.post0 |
| python-dotenv | 1.2.2 |
| pywin32-ctypes | 0.2.3 |
| requests | 2.33.1 |
| setuptools | 82.0.1 |
| six | 1.17.0 |
| SQLAlchemy | 2.0.48 |
| typing_extensions | 4.15.0 |
| urllib3 | 2.6.3 |
| wheel | 0.44.0 |
### Additional context
This appears to be a documentation or generated type-surface mismatch rather than a server-side Routes API bug.
The docs for `RouteMatrixElement.duration` describe the protobuf field type (`google.protobuf.duration_pb2.Duration`), but at runtime the Python client returns the marshaled native Python type (`datetime.timedelta`). That makes the docs misleading when trying to write type-aware Python code.
If this behavior is intentional because of proto-plus marshalling, the documentation should reflect the runtime Python type. If it is not intentional, then the runtime type is inconsistent with the documented type.
Guia de contribuição
Direção de pesquisa
Comece com a reprodução em main.py e inspecione a superfície de tipos documentada e gerada para routing_v2.RouteMatrixElement.duration, comparando-a com o valor datetime.timedelta retornado por compute_route_matrix. Confirme se o comportamento do cliente é intencional e, em seguida, atualize a documentação ou a descrição de tipo relevante para que os tipos Python declarados e observados sejam compatíveis.
Escrita pelo modelo de indexação a partir do texto da issue.
Avaliação
- Stack de tecnologia
- python
- Domínio
- api, documentation
- Tipo de issue
- Documentação
- Dificuldade
- 3/5
- Tempo estimado
- 1-2 dias
- Status de atividade
- Pouca atividade
- Clareza
- Razoavelmente clara
- Facilidade para iniciantes
- 52/100