From 5eb18c7f57a12565e6245d31b2e73d872c5ce603 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 23 Jan 2023 20:57:49 +0000 Subject: [PATCH 1/2] Clarify strategies --- lib/net/http.rb | 114 +++++++++++++++++++++++++----------------------- 1 file changed, 59 insertions(+), 55 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 551ec529..663bf3a6 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -34,67 +34,71 @@ class HTTPHeaderSyntaxError < StandardError; end # \Class \Net::HTTP provides a rich library that implements the client # in a client-server model that uses the \HTTP request-response protocol. - # For information about \HTTP, see + # For information about \HTTP, see: # # - {Hypertext Transfer Protocol}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol]. # - {Technical overview}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Technical_overview]. # - # Note: If you are performing only a few GET requests, consider using - # {OpenURI}[https://docs.ruby-lang.org/en/master/OpenURI.html]; - # otherwise, read on. - # - # == Synopsis - # - # If you are already familiar with \HTTP, this synopsis may be helpful. - # - # {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for - # {HTTP methods}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods]: - # - # Net::HTTP.start(hostname) do |http| - # # Session started automatically before block execution. - # http.get(path_or_uri, headers = {}) - # http.head(path_or_uri, headers = {}) - # http.post(path_or_uri, data, headers = {}) # Can also have a block. - # http.put(path_or_uri, data, headers = {}) - # http.delete(path_or_uri, headers = {Depth: 'Infinity'}) - # http.options(path_or_uri, headers = {}) - # http.trace(path_or_uri, headers = {}) - # http.patch(path_or_uri, data, headers = {}) # Can also have a block. - # # Session finished automatically at block exit. - # end - # - # {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for - # {WebDAV methods}[https://en.wikipedia.org/wiki/WebDAV#Implementation]: - # - # Net::HTTP.start(hostname) do |http| - # # Session started automatically before block execution. - # http.copy(path_or_uri, headers = {}) - # http.lock(path_or_uri, body, headers = {}) - # http.mkcol(path_or_uri, body = nil, headers = {}) - # http.move(path_or_uri, headers = {}) - # http.propfind(path_or_uri, body = nil, headers = {'Depth' => '0'}) - # http.proppatch(path_or_uri, body, headers = {}) - # http.unlock(path_or_uri, body, headers = {}) - # # Session finished automatically at block exit. - # end - # - # Each of the following methods automatically starts and finishes - # a {session}[rdoc-ref:Net::HTTP@Sessions] that sends a single request: - # - # # Return string response body. - # Net::HTTP.get(hostname, path, port = 80) - # Net::HTTP.get(uri, headers = {}, port = 80) + # == Strategies + # + # - If you will make only a few GET requests, + # consider using {OpenURI}[https://docs.ruby-lang.org/en/master/OpenURI.html]. + # - If performance is _not_ important, + # consider using various convenience methods in this class. + # Each of the following methods automatically starts and finishes + # a {session}[rdoc-ref:Net::HTTP@Sessions] that sends a single request: + # + # # Return string response body. + # Net::HTTP.get(hostname, path, port = 80) + # Net::HTTP.get(uri, headers = {}, port = 80) + # + # # Write string response body to $stdout. + # Net::HTTP.get_print(hostname, path_or_uri, port = 80) + # Net::HTTP.get_print(uri, headers = {}, port = 80) + # + # # Return response as Net::HTTPResponse object. + # Net::HTTP.get_response(hostname, path_or_uri, port = 80) + # Net::HTTP.get_response(uri, headers = {}, port = 80) + # Net::HTTP.post(uri, data, headers = {}) + # Net::HTTP.post_form(uri, params) + # + # - If performance _is_ important, consider using sessions, which lower request overhead: + # + # - {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for + # {HTTP methods}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods]: + # + # Net::HTTP.start(hostname) do |http| + # # Session started automatically before block execution. + # http.get(path_or_uri, headers = {}) + # http.head(path_or_uri, headers = {}) + # http.post(path_or_uri, body, headers = {}) # Can also have a block. + # http.put(path_or_uri, body, headers = {}) + # http.delete(path_or_uri, headers = {Depth: 'Infinity'}) + # http.options(path_or_uri, headers = {}) + # http.trace(path_or_uri, headers = {}) + # http.patch(path_or_uri, body, headers = {}) # Can also have a block. + # # Session finished automatically at block exit. + # end # - # # Write string response body to $stdout. - # Net::HTTP.get_print(hostname, path_or_uri, port = 80) - # Net::HTTP.get_print(uri, headers = {}, port = 80) + # - {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for + # {WebDAV methods}[https://en.wikipedia.org/wiki/WebDAV#Implementation]: + # + # Net::HTTP.start(hostname) do |http| + # # Session started automatically before block execution. + # http.copy(path_or_uri, headers = {}) + # http.lock(path_or_uri, body, headers = {}) + # http.mkcol(path_or_uri, body = nil, headers = {}) + # http.move(path_or_uri, headers = {}) + # http.propfind(path_or_uri, body = nil, headers = {'Depth' => '0'}) + # http.proppatch(path_or_uri, body, headers = {}) + # http.unlock(path_or_uri, body, headers = {}) + # # Session finished automatically at block exit. + # end # - # # Return response as Net::HTTPResponse object. - # Net::HTTP.get_response(hostname, path_or_uri, port = 80) - # Net::HTTP.get_response(uri, headers = {}, port = 80) + # The methods cited above are convenience methods that, via their few arguments, + # allow minimal control over the requests. + # For greater control, consider using {request objects}[rdoc-ref:Net::HTTPRequest]. # - # Net::HTTP.post(uri, data, headers = {}) - # Net::HTTP.post_form(uri, params) # # == About the Examples # @@ -183,7 +187,7 @@ class HTTPHeaderSyntaxError < StandardError; end # - May contain any number of requests. # - Is ended by instance method Net::HTTP#finish. # - # See example sessions at the {Synopsis}[rdoc-ref:Net::HTTP@Synopsis]. + # See example sessions at {Strategies}[rdoc-ref:Net::HTTP@Strategies]. # # === Session Using \Net::HTTP.start # From f745038bcae0bb12a00752ac6445ef60ba31ec10 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 24 Jan 2023 20:23:48 +0000 Subject: [PATCH 2/2] Clarify strategies --- lib/net/http.rb | 67 +++++++++++++++++++++---------------------------- 1 file changed, 29 insertions(+), 38 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 663bf3a6..270743e5 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -43,8 +43,8 @@ class HTTPHeaderSyntaxError < StandardError; end # # - If you will make only a few GET requests, # consider using {OpenURI}[https://docs.ruby-lang.org/en/master/OpenURI.html]. - # - If performance is _not_ important, - # consider using various convenience methods in this class. + # - If you will make only a few requests of all kinds, + # consider using the various singleton convenience methods in this class. # Each of the following methods automatically starts and finishes # a {session}[rdoc-ref:Net::HTTP@Sessions] that sends a single request: # @@ -62,43 +62,34 @@ class HTTPHeaderSyntaxError < StandardError; end # Net::HTTP.post(uri, data, headers = {}) # Net::HTTP.post_form(uri, params) # - # - If performance _is_ important, consider using sessions, which lower request overhead: - # - # - {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for - # {HTTP methods}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods]: - # - # Net::HTTP.start(hostname) do |http| - # # Session started automatically before block execution. - # http.get(path_or_uri, headers = {}) - # http.head(path_or_uri, headers = {}) - # http.post(path_or_uri, body, headers = {}) # Can also have a block. - # http.put(path_or_uri, body, headers = {}) - # http.delete(path_or_uri, headers = {Depth: 'Infinity'}) - # http.options(path_or_uri, headers = {}) - # http.trace(path_or_uri, headers = {}) - # http.patch(path_or_uri, body, headers = {}) # Can also have a block. - # # Session finished automatically at block exit. - # end - # - # - {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for - # {WebDAV methods}[https://en.wikipedia.org/wiki/WebDAV#Implementation]: - # - # Net::HTTP.start(hostname) do |http| - # # Session started automatically before block execution. - # http.copy(path_or_uri, headers = {}) - # http.lock(path_or_uri, body, headers = {}) - # http.mkcol(path_or_uri, body = nil, headers = {}) - # http.move(path_or_uri, headers = {}) - # http.propfind(path_or_uri, body = nil, headers = {'Depth' => '0'}) - # http.proppatch(path_or_uri, body, headers = {}) - # http.unlock(path_or_uri, body, headers = {}) - # # Session finished automatically at block exit. - # end - # - # The methods cited above are convenience methods that, via their few arguments, - # allow minimal control over the requests. - # For greater control, consider using {request objects}[rdoc-ref:Net::HTTPRequest]. + # - If performance is important, consider using sessions, which lower request overhead. + # This {session}[rdoc-ref:Net::HTTP@Sessions] has multiple requests for + # {HTTP methods}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods] + # and {WebDAV methods}[https://en.wikipedia.org/wiki/WebDAV#Implementation]: + # + # Net::HTTP.start(hostname) do |http| + # # Session started automatically before block execution. + # http.get(path_or_uri, headers = {}) + # http.head(path_or_uri, headers = {}) + # http.post(path_or_uri, body, headers = {}) # Can also have a block. + # http.put(path_or_uri, body, headers = {}) + # http.delete(path_or_uri, headers = {Depth: 'Infinity'}) + # http.options(path_or_uri, headers = {}) + # http.trace(path_or_uri, headers = {}) + # http.patch(path_or_uri, body, headers = {}) # Can also have a block. + # http.copy(path_or_uri, headers = {}) + # http.lock(path_or_uri, body, headers = {}) + # http.mkcol(path_or_uri, body = nil, headers = {}) + # http.move(path_or_uri, headers = {}) + # http.propfind(path_or_uri, body = nil, headers = {'Depth' => '0'}) + # http.proppatch(path_or_uri, body, headers = {}) + # http.unlock(path_or_uri, body, headers = {}) + # # Session finished automatically at block exit. + # end # + # The methods cited above are convenience methods that, via their few arguments, + # allow minimal control over the requests. + # For greater control, consider using {request objects}[rdoc-ref:Net::HTTPRequest]. # # == About the Examples #