"""Google 스프레드시트 쓰기 공통 계층. 인증 방식 두 가지를 지원한다(설정된 쪽을 자동 선택, 서비스 계정 우선). 1) 사용자 OAuth 리프레시 토큰 — 조직 정책으로 서비스 계정 **키 발급이 막힌** 경우 · `GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN` 1회 동의로 받은 refresh token · `GOOGLE_SHEETS_OAUTH_CLIENT_ID` / `..._SECRET` (없으면 로그인용 `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` 사용) 토큰 발급: `python scripts/google_sheets_authorize.py` 이 방식은 토큰을 발급한 **사용자 권한**으로 동작하므로, 그 사용자가 이미 편집할 수 있는 문서면 별도 공유가 필요 없다. 2) 서비스 계정 JSON · `GOOGLE_SHEETS_CREDENTIALS` 서비스 계정 JSON 파일 경로 · `GOOGLE_SHEETS_CREDENTIALS_JSON` JSON 본문(파일 대신 환경변수로) 대상 문서를 서비스 계정 이메일(client_email)에 **편집자로 공유**해야 한다. - 비밀값(키/토큰)은 로그·화면에 절대 출력하지 않는다. - 라이브러리(google-api-python-client)가 없거나 설정이 비어 있으면 `enabled = False` 로 조용히 비활성화되고, 호출부는 건너뛴다. """ from __future__ import annotations import functools import json import os import threading from typing import Any SCOPES = ["https://www.googleapis.com/auth/spreadsheets"] TOKEN_URI = "https://oauth2.googleapis.com/token" def _hex_color(value: str) -> dict[str, float]: """"RRGGBB" → Sheets API 색상.""" v = (value or "").lstrip("#") return { "red": int(v[0:2], 16) / 255.0, "green": int(v[2:4], 16) / 255.0, "blue": int(v[4:6], 16) / 255.0, } def a1_sheet(title: str) -> str: """A1 표기용 시트 이름 — 작은따옴표로 감싸고 안의 ' 는 '' 로.""" return "'" + title.replace("'", "''") + "'" def col_letter(col: int) -> str: """1-based 열 번호 → 열 문자(A, B, …, AA).""" letters = "" while col > 0: col, rem = divmod(col - 1, 26) letters = chr(65 + rem) + letters return letters def _repeat_cell( sheet_id: int, r1: int, c1: int, r2: int, c2: int, fmt: dict[str, Any], fields: str ) -> dict[str, Any]: """1-based 양끝 포함 범위에 같은 서식을 입히는 요청.""" return { "repeatCell": { "range": { "sheetId": sheet_id, "startRowIndex": r1 - 1, "endRowIndex": r2, "startColumnIndex": c1 - 1, "endColumnIndex": c2, }, "cell": {"userEnteredFormat": fmt}, "fields": fields, } } # 웹 핸들러가 sync def(스레드풀)라 여러 요청이 동시에 이 writer 를 쓸 수 있다. # googleapiclient 의 HTTP 클라이언트(httplib2)는 스레드 안전하지 않고, 같은 날짜 # 시트를 동시에 지우고/쓰면 내용이 섞이므로 시트 작업은 한 번에 하나씩만 한다. _LOCK = threading.RLock() def _serialized(fn: Any) -> Any: @functools.wraps(fn) def wrapper(*args: Any, **kwargs: Any) -> Any: with _LOCK: return fn(*args, **kwargs) return wrapper class GoogleSheetsWriter: """시트 1장을 통째로 다시 쓰는 용도의 얇은 래퍼.""" def __init__(self) -> None: self.enabled = False self.reason = "" self.auth_mode = "" # "service_account" | "oauth" self._service: Any = None self._client_email = "" try: from googleapiclient.discovery import build except ImportError: self.reason = "google-api-python-client 미설치" return creds = self._service_account_creds() if creds is None: creds = self._oauth_creds() if creds is None: if not self.reason: self.reason = ( "GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN 또는 " "GOOGLE_SHEETS_CREDENTIALS(_JSON) 미설정" ) return try: self._service = build("sheets", "v4", credentials=creds, cache_discovery=False) except Exception as exc: # noqa: BLE001 - 사유만 남긴다(비밀값 미출력) self.reason = f"Sheets 클라이언트 생성 실패: {type(exc).__name__}" return self.enabled = True # ── 인증 ───────────────────────────────────────── def _service_account_creds(self) -> Any: raw = (os.getenv("GOOGLE_SHEETS_CREDENTIALS_JSON") or "").strip() path = (os.getenv("GOOGLE_SHEETS_CREDENTIALS") or "").strip() if not raw and not path: return None try: info = json.loads(raw) if raw else json.loads( open(path, encoding="utf-8").read() ) except (OSError, ValueError): self.reason = "서비스 계정 JSON 을 읽지 못했습니다." return None try: from google.oauth2.service_account import Credentials creds = Credentials.from_service_account_info(info, scopes=SCOPES) except Exception as exc: # noqa: BLE001 self.reason = f"서비스 계정 인증 실패: {type(exc).__name__}" return None self._client_email = str(info.get("client_email") or "") self.auth_mode = "service_account" return creds def _oauth_creds(self) -> Any: refresh_token = (os.getenv("GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN") or "").strip() if not refresh_token: return None client_id = ( os.getenv("GOOGLE_SHEETS_OAUTH_CLIENT_ID") or os.getenv("GOOGLE_CLIENT_ID") or "" ).strip() client_secret = ( os.getenv("GOOGLE_SHEETS_OAUTH_CLIENT_SECRET") or os.getenv("GOOGLE_CLIENT_SECRET") or "" ).strip() if not client_id or not client_secret: self.reason = "GOOGLE_SHEETS_OAUTH_CLIENT_ID/SECRET 미설정" return None try: from google.oauth2.credentials import Credentials creds = Credentials( token=None, refresh_token=refresh_token, token_uri=TOKEN_URI, client_id=client_id, client_secret=client_secret, scopes=SCOPES, ) except Exception as exc: # noqa: BLE001 self.reason = f"OAuth 자격 생성 실패: {type(exc).__name__}" return None self.auth_mode = "oauth" return creds @property def client_email(self) -> str: """공유 대상 확인용(비밀값 아님).""" return self._client_email # ──────────────────────────────────────────────── def _sheet_id(self, spreadsheet_id: str, title: str) -> int | None: meta = self._service.spreadsheets().get(spreadsheetId=spreadsheet_id).execute() for sh in meta.get("sheets", []): props = sh.get("properties", {}) if props.get("title") == title: return int(props.get("sheetId")) return None def _create_sheet(self, spreadsheet_id: str, title: str) -> int: res = self._service.spreadsheets().batchUpdate( spreadsheetId=spreadsheet_id, body={"requests": [{"addSheet": {"properties": {"title": title}}}]}, ).execute() return int(res["replies"][0]["addSheet"]["properties"]["sheetId"]) @property def lock(self) -> Any: """읽고 → 쓰기를 한 덩어리로 묶을 때 쓰는 잠금(같은 시트에 동시에 덧붙이지 않게). RLock 이라 잡은 채로 이 writer 의 다른 메서드를 불러도 된다.""" return _LOCK @_serialized def sheet_titles(self, *, spreadsheet_id: str) -> list[str]: """문서의 시트 이름 목록(탭 순서).""" if not self.enabled: raise RuntimeError(self.reason or "Google Sheets 미설정") meta = self._service.spreadsheets().get( spreadsheetId=spreadsheet_id, fields="sheets.properties.title" ).execute() return [str(sh.get("properties", {}).get("title") or "") for sh in meta.get("sheets", [])] @_serialized def read_ranges( self, *, spreadsheet_id: str, ranges: list[str], chunk: int = 50 ) -> list[list[list[Any]]]: """A1 범위 여러 개의 값(범위마다 2차원 목록). 요청 하나가 너무 길지 않게 나눠 읽는다.""" if not self.enabled: raise RuntimeError(self.reason or "Google Sheets 미설정") out: list[list[list[Any]]] = [] for i in range(0, len(ranges), chunk): part = ranges[i:i + chunk] res = self._service.spreadsheets().values().batchGet( spreadsheetId=spreadsheet_id, ranges=part ).execute() got = res.get("valueRanges", []) out.extend(vr.get("values", []) for vr in got) out.extend([] for _ in range(len(part) - len(got))) return out @_serialized def append_block( self, *, spreadsheet_id: str, title: str, cells: dict[tuple[int, int], Any], merges: list[tuple[int, int, int, int]], first_row: int, last_row: int, first_col: int, last_col: int, left_cols: tuple[int, ...] = (9,), highlight: str = "", ) -> dict[str, Any]: """이미 있는 시트의 first_row~last_row 에 표 한 덩어리를 쓴다(위쪽 내용은 그대로). 서식은 write_table 의 데이터 행과 같다 — 가운데 정렬·줄바꿈·테두리, left_cols 만 왼쪽 정렬, highlight("RRGGBB")가 있으면 그 덩어리 배경색. 좌표는 1-based.""" if not self.enabled: raise RuntimeError(self.reason or "Google Sheets 미설정") meta = self._service.spreadsheets().get( spreadsheetId=spreadsheet_id, fields="sheets.properties(sheetId,title,gridProperties.rowCount)", ).execute() props = next( (sh.get("properties", {}) for sh in meta.get("sheets", []) if sh.get("properties", {}).get("title") == title), None, ) if props is None: raise LookupError(f"시트를 찾을 수 없습니다: {title}") sheet_id = int(props.get("sheetId")) row_count = int(props.get("gridProperties", {}).get("rowCount") or 0) requests: list[dict[str, Any]] = [] if row_count < last_row: # 격자보다 아래에는 값을 쓸 수 없으므로 행을 먼저 늘린다 requests.append({"appendDimension": { "sheetId": sheet_id, "dimension": "ROWS", "length": last_row - row_count, }}) for (r1, c1, r2, c2) in merges: requests.append({ "mergeCells": { "mergeType": "MERGE_ALL", "range": { "sheetId": sheet_id, "startRowIndex": r1 - 1, "endRowIndex": r2, "startColumnIndex": c1 - 1, "endColumnIndex": c2, }, } }) requests.append(_repeat_cell( sheet_id, first_row, first_col, last_row, last_col, {"horizontalAlignment": "CENTER", "verticalAlignment": "MIDDLE", "wrapStrategy": "WRAP"}, "userEnteredFormat(horizontalAlignment,verticalAlignment,wrapStrategy)", )) for col in left_cols: requests.append(_repeat_cell( sheet_id, first_row, col, last_row, col, {"horizontalAlignment": "LEFT"}, "userEnteredFormat(horizontalAlignment)", )) if highlight: requests.append(_repeat_cell( sheet_id, first_row, first_col, last_row, last_col, {"backgroundColor": _hex_color(highlight)}, "userEnteredFormat(backgroundColor)", )) border = {"style": "SOLID", "color": {"red": 0, "green": 0, "blue": 0}} requests.append({ "updateBorders": { "range": { "sheetId": sheet_id, "startRowIndex": first_row - 1, "endRowIndex": last_row, "startColumnIndex": first_col - 1, "endColumnIndex": last_col, }, "top": border, "bottom": border, "left": border, "right": border, "innerHorizontal": border, "innerVertical": border, } }) self._service.spreadsheets().batchUpdate( spreadsheetId=spreadsheet_id, body={"requests": requests} ).execute() matrix = [ [cells.get((r, c), "") for c in range(first_col, last_col + 1)] for r in range(first_row, last_row + 1) ] self._service.spreadsheets().values().update( spreadsheetId=spreadsheet_id, range=f"{a1_sheet(title)}!{col_letter(first_col)}{first_row}", valueInputOption="USER_ENTERED", body={"values": matrix}, ).execute() return { "created": False, "title": title, "first_row": first_row, "last_row": last_row, "url": f"https://docs.google.com/spreadsheets/d/{spreadsheet_id}/edit#gid={sheet_id}", } @_serialized def delete_sheet(self, *, spreadsheet_id: str, title: str) -> dict[str, Any]: """이름이 정확히 일치하는 시트 1장을 삭제한다. - 없으면 아무것도 하지 않는다(missing). - 문서에 시트가 그 하나뿐이면 구글이 삭제를 거부하므로, 대신 내용을 비운다(cleared). """ if not self.enabled: raise RuntimeError(self.reason or "Google Sheets 미설정") meta = self._service.spreadsheets().get(spreadsheetId=spreadsheet_id).execute() sheets = meta.get("sheets", []) target = None for sh in sheets: props = sh.get("properties", {}) if props.get("title") == title: target = int(props.get("sheetId")) break if target is None: return {"ok": True, "action": "missing", "title": title} if len(sheets) <= 1: self._service.spreadsheets().batchUpdate( spreadsheetId=spreadsheet_id, body={"requests": [ {"unmergeCells": {"range": {"sheetId": target}}}, {"updateCells": {"range": {"sheetId": target}, "fields": "*"}}, ]}, ).execute() return {"ok": True, "action": "cleared", "title": title} self._service.spreadsheets().batchUpdate( spreadsheetId=spreadsheet_id, body={"requests": [{"deleteSheet": {"sheetId": target}}]}, ).execute() return {"ok": True, "action": "deleted", "title": title} @_serialized def write_table( self, *, spreadsheet_id: str, title: str, cells: dict[tuple[int, int], Any], merges: list[tuple[int, int, int, int]], header_row: int, first_data_row: int, last_row: int, first_col: int, last_col: int, title_row: int, widths: dict[int, int], # 열 번호(1-based) -> 픽셀 header_bg: str = "", row_highlights: list[tuple[int, int, str]] | None = None, ) -> dict[str, Any]: """시트를 만들고(있으면 비우고) 표를 통째로 기록한다. 좌표는 모두 1-based(엑셀과 동일). 반환값에 시트 URL 을 담는다. header_bg / row_highlights 의 색은 "RRGGBB" 16진 문자열. """ if not self.enabled: raise RuntimeError(self.reason or "Google Sheets 미설정") sheet_id = self._sheet_id(spreadsheet_id, title) created = sheet_id is None if created: sheet_id = self._create_sheet(spreadsheet_id, title) rows_n = max([r for (r, _c) in cells] or [1]) cols_n = last_col matrix: list[list[Any]] = [["" for _ in range(cols_n)] for _ in range(rows_n)] for (r, c), value in cells.items(): matrix[r - 1][c - 1] = value requests: list[dict[str, Any]] = [ # 기존 내용/서식/병합 초기화 → 같은 날짜로 다시 확정해도 깨끗하게 덮어쓴다 {"unmergeCells": {"range": {"sheetId": sheet_id}}}, {"updateCells": {"range": {"sheetId": sheet_id}, "fields": "*"}}, ] for (r1, c1, r2, c2) in merges: requests.append({ "mergeCells": { "mergeType": "MERGE_ALL", "range": { "sheetId": sheet_id, "startRowIndex": r1 - 1, "endRowIndex": r2, "startColumnIndex": c1 - 1, "endColumnIndex": c2, }, } }) def _fmt(r1: int, c1: int, r2: int, c2: int, fmt: dict[str, Any], fields: str) -> dict[str, Any]: return _repeat_cell(sheet_id, r1, c1, r2, c2, fmt, fields) requests.append(_fmt( title_row, first_col, title_row, last_col, {"horizontalAlignment": "CENTER", "verticalAlignment": "MIDDLE", "textFormat": {"bold": True, "fontSize": 16}}, "userEnteredFormat(horizontalAlignment,verticalAlignment,textFormat)", )) header_fmt: dict[str, Any] = { "horizontalAlignment": "CENTER", "verticalAlignment": "MIDDLE", "textFormat": {"bold": True}, } header_fields = "userEnteredFormat(horizontalAlignment,verticalAlignment,textFormat)" if header_bg: header_fmt["backgroundColor"] = _hex_color(header_bg) header_fields = ( "userEnteredFormat(horizontalAlignment,verticalAlignment," "textFormat,backgroundColor)" ) requests.append(_fmt(header_row, first_col, header_row, last_col, header_fmt, header_fields)) if last_row >= first_data_row: requests.append(_fmt( first_data_row, first_col, last_row, last_col, {"horizontalAlignment": "CENTER", "verticalAlignment": "MIDDLE", "wrapStrategy": "WRAP"}, "userEnteredFormat(horizontalAlignment,verticalAlignment,wrapStrategy)", )) # 제품명 칸만 왼쪽 정렬 requests.append(_fmt( first_data_row, 9, last_row, 9, {"horizontalAlignment": "LEFT"}, "userEnteredFormat(horizontalAlignment)", )) border = {"style": "SOLID", "color": {"red": 0, "green": 0, "blue": 0}} requests.append({ "updateBorders": { "range": { "sheetId": sheet_id, "startRowIndex": header_row - 1, "endRowIndex": last_row, "startColumnIndex": first_col - 1, "endColumnIndex": last_col, }, "top": border, "bottom": border, "left": border, "right": border, "innerHorizontal": border, "innerVertical": border, } }) # 특정 행 구간 배경색(예: 파렛트 출고 블록) for (r1, r2, color) in (row_highlights or []): requests.append(_fmt( r1, first_col, r2, last_col, {"backgroundColor": _hex_color(color)}, "userEnteredFormat(backgroundColor)", )) for col, width in widths.items(): requests.append({ "updateDimensionProperties": { "range": { "sheetId": sheet_id, "dimension": "COLUMNS", "startIndex": col - 1, "endIndex": col, }, "properties": {"pixelSize": int(width)}, "fields": "pixelSize", } }) self._service.spreadsheets().batchUpdate( spreadsheetId=spreadsheet_id, body={"requests": requests} ).execute() self._service.spreadsheets().values().update( spreadsheetId=spreadsheet_id, range=f"'{title}'!A1", valueInputOption="USER_ENTERED", body={"values": matrix}, ).execute() return { "created": created, "title": title, "url": f"https://docs.google.com/spreadsheets/d/{spreadsheet_id}/edit#gid={sheet_id}", } _writer: GoogleSheetsWriter | None = None def get_writer() -> GoogleSheetsWriter: """프로세스 1개당 1회 초기화.""" global _writer # noqa: PLW0603 with _LOCK: if _writer is None: _writer = GoogleSheetsWriter() return _writer