You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@hamilton.apache.org by "philipljh (via GitHub)" <gi...@apache.org> on 2026/07/15 16:59:32 UTC
[PR] docs(data-quality): add check_output_custom section (#212) [hamilton]
philipljh opened a new pull request, #1658:
URL: https://github.com/apache/hamilton/pull/1658
Closes [#212 ](https://github.com/apache/hamilton/issues/212) - adds documentation for `@check_output_custom`
It walks through the full lifecycle of a custom validator:
- **When you need one**: positions `@check_output_custom` relative to `@check_output`'s default validators (data type, range, allowed values, ...), with a cross-reference to the `check_output` API reference.
- **Writing the validator**: a complete example class, `AllPositiveValidator`, that subclasses `hamilton.data_quality.base.DataValidator` and checks a pandas Series for negative values. Each required method is then explained individually: `applies_to`, `description`, `name`, `validate` returning a `ValidationResult` (with `passes`, `message`, and the free-form `diagnostics` dict), plus the `importance` constructor argument.
- **Applying it**: decorating a function with a validator *instance*, including that multiple validators go into a single decorator call and that stacking `@check_output_custom` decorators is not supported.
- **Runtime semantics**: `importance="warn"` logs through the standard `logging` module and continues; `importance="fail"` raises `DataValidationError`, with all validators evaluated first so every failure is reported at once.
- **What happens to the DAG**: the `{name}_raw` / per-validator / final-node split, the `hamilton.data_quality.contains_dq_results` and `hamilton.data_quality.source_node` tags, and a driver example showing that validator nodes can simply be requested as outputs to inspect their `ValidationResult`.
## Changes
Adds a "Custom validators" section to the "Data quality" how-to page (`docs/how-tos/run-data-quality-checks.rst`) covering:
- when to write a custom validator vs. using `@check_output`'s built-in validators
- a complete, runnable `DataValidator` subclass example
- applying one or more validator instances with `@check_output_custom` (and that decorators can't be stacked)
- runtime behavior of `importance="warn"` (logs, continues) vs `"fail"` (raises `DataValidationError`)
- how validation results appear as tagged nodes in the DAG and how to request them as outputs
## How I tested this
- Ran every code snippet in the section against a local editable install; outputs match the docs verbatim.
- Built the docs locally with `sphinx-build -b dirhtml -W`; no warnings from the changed page.
- Screenshot of the rendered section attached.
<img width="1400" height="3200" alt="image" src="https://github.com/user-attachments/assets/dff6d44b-48de-4fdb-a09c-8b438392ab18" />
## Notes
- Docs-only change
## Checklist
- [x] PR has an informative and human-readable title (this will be pulled into the release notes)
- [x] Changes are limited to a single goal (no scope creep)
- [x] Code passed the pre-commit check & code is left cleaner/nicer than when first encountered.
- [ ] Any _change_ in functionality is tested (n/a - docs only)
- [ ] New functions are documented (n/a - docs only)
- [ ] Placeholder code is flagged / future TODOs are captured in comments (n/a)
- [x] Project documentation has been updated if adding/changing functionality.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@hamilton.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs(data-quality): add check_output_custom section (#212) [hamilton]
Posted by "jernejfrank (via GitHub)" <gi...@apache.org>.
jernejfrank commented on code in PR #1658:
URL: https://github.com/apache/hamilton/pull/1658#discussion_r3794943273
##########
docs/how-tos/run-data-quality-checks.rst:
##########
@@ -11,6 +11,102 @@ The goal of this is to show how to use runtime data quality checks in a larger,
1. `Data quality with hamilton <https://github.com/apache/hamilton/tree/main/examples/data_quality/simple>`_
2. `Data quality with pandera <https://github.com/apache/hamilton/tree/main/examples/data_quality/pandera>`_
+Custom validators
+~~~~~~~~~~~~~~~~~
+
+The ``@check_output`` decorator ships with default validators that cover common checks (data type, range, allowed values, etc. -- see the :doc:`check_output reference <../reference/decorators/check_output>`). When you need a check they don't cover -- say, a business rule specific to your data -- you can write your own validator class and apply it with ``@check_output_custom``.
+
+A validator subclasses ``hamilton.data_quality.base.DataValidator`` and implements four methods, plus a constructor that forwards ``importance`` to the base class:
+
+.. code-block:: python
+
+ # my_module.py
+ import pandas as pd
+
+ from hamilton.data_quality import base
+
+
+ class AllPositiveValidator(base.DataValidator):
+ """Validates that a pandas series contains no negative values."""
+
+ def __init__(self, importance: str):
+ super().__init__(importance=importance)
+
+ @classmethod
+ def applies_to(cls, datatype: type) -> bool:
+ return issubclass(datatype, pd.Series)
+
+ def description(self) -> str:
+ return "Validates that the series contains no negative values."
+
+ @classmethod
+ def name(cls) -> str:
+ return "all_positive_validator"
+
+ def validate(self, dataset: pd.Series) -> base.ValidationResult:
+ negative_count = int((dataset < 0).sum())
+ passes = negative_count == 0
+ if passes:
+ message = "All values are non-negative."
+ else:
+ message = f"Found {negative_count} negative value(s)."
+ return base.ValidationResult(
+ passes=passes,
+ message=message,
+ diagnostics={"negative_count": negative_count, "series_length": len(dataset)},
+ )
+
+The pieces are:
+
+* ``applies_to`` -- whether this validator can run on the output type of the decorated function.
Review Comment:
So turns out this actually does not fire on the custom validator route.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@hamilton.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs(data-quality): add check_output_custom section (#212) [hamilton]
Posted by "philipljh (via GitHub)" <gi...@apache.org>.
philipljh commented on PR #1658:
URL: https://github.com/apache/hamilton/pull/1658#issuecomment-5313984767
> Hey, nice work and welcome!
>
> So I checked the underlying code and it turns out we have a bug there. Let me know if you are up for it to fixing it, otherwise I can also do it and we can merge your PR on top?
>
> FYI: https://github.com/apache/hamilton/blob/a55e214b0cd6b1d44f06170698a32599ac1efe62/hamilton/function_modifiers/validation.py#L188, here we just return the full list ignoring the `applies_to` method. This would need to be fixed to actually check whether the validator can be applied to the output and maybe add a test or two.
Feel free to do a fix!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@hamilton.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs(data-quality): add check_output_custom section (#212) [hamilton]
Posted by "jernejfrank (via GitHub)" <gi...@apache.org>.
jernejfrank commented on PR #1658:
URL: https://github.com/apache/hamilton/pull/1658#issuecomment-5314879902
> > Hey, nice work and welcome!
> > So I checked the underlying code and it turns out we have a bug there. Let me know if you are up for it to fixing it, otherwise I can also do it and we can merge your PR on top?
> > FYI: https://github.com/apache/hamilton/blob/a55e214b0cd6b1d44f06170698a32599ac1efe62/hamilton/function_modifiers/validation.py#L188
> > , here we just return the full list ignoring the `applies_to` method. This would need to be fixed to actually check whether the validator can be applied to the output and maybe add a test or two.
>
> Feel free to do a fix!
Cool, opened #1688 and will merge yours afterwards :+1:
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@hamilton.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs(data-quality): add check_output_custom section (#212) [hamilton]
Posted by "philipljh (via GitHub)" <gi...@apache.org>.
philipljh commented on PR #1658:
URL: https://github.com/apache/hamilton/pull/1658#issuecomment-4983265413
Hello, made my first oss pr, open to any feedback and guidance. Cheers~
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@hamilton.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org