Metadata-Version: 2.4
Name: rainbow-rb-flat-buffers
Version: 0.0.9.dev11
Summary: Rainbow FlatBuffers Conveted to Python
Author-email: Derek <dfd1123@rainbow-robotics.com>
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: flatbuffers<26.0.0,>=25.2.10
Requires-Dist: numpy>=2.3.3

# rb_flat_buffers

`rb_flat_buffers`는 `schemas/*.fbs`로부터 생성된 Python FlatBuffer 코드 패키지입니다.

## 핵심 요약

- 소스 스키마: `/schemas/**/*.fbs`
- 생성 결과 1: `backend/packages/rb_flat_buffers/src/rb_flat_buffers/**` (FlatBuffer Python generated code)
- 생성 결과 2: `backend/packages/rb_schemas/src/rb_schemas/fbs_models/**` (Pydantic 모델)

즉, `make backend.flatc`를 실행하면:
1. FlatBuffer Python 코드가 `rb_flat_buffers`에 생성되고
2. 동일 스키마 기반 Pydantic 모델이 `rb_schemas`에 생성됩니다.

## 생성 방법

프로젝트 루트에서:

```bash
make backend.flatc
```

`backend.mk`의 `backend.flatc` 타깃은 내부적으로 아래를 순서대로 실행합니다.

1) `scripts/backend/generate_flatbuffers.py`
- `flatc --python --gen-object-api --gen-all` 기반 생성
- 출력: `backend/packages/rb_flat_buffers/src/rb_flat_buffers`

2) `backend/packages/rb_flat_buffers/scripts/patch_imports.py`
- generated import 경로/누락 import 보정

3) `scripts/backend/fbs_to_pydantic.py`
- `.fbs`를 Pydantic 모델로 변환
- 출력: `backend/packages/rb_schemas/src/rb_schemas/fbs_models`

## 언제 실행해야 하나

아래 케이스에서는 `make backend.flatc`를 다시 실행해야 합니다.

- `schemas/*.fbs` 수정
- 신규 `.fbs` 파일 추가/삭제
- FlatBuffer 타입/필드 변경(table/struct/enum/union)

## rb_flat_buffers 사용 예시

예: 요청 객체 전송 + **값이 채워진 FlatBuffer 응답(`returnValue`)** 수신

```python
# server/queryable 쪽
from rb_flat_buffers.IPC.Request_Move_SmoothJogStop import Request_Move_SmoothJogStopT
from rb_flat_buffers.IPC.Response_Functions import Response_FunctionsT
from rb_zenoh.router import ZenohRouter

router = ZenohRouter()

@router.queryable(
    "C500920/call_smoothjog_stop",
    flatbuffer_req_t=Request_Move_SmoothJogStopT,
    flatbuffer_res_buf_size=64,
)
def on_call_pause(req, params=None):
    print(req.stoptime)  # 요청으로 전달된 값 사용 가능
    res = Response_FunctionsT()
    res.returnValue = 123  # 빈 payload가 아니라 실제 값 포함
    return res
```

```python
# client/query 쪽
from rb_flat_buffers.IPC.Request_Move_SmoothJogStop import Request_Move_SmoothJogStopT
from rb_flat_buffers.IPC.Response_Functions import Response_FunctionsT
from rb_zenoh.client import ZenohClient

client = ZenohClient()
req = Request_Move_SmoothJogStopT()
req.stoptime = 0.7

res = client.query_one(
    "C500920/call_smoothjog_stop",
    flatbuffer_req_obj=req,
    flatbuffer_res_T_class=Response_FunctionsT,
    flatbuffer_buf_size=64,
)

obj = res.get("obj_payload")
print(obj.returnValue)  # 123
```

## rb_schemas(Pydantic) 사용 예시

`query_one` 응답의 `obj_payload`를 Pydantic으로 validate한 뒤, `model_dump`에서 원하는 key case를 선택할 수 있습니다.

```python
from rb_flat_buffers.IPC.Response_Functions import Response_FunctionsT
from rb_schemas.fbs_models.nexus.v1.deploy_models import Response_Deploy_UploadPD
from rb_utils.parser import t_to_dict
from rb_zenoh.client import ZenohClient

client = ZenohClient()

res = client.query_one(
    "deploy/call_upload",
    flatbuffer_res_T_class=Response_FunctionsT,
    timeout=0.3,
)

obj_payload = res.get("obj_payload")

# 1) FlatBuffer T 객체 -> dict 변환
raw_dict = t_to_dict(obj_payload) if obj_payload is not None else {}

# 2) Pydantic validate
pd_obj = Response_Deploy_UploadPD.model_validate(raw_dict)

# 3) key case 선택
snake_case = pd_obj.model_dump(by_alias=False)  # ex) return_value
camel_case = pd_obj.model_dump(by_alias=True)   # ex) returnValue
```

## 주의사항

- 패키지명은 `rb_flat_buffers`입니다. (`rb_flat_buffer` 아님)
- generated 파일은 수동 수정하지 않는 것을 권장합니다.
- `flatc`가 PATH에 없으면 `make backend.flatc`가 실패합니다.
