/atom/client.py
Python | 182 lines | 136 code | 12 blank | 34 comment | 4 complexity | 34d7b6735437f73be022c26882ca3653 MD5 | raw file
1#!/usr/bin/env python 2# 3# Copyright (C) 2009 Google Inc. 4# 5# Licensed under the Apache License, Version 2.0 (the "License"); 6# you may not use this file except in compliance with the License. 7# You may obtain a copy of the License at 8# 9# http://www.apache.org/licenses/LICENSE-2.0 10# 11# Unless required by applicable law or agreed to in writing, software 12# distributed under the License is distributed on an "AS IS" BASIS, 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14# See the License for the specific language governing permissions and 15# limitations under the License. 16 17 18"""AtomPubClient provides CRUD ops. in line with the Atom Publishing Protocol. 19 20""" 21 22__author__ = 'j.s@google.com (Jeff Scudder)' 23 24 25import atom.http_core 26 27 28class Error(Exception): 29 pass 30 31 32class MissingHost(Error): 33 pass 34 35 36class AtomPubClient(object): 37 host = None 38 auth_token = None 39 ssl = False # Whether to force all requests over https 40 41 def __init__(self, http_client=None, host=None, 42 auth_token=None, source=None, **kwargs): 43 """Creates a new AtomPubClient instance. 44 45 Args: 46 source: The name of your application. 47 http_client: An object capable of performing HTTP requests through a 48 request method. This object is used to perform the request 49 when the AtomPubClient's request method is called. Used to 50 allow HTTP requests to be directed to a mock server, or use 51 an alternate library instead of the default of httplib to 52 make HTTP requests. 53 host: str The default host name to use if a host is not specified in the 54 requested URI. 55 auth_token: An object which sets the HTTP Authorization header when its 56 modify_request method is called. 57 """ 58 self.http_client = http_client or atom.http_core.ProxiedHttpClient() 59 if host is not None: 60 self.host = host 61 if auth_token is not None: 62 self.auth_token = auth_token 63 self.source = source 64 65 def request(self, method=None, uri=None, auth_token=None, 66 http_request=None, **kwargs): 67 """Performs an HTTP request to the server indicated. 68 69 Uses the http_client instance to make the request. 70 71 Args: 72 method: The HTTP method as a string, usually one of 'GET', 'POST', 73 'PUT', or 'DELETE' 74 uri: The URI desired as a string or atom.http_core.Uri. 75 http_request: 76 auth_token: An authorization token object whose modify_request method 77 sets the HTTP Authorization header. 78 79 Returns: 80 The results of calling self.http_client.request. With the default 81 http_client, this is an HTTP response object. 82 """ 83 # Modify the request based on the AtomPubClient settings and parameters 84 # passed in to the request. 85 http_request = self.modify_request(http_request) 86 if isinstance(uri, (str, unicode)): 87 uri = atom.http_core.Uri.parse_uri(uri) 88 if uri is not None: 89 uri.modify_request(http_request) 90 if isinstance(method, (str, unicode)): 91 http_request.method = method 92 # Any unrecognized arguments are assumed to be capable of modifying the 93 # HTTP request. 94 for name, value in kwargs.iteritems(): 95 if value is not None: 96 value.modify_request(http_request) 97 # Default to an http request if the protocol scheme is not set. 98 if http_request.uri.scheme is None: 99 http_request.uri.scheme = 'http' 100 # Override scheme. Force requests over https. 101 if self.ssl: 102 http_request.uri.scheme = 'https' 103 if http_request.uri.path is None: 104 http_request.uri.path = '/' 105 # Add the Authorization header at the very end. The Authorization header 106 # value may need to be calculated using information in the request. 107 if auth_token: 108 auth_token.modify_request(http_request) 109 elif self.auth_token: 110 self.auth_token.modify_request(http_request) 111 # Check to make sure there is a host in the http_request. 112 if http_request.uri.host is None: 113 raise MissingHost('No host provided in request %s %s' % ( 114 http_request.method, str(http_request.uri))) 115 # Perform the fully specified request using the http_client instance. 116 # Sends the request to the server and returns the server's response. 117 return self.http_client.request(http_request) 118 119 Request = request 120 121 def get(self, uri=None, auth_token=None, http_request=None, **kwargs): 122 """Performs a request using the GET method, returns an HTTP response.""" 123 return self.request(method='GET', uri=uri, auth_token=auth_token, 124 http_request=http_request, **kwargs) 125 126 Get = get 127 128 def post(self, uri=None, data=None, auth_token=None, http_request=None, 129 **kwargs): 130 """Sends data using the POST method, returns an HTTP response.""" 131 return self.request(method='POST', uri=uri, auth_token=auth_token, 132 http_request=http_request, data=data, **kwargs) 133 134 Post = post 135 136 def put(self, uri=None, data=None, auth_token=None, http_request=None, 137 **kwargs): 138 """Sends data using the PUT method, returns an HTTP response.""" 139 return self.request(method='PUT', uri=uri, auth_token=auth_token, 140 http_request=http_request, data=data, **kwargs) 141 142 Put = put 143 144 def delete(self, uri=None, auth_token=None, http_request=None, **kwargs): 145 """Performs a request using the DELETE method, returns an HTTP response.""" 146 return self.request(method='DELETE', uri=uri, auth_token=auth_token, 147 http_request=http_request, **kwargs) 148 149 Delete = delete 150 151 def modify_request(self, http_request): 152 """Changes the HTTP request before sending it to the server. 153 154 Sets the User-Agent HTTP header and fills in the HTTP host portion 155 of the URL if one was not included in the request (for this it uses 156 the self.host member if one is set). This method is called in 157 self.request. 158 159 Args: 160 http_request: An atom.http_core.HttpRequest() (optional) If one is 161 not provided, a new HttpRequest is instantiated. 162 163 Returns: 164 An atom.http_core.HttpRequest() with the User-Agent header set and 165 if this client has a value in its host member, the host in the request 166 URL is set. 167 """ 168 if http_request is None: 169 http_request = atom.http_core.HttpRequest() 170 171 if self.host is not None and http_request.uri.host is None: 172 http_request.uri.host = self.host 173 174 # Set the user agent header for logging purposes. 175 if self.source: 176 http_request.headers['User-Agent'] = '%s gdata-py/2.0.9' % self.source 177 else: 178 http_request.headers['User-Agent'] = 'gdata-py/2.0.9' 179 180 return http_request 181 182 ModifyRequest = modify_request