Parent

Files

Patron::Session

This class represents multiple request/response transactions with an HTTP server. This is the primary API for Patron.

Attributes

connect_timeout[RW]

HTTP connection timeout in seconds. Defaults to 1 second.

timeout[RW]

HTTP transaction timeout in seconds. Defaults to 5 seconds.

max_redirects[RW]

Maximum number of times to follow redirects. Set to 0 to disable and -1 to follow all redirects. Defaults to 5.

base_url[RW]

Prepended to the URL in all requests.

username[RW]

Username and password for http authentication

password[RW]

Username and password for http authentication

proxy[RW]

Proxy URL in cURL format (‘hostname:8080’)

proxy_type[RW]

Proxy type (default is HTTP), see constants under ProxyType for supported types.

headers[R]

Standard set of headers that are used in all requests.

auth_type[RW]

Set the authentication type for the request. @see Patron::Request#auth_type

insecure[RW]

Does this session stricly verify SSL certificates?

ignore_content_length[RW]

Does this session ignore Content-Size headers?

buffer_size[RW]

Set the buffer size for this request. This option will only be set if buffer_size is non-nil

default_response_charset[RW]

Default encoding of responses. Used if no charset is provided by the host.

Public Class Methods

new() click to toggle source

Create a new Session object.

    # File lib/patron/session.rb, line 84
84:     def initialize
85:       @headers = {}
86:       @timeout = 5
87:       @connect_timeout = 1
88:       @max_redirects = 5
89:       @auth_type = :basic
90:     end

Public Instance Methods

copy(url, dest, headers = {}) click to toggle source

Sends a WebDAV COPY request to the specified url.

     # File lib/patron/session.rb, line 181
181:     def copy(url, dest, headers = {})
182:       headers['Destination'] = dest
183:       request(:copy, url, headers)
184:     end
delete(url, headers = {}) click to toggle source

As # but sends an HTTP DELETE request.

     # File lib/patron/session.rb, line 141
141:     def delete(url, headers = {})
142:       request(:delete, url, headers)
143:     end
enable_debug(file = nil) click to toggle source

Enable debug output to stderr or to specified file.

     # File lib/patron/session.rb, line 110
110:     def enable_debug(file = nil)
111:       set_debug_file(file.to_s)
112:     end
escape( string ) → escaped string click to toggle source

URL escapes the provided string.

static VALUE session_escape(VALUE self, VALUE value) 
Also aliased as: urlencode
get(url, headers = {}) click to toggle source

Retrieve the contents of the specified url optionally sending the specified headers. If the base_url varaible is set then it is prepended to the url parameter. Any custom headers are merged with the contents of the headers instance variable. The results are returned in a Response object. Notice: this method doesn’t accept any data argument: if you need to send data with a get request, please, use the # method.

     # File lib/patron/session.rb, line 125
125:     def get(url, headers = {})
126:       request(:get, url, headers)
127:     end
get_file(url, filename, headers = {}) click to toggle source

Retrieve the contents of the specified url as with #, but the content at the URL is downloaded directly into the specified file.

     # File lib/patron/session.rb, line 131
131:     def get_file(url, filename, headers = {})
132:       request(:get, url, headers, :file => filename)
133:     end
handle_cookies(file = nil) click to toggle source

Turn on cookie handling for this session, storing them in memory by default or in file if specified. The file must be readable and writable. Calling multiple times will add more files.

     # File lib/patron/session.rb, line 95
 95:     def handle_cookies(file = nil)
 96:       if file
 97:         path = Pathname(file).expand_path
 98:         unless File.exists?(file) and File.writable?(path.dirname)
 99:           raise ArgumentError, "Can't create file #{path} (permission error)"
100:         end
101:         unless File.readable?(file) or File.writable?(path)
102:           raise ArgumentError, "Can't read or write file #{path} (permission error)"
103:         end
104:       end
105:       enable_cookie_session(path.to_s)
106:       self
107:     end
handle_request( request ) → response click to toggle source

Peform the actual HTTP request by calling libcurl. Each filed in the request object will be used to set the appropriate option on the libcurl library. After the request completes, a Response object will be created and returned.

In the event of an error in the libcurl library, a Ruby exception will be created and raised. The exception will return the libcurl error code and error message.

static VALUE session_handle_request(VALUE self, VALUE request) 
head(url, headers = {}) click to toggle source

As # but sends an HTTP HEAD request.

     # File lib/patron/session.rb, line 136
136:     def head(url, headers = {})
137:       request(:head, url, headers)
138:     end
interrupt → session click to toggle source

Interrupt any currently executing request. This will cause the current request to error and raise an exception.

static VALUE session_interrupt(VALUE self) 
post(url, data, headers = {}) click to toggle source

Uploads the passed data to the specified url using HTTP POST. data can be a string or a hash.

     # File lib/patron/session.rb, line 158
158:     def post(url, data, headers = {})
159:       if data.is_a?(Hash)
160:         data = data.map {|k,v| urlencode(k.to_s) + '=' + urlencode(v.to_s) }.join('&')
161:         headers['Content-Type'] = 'application/x-www-form-urlencoded'
162:       end
163:       request(:post, url, headers, :data => data)
164:     end
post_file(url, filename, headers = {}) click to toggle source

Uploads the contents of a file to the specified url using HTTP POST.

     # File lib/patron/session.rb, line 167
167:     def post_file(url, filename, headers = {})
168:       request(:post, url, headers, :file => filename)
169:     end
post_multipart(url, data, filename, headers = {}) click to toggle source

Uploads the contents of a file and data to the specified url using HTTP POST.

     # File lib/patron/session.rb, line 172
172:     def post_multipart(url, data, filename, headers = {})
173:       request(:post, url, headers, {:data => data, :file => filename, :multipart => true})
174:     end
put(url, data, headers = {}) click to toggle source

Uploads the passed data to the specified url using HTTP PUT. data must be a string.

     # File lib/patron/session.rb, line 147
147:     def put(url, data, headers = {})
148:       request(:put, url, headers, :data => data)
149:     end
put_file(url, filename, headers = {}) click to toggle source

Uploads the contents of a file to the specified url using HTTP PUT.

     # File lib/patron/session.rb, line 152
152:     def put_file(url, filename, headers = {})
153:       request(:put, url, headers, :file => filename)
154:     end
request(action, url, headers, options = {}) click to toggle source

Send an HTTP request to the specified url.

     # File lib/patron/session.rb, line 191
191:     def request(action, url, headers, options = {})
192:       # If the Expect header isn't set uploads are really slow
193:       headers['Expect'] ||= ''
194: 
195:       req = Request.new
196:       req.action                 = action
197:       req.headers                = self.headers.merge headers
198:       req.timeout                = options.fetch :timeout,               self.timeout
199:       req.connect_timeout        = options.fetch :connect_timeout,       self.connect_timeout
200:       req.max_redirects          = options.fetch :max_redirects,         self.max_redirects
201:       req.username               = options.fetch :username,              self.username
202:       req.password               = options.fetch :password,              self.password
203:       req.proxy                  = options.fetch :proxy,                 self.proxy
204:       req.proxy_type             = options.fetch :proxy_type,            self.proxy_type
205:       req.auth_type              = options.fetch :auth_type,             self.auth_type
206:       req.insecure               = options.fetch :insecure,              self.insecure
207:       req.ignore_content_length  = options.fetch :ignore_content_length, self.ignore_content_length
208:       req.buffer_size            = options.fetch :buffer_size,           self.buffer_size
209:       req.multipart              = options[:multipart]
210:       req.upload_data            = options[:data]
211:       req.file_name              = options[:file]
212: 
213:       url = self.base_url.to_s + url.to_s
214:       uri = URI.parse(url)
215:       query = uri.query.to_s.split('&')
216:       query += options[:query].is_a?(Hash) ? Util.build_query_pairs_from_hash(options[:query]) : options[:query].to_s.split('&')
217:       uri.query = query.join('&')
218:       uri.query = nil if uri.query.empty?
219:       url = uri.to_s
220:       raise ArgumentError, "Empty URL" if url.empty?
221:       req.url = url
222: 
223:       handle_request(req)
224:     end
reset → session click to toggle source

Reset the underlying cURL session. This effectively closes all open connections and disables debug output.

static VALUE session_reset(VALUE self) 
set_debug_file( file ) → session click to toggle source

Enable debug output to stderr or to specified file.

static VALUE set_debug_file(VALUE self, VALUE file) 
unescape( string ) → unescaped string click to toggle source

Unescapes the provided string.

static VALUE session_unescape(VALUE self, VALUE value) 
Also aliased as: urldecode
urldecode(p1) click to toggle source
Alias for: unescape
urlencode(p1) click to toggle source
Alias for: escape

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.