Improve type safety and documentation in powerups modules

[tomdemeyere]

Summary

Made changes to atomate2/vasp/powerups.py and atomate2/common/powerups.py

• Improved docstrings
• Added a JobType TypeVar for functions accepting union of types such as Job | Flow | Maker so that the return type by the static type checker is the same as the input type.

Potential problem: at some point we can find flow: Flow, additional_fields: dict, class_filter: Maker = BaseVaspMaker, the class filter then get send to update_custodian_handlers where we can find code = class_filter.name.split(" ")[1]

Here an instance property is called on what is supposed to be a type, I assume this is done because in practice the property is only implemented in the Maker base class and conventionally overridden by a class attribute in most subclasses (hacky).

@JaGeo @naik-aakash

Checklist

• Code is in the standard Python style.
  The easiest way to handle this is to run the following in the correct sequence on
  your local machine. Start with running ruff and ruff format on your new code. This will
  automatically reformat your code to PEP8 conventions and fix many linting issues.
• Doc strings have been added in the Numpy docstring format.
  Run ruff on your code.
• Type annotations are highly encouraged. Run mypy to
  type check your code.
• Tests have been added for any new functionality or bug fixes.
• All linting and tests pass.

[JaGeo]

Hi @tomdemeyere ,

Thanks for working on this.

Could you elaborate on how this new change affects usage of the powerups, and also check if the failing tests have anything to do with your changes? Thanks in advance!

[esoteric-ephemera]

Thanks for the docstr updates @tomdemeyere! Some comments for stylistic consistency, also @JaGeo the failing tests were just the emmet-core incompatibility which should be resolved now

[esoteric-ephemera]

@tomdemeyere can you look at why the cp2k tests are failing from these changes?

[tomdemeyere]

Thanks for you comments @esoteric-ephemera I did not know about "or" I always thought NumPy style was with pipes, it's nice to know!

Tests should be passing now.

[tomdemeyere]

Could you elaborate on how this new change affects usage of the powerups

@JaGeo No runtime changes in this PR, only type hinting. The TypeVar introduced in functions ensure that if users send an object A to the function, they will get an object A back:

# Previous behavior
my_job: Job
my_job = update_user_kpoints_settings(my_job, ...)
# `my_job` is now Job | Flow | Maker type due to the return type of the function

#Current behavior
my_job: Job
my_job = update_user_kpoints_settings(my_job, ...)
# `my_job` is still the same exact type `Job` due to the TypeVar

[JaGeo]

To me everything looks fine 😀.

Are any comments still open from your side @esoteric-ephemera ?

[JaGeo]

Thanks @tomdemeyere ! :)