Arista Protobuf / Python gRPC bindings generator & library

Common errors

• ModuleNotFoundError: No module named 'grpc_tools'

  cause The `grpcio-tools` package, which contains the `grpc_tools.protoc` module for Python-based compilation, is not installed.
  fix Install the `grpcio-tools` package: `pip install grpcio-tools`. Alternatively, ensure the full `aristaproto[compiler]` is installed: `pip install "aristaproto[compiler]"`.

• TypeError: 'Timestamp' object has no attribute 'tzinfo' (or similar datetime related errors)

  cause `aristaproto` customizes `Timestamp` handling by subclassing Python's `datetime` to maintain nanosecond precision. Direct interactions expecting standard `datetime` behavior without considering this subclassing can lead to issues.
  fix When converting between `aristaproto.Timestamp` and standard `datetime` objects, be mindful of the subclassing. If you need a pure `datetime` object, explicitly convert it, but be aware of potential loss of nanosecond precision if not handled correctly. Refer to `aristaproto` documentation on `Timestamp` conversions.

• ERROR: Package 'aristaproto' requires a different Python: <4.0, >=3.9

  cause You are attempting to install `aristaproto` on a Python version older than 3.9.
  fix Upgrade your Python environment to version 3.9 or newer. Consider using `pyenv` or `conda` for managing multiple Python versions.

Warnings

• breaking Python versions older than 3.9 are no longer supported. Attempting to install or run on older versions will fail.
  Fix: Upgrade your Python environment to 3.9 or newer.
• gotcha `aristaproto` is a fork of `python-betterproto`. While many concepts are similar, direct migrations may require adjustments due to renaming, specific behavior changes (e.g., Timestamp handling), and updated dependencies.
  Fix: Review the `aristaproto` GitHub README for a list of changes compared to the base project, especially regarding `Timestamp` precision and `serialized_on_wire` behavior.
• gotcha The `aristaproto.serialized_on_wire()` function only supports checking if Proto 3 *message* fields were sent on the wire. It cannot be used to determine if *scalar* fields (like strings, integers) were explicitly sent or are just default values.
  Fix: Be aware of this limitation when designing your protobuf messages and logic. For scalar fields, you might need to use wrapper types (e.g., `google.protobuf.StringValue`) if differentiating between unset and default values is critical.
• gotcha When using the `--python_aristaproto_opt=pydantic_dataclasses` option for Pydantic model generation, you must explicitly install `pydantic` in your project. It is not included by default with `aristaproto`.
  Fix: Ensure `pydantic` is listed as a dependency in your project (e.g., `pip install pydantic`).

Install

• pip install "aristaproto[compiler]" Install with compiler support
• pip install aristaproto Install library only

Imports

• Message

  import aristaproto
  from generated_proto_file import MyMessage
  
  class MyMessage(aristaproto.Message): ...

  Base class for generated protobuf messages.
• which_one_of

  import aristaproto
  
  field_name, value = aristaproto.which_one_of(message_instance, 'oneof_group_name')

  Helper to determine which field in a 'oneof' group is set.
• serialized_on_wire

  import aristaproto
  
  if aristaproto.serialized_on_wire(message_instance.field_name): ...

  Checks if a message field (Proto 3 only) was sent on the wire, not applicable to scalar fields.

Quickstart

This quickstart demonstrates compiling a simple `.proto` file and then importing and using the generated Python message classes for creation, serialization to JSON, and deserialization from JSON. It requires `protoc` to be installed and accessible in your PATH, or `grpcio-tools` if using the Python `grpc_tools.protoc` module for compilation.

# 1. Create a .proto file (e.g., example.proto)
# syntax = "proto3";
# package hello;
# message Greeting {
#     string message = 1;
# }

# 2. Compile the .proto file (assuming 'example.proto' is in current dir)
# mkdir -p lib
# protoc -I . --python_aristaproto_out=lib example.proto
# OR using grpcio-tools (after pip install grpcio-tools):
# python -m grpc_tools.protoc -I . --python_aristaproto_out=lib example.proto

# 3. Use the generated code (e.g., from lib/hello/__init__.py)
import os
import sys
# Add the 'lib' directory to Python path if not already added
# In a real project, 'lib' would likely be part of your package structure
# or installed.
if os.path.exists('lib') and 'lib' not in sys.path:
    sys.path.insert(0, 'lib')

from hello import Greeting

g = Greeting(message="Hello, Arista!")
print(f"Created message: {g.message}")

# Example of serialization
json_output = g.to_json()
print(f"JSON representation: {json_output}")

# Example of deserialization
g_from_json = Greeting.from_json(json_output)
print(f"Message from JSON: {g_from_json.message}")