I am trying to create an email address as in the Python doc example 
https://docs.python.org/3/library/email-examples.html

The example does not work as given on the page.

I tried Python 3.4rc1 and the 3.5 compiled from source on Ubuntu 12.

I found two possible reasons:

1) Python bug in headerregistry.py
The string resulting from the command below contains extra quotes:

str(Address('Foo Example', 'foo@example.com'))
--> 'Foo Example <"foo@example.com">'


2) Documentation bug

The documentation of headerregistry.Address states:

"username and domain may be specified together by using 
the addr_spec keyword *instead of* the username and domain keywords"

However, this is inconsistent with example 19.1.14.1. on
https://docs.python.org/3/library/email-examples.html

Attached are two tests that reproduce the situation.
The first test below fails but the second passes.

Conclusion:
In my opinion, it is more intuitive if the following would work as well:
Address('Foo Example', 'foo@example.com')

That example is wrong, but that fact weighs heavily in favor of the idea that the "natural" way to write it is the way it is in the example.

Since this part of the email api is still provisional, I propose we change the signature of Address to be:

  Address(display_name='', addr_spec=None, *, username='', domain='')

and make it a ValueError to specify both addr_spec and one or both of username and domain.  For 3.5 I'd just make that change, but for 3.4 I'd make a backward compatibility check and deprecation warning looking for an '@' in the second argument and treat it as username if there's no @ and an addr_spec if there is.