PEP 594: uuencode codec and binascii functions apparently not properly deprecated or documented as such

[CAM-Gerlach]

As referred to in #92611 , PEP 594 (PEP-594) states that the uuencode/decode-related functions in the binascii module, as well as the uu codec will be deprecated in Python 3.11 and removed in Python 3.13:

The uu module provides uuencode format, an old binary encoding format for email from 1980. The uu format has been replaced by MIME. The uu codec is provided by the binascii module. There’s also encodings/uu_codec.py which is a codec for the same encoding; it should also be deprecated.

However, as far as I can tell, those deprecations are neither implemented with warnings in uu_codec.py or binascii (although I'm not sure what a deprecation warning at the C level that should appear at the Python level is actually supposed to look like) nor are they documented in the respective uu codec or binascii documentation sections.

Is this intentional. If not, shouldn't we get these in for 3.11?

@brettcannon @tiran

• PR: gh-92613: Deprecate other uuencode functionality per PEP 594 & document as such #92758

[brettcannon]

Probably just an oversight, although not a critical one.

[CAM-Gerlach]

Still, one that should be corrected, since per PEP 387 (PEP-387), in order to be removed, any APIs must raise a deprecation warning (and be documented as such) for at least two releases, and their deprecation is also explicitly specified per PEP 594.

Raising a DeprecationWarning on use of the codec is straightforward (since it can use the same function as the rest, presumably), as are the docs changes, but what about the two binascii functions are part of an extension module written in C? I'm not familiar with standard practice there, and I wasn't able to easily find existing examples or devguide guidance on this issue, (though its entirely possible I missed it), so I'd appreciate your advice on this.

Also, I presume this can still get landed in 3.11, since otherwise they would block uu's removal for another release, but can/should the docs deprecation notices also be backported like the module-level ones (presumably without the version), or no?

[hugovk]

Raising a DeprecationWarning on use of the codec is straightforward (since it can use the same function as the rest, presumably), as are the docs changes, but what about the two binascii functions are part of an extension module written in C?

Here's an example from https://github.com/python/cpython/pull/91846/files:

PyMODINIT_FUNC
PyInit_spwd(void)
{
    if (PyErr_WarnEx(PyExc_DeprecationWarning,
                     "'spwd' is deprecated and slated for removal in "
                     "Python 3.13",
                     7)) {
        return NULL;
    }

Some more:

• https://github.com/python/cpython/pull/91846/files
• https://github.com/python/cpython/pull/91641/files
• https://github.com/python/cpython/pull/91606/files
• https://github.com/python/cpython/pull/32392/files

[brettcannon]

Still, one that should be corrected

Yep, I'm just saying I don't have the time to do it myself.

since per PEP 387 (PEP-387), in order to be removed, any APIs must raise a deprecation warning (and be documented as such) for at least two releases

As co-author of the PEP, I'm aware. 😉

Also, I presume this can still get landed in 3.11, since otherwise they would block uu's removal for another release

That's a question for @pablogsal

but can/should the docs deprecation notices also be backported like the module-level ones (presumably without the version), or no?

No as it's too small of a deprecation.

[CAM-Gerlach]

I'm partway through implementing this (most of the work is just silencing the warnings in the tests).

BTW, I noticed one other minor use of uu too small to be noted in the PEP—its not mentioned in the documentation, but the uu decode function is also called to decode uuencoded attachments of (ancient, pre-MIME) emails, so a DeprecationWarning and docs note can be added there as well, to identify any unexpected user impacts.

Yep, I'm just saying I don't have the time to do it myself.

Yep, I assumed you'd have more important things to do, heh, so I assigned myself here.

As co-author of the PEP, I'm aware. 😉

I'd almost said "your PEP 387", but double-checked and noticed you were the PEP-Delegate, not an author (which would be a COI)

That's a question for @pablogsal

Is there something specific I need to do to apply for/justify an exception on this, or do we just wait for Pablo to respond here? I know release managers are very busy people...

No as it's too small of a deprecation.

👍

[CAM-Gerlach]

All done, PR opened as #92758

[brettcannon]

I noticed one other minor use of uu too small to be noted in the PEP—its not mentioned in the documentation, but the uu decode function is also called to decode uuencoded attachments of (ancient, pre-MIME) emails, so a DeprecationWarning and docs note can be added there as well, to identify any unexpected user impacts.

That's a question for @warsaw and the @python/email-team as to how they want to handle that. I ported the old uu code over to the email package using binascii to keep the functionality: 407c3af .

Is there something specific I need to do to apply for/justify an exception on this, or do we just wait for Pablo to respond here?

You request a review from him on the PR.

[CAM-Gerlach]

That's a question for @warsaw and the https://github.com/orgs/python/teams/email-team as to how they want to handle that. I ported the old uu code over to the email package using binascii to keep the functionality: 407c3af .

Right, but per the approved text of the PEP, those binascii functions were also deprecated and slated for removal. Fortunately, this functionality was only actually used for one specific method of the legacy email.message.Message API using the compat32 policy, and only when the non-default decode=True argument was passed (which was dropped in the modern email.message.EmailMessage API), and not used anywhere else.

In any case, I've pinged @warsaw and the email team on the PEP and requested them for review, get their feedback on that approach and any alternatives.

You request a review from him on the PR.

Done, thanks.

[brettcannon]

Right, but per the approved text of the PEP, those binascii functions were also deprecated and slated for removal.

Sure, but we can also roll that decision back if it turns out the support in the email package is important for some reason (I don't know emails well enough to know if uuencoded attachments is a critical feature).

[vadmium]

Is binascii.b2a_uu deprecated? If so, it would be nice to see this when reading the documentation. I recently wrote a script that will use it, without being aware of this push for deprecation. The PEP does not say any binascii functions will be deprecated; it only mentions deprecating the uu module, and encodings/uu_codec.py.

[hugovk]

It's not yet formally deprecated.

#92758 plans to add docs and deprecation warnings, but it's been open for nearly two years...

If it is merged before May (in Python 3.13) then it could he removed in October 2026 (in 3.15).

[brettcannon]

@warsaw should we move forward w/ this deprecation or drop it?