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!