mailbox: document Message vs EmailMessage situation

Aberta
#96,425 0 comentários 1 reação 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
3/5
Tempo estimado
1-2 dias
Facilidade para iniciantes
48/100
Tipo de issue
Documentação
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
python
Domínio
documentation

Direção de pesquisa

Comece pela documentação do módulo mailbox e compare suas referências a email.Message com a documentação do pacote email sobre EmailMessage e a compat32 API. Revise a relação entre mailbox.Message, email.Message e email.message.EmailMessage e, em seguida, esclareça suas funções e o status da migração na documentação de mailbox. Considera-se concluído quando a documentação explicar qual classe as aplicações devem usar e por que mailbox ainda expõe a hierarquia legada.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

docs

Documentation

If I read the email documentation, it makes a clear case for staying away from email.Message:

The foregoing represent the modern (unicode friendly) API of the email package. The remaining sections, starting with the Message class, cover the legacy compat32 API that deals much more directly with the details of how email messages are represented. The compat32 API does not hide the details of the RFCs from the application, but for applications that need to operate at that level, they can be useful tools. This documentation is also relevant for applications that are still using the compat32 API for backward compatibility reasons.

Changed in version 3.6: Docs reorganized and rewritten to promote the new EmailMessage/EmailPolicy API.

And indeed, there are common tasks that are hard to do in email.Message and easy with EmailMessage (see get_body() for a very common use case).

However in the documentation of mailbox, email.Message is mentioned like it's the standard.

Since at the moment in the standard library, with regards to email handling, the rule "There should be one-- and preferably only one --obvious way to do it." seems to be violated, and there are several classes with confusingly similar names but very different roles (mailbox.Message, email.Message, email.message.EmailMessage) it would help to have a clarification of the situation in the documentation of mailbox, at least until #77156 happens.

I don't know enough of the background that led to this situation to be able to draft a serious proposal for the documentation, but I guess something along the lines of this could be an initial draft:

There are currently two distinct classes for handling emails: email.Message (deprecated), and email.message.EmailMessage. The latter is more featureful and easier to use, but the mailbox module still has not been updated to transition to it.
mailbox subclasses the deprecated email.Message as mailbox.Message, to act as the base hierarchy for messages read from mailboxes.
It is expected that mailbox.Message will become a subclass of email.message.EmailMessage in a future version of Python [insert API compatibility notes].

Linguagem predominante
Python
Estrelas
77.2k
Forks
36k
Merge médio
1d 9h
PRs com merge (30d)
558

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de python/cpython

Todas as issues de python/cpython

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.