codeflowhub 1.0.0__tar.gz → 1.2.0__tar.gz

{codeflowhub-1.0.0 → codeflowhub-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeflowhub
-Version: 1.0.0
+Version: 1.2.0
 Summary: workflow development tools
 Author: creaddiscans
 Author-email: creaddiscans@gmail.com

{codeflowhub-1.0.0 → codeflowhub-1.2.0}/codeflowhub/flow.py

@@ -3,6 +3,7 @@ import inspect
 import json
 import os
 import sys
+from datetime import datetime
 from pathlib import Path
 
 from .base import BaseDecorator
@@ -28,13 +29,16 @@ class FlowDecorator(BaseDecorator):
     path:str  # Git repo 내 작업 경로
     export_destination:str  # Export 시 생성 파일 저장 디렉토리
     default_args:dict  # Airflow DAG default_args (owner, retries, retry_delay 등 override)
+    schedule:str  # Airflow DAG 스케줄 (cron 문자열 / preset / timedelta / None=수동 트리거)
+    start_date:datetime  # Airflow DAG start_date (None이면 export 시점)
     secrets:list  # 모든 task에 공통 주입할 K8s Secret(env) 목록
     on_failure: 'BaseDecorator' = None  # 모든 task의 기본 failure handler
 
     def __init__(self, *args, namespace='default', env=None, name=None, description=None, params=None,
                  tags=None, annotations=None, service_account_name=None, volumes=None,
                  airflow_sidecar_image=None, airflow_connection_id=None, repo=None, path=None,
-                 export_destination='dags', default_args=None, secrets=None, on_failure=None, **kwargs):
+                 export_destination='dags', default_args=None, secrets=None, on_failure=None,
+                 schedule=None, start_date=None, schedule_interval=None, **kwargs):
         # CLI 속성 먼저 초기화 (init()에서 사용됨)
         self._cli_export = None
         self._cli_job_dir = None
@@ -57,6 +61,10 @@ class FlowDecorator(BaseDecorator):
         self.path = path
         self.export_destination = export_destination or 'dags'
         self.default_args = default_args or {}
+        self.schedule = self._normalize_schedule(
+            self._resolve_schedule_alias(schedule, schedule_interval)
+        )
+        self.start_date = start_date
         # Design Ref: §3.2 — flow-level 공통 Secret(env)
         self.secrets = secrets or []
         self.on_failure = on_failure
@@ -67,6 +75,80 @@ class FlowDecorator(BaseDecorator):
         # super().__init__()는 마지막에 호출 (init()이 실행됨)
         super().__init__(*args, name=name, **kwargs)
 
+    @staticmethod
+    def _resolve_schedule_alias(schedule, schedule_interval):
+        """schedule / schedule_interval(구 이름) 중 하나로 정리
+
+        Airflow 2.4+에서 DAG 파라미터가 schedule로 통합되었고 Airflow 3에서
+        schedule_interval은 제거되었다. 구 이름도 계속 받되 경고한다.
+        """
+        if schedule_interval is None:
+            return schedule
+        if schedule is not None:
+            raise ValueError(
+                'schedule과 schedule_interval을 동시에 지정할 수 없습니다. '
+                'schedule만 사용하세요 (schedule_interval은 구 이름).'
+            )
+        print(
+            "⚠️  schedule_interval은 구 이름입니다. Airflow 2.4+ 표준인 "
+            "schedule을 사용하세요.",
+            file=sys.stderr
+        )
+        return schedule_interval
+
+    @staticmethod
+    def _normalize_schedule(schedule):
+        """schedule 검증 (선언 시점에 조기 실패)
+
+        허용: None(수동 트리거), cron 문자열('0 2 * * *'), preset('@daily'), timedelta
+        """
+        from datetime import timedelta
+
+        if schedule is None or isinstance(schedule, timedelta):
+            return schedule
+
+        if not isinstance(schedule, str):
+            raise TypeError(
+                f'schedule은 str(cron/preset), timedelta, None만 가능합니다. '
+                f'전달된 타입: {type(schedule).__name__}'
+            )
+
+        value = schedule.strip()
+        if not value:
+            return None
+
+        presets = {'@once', '@hourly', '@daily', '@weekly', '@monthly',
+                   '@quarterly', '@yearly', '@annually', '@continuous', '@none'}
+        if value.startswith('@'):
+            if value not in presets:
+                raise ValueError(
+                    f'알 수 없는 스케줄 preset: "{value}". '
+                    f'사용 가능: {", ".join(sorted(presets))}'
+                )
+            return None if value == '@none' else value
+
+        # cron 표현식은 5개 필드 (분 시 일 월 요일)
+        fields = value.split()
+        if len(fields) != 5:
+            raise ValueError(
+                f'cron 표현식은 5개 필드(분 시 일 월 요일)여야 합니다. '
+                f'전달된 값: "{value}" ({len(fields)}개 필드)'
+            )
+        return value
+
+    def _resolve_start_date(self):
+        """DAG start_date 결정 (Airflow는 스케줄이 있으면 start_date 필수)
+
+        우선순위: start_date 파라미터 > default_args['start_date'] > 고정 기본값.
+        기본값을 datetime.now()가 아닌 고정값으로 두어 재export 시 결정적이도록 한다.
+        """
+        if self.start_date is not None:
+            return self.start_date
+        from_default_args = (self.default_args or {}).get('start_date')
+        if from_default_args is not None:
+            return from_default_args
+        return datetime(2024, 1, 1)
+
     def _initialize_env(self, env):
         """환경 설정 초기화"""
         if env and isinstance(env, dict) and all(isinstance(v, dict) for v in env.values()):
@@ -258,28 +340,33 @@ class FlowDecorator(BaseDecorator):
             print(f'   Supported: airflow')
             os._exit(1)
 
-        from datetime import datetime, timedelta
+        from datetime import timedelta
 
         flow_id = self.flow_name or self.name
         dest_dir = self.export_destination or 'dags'
         print(f'🚀 Exporting {flow_id} to Airflow DAG... (destination: {dest_dir})')
 
+        # 스케줄이 설정된 DAG는 start_date가 필수이므로 default_args에 항상 포함시킨다
+        start_date = self._resolve_start_date()
         default_args = {
             'owner': 'flowhub',
             'retries': 1,
             'retry_delay': timedelta(minutes=5),
             **(self.default_args or {}),
+            'start_date': start_date,
         }
 
         dag_path = self.export_airflow(
             output_path=os.path.join(dest_dir, f'{flow_id}_dag.py'),
-            schedule_interval=None,
-            start_date=datetime.now(),
+            schedule=self.schedule,
+            start_date=start_date,
             default_args=default_args,
         )
 
         print(f'✅ Successfully exported to: {dag_path}')
         print(f'📋 DAG ID: {flow_id}')
+        print(f'⏰ Schedule: {self.schedule or "None (manual trigger)"}')
+        print(f'📅 Start date: {start_date.isoformat()}')
         print(f'🏷️  Tags: [{self.namespace}]')
         os._exit(0)
 
@@ -576,23 +663,34 @@ class FlowDecorator(BaseDecorator):
             f'--input-data를 제공하거나 먼저 전체 workflow를 실행하세요.'
         )
 
-    def export_airflow(self, output_path=None, schedule_interval=None, start_date=None, default_args=None):
+    def export_airflow(self, output_path=None, schedule=None, start_date=None, default_args=None,
+                       schedule_interval=None):
         """
         Airflow DAG로 export
 
         Args:
             output_path: DAG 파일 저장 경로 (기본: dags/{dag_id}.py)
-            schedule_interval: DAG 스케줄 (기본: None)
-            start_date: DAG 시작 날짜 (기본: 오늘)
+            schedule: DAG 스케줄. 미지정 시 @flow(schedule=...) 값 사용
+            start_date: DAG 시작 날짜. 미지정 시 @flow(start_date=...) 또는 기본값 사용
             default_args: DAG default_args
+            schedule_interval: schedule의 구 이름 (deprecated)
 
         Returns:
             str: 생성된 DAG 파일 경로
         """
+        # 인자 미지정 시 flow 데코레이터에 선언된 값으로 폴백
+        schedule = self._resolve_schedule_alias(schedule, schedule_interval)
+        if schedule is None:
+            schedule = self.schedule
+        else:
+            schedule = self._normalize_schedule(schedule)
+        if start_date is None:
+            start_date = self._resolve_start_date()
+
         exporter = AirflowExporter(self)
         return exporter.export(
             output_path=output_path,
-            schedule_interval=schedule_interval,
+            schedule=schedule,
             start_date=start_date,
             default_args=default_args
         )

{codeflowhub-1.0.0 → codeflowhub-1.2.0}/codeflowhub/service/airflow_exporter.py

@@ -6,6 +6,19 @@ from datetime import datetime, timedelta
 from typing import Optional
 from pathlib import Path
 
+# Design Ref: §2.1 — exporter가 DAG 생성에 소비하는 키 (컨테이너에는 의미 없음)
+INFRA_KEYS = frozenset({
+    'K8S_IMAGE', 'K8S_NAMESPACE', 'K8S_COMMON',
+    'XCOM_SIDECAR_IMAGE', 'EXTRA_PACKAGES',
+})
+
+# Design Ref: §2.2 — 실행 시점에 주입되는 키 (export 시점 값을 굽으면 잘못된 값 고정)
+RUNTIME_KEYS = frozenset({'project', 'run_id', 'task'})
+
+# Design Ref: §2.3 — _fh_api_env가 사용하는 이름 (중복 V1EnvVar 방지)
+RESERVED_ENV_NAMES = frozenset({'FLOWHUB_API_URL', 'FLOWHUB_API_USER', 'FLOWHUB_API_PASS'})
+
+
 class AirflowExporter:
     """Airflow DAG로 export하는 서비스"""
 
@@ -39,12 +52,13 @@ class AirflowExporter:
         self.configmap_mount_path = '/flowhub/code'
 
         # Common K8s 설정
-        self.common_config = self.env.get('K8S_COMMON', {
+        # Design Ref: §3.1 — 사용자 env dict를 직접 변형하지 않도록 얕은 복사
+        self.common_config = dict(self.env.get('K8S_COMMON', {
             'namespace': self.k8s_namespace,
             'cmds': ['/bin/sh', '-c'],
             'do_xcom_push': True,
             'startup_timeout_seconds': 3600,
-        })
+        }))
 
         # 커스텀 CLI 인자 가져오기 (FlowDecorator에서 저장된 값)
         from ..flow import FlowDecorator
@@ -79,16 +93,63 @@ class AirflowExporter:
         self.flow_secrets = getattr(flow_decorator, 'secrets', None) or []
 
         # secret 존재 여부 (import 생성 조건). on_failure task 포함
-        _all_tasks = list(flow_decorator.depend or [])
-        if flow_decorator.on_failure:
-            _all_tasks.append(flow_decorator.on_failure)
         self._has_secrets = bool(self.flow_secrets) or any(
-            getattr(t, 'secrets', None) for t in _all_tasks
+            getattr(t, 'secrets', None) for t in self._all_tasks()
         )
 
+        # Design Ref: §3.1 — 사용자 env → 컨테이너 환경변수
+        # K8S_COMMON에 env_vars가 있으면 **common과 키워드 충돌하므로 여기서 흡수
+        self._common_env_vars_raw = self.common_config.pop('env_vars', None)
+
+        self.env_var_items = self._collect_env_vars()
+        self._has_env_vars = bool(self.env_var_items) or bool(self._common_env_vars_raw)
+
+    def _all_tasks(self):
+        """workflow task + on_failure handler 전체 목록"""
+        tasks = list(self.flow.depend or [])
+        if self.flow.on_failure:
+            tasks.append(self.flow.on_failure)
+        return tasks
+
+    def _collect_env_vars(self):
+        """선택된 env → [(name, value_str)] 목록. Design Ref: §2"""
+        all_secrets = list(self.flow_secrets)
+        for t in self._all_tasks():
+            all_secrets.extend(getattr(t, 'secrets', None) or [])
+        secret_names = {
+            s.env_name for s in all_secrets if getattr(s, 'env_name', None)
+        }
+
+        skip = INFRA_KEYS | RUNTIME_KEYS | RESERVED_ENV_NAMES | secret_names
+
+        items = []
+        for key, value in (self.env or {}).items():
+            if key in skip or value is None:
+                continue
+            if isinstance(value, bool):
+                items.append((key, 'true' if value else 'false'))
+            elif isinstance(value, (str, int, float)):
+                items.append((key, str(value)))
+            elif isinstance(value, (dict, list, tuple, set)):
+                # Design Ref: §2.4 — dict/list는 경고 후 제외 (args 경로로는 전달됨)
+                print(
+                    f"⚠️  env['{key}']: {type(value).__name__} 값은 컨테이너 "
+                    f"환경변수로 주입할 수 없어 제외합니다.\n"
+                    f"    (args['env']['{key}']로는 정상 전달됩니다. "
+                    f"환경변수가 필요하면 문자열로 변환해 지정하세요.)",
+                    file=sys.stderr
+                )
+            else:
+                print(
+                    f"⚠️  env['{key}']: {type(value).__name__} 타입은 환경변수로 "
+                    f"변환할 수 없어 제외합니다.",
+                    file=sys.stderr
+                )
+        return items
+
     def export(self,
                output_path: str = None,
-               schedule_interval: Optional[str] = None,
+               schedule: Optional[str] = None,
                start_date: Optional[datetime] = None,
                default_args: Optional[dict] = None):
         """Airflow DAG Python 파일로 export"""
@@ -117,7 +178,7 @@ class AirflowExporter:
             configmap_path = self._generate_configmap_yaml(dir_path)
 
         # DAG 코드 생성
-        dag_code = self._generate_dag_code(schedule_interval, start_date, default_args)
+        dag_code = self._generate_dag_code(schedule, start_date, default_args)
 
         # 파일 저장
         with open(output_path, 'w', encoding='utf-8') as f:
@@ -131,7 +192,7 @@ class AirflowExporter:
             print(f'📋 Apply ConfigMap: kubectl apply -f {configmap_path}')
         return output_path
 
-    def _generate_dag_code(self, schedule_interval, start_date, default_args):
+    def _generate_dag_code(self, schedule, start_date, default_args):
         """DAG Python 코드 생성 (target.py 스타일)"""
 
         flow_name = self.flow.flow_name or self.flow.name
@@ -212,7 +273,7 @@ SETUP_SCRIPT = """{setup_script}"""
     '{self.dag_id}',
     default_args={default_args_str},
     description='{description}',
-    schedule_interval={repr(schedule_interval)},
+    schedule={self._render_schedule(schedule)},
     catchup=False,
     tags={tags_str},{params_line}
 )
@@ -263,6 +324,31 @@ base_volume_mounts = [
                 + "\n]\n\n"
             )
 
+        # Design Ref: §3.3 — 선택된 env를 base_env_vars 변수로 렌더
+        env_vars_definition = ""
+        if self._has_env_vars:
+            rendered = [self._render_env_var(k, v) for k, v in self.env_var_items]
+
+            # K8S_COMMON.env_vars(사용자 원시 지정)를 뒤에 붙여 명시값이 우선
+            raw = self._common_env_vars_raw
+            if raw:
+                entries = raw.items() if isinstance(raw, dict) else raw
+                for entry in entries:
+                    code = self._render_common_env_var(entry)
+                    if code:
+                        rendered.append(code)
+
+            if rendered:
+                env_vars_definition = (
+                    f"# Base env vars (flow env: {self.current_env})\n"
+                    "base_env_vars = [\n    "
+                    + ",\n    ".join(rendered)
+                    + "\n]\n\n"
+                )
+            else:
+                # 렌더 가능한 항목이 하나도 없으면 변수를 만들지 않는다
+                self._has_env_vars = False
+
         # Task 정의들 (일반 workflow tasks만)
         tasks_code = "with dag:\n"
         for i, task in enumerate(self.flow.depend):
@@ -292,7 +378,8 @@ base_volume_mounts = [
                 tasks_code += f"    # Failure handler dependency\n"
                 tasks_code += f"    [{', '.join(last_tasks)}] >> {self.flow.on_failure.name}\n"
 
-        return header + dag_definition + common_definition + secrets_definition + tasks_code
+        return (header + dag_definition + common_definition + secrets_definition
+                + env_vars_definition + tasks_code)
 
     def _generate_task_operator(self, task, is_first=False, trigger_rule=None):
         """KubernetesPodOperator 생성"""
@@ -325,10 +412,8 @@ base_volume_mounts = [
         # failure handler는 retries=0 설정
         retries_code = "\n        retries=0," if trigger_rule == 'one_failed' else ""
 
-        # XCom API fetch를 사용하는 task에 env_vars 주입 (is_first: params fetch, depend: xcom fetch)
-        env_vars_code = ""
-        if self.airflow_connection_id and (is_first or task.depend):
-            env_vars_code = "\n        env_vars=_fh_api_env,"
+        # Design Ref: §3.4 — flow env(base_env_vars) + XCom API fetch(_fh_api_env) 병합
+        env_vars_code = self._build_env_vars_code(task, is_first=is_first)
 
         # Design Ref: §4.5 — Secret(env) 주입 (flow base_secrets + task secrets 병합)
         secrets_code = self._build_secrets_code(task)
@@ -553,6 +638,44 @@ base_volume_mounts = [
             return f"\n        secrets=[{', '.join(task_items)}],"
         return ""
 
+    def _render_env_var(self, name, value):
+        """단일 V1EnvVar 코드 문자열 (Design Ref: §3.2)
+
+        value는 repr()로 감싸 따옴표/개행/유니코드 이스케이프를 Python에 위임한다.
+        """
+        return f"k8s.V1EnvVar(name={name!r}, value={value!r})"
+
+    def _render_common_env_var(self, entry):
+        """K8S_COMMON에서 흡수한 env_vars 항목 → V1EnvVar 코드 문자열
+
+        dict({'name','value'}) / (name, value) 튜플 / V1EnvVar 객체를 모두 허용.
+        해석 불가하면 None을 반환해 호출측에서 제외한다.
+        """
+        if isinstance(entry, dict) and 'name' in entry:
+            return self._render_env_var(str(entry['name']), str(entry.get('value', '')))
+        if isinstance(entry, (tuple, list)) and len(entry) == 2:
+            return self._render_env_var(str(entry[0]), str(entry[1]))
+        name = getattr(entry, 'name', None)
+        if name:
+            return self._render_env_var(str(name), str(getattr(entry, 'value', '') or ''))
+        print(
+            f"⚠️  K8S_COMMON['env_vars']의 항목을 해석할 수 없어 제외합니다: {entry!r}",
+            file=sys.stderr
+        )
+        return None
+
+    def _build_env_vars_code(self, task, is_first=False):
+        """base_env_vars + _fh_api_env 병합 (Design Ref: §3.4)"""
+        use_api_env = bool(self.airflow_connection_id) and (is_first or task.depend)
+
+        if self._has_env_vars and use_api_env:
+            return "\n        env_vars=base_env_vars + _fh_api_env,"
+        elif self._has_env_vars:
+            return "\n        env_vars=base_env_vars,"
+        elif use_api_env:
+            return "\n        env_vars=_fh_api_env,"
+        return ""
+
     def _build_custom_cli_args(self):
         """커스텀 CLI 인자를 명령줄 문자열로 변환
 
@@ -758,6 +881,17 @@ base_volume_mounts = [
                     dependencies.append(f"[{deps_str}] >> {task.name}")
         return dependencies
 
+    def _render_schedule(self, schedule):
+        """schedule → DAG 코드 문자열
+
+        repr(timedelta)는 'datetime.timedelta(...)'를 만들지만 생성 DAG는
+        `from datetime import timedelta`만 import하므로 NameError가 된다.
+        """
+        if isinstance(schedule, timedelta):
+            total = int(schedule.total_seconds())
+            return f'timedelta(seconds={total})'
+        return repr(schedule)
+
     def _format_dict(self, d, indent=0, base_indent=0):
         """Dict를 Python 코드 형식으로 포맷팅"""
         return self._format_dict_with_raw_values(d, indent, raw_keys=set(), base_indent=base_indent)
@@ -785,9 +919,21 @@ base_volume_mounts = [
             elif isinstance(value, str):
                 items.append(f"'{key}': '{value}'")
             elif isinstance(value, datetime):
-                items.append(f"'{key}': datetime({value.year}, {value.month}, {value.day})")
+                # 시/분/초가 있으면 함께 렌더 (start_date 정밀도 손실 방지)
+                if (value.hour, value.minute, value.second) == (0, 0, 0):
+                    items.append(f"'{key}': datetime({value.year}, {value.month}, {value.day})")
+                else:
+                    items.append(
+                        f"'{key}': datetime({value.year}, {value.month}, {value.day}, "
+                        f"{value.hour}, {value.minute}, {value.second})"
+                    )
             elif isinstance(value, timedelta):
-                items.append(f"'{key}': timedelta(minutes={int(value.total_seconds() / 60)})")
+                # 분 단위로 나누어떨어지지 않는 값은 초 단위로 렌더 (절삭 방지)
+                total = int(value.total_seconds())
+                if total % 60 == 0:
+                    items.append(f"'{key}': timedelta(minutes={total // 60})")
+                else:
+                    items.append(f"'{key}': timedelta(seconds={total})")
             elif isinstance(value, bool):
                 items.append(f"'{key}': {value}")
             elif isinstance(value, (int, float)):

{codeflowhub-1.0.0 → codeflowhub-1.2.0}/codeflowhub.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeflowhub
-Version: 1.0.0
+Version: 1.2.0
 Summary: workflow development tools
 Author: creaddiscans
 Author-email: creaddiscans@gmail.com

{codeflowhub-1.0.0 → codeflowhub-1.2.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name='codeflowhub',
-    version='1.0.0',
+    version='1.2.0',
     description='workflow development tools',
     author='creaddiscans',
     author_email='creaddiscans@gmail.com',