It would be good to add a code example, but our public API does not directly expose any units suitable for this purpose and parsing a string would emit a different warning. In the unit tests I avoided that warning by going through private API, but in user documentation that is unacceptable.

Not the prettiest, but in principle one could do,

from astropy.units import cds
cds.Crab.to_string(format="ogip")

p.s. It is indeed a bit annoying that u.Unit("Crab", format="ogip", parse_strict="silent") actually is not silent...

Using cds here would make the example too confusing.

Are strings permitted?

It is best if these options do not differ needlessly from the parse_strict options the unit parsing methods have, and those are all strings.

Then are the type annotations correct?

The tests and documentation only use strings.

With the following defined elsewhere

DEPRECATED_UNIT_MSG: Final = "The unit {} has been deprecated in the {} standard."

I'm not sure deprecations = DeprecatedUnitAction(deprecations) is necessary given the type annotation, but the docstring made me put it in.

This is slightly more compact and avoids assigning to intermediate variables unless needed.

The creation of msg in separate branches may be an over-optimization.

First of all your suggestion would mean the deprecations value is checked whether or not there are any deprecated units, whereas with my code deprecations is ignored unless it is actually needed. That is a visible difference in code behavior.

For code readability it is best if things are defined close to where they are used unless doing so would cause code duplication. Unfortunately some of your suggestions move definitions away from usage while also increasing duplication. The claim that the suggested code is more compact is not true because shortening the function here by a few lines is achieved by adding even more lines elsewhere.

Given that it's a str enum, can't the parse step be moved anywhere?
Edit: I just did. I moved it to address your first point.
And doesn't _missing_ move things closer to their usage? It's like __contains__ and performs a similar separation of concerns between determining if an action is valid and performing that action. And Enums naturally contain a _missing_ check, which the proposed code doesn't use when raising on an incompatible input. This suggestion customizes _missing_ and uses the Enum mechanism.

I quite like the match here, as well as using the StrEnum (if we're using it at all) to generate the error message. I would not worry at all about performance in this path, where we're already dealing with a deprecated unit, so in an unlikely scenario.

I'd do CONVERT first, since then alternative is still close by.

Not the prettiest, but in principle one could do,

from astropy.units import cds
cds.Crab.to_string(format="ogip")

p.s. It is indeed a bit annoying that u.Unit("Crab", format="ogip", parse_strict="silent") actually is not silent...

I quite like the match here, as well as using the StrEnum (if we're using it at all) to generate the error message. I would not worry at all about performance in this path, where we're already dealing with a deprecated unit, so in an unlikely scenario.

I'd do CONVERT first, since then alternative is still close by.

I like it.

I think the match is working out! But I'd still prefer to forego performance here and just start the match after the existing

if s in cls._deprecated_units:
    msg = "..."
    if (alternative := ...):
        msg += ...
    match DeprecatedUnitAction(deprecations):
        case DeprecatedUnitAction.CONVERT:
            if alternative:
                return alternative
            warnings.warn(msg + ...)
        case ...

It keeps the code easy to follow, with all logic to the various deprecated unit possibilities in one place; performance really is not a worry here.

Late to this party, but calling this as the last resort is a bit overly judgy -- erg and Angstroms will likely stay with us for a while, no need for this snarky comment in the docs.