I think an explicit HTTP put request example in the docs may help. Previously, I thought the POST example was enough as PUT is very similar, but given the folks are looking for it, an example of how to do a PUT request using httplib may be helpful.

Here is patch attached for review.

Shouldn't that be done with urllib?

Ezio. yes in 3.3 onwards it should be done in urllib.request. I was having 2.7 docs in my mind, but I ended up writing for latest with the intention to backport. I have updated the patch to include both ways, while backporting to 2.7 and 3.2, plan to include only the httplib ones.

Sentil:

About the PUT/POST, I would say:

    A POST and PUT methods differs only by the 
    intent of the enclosed representation. In the 
    case of a POST, the target resource (URI) on 
    the server decides what is the meaning of the 
    enclosed representation in the POST request.
    In a PUT request, the enclosed representation 
    is meant to replace the state of the target 
    resource (URI) on the server.
    It is why PUT is idempotent.

About the code:

* http.client
I would remove the following comment, because the term "file" is confusing in HTTP terms.

   # This will create a resource file with contents of BODY

or I would say more exactly


   # This creates an HTTP message 
   # with the content of BODY as the enclosed representation 
   # for the resource http://localhost:8080/foobar

   >>> import http.client
   >>> BODY = "Some data"
   >>> conn = http.client.HTTPConnection("localhost", 8080)
   >>> conn.request("PUT", "/foobar", BODY) # The actual PUT Request
   >>> response = conn.getresponse()
   >>> print(resp.status, response.reason)

Maybe it would be good to display the message which is sent so people can understand what goes on the wire.

* urllib
the client code for urllib doesn't create challenge, I would had a content-type but no hard feeling about it. On the other hand the server code makes me a bit uncomfortable. It sets people into believing that this is the way you should reply to a PUT which is not really the case.

1. If the resource was not existing and has been successfully created, the server MUST answer 204.
2. if the resource already exists and has been successfully replaced/modified, then the server SHOULD answer either 200 or 204 (depending on the design choice)

There are plenty of other cases depending on the constraints.  See for the details http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-22#section-4.3.4

If we keep the server code, I would be willing to have a note saying that it is not usable as-is in production code. 

Does that make sense? :)

Karl, I am getting back to this. Thanks for your review comments on the patch.

1. Agree with your explanation on HTTP PUT. I shall modify the comment.
2. I think, it is okay to remove the HTTP PUT server example. I wrote it for test purposes and I think, it is a good idea to publish the test servers in the python docs.

New changeset 4edde40afee6 by Senthil Kumaran in branch '2.7':
#17307 - Example of HTTP PUT Request using httplib
http://hg.python.org/cpython/rev/4edde40afee6

New changeset d4ab6556ff97 by Senthil Kumaran in branch '3.2':
#17307 - Example of HTTP PUT Request using http.client
http://hg.python.org/cpython/rev/d4ab6556ff97

New changeset 9941a9bbfeb6 by Senthil Kumaran in branch '3.3':
#17307 - merge from 3.2
http://hg.python.org/cpython/rev/9941a9bbfeb6

New changeset 57e5409a998e by Senthil Kumaran in branch 'default':
#17307 - merge from 3.3
http://hg.python.org/cpython/rev/57e5409a998e

Thanks for the review, Karl. Made the doc changes in all codelines.