Improve parameter kind handling for argument requirement determination

[MilkClouds]

What does this PR do?

Fixes #757

This PR enhances the logic for determining whether function/method parameters should be treated as required CLI arguments by implementing more sophisticated parameter kind-aware handling.

Problem: The current implementation uses a simple rule (is_required = default == inspect_empty) which doesn't properly account for Python's different parameter kinds. This conflates two different concepts:

1. Python requirement semantics: Whether a parameter needs a value for the function to work
2. CLI argument style: Whether to use positional args vs --flag style

This causes issues particularly with KEYWORD_ONLY parameters, which should always use the --flag style regardless of whether they have defaults, and should be properly marked as required when they don't have defaults. This design matches with CLI project, https://github.com/BrianPugh/cyclopts.

Solution: Introduced a more sophisticated parameter kind-aware approach:

1. POSITIONAL_ONLY: Always required, can be positional
2. POSITIONAL_OR_KEYWORD: Required if no default, can be positional
3. KEYWORD_ONLY: Required if no default, must use --flag style
4. VAR_POSITIONAL/VAR_KEYWORD: Skip entirely (unchanged behavior)
5. None (fallback): Required if no default, can be positional (for programmatically created parameters)

Before/After Comparison

Consider this test function:

from typing_extensions import TypedDict, Unpack

class MyTestUnpackDict(TypedDict, total=False):
    a: int
    b: int

def main(posarg: int, *, kwarg: str, kwarg_default: str = "default", **kwargs: Unpack[MyTestUnpackDict]):
    pass

auto_cli(main, as_positional=True)

Before this PR:

usage: main.py [-h] [--config CONFIG] [--print_config[=flags]]
               [--kwarg_default KWARG_DEFAULT] [--print_shtab {bash,zsh,tcsh}]
               posarg kwarg a b

After this PR:

usage: main.py [-h] [--config CONFIG] [--print_config[=flags]] --kwarg KWARG
               [--kwarg_default KWARG_DEFAULT] --a A --b B
               [--print_shtab {bash,zsh,tcsh}]
               posarg

Key improvements:

• ✅ KEYWORD_ONLY parameters (kwarg, a, b) now correctly use --flag style instead of being treated as positional arguments
• ✅ Required KEYWORD_ONLY parameters are properly marked with --kwarg KWARG, --a A, --b B in the usage line
• ✅ POSITIONAL_OR_KEYWORD parameters (posarg) can still become positional when appropriate
• ✅ Works correctly with modern Python typing features like Unpack[TypedDict]
• ✅ Maintains backward compatibility for all existing functionality

The core issue was that KEYWORD_ONLY parameters were incorrectly being treated as positional arguments when as_positional=True, which violates Python's parameter semantics. Now they correctly always use the --flag style as they should.

Before submitting

• Did you read the contributing guideline?
• Did you update the documentation? (readme and public docstrings) - n/a (internal logic improvement, no API changes)
• Did you write unit tests such that there is 100% coverage on related code? (required for bug fixes and new features) - Existing tests cover the functionality and all pass
• Did you verify that new and existing tests pass locally?
• Did you make sure that all changes preserve backward compatibility?
• Did you update the CHANGELOG with the pull request link? (not for typos, docs, test updates, or minor internal changes/refactors) - Will update after PR number is available

[mauvilsa]

Makes sense what you propose here. I had not considered well the keyword-only cases. But sound more like a bug fix to me.

Thank you for contributing!

[MilkClouds]

Thanks for the positive review! I'll have a look at your review and make revision in the near future.

[MilkClouds]

@mauvilsa I finished revision, please have a review again.

[mauvilsa]

Looking good, but more testing is needed.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (785af2c) to head (f2b2dc7).

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #756   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           22        22           
  Lines         6884      6895   +11     
=========================================
+ Hits          6884      6895   +11     

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

[mauvilsa]

I committed some changes to finish it off.