Merge pull request twisted#1205 from twisted/9742-contentdecoderagent…

…-docs Author: twm Reviewer: rodrigc Fixes: ticket:9742 Improve ContentDecoderAgent docs
ryanpetrello · Mar 28, 2020 · 40c5235 · 40c5235
2 parents 3035efc + f74b712
commit 40c5235
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 7 deletions.
diff --git a/src/twisted/web/client.py b/src/twisted/web/client.py
@@ -2035,16 +2035,27 @@ class ContentDecoderAgent(object):
     An L{Agent} wrapper to handle encoded content.
 
     It takes care of declaring the support for content in the
-    I{Accept-Encoding} header, and automatically decompresses the received data
-    if it's effectively using compression.
+    I{Accept-Encoding} header and automatically decompresses the received data
+    if the I{Content-Encoding} header indicates a supported encoding.
 
-    @param decoders: A list or tuple of (name, decoder) objects. The name
-        declares which decoding the decoder supports, and the decoder must
-        return a response object when called/instantiated. For example,
-        C{(('gzip', GzipDecoder))}. The order determines how the decoders are
-        going to be advertized to the server.
+    For example::
+
+        agent = ContentDecoderAgent(Agent(reactor),
+                                    [(b'gzip', GzipDecoder)])
+
+    @param agent: The agent to wrap
+    @type agent: L{IAgent}
+
+    @param decoders: A sequence of (name, decoder) objects. The name
+        declares which encoding the decoder supports. The decoder must accept
+        an L{IResponse} and return an L{IResponse} when called. The order
+        determines how the decoders are advertised to the server. Names must
+        be unique.not be duplicated.
+    @type decoders: sequence of (L{bytes}, L{callable}) tuples
 
     @since: 11.1
+
+    @see: L{GzipDecoder}
     """
 
     def __init__(self, agent, decoders):

diff --git a/src/twisted/web/newsfragments/9742.doc b/src/twisted/web/newsfragments/9742.doc
@@ -0,0 +1 @@
+twisted.web.client.ContentDecoderAgent's documentation has been corrected and improved.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		twisted.web.client.ContentDecoderAgent's documentation has been corrected and improved.