canonical / canonical/operator

Expose the testing _Event.deferred docs

Open
#1,789 2 comments 1 reaction 0 assignees View on GitHub
docs rainy day tests
Dominant language
Python
Stars
267
Forks
136
Avg merge
1d 22h
Merged PRs (30d)
28

Description

Because `scenario._Event` is private, it doesn't show up in the API reference documentation. Users shouldn't be subclassing `_Event` and shouldn't be creating them other than via `ctx.on`, so it is nice if the class does remain private.

However, when you have an `_Event`, we provide a `deferred()` method on it that is meant for use. This will show up in `help()` and in IDE tips but is missing from our published API reference docs, since it's on the private class.

We should solve this somehow. Maybe we go back to having a top-level `deferred()` function instead of attaching it to `_Event`? (We'd need to keep the existing one for backwards compatibility, but it could just call the public one). Maybe the `deferred()` docs can be on `CharmEvents` or somewhere similar?

Contributor guide

Open the contributing guide

Research direction

Start by reviewing scenario._Event, its deferred() method, ctx.on, and the existing CharmEvents documentation path. Compare how help(), IDE tips, and the published API reference expose deferred(). Done means users can find the supported deferred() documentation in the API reference without making the private _Event class public, while preserving the existing behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.