class Patron::Session

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

Attributes

auth_type[RW]

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

base_url[RW]

Prepended to the URL in all requests.

buffer_size[RW]

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

connect_timeout[RW]

HTTP connection timeout in seconds. Defaults to 1 second.

default_response_charset[RW]

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

headers[R]

Standard set of headers that are used in all requests.

ignore_content_length[RW]

Does this session ignore Content-Size headers?

insecure[RW]

Does this session stricly verify SSL certificates?

max_redirects[RW]

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

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.

timeout[RW]

HTTP transaction timeout in seconds. Defaults to 5 seconds.

username[RW]

Username and password for http authentication

Public Class Methods

new() click to toggle source

Create a new Session object.

# File lib/patron/session.rb, line 84
def initialize
  @headers = {}
  @timeout = 5
  @connect_timeout = 1
  @max_redirects = 5
  @auth_type = :basic
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
def copy(url, dest, headers = {})
  headers['Destination'] = dest
  request(:copy, url, headers)
end
delete(url, headers = {}) click to toggle source

As get but sends an HTTP DELETE request.

# File lib/patron/session.rb, line 141
def delete(url, headers = {})
  request(:delete, url, headers)
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
def enable_debug(file = nil)
  set_debug_file(file.to_s)
end
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 request method.

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

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

# File lib/patron/session.rb, line 131
def get_file(url, filename, headers = {})
  request(:get, url, headers, :file => filename)
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
def handle_cookies(file = nil)
  if file
    path = Pathname(file).expand_path
    unless File.exists?(file) and File.writable?(path.dirname)
      raise ArgumentError, "Can't create file #{path} (permission error)"
    end
    unless File.readable?(file) or File.writable?(path)
      raise ArgumentError, "Can't read or write file #{path} (permission error)"
    end
  end
  enable_cookie_session(path.to_s)
  self
end
head(url, headers = {}) click to toggle source

As get but sends an HTTP HEAD request.

# File lib/patron/session.rb, line 136
def head(url, headers = {})
  request(:head, url, headers)
end
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
def post(url, data, headers = {})
  if data.is_a?(Hash)
    data = data.map {|k,v| urlencode(k.to_s) + '=' + urlencode(v.to_s) }.join('&')
    headers['Content-Type'] = 'application/x-www-form-urlencoded'
  end
  request(:post, url, headers, :data => data)
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
def post_file(url, filename, headers = {})
  request(:post, url, headers, :file => filename)
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
def post_multipart(url, data, filename, headers = {})
  request(:post, url, headers, {:data => data, :file => filename, :multipart => true})
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
def put(url, data, headers = {})
  request(:put, url, headers, :data => data)
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
def put_file(url, filename, headers = {})
  request(:put, url, headers, :file => filename)
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
def request(action, url, headers, options = {})
  # If the Expect header isn't set uploads are really slow
  headers['Expect'] ||= ''

  req = Request.new
  req.action                 = action
  req.headers                = self.headers.merge headers
  req.timeout                = options.fetch :timeout,               self.timeout
  req.connect_timeout        = options.fetch :connect_timeout,       self.connect_timeout
  req.max_redirects          = options.fetch :max_redirects,         self.max_redirects
  req.username               = options.fetch :username,              self.username
  req.password               = options.fetch :password,              self.password
  req.proxy                  = options.fetch :proxy,                 self.proxy
  req.proxy_type             = options.fetch :proxy_type,            self.proxy_type
  req.auth_type              = options.fetch :auth_type,             self.auth_type
  req.insecure               = options.fetch :insecure,              self.insecure
  req.ignore_content_length  = options.fetch :ignore_content_length, self.ignore_content_length
  req.buffer_size            = options.fetch :buffer_size,           self.buffer_size
  req.multipart              = options[:multipart]
  req.upload_data            = options[:data]
  req.file_name              = options[:file]

  url = self.base_url.to_s + url.to_s
  uri = URI.parse(url)
  query = uri.query.to_s.split('&')
  query += options[:query].is_a?(Hash) ? Util.build_query_pairs_from_hash(options[:query]) : options[:query].to_s.split('&')
  uri.query = query.join('&')
  uri.query = nil if uri.query.empty?
  url = uri.to_s
  raise ArgumentError, "Empty URL" if url.empty?
  req.url = url

  handle_request(req)
end