Skip to content

[CONTRIB] Promote ExpectColumnValuesToMatchStrftimeFormat to supported-core #12009

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joshua-stauffer merged 3 commits into from
Aug 5, 2026
Merged

[CONTRIB] Promote ExpectColumnValuesToMatchStrftimeFormat to supported-core #12009

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7146690
Promote ExpectColumnValuesToMatchStrftimeFormat to supported-core
nanjeshramesh Jul 28, 2026
ed298be
Address review: fix docstring examples and formatting
nanjeshramesh Aug 4, 2026
f026d35
Actually remove the line continuation, not just relocate it
nanjeshramesh Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 143 additions & 10 deletions great_expectations/expectations/core/expect_column_values_to_match_strftime_format.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
from __future__ import annotations

from datetime import datetime, timezone
from typing import TYPE_CHECKING, Optional, Union
from typing import TYPE_CHECKING, Any, ClassVar, Dict, Optional, Type, Union

from great_expectations.compatibility import pydantic
from great_expectations.core.suite_parameters import (
Expand All @@ -12,6 +12,12 @@
_style_row_condition,
render_suite_parameter_string,
)
from great_expectations.expectations.metadata_types import DataQualityIssues, SupportedDataSources
from great_expectations.expectations.model_field_descriptions import (
COLUMN_DESCRIPTION,
FAILURE_SEVERITY_DESCRIPTION,
MOSTLY_DESCRIPTION,
)
from great_expectations.render import LegacyRendererType, RenderedStringTemplateContent
from great_expectations.render.renderer.renderer import renderer
from great_expectations.render.renderer_configuration import (
Expand All @@ -33,25 +39,37 @@
)
from great_expectations.render.renderer_configuration import AddParamArgs

EXPECTATION_SHORT_DESCRIPTION = (
"Expect the column entries to be strings representing a date or time with a given format."
)
STRFTIME_FORMAT_DESCRIPTION = "A strftime format string to use for matching."
DATA_QUALITY_ISSUES = [DataQualityIssues.VALIDITY.value]
SUPPORTED_DATA_SOURCES = [
SupportedDataSources.PANDAS.value,
SupportedDataSources.SPARK.value,
]


class ExpectColumnValuesToMatchStrftimeFormat(ColumnMapExpectation):
"""Expect the column entries to be strings representing a date or time with a given format.
__doc__ = f"""{EXPECTATION_SHORT_DESCRIPTION}

ExpectColumnValuesToMatchStrftimeFormat is a \
Column Map Expectation.

Column Map Expectations are one of the most common types of Expectation.
They are evaluated for a single column and ask a yes/no question for every row in that column.
Based on the result, they then calculate the percentage of rows that gave a positive answer. If the percentage is high enough, the Expectation considers that data valid.

Args:
column (str): \
The column name.
{COLUMN_DESCRIPTION}
strftime_format (str or SuiteParameterDict): \
A strftime format string to use for matching
{STRFTIME_FORMAT_DESCRIPTION}

Keyword Args:
Other Parameters:
mostly (None or a float between 0 and 1): \
Successful if at least mostly fraction of values match the expectation. \
{MOSTLY_DESCRIPTION} \
For more detail, see [mostly](https://docs.greatexpectations.io/docs/reference/expectations/standard_arguments/#mostly).

@joshua-stauffer joshua-stauffer Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we append Default 1. to this line, like in great_expectations/expectations/core/expect_column_values_to_match_regex.py?


Other Parameters:
result_format (str or None): \
Which output mode to use: BOOLEAN_ONLY, BASIC, COMPLETE, or SUMMARY. \
For more detail, see [result_format](https://docs.greatexpectations.io/docs/reference/expectations/result_format).
Expand All @@ -69,9 +87,90 @@ class ExpectColumnValuesToMatchStrftimeFormat(ColumnMapExpectation):
An [ExpectationSuiteValidationResult](https://docs.greatexpectations.io/docs/terms/validation_result)

Exact fields vary depending on the values passed to result_format, catch_exceptions, and meta.

Supported Data Sources:
[{SUPPORTED_DATA_SOURCES[0]}](https://docs.greatexpectations.io/docs/application_integration_support/)
[{SUPPORTED_DATA_SOURCES[1]}](https://docs.greatexpectations.io/docs/application_integration_support/)

SQL data sources are not currently supported: strftime format tokens do not map cleanly \
onto the date-format models of SQL dialects.

@joshua-stauffer joshua-stauffer Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the newline continuation here is likely to cause extra whitespace to be rendered. Can we remove it, and move this section up to the bottom of the Column Map Expectations are one of the most common types of Expectation. paragraph?

Data Quality Issues:
{DATA_QUALITY_ISSUES[0]}

Example Data:
event_date
0 "2024-01-15"
1 "2024-06-20"
2 "not-a-date"

Code Examples:
Passing Case:
Input:
ExpectColumnValuesToMatchStrftimeFormat(
column="event_date",
strftime_format="%Y-%m-%d",
)

Output:
{{
"exception_info": {{
"raised_exception": false,
"exception_traceback": null,
"exception_message": null
}},
"result": {{
"element_count": 3,
"unexpected_count": 1,
"unexpected_percent": 33.33333333333333,
"partial_unexpected_list": [
"not-a-date"
],
"missing_count": 0,
"missing_percent": 0.0,
"unexpected_percent_total": 33.33333333333333,
"unexpected_percent_nonmissing": 33.33333333333333
}},
"meta": {{}},
"success": false
}}

@joshua-stauffer joshua-stauffer Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is labeled as a passing case, but success is (correctly) false. We could use the pattern in great_expectations/expectations/core/expect_column_values_to_match_regex.py and have the example data use two columns instead, then use one for the passing case and the other for the failing case.

@joshua-stauffer joshua-stauffer Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the docstrings are rendered in the Expectations gallery, so we want one actual passing case, and one failing case.


Failing Case:
Input:
ExpectColumnValuesToMatchStrftimeFormat(
column="event_date",
strftime_format="%m/%d/%Y",
)

Output:
{{
"exception_info": {{
"raised_exception": false,
"exception_traceback": null,
"exception_message": null
}},
"result": {{
"element_count": 3,
"unexpected_count": 3,
"unexpected_percent": 100.0,
"partial_unexpected_list": [
"2024-01-15",
"2024-06-20",
"not-a-date"
],
"missing_count": 0,
"missing_percent": 0.0,
"unexpected_percent_total": 100.0,
"unexpected_percent_nonmissing": 100.0
}},
"meta": {{}},
"success": false
}}
""" # noqa: E501 # FIXME CoP

strftime_format: Union[str, SuiteParameterDict]
strftime_format: Union[str, SuiteParameterDict] = pydantic.Field(
description=STRFTIME_FORMAT_DESCRIPTION
)

@pydantic.validator("strftime_format")
def validate_strftime_format(
Expand All @@ -88,7 +187,7 @@ def validate_strftime_format(

return strftime_format

library_metadata = {
library_metadata: ClassVar[Dict[str, Union[str, list, bool]]] = {
"maturity": "production",
"tags": ["core expectation", "column map expectation"],
"contributors": [
Expand All @@ -98,6 +197,7 @@ def validate_strftime_format(
"has_full_test_suite": True,
"manually_reviewed_code": True,
}
_library_metadata = library_metadata

map_metric = "column_values.match_strftime_format"
success_keys = (
Expand All @@ -109,6 +209,39 @@ def validate_strftime_format(
"strftime_format",
)

class Config:
title = "Expect column values to match strftime format"

@staticmethod
def schema_extra(
schema: Dict[str, Any], model: Type[ExpectColumnValuesToMatchStrftimeFormat]
) -> None:
ColumnMapExpectation.Config.schema_extra(schema, model)
schema["properties"]["metadata"]["properties"].update(
{
"data_quality_issues": {
"title": "Data Quality Issues",
"type": "array",
"const": DATA_QUALITY_ISSUES,
},
"library_metadata": {
"title": "Library Metadata",
"type": "object",
"const": model._library_metadata,
},
"short_description": {
"title": "Short Description",
"type": "string",
"const": EXPECTATION_SHORT_DESCRIPTION,
},
"supported_data_sources": {
"title": "Supported Data Sources",
"type": "array",
"const": SUPPORTED_DATA_SOURCES,
},
}
)

@classmethod
def _prescriptive_template(
cls,
Expand Down
Loading
Loading