Add SAVED_CHECKPOINT event to Checkpoint handler

[JeevanChevula]

Fixes #934

This PR adds a "saved_checkpoint" event that fires after successful checkpoint saves.

Usage:

# Users need to register the event first
engine.register_events("saved_checkpoint")

@trainer.on("saved_checkpoint")
def after_saving(engine):
    print("Checkpoint saved!")

[vfdev-5]

@JeevanChevula thanks for the PR. However, let's rework the API of the new feature you are working on:

1. Let's avoid using string type as event name and do not ask users to register the event. This should be done internally by ignite.

2. Let's define the event in the Checkpoint as following:

# checkpoint.py

class CheckpointEvents(EventEnum):
    SAVED_CHECKPOINT = "saved_checkpoint"


class Checkpoint(...):
    SAVED_CHECKPOINT = CheckpointEvents.SAVED_CHECKPOINT
    ...

3. finally the usage can be something like this:

from ignite.engine import Engine, Events
from ignite.handlers import Checkpoint, global_step_from_engine

trainer = ...
evaluator = ...
# Setup Accuracy metric computation on evaluator.
# evaluator.state.metrics contain 'accuracy',
# which will be used to define ``score_function`` automatically.
# Run evaluation on epoch completed event
# ...

to_save = {'model': model}
handler = Checkpoint(
    to_save, '/tmp/models',
    n_saved=2, filename_prefix='best',
    score_name="accuracy",
    global_step_transform=global_step_from_engine(trainer)
)

evaluator.add_event_handler(Events.COMPLETED, handler)

# ---- New API with Checkpoint.SAVED_CHECKPOINT event: -----

@evaluator.on(Checkpoint.SAVED_CHECKPOINT)
def notify_when_saved(eval_engine, chkpt_handler):   # we should pass to the attached handlers the engine and the checkpoint instance.
    assert eval_engine is engine
    assert chkpt_handler is handler
    print("Saved checkpoint:", chkpt_handler.last_checkpoint)
    
# ---- End of New API with Checkpoint.SAVED_CHECKPOINT event: -----

trainer.run(data_loader, max_epochs=10)
> ["best_model_9_accuracy=0.77.pt", "best_model_10_accuracy=0.78.pt", ]

Let me know what do you think?

[JeevanChevula]

Thanks for the suggestion . I’ll try to work on updating the PR to follow the API approach you mentioned with

[JeevanChevula]

Implementation Note:

Implemented EventEnum-based SAVED_CHECKPOINT event as requested. However, Ignite's event system only supports single-parameter handlers - the originally requested two-parameter signature (handler(engine, checkpoint_handler)) failed during event firing and registration.

Current implementation uses single parameter with checkpoint access via engine._current_checkpoint_handler. All 61 core tests pass, confirming functionality works without breaking existing features. The 3 distributed test errors are pre-existing infrastructure issues unrelated to this change.

[vfdev-5]

Thanks for working on this PR @JeevanChevula
I left few more comments to improve the PR

[vfdev-5]

Can you explain this code? I do not understand why we need this.

[JeevanChevula]

This is a workaround for Ignite's event system limitation. You originally requested a two-parameter handler signature handler(engine, checkpoint_handler), but Ignite's fire_event() only supports single parameters and rejects handlers expecting additional arguments. This line stores the checkpoint reference in the engine so handlers can access it via engine._current_checkpoint_handler.

[vfdev-5]

I have to check details about this limitation. Unfortunately engine._current_checkpoint_handler is not good enough for a public API usage.

Alternatively, we can pass the instance of the checkpointer as an arg when attaching:

checkpoint = Checkpoint(...)

@trainer.on(Checkpoint. SAVED_CHECKPOINT, checkpoint)
def handler(engine, chkpt_handler):
    assert engine is trainer
    assert chkpt_handler is checkpoint

Maybe, we can skip automatic chkpt_handler arg injection:

checkpoint = Checkpoint(...)

@trainer.on(Checkpoint. SAVED_CHECKPOINT)
def handler(engine):
    assert engine is trainer
```

[vfdev-5]

@JeevanChevula please remove this private attribute

[JeevanChevula]

Pushing current implementation with working SAVED_CHECKPOINT event functionality. Will add proper Google-style docstrings with version directives by Monday per contributing guidelines

[vfdev-5]

@JeevanChevula please rebase your PR branch, you have now some extra commits

[vfdev-5]

This should be added to the docstrings. Can you locally render the docs and show how this look like?

Suggested change

	.. versionadded:: 0.5.0
	.. versionadded:: 0.5.3

[vfdev-5]

Suggested change

	"""Events fired by Checkpoint handler"""
	"""Events fired by Checkpoint handler
	.. versionadded:: 0.5.0
	"""

[JeevanChevula]

Thanks for the feedback 🙏

I will update checkpoint.py so that the CheckpointEvents class docstring includes the version:

class CheckpointEvents(EventEnum):
    """Events fired by Checkpoint handler
    
    .. versionadded:: 0.5.3
    """
    SAVED_CHECKPOINT = `"saved_checkpoint"

One clarification: should I completely remove the Checkpoint Events section from docs/source/handlers.rst, or just update the version there from 0.5.0 → 0.5.3?

[vfdev-5]

One clarification: should I completely remove the Checkpoint Events section from docs/source/handlers.rst, or just update the version there from 0.5.0 → 0.5.3?

Do not remove it. Change what is suggested and build and visualize the docs locally. I think versionadded part of docs:

Checkpoint Events
-----------------

.. versionadded:: 0.5.3

wont be rendered correctly. In this case just remove .. versionadded:: 0.5.3 and keep everything else

[JeevanChevula]

I've updated the CheckpointEvents docstring with the version directive and kept the RST documentation without the versionadded line as suggested. The local docs build hits a Windows-specific environment issue at 97% completion (not related to our changes - the RST parsing completed successfully).However, the documentation syntax appears correct based on the successful parsing before the build failure.