The location of the get_connection() function does not correspond with the documentation

[caumons]

If we try to import the get_connection() function from django.core.mail as specified in the documentation we get the following ImportError in Django 1.1.1:

Python 2.6.4 (r264:75706, Dec  7 2009, 18:43:55) 
[GCC 4.4.1] on linux2
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from django.core.mail import get_connection
Traceback (most recent call last):
  File "<console>", line 1, in <module>
ImportError: cannot import name get_connection

Looking at the source code of the module situated at /usr/local/lib/python2.6/dist-packages/django/core/mail.py we can check that no get_connection() is declared in the module.
If we want to create a connection to send emails, we have to instantiate the SMTPConnection class and then call its methods. For example:

mailConnection = SMTPConnection()
mailConnection.open()
mailConnection.send_messages([email1, email2])
mailConnection.close()

get_connection(self, fail_silently=False) is a method inside the EmailMessage class situated in line 228 and used in line 266, not a function.

The solution I see is to update the documentation referring to emails section.

[Karen Tracey]

Fixed formatting; please use preview.

You seem to be looking at the doc for Django 1.2 (or current trunk) while using Django 1.1.1. get_connection is mentioned under the doc for email backends, which is flagged as new in 1.2: ​http://docs.djangoproject.com/en/dev/topics/email/#e-mail-backends. This function does exist in Django 1.2:

>>> import django
>>> django.get_version()
'1.2.1'
>>> from django.core.mail import get_connection
>>>

django.core.mail.get_connection did not exist in 1.1 and is not mentioned in the 1.1 version of the doc (​http://docs.djangoproject.com/en/1.1/topics/email/).

[caumons]

Yes, I was looking at the Django 1.2 documentation and therefore I thought that the code did not match the documentation. However, I think that it is not enough clear which part is exactly a new feature for the new 1.2 version because the note is very tinny and a little difficult to know which features affect. Another developer also did not see a note like this in the template syntax part (with the new smart ifs) and confused him. So I propose to make this notes more visible.