Skip to content

[DEPRECATION] Python interface deprecations and changes for v2 #1660

Description

@mgovers

We have some additional legacy that we would like to remove when we're going to do a major version bump (see milestone https://github.com/PowerGridModel/power-grid-model/milestone/3 ).

Overview of all publicly exposed Python functions of power_grid_model and the decision on whether to make (some of)
their regular arguments keyword-only (by putting them after a *, marker).

  • Order: same as the readthedocs Python API reference
    (python-api-reference.md).
  • Filename: the file in src/power_grid_model where the function is defined.
  • ⚠️ in the deprecate/remove column: the function is deprecated and/or to be removed.
Function Filename Deprecate/remove Do nothing Make all arguments keyword-only Make some arguments keyword-only Regular arguments Keyword arguments
PowerGridModel.__init__ _core/power_grid_model.py ✅ input_data system_frequency
PowerGridModel.batch_error (property) _core/power_grid_model.py ✅
PowerGridModel.all_component_count (property) _core/power_grid_model.py ✅
PowerGridModel.copy _core/power_grid_model.py ✅
PowerGridModel.update _core/power_grid_model.py ✅
PowerGridModel.get_indexer _core/power_grid_model.py ✅
PowerGridModel.calculate_power_flow _core/power_grid_model.py ✅
PowerGridModel.calculate_state_estimation _core/power_grid_model.py ✅
PowerGridModel.calculate_short_circuit _core/power_grid_model.py ✅
initialize_array _core/power_grid_meta.py ✅ data_type, component_type, shape empty
attribute_dtype _core/power_grid_meta.py ✅
attribute_empty_value _core/power_grid_meta.py ✅
validation.validate_input_data validation/_validation.py ✅
validation.validate_batch_data validation/_validation.py ✅
validation.assert_valid_input_data validation/assertions.py ✅
validation.assert_valid_batch_data validation/assertions.py ✅
validation.assert_valid_data_structure validation/_validation.py ✅
validation.errors_to_string validation/utils.py ⚠️
validation.ValidationException.__init__ validation/assertions.py ✅
validation.ValidationError.get_context validation/errors.py ⚠️
validation.errors.* (constructors of the ValidationError subclasses) validation/errors.py ⚠️
Logger.__init__ _core/logger.py ✅
Logger.output (property) _core/logger.py ✅
Logger.clear_content _core/logger.py ✅
utils.get_dataset_type _core/utils.py ✅
utils.get_dataset_scenario utils.py ✅
utils.get_dataset_batch_size utils.py ✅
utils.get_component_batch_size utils.py ✅
utils.is_columnar _core/utils.py ✅
utils.is_sparse _core/utils.py ✅
utils.json_deserialize _core/serialization.py ✅ data data_filter
utils.json_serialize _core/serialization.py ✅ data dataset_type, use_compact_list, indent
utils.msgpack_deserialize _core/serialization.py ✅ data data_filter
utils.msgpack_serialize _core/serialization.py ✅ data dataset_type, use_compact_list
utils.json_deserialize_from_file utils.py ✅
utils.json_serialize_to_file utils.py ✅
utils.msgpack_deserialize_from_file utils.py ✅
utils.msgpack_serialize_to_file utils.py ✅
utils.msgpack_deserialize_from_stream utils.py ✅
utils.msgpack_serialize_to_stream utils.py ✅
utils.import_json_data utils.py ⚠️
utils.export_json_data utils.py ⚠️
utils.self_test utils.py ✅

Notes

  • PowerGridModel.update and the three calculate_* methods already have all their arguments after a *, so nothing
    changes there.
  • import_json_data, export_json_data and errors_to_string are deprecated (the first two will be removed), so no
    keyword changes are needed.
  • ValidationError (the base type, including get_context) and all derived error types in validation.errors are
    deprecated, because the validation is being revamped. ValidationException itself is not deprecated, but its
    contents and the type of its arguments (currently errors and name) will change, so its signature is not touched
    now.
  • validate_input_data and validate_batch_data are kept (no validate_data function will be introduced). They become
    fully keyword-only, together with the assert_valid_* functions (they should behave the same).
  • All json_*/msgpack_* file and stream functions shall be fully keyword-only, in both directions.
    This also affects the examples and documentation.
  • Logger.__init__(logger_type, *, python_logger, python_logging_level) already has * after the optional
    logger_type, which is kept as is.
  • Not discussed explicitly: ValidationException.__init__ (signature will change anyway)
  • No functions (nothing to change) in: enum, data_types, the error types in errors (the InvalidBranch and
    InvalidBranch3 constructors only take *args, **kwargs), typing (the metadata dataclass constructors are
    not meant for users, so they are left alone), and the power_grid_meta_data constant.

Path going forward

  • Enable early migration
    • Migrate as much as possible to new interface while keeping backwards compatibility
    • Add deprecation warnings where needed
  • Disallow/remove the old behavior in the release branch
  • Optional follow-up after releasing v2: remove any remaining options

Activity

  1. added this to the Release 2.0 milestone on Oct 22, 2026
  2. added theissue type on Oct 22, 2026
  3. pinned this issue on Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    improvementImprovement on internal implementation

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions