ENH: Add case_when method
State: closed

- [x] closes #39154
- [x] [Tests added and passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#writing-tests) if fixing a bug or adding a new feature
- [x] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).
- [x] Added [type annotations](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#type-hints) to new arguments/methods/functions.
- [x] Added an entry in the latest `doc/source/whatsnew/vX.X.X.rst` file if fixing a bug or adding a new feature.

Continues the work started by @ElHoussineT(#50343)

- uses `pd.Series.mask` under the hood
- function implementation, as well as a Series method


Labels:
name: Series
description: Series data structure

Comments:
pre-commit.ci autofix
@rhshadrach had issues with the previous pr #55390 and created this one. If there is a way to reconnect to the old one, kindly advise me on the approach. Thanks 
@rhshadrach made changes based on your feedback. Looking forward to your reviews 
Thanks for the changes. I think this is looking good - but want to add more tests when I get a chance. In the meantime, cc @pandas-dev/pandas-core for any thoughts/feedback here.
Thoughts:

1) @samukweku will you have bandwidth/willingness to be responsible for maintenance of this going forward?
2) id prefer either a top-level function _or_ a method rather than both
3) in the same direction as Irv: strong-as-possible typing will make me minimally cranky
@jbrockmendel in response to your comments: 
1. yes i am willing to be responsible for the maintenance going forward.
2. i'd lean more in favour of a method - it would certainly make the code simpler, since it would be a method on a Series. if the team agrees on this, that would be great. The reason behind providing a function was to provide more flexibility - the [conversation](https://github.com/pandas-dev/pandas/pull/55390#discussion_r1375259556) gives an idea of where the function could be helpful, but generally a method would be my preference.
3. made some changes based on @Dr-Irv feedback. Thanks @Dr-Irv 
Strong preference for method
I also prefer method.
I will make the changes and keep only the Series method option
Can you fix the doc build and the typing checks?

This should be ready then
@phofl can I get your help on resolving the doc build error- cant make sense of the sphinx error message pointing to line 131 in the whatsnew section
Your example was buggy (our doc builds are not very useful for debugging, sorry), my suggestion should fix this error
@samukweku - I merged main to make sure CI is green here.
How does this handle attrs/_metadata/flags when given mismatched args with mismatched attrs/_metadat/flags?
> How does this handle attrs/_metadata/flags when given mismatched args with mismatched attrs/_metadat/flags?

@jbrockmendel i am unfamiliar with your question. Kindly share an example to help me understand.
@samukweku your latest rebase threw something off here, the diff is too large. Could you take a look?
@jbrockmendel 

The handling off metadata is dispatched to mask in this case, so we should be good
> I think the implementation is looking pretty good - but tests can be expanded on. Would it be okay if I pushed some tests to your branch?

@rhshadrach yes pls feel free to add more tests
merging this, we can always add tests after if necessary
thx for staying with us @samukweku 
Something went wrong ... Please have a look at my logs.