Document IMAP4.append() message type and optional arguments
Nadie ha tomado este issue todavía.
- Lenguaje dominante
- Python
- Estrellas
- 77.2k
- Forks
- 35.9k
- Métricas de merge de PR
- Métricas de PR pendientes
Descripción
The IMAP4.append() documentation currently says only:
Append message to named mailbox.
It now documents the flags argument, but the remaining argument behavior is still easier to discover from Lib/imaplib.py than from the library docs.
In the implementation:
mailboxis treated as optional in practice: a false value is replaced with'INBOX'.flagsanddate_timemay beNone, in which case they are omitted from the command.messageis not optional. It is passed toMapCRLF.sub(CRLF, message), whereMapCRLFis a bytes regular expression, somessagemust be a bytes-like object. Passing astrraisesTypeErrorbefore the command is sent.
The method docstring already hints at this by saying "All args except 'message' can be None", but that detail is not in Doc/library/imaplib.rst.
This is related to the broader documentation issue in #68215, but this issue is intentionally narrower: clarify the public documentation for IMAP4.append() only.
Suggested documentation scope:
- State that message must be a bytes-like object.
- State which arguments may be
None. - Clarify that
mailbox=None(or another false value) usesINBOX. - Clarify that
date_time=Noneomits the internal date argument.
This should stay separate from the existing CR/LF-normalization behavior tracked in #49680.
Linked PRs
- gh-149964
Guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Línea de trabajo
Abre Doc/library/imaplib.rst y localiza la documentación pública de IMAP4.append(). Actualízala para cubrir el requisito de que el mensaje sea de tipo bytes-like, qué argumentos pueden ser None, que los valores falsy del buzón toman INBOX por defecto y que date_time=None omite el argumento de fecha interna; el PR enlazado indica que este trabajo ya está en curso.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- python
- Área
- documentation
- Tipo de issue
- Documentación
- Dificultad
- 1/5
- Tiempo estimado
- Menos de una hora
- Estado de actividad
- Estancado
- Claridad
- Bien especificado
- Aptitud para principiantes
- 25/100