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

[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]

@JeevanChevula here is how docs are rendered for this PR: https://deploy-preview-3440--pytorch-ignite-preview.netlify.app/handlers

Thanks for all the updates you made recently. The last thing I think we still have to do is to reorganize a bit the docs on CheckpointEvents.

The example you wrote in handlers.rst: https://github.com/pytorch/ignite/pull/3440/files#diff-fed20f17bf0c40747938f76730fe5cdc467c919bd185eeb9fe0870b861379681R38 should be moved into Checkpoint docstring. And this page: https://deploy-preview-3440--pytorch-ignite-preview.netlify.app/generated/ignite.handlers.checkpoint.checkpoint#ignite.handlers.checkpoint.Checkpoint should mention the attribute Checkpoint.SAVED_CHECKPOINT: e.g. alias of SAVED_CHECKPOINT from :class:~ignite.handlers.checkpoint.CheckpointEvents.

[JeevanChevula]

Hi! Thank you for the detailed feedback on the documentation reorganization

I want to make sure I implement the changes exactly as you envision them. Three specific questions for clarification:

1. Checkpoint class docstring placement (class Checkpoint(Serializable):)
   The Checkpoint class already has a long docstring with multiple Examples: sections.
   Should I add the checkpoint event usage example:

   • After the last existing example (the “Customise the save_handler” section) but before the .. versionchanged:: notes?
   • Or in a different location within the docstring?

2. handlers.rst reorganization
   For the Checkpoint Events section in handlers.rst, should I:

   • Remove the entire section completely (since the example will be moved to the docstring)?
   • Or keep the heading and basic description, but remove only the detailed usage example?

3.SAVED_CHECKPOINT attribute documentation
For documenting "alias of SAVED_CHECKPOINT from CheckpointEvents", would you prefer that I:

 * Add it in an Attributes: section inside the Checkpoint docstring?
 * Or simply put a short comment/docstring next to the line SAVED_CHECKPOINT = CheckpointEvents.SAVED_CHECKPOINT?
 * Or another location entirely?

I’d like to follow your vision precisely, so confirming these points will help me make the changes correctly.

[vfdev-5]

Here are details on your questions:

Point 1: -> After the last existing example (the “Customise the save_handler” section) but before the .. versionchanged:: notes

Point 2: -> Remove the entire section completely (since the example will be moved to the docstring)?

Point 3: -> Add it in an Attributes: section inside the Checkpoint docstring

Attributes:
    SAVED_CHECKPOINT: alias of SAVED_CHECKPOINT from :class:~ignite.handlers.checkpoint.CheckpointEvents.

Make sure to check rendered docs (on netlify: https://deploy-preview-3440--pytorch-ignite-preview.netlify.app/)

[JeevanChevula]

Hi!

I’ve applied the requested changes:

• Moved the checkpoint event usage example into the Checkpoint class docstring (after “Customise the save_handler” and before the .. versionchanged:: notes).

• Added an Attributes: section documenting SAVED_CHECKPOINT as an alias of :class:~ignite.handlers.checkpoint.CheckpointEvents``.

• Removed the “Checkpoint Events” section from handlers.rst and kept only the API references.

On my Windows machine I wasn’t able to fully render the docs locally due to a Sphinx subprocess issue in my environment. I may be missing a dependency—I'll revisit this when I’m back. In the meantime, the Netlify preview should reflect these changes; if anything doesn’t look right, I’m happy to adjust.

I’ll be OOO ( Sep 26 – Oct 5, IST]. Please feel free to leave comments or push small cleanups; I’ll pick up any remaining fixes as soon as I return. Thanks!

[vfdev-5]

LGTM, thanks @JeevanChevula !