From 735b7bf75c41ff3d6e0522557cf01b88245fce78 Mon Sep 17 00:00:00 2001 From: OwenKephart Date: Tue, 18 Jul 2023 14:52:51 -0700 Subject: [PATCH] [docs] Docstrings for public methods/properties (runs & events) (#15322) ## Summary & Motivation https://github.com/dagster-io/dagster/pull/15078 ## How I Tested These Changes --- .../dagster/dagster/_core/events/__init__.py | 27 ++++++++++++++++++- .../dagster/dagster/_core/events/log.py | 8 +++++- .../dagster/_core/storage/dagster_run.py | 7 ++++- 3 files changed, 39 insertions(+), 3 deletions(-) diff --git a/python_modules/dagster/dagster/_core/events/__init__.py b/python_modules/dagster/dagster/_core/events/__init__.py index 67b2eb1521a3f..f35aa11d8e154 100644 --- a/python_modules/dagster/dagster/_core/events/__init__.py +++ b/python_modules/dagster/dagster/_core/events/__init__.py @@ -515,14 +515,15 @@ def event_type(self) -> DagsterEventType: @public @property def is_step_event(self) -> bool: + """bool: If this event relates to a specific step.""" return self.event_type in STEP_EVENTS @public @property def is_hook_event(self) -> bool: + """bool: If this event relates to the execution of a hook.""" return self.event_type in HOOK_EVENTS - @public @property def is_alert_event(self) -> bool: return self.event_type in ALERT_EVENTS @@ -536,41 +537,49 @@ def step_kind(self) -> "StepKind": @public @property def is_step_success(self) -> bool: + """bool: If this event is of type STEP_SUCCESS.""" return self.event_type == DagsterEventType.STEP_SUCCESS @public @property def is_successful_output(self) -> bool: + """bool: If this event is of type STEP_OUTPUT.""" return self.event_type == DagsterEventType.STEP_OUTPUT @public @property def is_step_start(self) -> bool: + """bool: If this event is of type STEP_START.""" return self.event_type == DagsterEventType.STEP_START @public @property def is_step_failure(self) -> bool: + """bool: If this event is of type STEP_FAILURE.""" return self.event_type == DagsterEventType.STEP_FAILURE @public @property def is_resource_init_failure(self) -> bool: + """bool: If this event is of type RESOURCE_INIT_FAILURE.""" return self.event_type == DagsterEventType.RESOURCE_INIT_FAILURE @public @property def is_step_skipped(self) -> bool: + """bool: If this event is of type STEP_SKIPPED.""" return self.event_type == DagsterEventType.STEP_SKIPPED @public @property def is_step_up_for_retry(self) -> bool: + """bool: If this event is of type STEP_UP_FOR_RETRY.""" return self.event_type == DagsterEventType.STEP_UP_FOR_RETRY @public @property def is_step_restarted(self) -> bool: + """bool: If this event is of type STEP_RESTARTED.""" return self.event_type == DagsterEventType.STEP_RESTARTED @property @@ -588,6 +597,7 @@ def is_run_failure(self) -> bool: @public @property def is_failure(self) -> bool: + """bool: If this event represents the failure of a run or step.""" return self.event_type in FAILURE_EVENTS @property @@ -597,41 +607,52 @@ def is_job_event(self) -> bool: @public @property def is_engine_event(self) -> bool: + """bool: If this event is of type ENGINE_EVENT.""" return self.event_type == DagsterEventType.ENGINE_EVENT @public @property def is_handled_output(self) -> bool: + """bool: If this event is of type HANDLED_OUTPUT.""" return self.event_type == DagsterEventType.HANDLED_OUTPUT @public @property def is_loaded_input(self) -> bool: + """bool: If this event is of type LOADED_INPUT.""" return self.event_type == DagsterEventType.LOADED_INPUT @public @property def is_step_materialization(self) -> bool: + """bool: If this event is of type ASSET_MATERIALIZATION.""" return self.event_type == DagsterEventType.ASSET_MATERIALIZATION @public @property def is_expectation_result(self) -> bool: + """bool: If this event is of type STEP_EXPECTATION_RESULT.""" return self.event_type == DagsterEventType.STEP_EXPECTATION_RESULT @public @property def is_asset_observation(self) -> bool: + """bool: If this event is of type ASSET_OBSERVATION.""" return self.event_type == DagsterEventType.ASSET_OBSERVATION @public @property def is_asset_materialization_planned(self) -> bool: + """bool: If this event is of type ASSET_MATERIALIZATION_PLANNED.""" return self.event_type == DagsterEventType.ASSET_MATERIALIZATION_PLANNED @public @property def asset_key(self) -> Optional[AssetKey]: + """Optional[AssetKey]: For events that correspond to a specific asset_key / partition + (ASSET_MATERIALIZTION, ASSET_OBSERVATION, ASSET_MATERIALIZATION_PLANNED), returns that + asset key. Otherwise, returns None. + """ if self.event_type == DagsterEventType.ASSET_MATERIALIZATION: return self.step_materialization_data.materialization.asset_key elif self.event_type == DagsterEventType.ASSET_OBSERVATION: @@ -644,6 +665,10 @@ def asset_key(self) -> Optional[AssetKey]: @public @property def partition(self) -> Optional[str]: + """Optional[AssetKey]: For events that correspond to a specific asset_key / partition + (ASSET_MATERIALIZTION, ASSET_OBSERVATION, ASSET_MATERIALIZATION_PLANNED), returns that + partition. Otherwise, returns None. + """ if self.event_type == DagsterEventType.ASSET_MATERIALIZATION: return self.step_materialization_data.materialization.partition elif self.event_type == DagsterEventType.ASSET_OBSERVATION: diff --git a/python_modules/dagster/dagster/_core/events/log.py b/python_modules/dagster/dagster/_core/events/log.py index d250fc0d03d88..3321ed31b3a82 100644 --- a/python_modules/dagster/dagster/_core/events/log.py +++ b/python_modules/dagster/dagster/_core/events/log.py @@ -92,10 +92,14 @@ def __new__( @public @property def is_dagster_event(self) -> bool: + """bool: If this entry contains a DagsterEvent.""" return bool(self.dagster_event) @public def get_dagster_event(self) -> DagsterEvent: + """DagsterEvent: Returns the DagsterEvent contained within this entry. If this entry does not + contain a DagsterEvent, an error will be raised. + """ if not isinstance(self.dagster_event, DagsterEvent): check.failed( "Not a dagster event, check is_dagster_event before calling get_dagster_event", @@ -112,7 +116,9 @@ def from_json(json_str: str): @public @property - def dagster_event_type(self): + def dagster_event_type(self) -> Optional[DagsterEventType]: + """Optional[DagsterEventType]: The type of the DagsterEvent contained by this entry, if any. + """ return self.dagster_event.event_type if self.dagster_event else None @public diff --git a/python_modules/dagster/dagster/_core/storage/dagster_run.py b/python_modules/dagster/dagster/_core/storage/dagster_run.py index 92dc274e61ecb..25dac8b723a58 100644 --- a/python_modules/dagster/dagster/_core/storage/dagster_run.py +++ b/python_modules/dagster/dagster/_core/storage/dagster_run.py @@ -390,26 +390,31 @@ def tags_for_storage(self) -> Mapping[str, str]: @public @property def is_finished(self) -> bool: + """bool: If this run has completely finished execution.""" return self.status in FINISHED_STATUSES @public @property def is_success(self) -> bool: + """bool: If this run has successfully finished executing.""" return self.status == DagsterRunStatus.SUCCESS @public @property def is_failure(self) -> bool: + """bool: If this run has failed.""" return self.status == DagsterRunStatus.FAILURE @public @property - def is_failure_or_canceled(self): + def is_failure_or_canceled(self) -> bool: + """bool: If this run has either failed or was canceled.""" return self.status == DagsterRunStatus.FAILURE or self.status == DagsterRunStatus.CANCELED @public @property def is_resume_retry(self) -> bool: + """bool: If this run was created from retrying another run from the point of failure.""" return self.tags.get(RESUME_RETRY_TAG) == "true" @property