[Python] 두 개의 Task 클래스를 계층 구조로 리팩터링 하기

수행에 오랜 시간이 걸려서 한번 trigger 되면 알아서 주어진 일을 수행하고 그 결과 물을 전달하는 task를 worker라는 패키지 안에 넣어 두었다. 이 녀석은 주어진 dataset으로 AI model training을 수행했기에 TrainingTask 라는 class에 넣어 두었다. 조금 시간이 흘러서 이번에는 Dataset을 한 번 받으면 그 안에 있는 내용을 unzip해서 database에 등록하고 여차저차한 일을 수행하는 새로운 class를 도입해야 하는 상황이 되었는데, 이 녀석의 이름을 DatasetTask라고 짓고 코드를 구성하다 보니, task에 필요한 parameter들을 가져와서 작업하고 결과물을 돌려주는 구조가 기존의 TrainingTask와 매우 유사했다.

이번 포스팅에서는 혼자만 있던 TrainingTask와 유사한 기능을 가진 DatasetTask를 정의하면서 중복을 걷어낸 과정을 단계별로 정리한다. 파이썬의 ABC, 추상 프로퍼티, frozen dataclass, 구조적 패턴 매칭을 어떻게 사용했는지를 보려고 한다.

공통 코드를 베이스 클래스로 끌어올리기

두 클래스는 각자의 고유한 일을 하기 전에 똑같은 준비 작업을 수행하고 있다.

  • 환경 변수에서 페이로드 읽기
  • JSON 파싱
  • 페이로드의 task_id가 기대한 값과 같은지 확인
  • 로드 여부 추적

이 부분을 BaseTask로 옮기고 템플릿 메서드 패턴을 적용했다. 전체 흐름은 베이스 클래스가 잡고, 서브클래스는 hook인 _inflate_payload()의 내용을 채워준다.

class BaseTask:
    def inflate(self):
        raw = os.environ.get(self._PAYLOAD_ENV)
        if raw is None:
            raise RuntimeError(f"Environment variable {self._PAYLOAD_ENV!r} is not set.")
        payload = json.loads(raw)
        if payload.get("task_id") != self._id:
            raise RuntimeError("task_id mismatch")
        self._inflate_payload(payload)   # 서브클래스별 로직
        self._loaded = True

여기에 작은 헬퍼 _ensure_loaded(field)도 추가했다. 여러 곳에 흩어져 있던 “아직 로드되지 않았음” 검사를 하나로 묶은 것이다. 에러 메시지에 type(self).__name__을 넣어서, 각 서브클래스는 여전히 자기 클래스 이름이 찍힌 에러를 받는다.

함정: 클래스 본문 안에서는 부모에게 상속받은 속성을 이름만으로 참조할 수 없다. _PYTHON_VERSION을 부모로 옮긴 뒤 서브클래스 본문에서 Path(f".../python{_PYTHON_VERSION}/...")처럼 쓰면 NameError가 난다. 클래스 본문은 상속 체인을 타는 스코프가 아니기 때문이다. BaseTask._PYTHON_VERSION으로 명시해야 한다.

BastTask 클래스를 추상 클래스로 만들기

훅이 raise NotImplementedError만 하는 베이스 클래스는 실제로 호출될 때가 되어서야 문제를 알려주지만, ABC로 바꾸면 그 에러가 인스턴스를 만드는 시점으로 앞당겨지기에 실제 호출 pass가 없더라도 비교적 쉽게 문제를 알 수 있다.

from abc import ABC, abstractmethod

class BaseTask(ABC):
    @abstractmethod
    def _inflate_payload(self, payload: dict[str, Any]):
        """Populate the task specific fields from the validated payload."""

이제 훅을 빠뜨린 서브클래스는 만들자마자 실패한다.

TypeError: Can't instantiate abstract class XXX without an implementation for abstract method '_inflate_payload'

워커가 한참 일하다가 터지는 대신, 테스트나 시작 단계에서 바로 문제를 알 수 있다.

클래스 상수 강제하기

각 서브클래스는 어떤 환경 변수를 읽을지도 정해야 한다. _PAYLOAD_ENV: str같은 어노테이션만 두면 아무것도 강제하지 않는다. 추상 프로퍼티로 선언하면 이 것을 강제할 수 있다.

class BaseTask(ABC):
    @property
    @abstractmethod
    def _PAYLOAD_ENV(self) -> str:
        """Name of the environment variable that holds the task payload."""

좋은 점은 서브클래스가 프로퍼티를 직접 작성할 필요가 없다는 것이다. 클래스 속성을 정의하는 것으로 추상 멤버를 덮어쓴 것으로 인정된다.

class TrainingTask(BaseTask):
    _PAYLOAD_ENV = "TRAINING_TASK_PAYLOAD"

선언을 빠뜨리면 이것 역시도 인스턴스 생성 시점에 TypeError가 발생한다.

연산별 파라미터는 Subclassing 대신 Sum type으로

DatasetTask는 여러 연산(add, remove, export)을 지원하고, 연산마다 필요한 파라미터가 다르다. 처음에는 연산마다 서브클래스를 만들 생각이었지만 두 가지 이유로 접었다.

  • 페이로드를 읽기 전에는 어떤 클래스를 만들지 알 수 없다. 결국 페이로드를 두 번 읽는 팩토리가 필요해진다.
  • 서브클래스들이 동작이 아니라 데이터만 다르다.

대신 DatasetTask는 하나로 두고, 연산마다 작고 불변하는 dataclass를 하나씩 선언하고 Params라고 이름을 붙였다. Payload를 읽을 때는 조회 테이블(_PARAMS_BY_OP)이 적합한 클래스를 고르게 된다. 이 세 클래스를 '|'로 묶은 DatasetParams는 “셋 중 정확히 하나”인 값을 나타내는데, 이러한 타입을 sum type이라 한다.

@dataclass(frozen=True)
class ExportParams:
    dataset_id: str
    dataset_version: str

    @classmethod
    def from_payload(cls, p: dict[str, Any]) -> Self:
        return cls(dataset_id=p["dataset_id"], dataset_version=p["dataset_version"])

DatasetParams = AddParams | RemoveParams | ExportParams

class DatasetTask(BaseTask):
    _PARAMS_BY_OP = {"ADD": AddParams, "REMOVE": RemoveParams, "EXPORT": ExportParams}

    def _inflate_payload(self, payload):
        op = payload.get("dataset_op", "").upper()
        params_cls = self._PARAMS_BY_OP.get(op)
        if params_cls is None:
            raise RuntimeError(f"Unknown dataset_op {op!r}.")
        self._params = params_cls.from_payload(payload)

워커 쪽에서는 패턴 매칭으로 파라미터 타입에 따라 분기한다.

match task.params():
    case ExportParams() as p:
        self._op_export(p)   # p.dataset_id가 타입을 갖고 에디터에서 자동완성된다
    case AddParams() as p:
        self._op_add(p)

이 방식으로 얻은 것은 세 가지다.

  • 어떤 속성이 채워져 있을지 추측할 필요가 없다.
  • 빠진 필드나 모르는 연산은 작업 도중이 아니라 inflate()에서 실패한다.
  • 새 연산은 dataclass, 테이블 항목 추가, case문 추가를 수행해 주면 된다.

결론

진짜로 공유되는 코드만 베이스 클래스로 끌어올리고, 베이스 클래스가 추상 메서드와 추상 프로퍼티로 계약을 강제하게 하자.

동작이 아니라 데이터만 다른 경우라면 서브클래스 보다는 타입이 있는 값 객체를 두고 sum type으로 묶는 방안을 고려해보자.

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다