#17307 - merge from 3.2

diff --cc Doc/library/http.client.rst
index 5599dac187b039271bdd283a344704891a9b868c,408a3e7bb0fc873f8f0e5e85b1404dc122b1accf..2d93aa47c3868b2b34d1f7ccca38d5f254d982e0
--- 1/Doc/library/http.client.rst
--- 2/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@@ -633,6 -612,22 +633,24 @@@ Here is an example session that shows h
     b'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
     >>> conn.close()
  
 -be created via ``PUT`` request. Here is an example session that shows how to do
 -``PUT`` request using http.client::
+ Client side ``HTTP PUT`` requests are very similar to ``POST`` requests. The
+ difference lies only the server side where HTTP server will allow resources to
++be created via ``PUT`` request. It should be noted that custom HTTP methods
+++are also handled in :class:`urllib.request.Request` by sending the appropriate
+++method attribute.Here is an example session that shows how to do ``PUT``
++request using http.client::
+ 
+     >>> # 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 = "***filecontents***"
+     >>> conn = http.client.HTTPConnection("localhost", 8080)
+     >>> conn.request("PUT", "/file", BODY)
+     >>> response = conn.getresponse()
+     >>> print(resp.status, response.reason)
+     200, OK
  
  .. _httpmessage-objects:
  

diff --cc Doc/library/urllib.request.rst
index 505f738e3c46cf75439c5b492d5e366f29383aa6,33244daf6ec2fa1d63ebcb0ed2e56a202adbdbae..2cf1304536845e14c18012efbf4e8b1f4c3ad31e
--- 1/Doc/library/urllib.request.rst
--- 2/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@@ -1109,6 -1044,6 +1109,15 @@@ The code for the sample CGI used in th
     data = sys.stdin.read()
     print('Content-type: text-plain\n\nGot Data: "%s"' % data)
  
++Here is an example of doing a ``PUT`` request using :class:`Request`::
++
++    import urllib.request
++    DATA=b'some data'
++    req = urllib.request.Request(url='http://localhost:8080', data=DATA,method='PUT')
++    f = urllib.request.urlopen(req)
++    print(f.status)
++    print(f.reason)
++
  Use of Basic HTTP Authentication::
  
     import urllib.request