smtplib documentation fixes (GH-8708)
* SMTP.startssl: Fix doc on keyfile and certfile use
* SMTP.startssl: Add missing keyfile and certfile deprecation notice
* SMTP: Doc grammar fixes
(cherry picked from commit da12063f2f53b7d272824863ed24260cefb22e8c)
Co-authored-by: Ville Skyttä <ville.skytta@iki.fi>
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index 86e769e..e5effd0 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -271,7 +271,7 @@
.. method:: SMTP.ehlo_or_helo_if_needed()
- This method call :meth:`ehlo` and or :meth:`helo` if there has been no
+ This method calls :meth:`ehlo` and/or :meth:`helo` if there has been no
previous ``EHLO`` or ``HELO`` command this session. It tries ESMTP ``EHLO``
first.
@@ -379,16 +379,23 @@
commands that follow will be encrypted. You should then call :meth:`ehlo`
again.
- If *keyfile* and *certfile* are provided, these are passed to the :mod:`socket`
- module's :func:`ssl` function.
+ If *keyfile* and *certfile* are provided, they are used to create an
+ :class:`ssl.SSLContext`.
- Optional *context* parameter is a :class:`ssl.SSLContext` object; This is
+ Optional *context* parameter is an :class:`ssl.SSLContext` object; This is
an alternative to using a keyfile and a certfile and if specified both
*keyfile* and *certfile* should be ``None``.
If there has been no previous ``EHLO`` or ``HELO`` command this session,
this method tries ESMTP ``EHLO`` first.
+ .. deprecated:: 3.6
+
+ *keyfile* and *certfile* are deprecated in favor of *context*.
+ Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+ :func:`ssl.create_default_context` select the system's trusted CA
+ certificates for you.
+
:exc:`SMTPHeloError`
The server didn't reply properly to the ``HELO`` greeting.