python-feature-lifecycle

Python Feature Lifecycle

Two lifecycle levels

Agent Framework uses lifecycle at two different levels:

1. Package lifecycle — the maturity of the package as a whole
2. Feature lifecycle — the maturity of a specific API or feature inside that package

These are related, but they are not the same thing.

• The package stage is the default for everything in the package.
• Feature-stage decorators are only for exceptions when a feature is behind the package's default stage.
• Do not decorate every class or function just because the package is experimental or release candidate.

Important default

If a package is still in beta / experimental preview, all public APIs in that package are experimental by default.

• Do not add @experimental(...) everywhere in that package.
• The package stage already communicates that default.

Once a package moves forward, you can keep individual features behind:

• If a package moves to release candidate, a feature may remain experimental
• If a package moves to released / GA, a feature may remain experimental or release candidate

That is the main use case for feature-stage decorators.

The four stages

1. Experimental

Use for features that are still unstable and may change or be removed without notice.

Feature-level code pattern:

from ._feature_stage import ExperimentalFeature, experimental


@experimental(feature_id=ExperimentalFeature.MY_FEATURE)
class MyFeature:
    ...

Behavior:

• Adds an experimental warning block to the docstring
• Records feature metadata on the decorated object
• Emits a runtime warning the first time the feature is used (once per feature by default)

Enum setup:

• Add an all-caps member to ExperimentalFeature
• Reuse the same feature ID across all APIs that belong to the same conceptual feature

2. Release candidate

Use for features that are nearly stable but may still receive small refinements before GA.

Feature-level code pattern: