Clarify behavior of decorator ordering

[HamiltonRepoMigrationBot]

Issue by skrawcz Sunday Dec 18, 2022 at 01:28 GMT Originally opened as https://github.com/stitchfix/hamilton/issues/249

---

We need to make clear our philosophy and resolution method for functions such as:

@extract_fields({'out_value1': int, 'out_value2': str})
@tag(test_key="test-value")
@check_output(data_type=dict, importance="fail")
@does(_dummy)
def uber_decorated_function(in_value1: int, in_value2: str) -> dict:
    pass

Right now it is not clear, nor obvious.

Current behavior

This is what the graph looks like:

So it would be unexpected to see check_output over the output of extract_fields.

Steps to replicate behavior

Function code:

def _dummy(**values) -> dict:
    return {f"out_{k.split('_')[1]}": v for k, v in values.items()}


@extract_fields({'out_value1': int, 'out_value2': str})
@tag(test_key="test-value")
@check_output(data_type=dict, importance="fail")
@does(_dummy)
def uber_decorated_function(in_value1: int, in_value2: str) -> dict:
    pass

Expected behavior

check_output should probably operate over what's directly underneath that. tag similarly should apply to all? or just what's underneath? does should apply to uber_decorated_function extract_fields is the last thing that's applied?

Additional context

Thoughts: can we create a linter that reorders decorators?