refactor!: Rename filter_relationship_one_to_one to require_relationship_one_to_one and add drop_unique parameter

[delsner]

Motivation

filter_relationship_one_to_one does only check for a 1:1 relationship in case both data frames are unique w.r.t. the provided join key. Also, the docstrings are incorrect as the join columns cannot be inferred.

Changes

• Rename filter_relationship_one_to_one to require_relationship_one_to_one
• Add drop_unique to allow filtering for 1:1 or 1:{1,N} relationships in case join columns do not uniquely identify rows
• Fix docstrings

[delsner]

@borchero @AndreasAlbertQC wdyt of this fix? One could argue that these functions are only to be used inside dy.filter where you would typically pass the common primary key as join key, but I still find it unintuitive that we don't actually filter for a 1:1 relationship.

Happy to adjust the API if you have a better idea.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (53c72bd) to head (000a99b).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main       #67   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           50        50           
  Lines         2904      2908    +4     
=========================================
+ Hits          2904      2908    +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[AndreasAlbertQC]

@delsner I think your change is good, but I wonder if we need to do something else to mitigate confusing results if the dataframes are not unique on the join keys already. If I don't set the new flag, I will get nonsensical results, right?
Possible solutions:

1. check for uniqueness and if its violated, do one of the following:
   1.1 hard error
   1.2 warning
   1.3 automatically activate the new flag plus warning
2. Don't check anything, and document that you will get nonsensical results if you don't ensure that the keys are unique already, so the user has to take care of it.

I am hesitating between 1.3 and 2.

[delsner]

If I don't set the new flag, I will get nonsensical results, right?

Potentially, yes.

I am hesitating between 1.3 and 2.

2 is easy, I can just update the docstring.
IMO 1.3 is the right way to do it, but this is a breaking change, albeit a bug-fixing one. I think hardly anyone is using this feature since it's undocumented, so I'd also be fine to go with 1.3. Wdyt?

Any thoughts @borchero?

[AndreasAlbertQC]

@delsner I'd be happy with counting option 1.3 as a bug fix bc I think the current behavior generates incorrect output data

[borchero]

I made the current choice deliberately as additional uniqueness validations are really expensive. Hence, my initial thought would be to go for (2).

Nevertheless, it potentially makes sense to make this behavior opt-in, i.e. require the user to set some kind of flag to skip the additional validation step.

However, I'm not sure I love the extension of the filter_relationship_one_to_one method; we're somehow evaluating a "many-to-many" relationship here, don't we? 🤔

[delsner]

@borchero and I decided to rename these functions to require_* and also will update the one_to_at_least_one function. We'll also rename the parameter to is_unique and change its default to False.

[AndreasAlbertQC]

lgtm, thanks <3

[borchero]

Thanks 😄