Class: Patron::Session

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

Attributes

Instance Attributes

auth_type	[RW]	public	Set the authentication type for the request.
base_url	[RW]	public	Prepended to the URL in all requests.
connect_timeout	[RW]	public	HTTP connection timeout in milliseconds.
headers	[R]	public	Standard set of headers that are used in all requests.
insecure	[RW]	public	Does this session stricly verify SSL certificates?.
max_redirects	[RW]	public	Maximum number of times to follow redirects.
password	[RW]	public	Username and password for http authentication.
proxy	[RW]	public	HTTP proxy URL.
timeout	[RW]	public	HTTP transaction timeout in seconds.
username	[RW]	public	Username and password for http authentication.

Constructor Summary

public initialize

Create a new Session object.

[View source]

    
69
70
71
72
73
74
75
76
        
          # File 'lib/patron/session.rb', line 69

def initialize
  ext_initialize
  @headers = {}
  @timeout = 5
  @connect_timeout = 1000
  @max_redirects = -1
  @auth_type = :basic
end

Public Visibility

Public Instance Method Summary

#copy(url, dest, headers = {})	WebDAV methods.
#delete(url, headers = {})	As #get but sends an HTTP DELETE request.
#get(url, headers = {})	Standard HTTP methods.
#get_file(url, filename, headers = {})	Retrieve the contents of the specified `url` as with #get, but the content at the URL is downloaded directly into the specified file.
#handle_cookies(file = nil)	Makes this session handle cookies and store them in in `file`.
#head(url, headers = {})	As #get but sends an HTTP HEAD request.
#post(url, data, headers = {})	Uploads the passed `data` to the specified `url` using HTTP POST.
#post_file(url, filename, headers = {})	Uploads the contents of a file to the specified `url` using HTTP POST.
#put(url, data, headers = {})	Uploads the passed `data` to the specified `url` using HTTP PUT.
#put_file(url, filename, headers = {})	Uploads the contents of a file to the specified `url` using HTTP PUT.
#request(action, url, headers, options = {})	Basic API methods.

Public Instance Method Details

copy

public copy(url, dest, headers = {})

WebDAV methods

Sends a WebDAV COPY request to the specified url.

[View source]

    
151
152
153
154
        
          # File 'lib/patron/session.rb', line 151

def copy(url, dest, headers = {})
  headers['Destination'] = dest
  request(:copy, url, headers)
end

delete

public delete(url, headers = {})

As #get but sends an HTTP DELETE request.

[View source]

    
120
121
122
        
          # File 'lib/patron/session.rb', line 120

def delete(url, headers = {})
  request(:delete, url, headers)
end

get

public get(url, headers = {})

Standard HTTP methods

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.

[View source]

    
104
105
106
        
          # File 'lib/patron/session.rb', line 104

def get(url, headers = {})
  request(:get, url, headers)
end

get_file

public get_file(url, filename, headers = {})

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

[View source]

    
110
111
112
        
          # File 'lib/patron/session.rb', line 110

def get_file(url, filename, headers = {})
  request(:get, url, headers, :file => filename)
end

handle_cookies

public handle_cookies(file = nil)

Makes this session handle cookies and store them in in file. If file is nil they will be stored in memory. Otherwise the file must be readable and writable. Calling multiple times will add more files.

[View source]

    
      
        
          

81
82
83
84
85
86
87
88
89
90
91
92
93
        
        
          # File 'lib/patron/session.rb', line 81

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, "Cant read or write file #{path} (permission error)"
    end
  end
  enable_cookie_session(path.to_s)
  self
end

        
      

  

head

public head(url, headers = {})

As #get but sends an HTTP HEAD request.

[View source]

    
115
116
117
        
          # File 'lib/patron/session.rb', line 115

def head(url, headers = {})
  request(:head, url, headers)
end

post

public post(url, data, headers = {})

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

[View source]

    
137
138
139
        
          # File 'lib/patron/session.rb', line 137

def post(url, data, headers = {})
  request(:post, url, headers, :data => data)
end

post_file

public post_file(url, filename, headers = {})

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

[View source]

    
142
143
144
        
          # File 'lib/patron/session.rb', line 142

def post_file(url, filename, headers = {})
  request(:post, url, headers, :file => filename)
end

put

public put(url, data, headers = {})

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

[View source]

    
126
127
128
        
          # File 'lib/patron/session.rb', line 126

def put(url, data, headers = {})
  request(:put, url, headers, :data => data)
end

put_file

public put_file(url, filename, headers = {})

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

[View source]

    
131
132
133
        
          # File 'lib/patron/session.rb', line 131

def put_file(url, filename, headers = {})
  request(:put, url, headers, :file => filename)
end

request

public request(action, url, headers, options = {})

Basic API methods

Send an HTTP request to the specified url.

Meta Tags

Raises:

[ArgumentError]

[View source]

    
      
        
          

161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
        
        
          # File 'lib/patron/session.rb', line 161

def request(action, url, headers, options = {})
  req = Request.new
  req.action = action
  req.timeout = self.timeout
  req.connect_timeout = self.connect_timeout
  req.max_redirects = self.max_redirects
  req.headers = self.headers.merge(headers)
  req.username = self.username
  req.password = self.password
  req.upload_data = options[:data]
  req.file_name = options[:file]
  req.proxy = proxy
  req.auth_type = auth_type
  req.insecure = insecure

  req.url = self.base_url.to_s + url.to_s
  raise ArgumentError, "Empty URL" if req.url.empty?

  handle_request(req)
end

        
      

  