codeflowhub 1.1.0__tar.gz → 1.3.0__tar.gz

{codeflowhub-1.1.0 → codeflowhub-1.3.0}/PKG-INFO

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

{codeflowhub-1.1.0 → codeflowhub-1.3.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,17 @@ 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=수동 트리거)
+    doc_md:str  # Airflow DAG doc_md (UI에 표시될 Markdown 문서)
+    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, doc_md=None, schedule_interval=None, **kwargs):
         # CLI 속성 먼저 초기화 (init()에서 사용됨)
         self._cli_export = None
         self._cli_job_dir = None
@@ -57,6 +62,11 @@ 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
+        self.doc_md = self._normalize_doc_md(doc_md)
         # Design Ref: §3.2 — flow-level 공통 Secret(env)
         self.secrets = secrets or []
         self.on_failure = on_failure
@@ -67,6 +77,109 @@ class FlowDecorator(BaseDecorator):
         # super().__init__()는 마지막에 호출 (init()이 실행됨)
         super().__init__(*args, name=name, **kwargs)
 
+    @staticmethod
+    def _normalize_doc_md(doc_md):
+        """doc_md 정규화 (선언 시점에 조기 실패)
+
+        - str: Markdown 본문. 함수 안에서 triple-quote로 쓴 경우의 공통 들여쓰기를 제거
+        - Path: 해당 파일의 내용을 읽어 사용 (README 등 별도 파일 참조용)
+        - None / 빈 문자열: doc_md 미설정
+        """
+        import textwrap
+
+        if doc_md is None:
+            return None
+
+        if isinstance(doc_md, Path):
+            if not doc_md.exists():
+                raise FileNotFoundError(f'doc_md 파일을 찾을 수 없습니다: {doc_md}')
+            text = doc_md.read_text(encoding='utf-8')
+        elif isinstance(doc_md, str):
+            text = doc_md
+        else:
+            raise TypeError(
+                f'doc_md는 str(Markdown 본문), Path(파일 경로), None만 가능합니다. '
+                f'전달된 타입: {type(doc_md).__name__}'
+            )
+
+        # 선행 개행 제거 후 dedent → triple-quote 블록의 들여쓰기가 코드블록으로 렌더되는 것 방지
+        text = textwrap.dedent(text.lstrip('\n')).rstrip()
+        return text or None
+
+    @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 +371,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 +694,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.1.0 → codeflowhub-1.3.0}/codeflowhub/service/airflow_exporter.py

@@ -149,7 +149,7 @@ class AirflowExporter:
 
     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"""
@@ -178,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:
@@ -192,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
@@ -269,13 +269,24 @@ SETUP_SCRIPT = """{setup_script}"""
             params_str = self._format_dict(self.flow.params, indent=1)
             params_line = f"\n    params={params_str},"
 
-        dag_definition = f'''dag = DAG(
+        # doc_md 설정 — 본문은 DAG_DOC_MD 변수로 분리 (여러 줄 Markdown)
+        doc_md_definition = ""
+        doc_md_line = ""
+        doc_md = getattr(self.flow, 'doc_md', None)
+        if doc_md:
+            doc_md_definition = f'''# DAG documentation (Airflow UI)
+DAG_DOC_MD = {self._render_doc_md(doc_md)}
+
+'''
+            doc_md_line = "\n    doc_md=DAG_DOC_MD,"
+
+        dag_definition = f'''{doc_md_definition}dag = DAG(
     '{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}
+    tags={tags_str},{params_line}{doc_md_line}
 )
 
 '''
@@ -881,6 +892,32 @@ base_volume_mounts = [
                     dependencies.append(f"[{deps_str}] >> {task.name}")
         return dependencies
 
+    def _render_doc_md(self, doc_md):
+        """Markdown 본문 → 생성 DAG의 문자열 리터럴 코드
+
+        줄 단위로 repr()을 적용해 이어붙인다. triple-quote를 쓰면 본문에 포함된
+        따옴표/백슬래시가 문법 오류를 만들 수 있으므로 repr로 완전히 이스케이프하고,
+        줄마다 나누어 생성 DAG에서도 읽을 수 있게 유지한다.
+        """
+        lines = doc_md.split('\n')
+        if len(lines) == 1:
+            return repr(lines[0])
+
+        rendered = [f"    {line + chr(10)!r}" for line in lines[:-1]]
+        rendered.append(f"    {lines[-1]!r}")
+        return '(\n' + '\n'.join(rendered) + '\n)'
+
+    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)
@@ -908,9 +945,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.1.0 → codeflowhub-1.3.0}/codeflowhub.egg-info/PKG-INFO

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

{codeflowhub-1.1.0 → codeflowhub-1.3.0}/setup.py

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