GeezerVison

Do we want to support unreasonable wrapcol values? Values that are not multiples of 4 really do not make sense and feel unlikely to be used for any practical use of base64. As do low values such as 1-3. (small values are inefficient with our post-processing implementation anyways)

Do we know of any practical actual need for odd-multiple wrapping?

If we restrict the allowed wrappings to start with, we could open them up wider later if anyone has a need. I doubt there is demand for such strange for base64's use case wrapping sizes.

Odd-wrapping: 4n - 1 to really have a space on the right if there is a hard wrap at 4n. Only for rendering purposes I'd say and likely not useful. But 4n - 2 may also be an option. Or odd-wrapping could be useful.

More generally, email's policy allows to specify its own max line length and we currently have: "maxlen = policy.max_line_length or sys.maxsize". So it's important to support all inputs. However, we can specialize the case sys.maxsize to be equivalent to "no wrapping".

I considered this. We can round wrapcol down to the multiplier of 4 and set some minimal non-zero limit. plistlib does this, with the minimum 16. a85encode() sets the limit to 2 if adobe=True. quopri also needs some minimum (not less than 3, plus an escaped newline).

For Base 4 the reason can be that some third-party decoders can not support groups split between lines. See also #76672. But I am not sure whether we should force this or left on the user responsibility? What should we do for values from 1 to 3? Raise an exception? Round up to 4?

For 1, 2, 3, if it's not efficient, then so be it. It's the user responsibility at this point. For 1, it's the same as having no wrap and then put \n in between each values. So they could just do their own b"\n.".join(list(encode(s))) in this case which may be faster than encode(s, wrapcol=1). For 2-3, if it works but is not efficient, just leave it as is I guess (though the case n=2 may be interesting and we could try to optimize it, but I don't think people really want to group b64 encoded content by 2; the number of lines is likely to be too large to be visually interesting).

noone will intentionally pass such pointless tiny values anyways - it is our choice if we bother to disallow them or not. if we do not I'd suggest a ValueError rather than rounding up so that anyone with an actual need (prediction: nobody) can come file a bug explaining why.

a85encode(data, adobe=True, wrapcol=1) wraps the output in lines of length 2, so <~ and ~> will not split.

I would put this before the 'May assert' line. Same applies to the other cases.

Done. But does not it create a contradiction in the binascii module?

I'm not sure what you mean? I thought I was just rewording your documentation to use the imperative mode like the first sentence. Or did I get it wrong? Does it add a final newline if wrapcol is 0? In which case it would be "if wrapcol is zero (default), add a single trailing newline."

It adds a final newline if newline is true (default), independently from wrapcol.

Of course, wrapcol is a new parameter, and we can change its behavior. But there are use cases for all 4 variants, so it is better to make these parameters orthogonal.

It sounds like my rephrasing was correct then? Or maybe "do not insert any newlines"?

I don't know, I only ask if that does not look weird in English. In one paragraph, "do not add any newlines", in the next paragraph -- "a newline character will be added at the end of the output".

But they are different paragraphs, and the latter specifically mention "at the end of the output", so this may be okay. If you don't see a problem, there is no problem.

Ah, I see what you mean now. Yes, I would change it from 'do not add any newlines' to 'do not insert any newlines'. That should keep it distinct from the 'add' in the next paragraph.