refactor: Update deprecate arguments.

[prmukherj]

Context

In the existing codebase, argument deprecations were handled inconsistently and often required writing repetitive, manual logic to warn users and remap deprecated arguments to their newer equivalents.
There was no unified or flexible way to deprecate multiple arguments at once, especially when multiple old arguments needed to map to one or more new arguments.
Additionally, existing deprecation decorators typically required developers to hardcode version strings and custom messages, leading to maintenance overhead and a higher chance of inconsistencies.

Change Summary

A new decorator, deprecate_arguments, is introduced with the following signature:

def deprecate_arguments(
    old_args: str | list[str],
    new_args: str | list[str],
    version: str,
    converter: Callable | None = None,
    warning_cls: type[Warning] = PyFluentDeprecationWarning,
) -> Callable:

A new decorator for deprecating function is also introduced.

def deprecate_function(
    version: str,
    new_func: str | None = None,
    warning_cls: type[Warning] = PyFluentDeprecationWarning,
) -> Callable:

Rationale

This decorator centralizes and simplifies how argument deprecations are declared and processed.
It reduces boilerplate, improves readability, and enforces consistency across the API.
By allowing grouped mappings, the design accommodates complex transitions (such as merging or splitting arguments).
Passing the full old_arg_list and new_arg_list to the converter provides more flexibility for complex transformation logic while keeping the default case straightforward.

Impact

Simplifies the process of marking arguments as deprecated.
Reduces risk of missing or inconsistent deprecation messages.
Provides an easy path for custom conversion logic between old and new APIs.

Example usage

>>> @deprecate_arguments(
>>>     old_args=["a", "b"],
>>>     new_args=["d", "e"],
>>>     version="3.0.0"
>>> )
>>> @deprecate_arguments(
>>>     old_args="c",
>>>     new_args="f",
>>>     version="3.0.0"
>>> )
>>> @deprecate_arguments(
>>>     old_args="x1",
>>>     new_args="z1",
>>>     version="3.0.0"
>>> )
>>> def example_func(**kwargs):
>>>     print(kwargs)

>>> example_func(a=1, b=2, c=3, x1=2, x2=4)

{'x2': 4, 'd': 1, 'e': 2, 'f': 3, 'z1': 2}
PyFluentDeprecationWarning: Arguments 'a', 'b' are deprecated; use 'd', 'e' instead.
  example_func(a=1, b=2, c=3, x1=2, x2=4)
PyFluentDeprecationWarning: Argument 'c' is deprecated; use 'f' instead.
  return wrapped_(*args_, **kwargs_)
PyFluentDeprecationWarning: Argument 'x1' is deprecated; use 'z1' instead.
  return wrapped_(*args_, **kwargs_)

>>>  def my_custom_converter(kwargs, old_args, new_args):
>>>      # Combine values of a, b into a tuple → d
>>>      values = tuple(kwargs.pop(arg) for arg in old_args if arg in kwargs)
>>>     if values:
>>>          kwargs[new_args[0]] = values
>>>     return kwargs

>>>  @deprecate_arguments(
>>>      old_args=["a", "b"],
>>>      new_args="d",
>>>      version="3.0.0",
>>>      converter=my_custom_converter,
>>>  )
>>>  @deprecate_arguments(
>>>      old_args="c",
>>>      new_args="e",
>>>      version="3.0.0",
>>>  )
>>>  def example_func(**kwargs):
>>>      print(kwargs)

>>>  example_func(a=1, b=2, c=3)

{'d': (1, 2), 'e': 3}
PyFluentDeprecationWarning: Arguments 'a', 'b' are deprecated; use 'd' instead.
  example_func(a=1, b=2, c=3)
PyFluentDeprecationWarning: Argument 'c' is deprecated; use 'e' instead.
  return wrapped_(*args_, **kwargs_)

>>>  @deprecate_function(version="3.0.0", new_func="new_add")
>>>  def old_add(a, b):
>>>      return a + b

>>>  def new_add(a, b):
>>>      return a + b + 10

>>>  old_add(1, 2)

PyFluentDeprecationWarning: Function 'old_add' is deprecated since version 3.0.0. Use 'new_add' instead. old_add(1, 2)

[Copilot]

Pull Request Overview

This PR introduces a new deprecate_arguments decorator to centralize and simplify argument deprecation handling. The decorator supports grouped argument mappings, custom conversion logic, and consistent warning messages across the API.

• Adds a flexible decorator that handles multiple deprecated arguments with automatic replacement
• Supports both default 1-to-1 mapping and custom conversion functions for complex argument transformations
• Provides consistent deprecation warnings with configurable warning classes

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[prmukherj]

Hi,

I have created this PR with the new signature. Please provide me your comments by referring to the example usages, based on your feedback will do improvements.

I have added some sample implementations in launcher, field_data and file_session code for reference.

Please note: method deprecator is yet to be implemented.

Thank you.

[Copilot]

Pull Request Overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

src/ansys/fluent/core/utils/deprecate_new.py:1

• The _show_gui_to_ui_mode function is not defined in this file and is being called without being imported. This will cause a NameError at runtime.

"""Deprecate Arguments."""

src/ansys/fluent/core/utils/deprecate_new.py:1

• The _version_to_dimension function is not defined in this file and is being called without being imported. This will cause a NameError at runtime.

"""Deprecate Arguments."""

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[seanpearsonuk]

@prmukherj Will there be a follow-up stage to completely supersede the old version?

[prmukherj]

@prmukherj Will there be a follow-up stage to completely supersede the old version?

yes, I have created this PR just to get feedback on the design from everyone. Now I'll mark this as draft and make the shift as part of this PR only.

Thank you for your feedback @seanpearsonuk

[seanpearsonuk]

@prmukherj Will there be a follow-up stage to completely supersede the old version?

yes, I have created this PR just to get feedback on the design from everyone. Now I'll mark this as draft and make the shift as part of this PR only.

Thank you for your feedback @seanpearsonuk

OK, feel free to merge in stages too.

[prmukherj]

>>> @deprecate_arguments(
>>>     old_args=["a", "b"],
>>>     new_args="d",
>>>     version="3.0.0",
>>>     converter=my_custom_converter,
>>> )
>>> @deprecate_arguments(
>>>     old_args="c",
>>>     new_args="e",
>>>     version="3.0.0",
>>>     converter=my_custom_converter,
>>> )
>>> def example_func(**kwargs):
>>>     print(kwargs)

[Copilot]

Pull Request Overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[seanpearsonuk]

@prmukherj The latest iteration looks a lot simpler and cleaner.

[raph-luc]

Suggested change

# Validation

[raph-luc]

Suggested change

	# Default converter
	def _default_converter(
	def _default_converter(

[raph-luc]

Suggested change

# Build reason message for @deprecated

[raph-luc]

Looks like a significant improvement to me, thanks for asking for review. Note the tests are failing, I didn't investigate if they are related to these changes or not

[Copilot]

Pull Request Overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}