| import cgi, datetime, re, time, urllib |
| from django import http |
| import django.core.exceptions |
| from django.core import urlresolvers |
| from django.utils import datastructures |
| import simplejson |
| from autotest_lib.frontend.shared import exceptions, query_lib |
| from autotest_lib.frontend.afe import model_logic |
| |
| |
| _JSON_CONTENT_TYPE = 'application/json' |
| |
| |
| def _resolve_class_path(class_path): |
| module_path, class_name = class_path.rsplit('.', 1) |
| module = __import__(module_path, {}, {}, ['']) |
| return getattr(module, class_name) |
| |
| |
| _NO_VALUE_SPECIFIED = object() |
| |
| class _InputDict(dict): |
| def get(self, key, default=_NO_VALUE_SPECIFIED): |
| return super(_InputDict, self).get(key, default) |
| |
| |
| @classmethod |
| def remove_unspecified_fields(cls, field_dict): |
| return dict((key, value) for key, value in field_dict.iteritems() |
| if value is not _NO_VALUE_SPECIFIED) |
| |
| |
| class Resource(object): |
| _permitted_methods = None # subclasses must override this |
| |
| |
| def __init__(self, request): |
| assert self._permitted_methods |
| # this request should be used for global environment info, like |
| # constructing absolute URIs. it should not be used for query |
| # parameters, because the request may not have been for this particular |
| # resource. |
| self._request = request |
| # this dict will contain the applicable query parameters |
| self._query_params = datastructures.MultiValueDict() |
| |
| |
| @classmethod |
| def dispatch_request(cls, request, *args, **kwargs): |
| # handle a request directly |
| try: |
| try: |
| instance = cls.from_uri_args(request, **kwargs) |
| except django.core.exceptions.ObjectDoesNotExist, exc: |
| raise http.Http404(exc) |
| |
| instance.read_query_parameters(request.GET) |
| return instance.handle_request() |
| except exceptions.RequestError, exc: |
| return exc.response |
| |
| |
| def handle_request(self): |
| if self._request.method.upper() not in self._permitted_methods: |
| return http.HttpResponseNotAllowed(self._permitted_methods) |
| |
| handler = getattr(self, self._request.method.lower()) |
| return handler() |
| |
| |
| # the handler methods below only need to be overridden if the resource |
| # supports the method |
| |
| def get(self): |
| """Handle a GET request. |
| |
| @returns an HttpResponse |
| """ |
| raise NotImplementedError |
| |
| |
| def post(self): |
| """Handle a POST request. |
| |
| @returns an HttpResponse |
| """ |
| raise NotImplementedError |
| |
| |
| def put(self): |
| """Handle a PUT request. |
| |
| @returns an HttpResponse |
| """ |
| raise NotImplementedError |
| |
| |
| def delete(self): |
| """Handle a DELETE request. |
| |
| @returns an HttpResponse |
| """ |
| raise NotImplementedError |
| |
| |
| @classmethod |
| def from_uri_args(cls, request, **kwargs): |
| """Construct an instance from URI args. |
| |
| Default implementation for resources with no URI args. |
| """ |
| return cls(request) |
| |
| |
| def _uri_args(self): |
| """Return kwargs for a URI reference to this resource. |
| |
| Default implementation for resources with no URI args. |
| """ |
| return {} |
| |
| |
| def _query_parameters_accepted(self): |
| """Return sequence of tuples (name, description) for query parameters. |
| |
| Documents the available query parameters for GETting this resource. |
| Default implementation for resources with no parameters. |
| """ |
| return () |
| |
| |
| def read_query_parameters(self, parameters): |
| """Read relevant query parameters from a Django MultiValueDict.""" |
| params_acccepted = set(param_name for param_name, _ |
| in self._query_parameters_accepted()) |
| for name, values in parameters.iterlists(): |
| base_name = name.split(':', 1)[0] |
| if base_name in params_acccepted: |
| self._query_params.setlist(name, values) |
| |
| |
| def set_query_parameters(self, **parameters): |
| """Set query parameters programmatically.""" |
| self._query_params.update(parameters) |
| |
| |
| def href(self, query_params=None): |
| """Return URI to this resource.""" |
| kwargs = self._uri_args() |
| path = urlresolvers.reverse(self.dispatch_request, kwargs=kwargs) |
| full_query_params = datastructures.MultiValueDict(self._query_params) |
| if query_params: |
| full_query_params.update(query_params) |
| if full_query_params: |
| path += '?' + urllib.urlencode(full_query_params.lists(), |
| doseq=True) |
| return self._request.build_absolute_uri(path) |
| |
| |
| def resolve_uri(self, uri): |
| # check for absolute URIs |
| match = re.match(r'(?P<root>https?://[^/]+)(?P<path>/.*)', uri) |
| if match: |
| # is this URI for a different host? |
| my_root = self._request.build_absolute_uri('/') |
| request_root = match.group('root') + '/' |
| if my_root != request_root: |
| # might support this in the future, but not now |
| raise exceptions.BadRequest('Unable to resolve remote URI %s' |
| % uri) |
| uri = match.group('path') |
| |
| try: |
| view_method, args, kwargs = urlresolvers.resolve(uri) |
| except http.Http404: |
| raise exceptions.BadRequest('Unable to resolve URI %s' % uri) |
| resource_class = view_method.im_self # class owning this classmethod |
| return resource_class.from_uri_args(self._request, **kwargs) |
| |
| |
| def resolve_link(self, link): |
| if isinstance(link, dict): |
| uri = link['href'] |
| elif isinstance(link, basestring): |
| uri = link |
| else: |
| raise exceptions.BadRequest('Unable to understand link %s' % link) |
| return self.resolve_uri(uri) |
| |
| |
| def link(self, query_params=None): |
| return {'href': self.href(query_params=query_params)} |
| |
| |
| def _query_parameters_response(self): |
| return dict((name, description) |
| for name, description in self._query_parameters_accepted()) |
| |
| |
| def _basic_response(self, content): |
| """Construct and return a simple 200 response.""" |
| assert isinstance(content, dict) |
| query_parameters = self._query_parameters_response() |
| if query_parameters: |
| content['query_parameters'] = query_parameters |
| encoded_content = simplejson.dumps(content) |
| return http.HttpResponse(encoded_content, |
| content_type=_JSON_CONTENT_TYPE) |
| |
| |
| def _decoded_input(self): |
| content_type = self._request.META.get('CONTENT_TYPE', |
| _JSON_CONTENT_TYPE) |
| raw_data = self._request.raw_post_data |
| if content_type == _JSON_CONTENT_TYPE: |
| try: |
| raw_dict = simplejson.loads(raw_data) |
| except ValueError, exc: |
| raise exceptions.BadRequest('Error decoding request body: ' |
| '%s\n%r' % (exc, raw_data)) |
| if not isinstance(raw_dict, dict): |
| raise exceptions.BadRequest('Expected dict input, got %s: %r' % |
| (type(raw_dict), raw_dict)) |
| elif content_type == 'application/x-www-form-urlencoded': |
| cgi_dict = cgi.parse_qs(raw_data) # django won't do this for PUT |
| raw_dict = {} |
| for key, values in cgi_dict.items(): |
| value = values[-1] # take last value if multiple were given |
| try: |
| # attempt to parse numbers, booleans and nulls |
| raw_dict[key] = simplejson.loads(value) |
| except ValueError: |
| # otherwise, leave it as a string |
| raw_dict[key] = value |
| else: |
| raise exceptions.RequestError(415, 'Unsupported media type: %s' |
| % content_type) |
| |
| return _InputDict(raw_dict) |
| |
| |
| def _format_datetime(self, date_time): |
| """Return ISO 8601 string for the given datetime""" |
| if date_time is None: |
| return None |
| timezone_hrs = time.timezone / 60 / 60 # convert seconds to hours |
| if timezone_hrs >= 0: |
| timezone_join = '+' |
| else: |
| timezone_join = '' # minus sign comes from number itself |
| timezone_spec = '%s%s:00' % (timezone_join, timezone_hrs) |
| return date_time.strftime('%Y-%m-%dT%H:%M:%S') + timezone_spec |
| |
| |
| @classmethod |
| def _check_for_required_fields(cls, input_dict, fields): |
| assert isinstance(fields, (list, tuple)), fields |
| missing_fields = ', '.join(field for field in fields |
| if field not in input_dict) |
| if missing_fields: |
| raise exceptions.BadRequest('Missing input: ' + missing_fields) |
| |
| |
| class Entry(Resource): |
| @classmethod |
| def add_query_selectors(cls, query_processor): |
| """Sbuclasses may override this to support querying.""" |
| pass |
| |
| |
| def short_representation(self): |
| return self.link() |
| |
| |
| def full_representation(self): |
| return self.short_representation() |
| |
| |
| def get(self): |
| return self._basic_response(self.full_representation()) |
| |
| |
| def put(self): |
| try: |
| self.update(self._decoded_input()) |
| except model_logic.ValidationError, exc: |
| raise exceptions.BadRequest('Invalid input: %s' % exc) |
| return self._basic_response(self.full_representation()) |
| |
| |
| def _delete_entry(self): |
| raise NotImplementedError |
| |
| |
| def delete(self): |
| self._delete_entry() |
| return http.HttpResponse(status=204) # No content |
| |
| |
| def create_instance(self, input_dict, containing_collection): |
| raise NotImplementedError |
| |
| |
| def update(self, input_dict): |
| raise NotImplementedError |
| |
| |
| class InstanceEntry(Entry): |
| class NullEntry(object): |
| def link(self): |
| return None |
| |
| |
| def short_representation(self): |
| return None |
| |
| |
| _null_entry = NullEntry() |
| _permitted_methods = ('GET', 'PUT', 'DELETE') |
| model = None # subclasses must override this with a Django model class |
| |
| |
| def __init__(self, request, instance): |
| assert self.model is not None |
| super(Entry, self).__init__(request) |
| self.instance = instance |
| self._is_prepared_for_full_representation = False |
| |
| |
| @classmethod |
| def from_optional_instance(cls, request, instance): |
| if instance is None: |
| return cls._null_entry |
| return cls(request, instance) |
| |
| |
| def _delete_entry(self): |
| self.instance.delete() |
| |
| |
| def full_representation(self): |
| self.prepare_for_full_representation([self]) |
| return super(InstanceEntry, self).full_representation() |
| |
| |
| @classmethod |
| def prepare_for_full_representation(cls, entries): |
| """ |
| Prepare the given list of entries to generate full representations. |
| |
| This method delegates to _do_prepare_for_full_representation(), which |
| subclasses may override as necessary to do the actual processing. This |
| method also marks the instance as prepared, so it's safe to call this |
| multiple times with the same instance(s) without wasting work. |
| """ |
| not_prepared = [entry for entry in entries |
| if not entry._is_prepared_for_full_representation] |
| cls._do_prepare_for_full_representation([entry.instance |
| for entry in not_prepared]) |
| for entry in not_prepared: |
| entry._is_prepared_for_full_representation = True |
| |
| |
| @classmethod |
| def _do_prepare_for_full_representation(cls, instances): |
| """ |
| Subclasses may override this to gather data as needed for full |
| representations of the given model instances. Typically, this involves |
| querying over related objects, and this method offers a chance to query |
| for many instances at once, which can provide a great performance |
| benefit. |
| """ |
| pass |
| |
| |
| class Collection(Resource): |
| _DEFAULT_ITEMS_PER_PAGE = 50 |
| |
| _permitted_methods=('GET', 'POST') |
| |
| # subclasses must override these |
| queryset = None # or override _fresh_queryset() directly |
| entry_class = None |
| |
| |
| def __init__(self, request): |
| super(Collection, self).__init__(request) |
| assert self.entry_class is not None |
| if isinstance(self.entry_class, basestring): |
| type(self).entry_class = _resolve_class_path(self.entry_class) |
| |
| self._query_processor = query_lib.QueryProcessor() |
| self.entry_class.add_query_selectors(self._query_processor) |
| |
| |
| def _query_parameters_accepted(self): |
| params = [('start_index', 'Index of first member to include'), |
| ('items_per_page', 'Number of members to include'), |
| ('full_representations', |
| 'True to include full representations of members')] |
| for selector in self._query_processor.selectors(): |
| params.append((selector.name, selector.doc)) |
| return params |
| |
| |
| def _fresh_queryset(self): |
| assert self.queryset is not None |
| # always copy the queryset before using it to avoid caching |
| return self.queryset.all() |
| |
| |
| def _entry_from_instance(self, instance): |
| return self.entry_class(self._request, instance) |
| |
| |
| def _representation(self, entry_instances): |
| entries = [self._entry_from_instance(instance) |
| for instance in entry_instances] |
| |
| want_full_representation = self._read_bool_parameter( |
| 'full_representations') |
| if want_full_representation: |
| self.entry_class.prepare_for_full_representation(entries) |
| |
| members = [] |
| for entry in entries: |
| if want_full_representation: |
| rep = entry.full_representation() |
| else: |
| rep = entry.short_representation() |
| members.append(rep) |
| |
| rep = self.link() |
| rep.update({'members': members}) |
| return rep |
| |
| |
| def _read_bool_parameter(self, name): |
| if name not in self._query_params: |
| return False |
| return (self._query_params[name].lower() == 'true') |
| |
| |
| def _read_int_parameter(self, name, default): |
| if name not in self._query_params: |
| return default |
| input_value = self._query_params[name] |
| try: |
| return int(input_value) |
| except ValueError: |
| raise exceptions.BadRequest('Invalid non-numeric value for %s: %r' |
| % (name, input_value)) |
| |
| |
| def _apply_form_query(self, queryset): |
| """Apply any query selectors passed as form variables.""" |
| for parameter, values in self._query_params.lists(): |
| if ':' in parameter: |
| parameter, comparison_type = parameter.split(':', 1) |
| else: |
| comparison_type = None |
| |
| if not self._query_processor.has_selector(parameter): |
| continue |
| for value in values: # forms keys can have multiple values |
| queryset = self._query_processor.apply_selector( |
| queryset, parameter, value, |
| comparison_type=comparison_type) |
| return queryset |
| |
| |
| def _filtered_queryset(self): |
| return self._apply_form_query(self._fresh_queryset()) |
| |
| |
| def get(self): |
| queryset = self._filtered_queryset() |
| |
| items_per_page = self._read_int_parameter('items_per_page', |
| self._DEFAULT_ITEMS_PER_PAGE) |
| start_index = self._read_int_parameter('start_index', 0) |
| page = queryset[start_index:(start_index + items_per_page)] |
| |
| rep = self._representation(page) |
| rep.update({'total_results': len(queryset), |
| 'start_index': start_index, |
| 'items_per_page': items_per_page}) |
| return self._basic_response(rep) |
| |
| |
| def full_representation(self): |
| # careful, this rep can be huge for large collections |
| return self._representation(self._fresh_queryset()) |
| |
| |
| def post(self): |
| input_dict = self._decoded_input() |
| try: |
| instance = self.entry_class.create_instance(input_dict, self) |
| entry = self._entry_from_instance(instance) |
| entry.update(input_dict) |
| except model_logic.ValidationError, exc: |
| raise exceptions.BadRequest('Invalid input: %s' % exc) |
| # RFC 2616 specifies that we provide the new URI in both the Location |
| # header and the body |
| response = http.HttpResponse(status=201, # Created |
| content=entry.href()) |
| response['Location'] = entry.href() |
| return response |
| |
| |
| class Relationship(Entry): |
| _permitted_methods = ('GET', 'DELETE') |
| |
| # subclasses must override this with a dict mapping name to entry class |
| related_classes = None |
| |
| |
| def __init__(self, **kwargs): |
| assert len(self.related_classes) == 2 |
| self.entries = dict((name, kwargs[name]) |
| for name in self.related_classes) |
| for name in self.related_classes: # sanity check |
| assert isinstance(self.entries[name], self.related_classes[name]) |
| |
| # just grab the request from one of the entries |
| some_entry = self.entries.itervalues().next() |
| super(Relationship, self).__init__(some_entry._request) |
| |
| |
| @classmethod |
| def from_uri_args(cls, request, **kwargs): |
| # kwargs contains URI args for each entry |
| entries = {} |
| for name, entry_class in cls.related_classes.iteritems(): |
| entries[name] = entry_class.from_uri_args(request, **kwargs) |
| return cls(**entries) |
| |
| |
| def _uri_args(self): |
| kwargs = {} |
| for name, entry in self.entries.iteritems(): |
| kwargs.update(entry._uri_args()) |
| return kwargs |
| |
| |
| def short_representation(self): |
| rep = self.link() |
| for name, entry in self.entries.iteritems(): |
| rep[name] = entry.short_representation() |
| return rep |
| |
| |
| @classmethod |
| def _get_related_manager(cls, instance): |
| """Get the related objects manager for the given instance. |
| |
| The instance must be one of the related classes. This method will |
| return the related manager from that instance to instances of the other |
| related class. |
| """ |
| this_model = type(instance) |
| models = [entry_class.model for entry_class |
| in cls.related_classes.values()] |
| if isinstance(instance, models[0]): |
| this_model, other_model = models |
| else: |
| other_model, this_model = models |
| |
| _, field = this_model.objects.determine_relationship(other_model) |
| this_models_fields = (this_model._meta.fields |
| + this_model._meta.many_to_many) |
| if field in this_models_fields: |
| manager_name = field.attname |
| else: |
| # related manager is on other_model, get name of reverse related |
| # manager on this_model |
| manager_name = field.related.get_accessor_name() |
| |
| return getattr(instance, manager_name) |
| |
| |
| def _delete_entry(self): |
| # choose order arbitrarily |
| entry, other_entry = self.entries.itervalues() |
| related_manager = self._get_related_manager(entry.instance) |
| related_manager.remove(other_entry.instance) |
| |
| |
| @classmethod |
| def create_instance(cls, input_dict, containing_collection): |
| other_name = containing_collection.unfixed_name |
| cls._check_for_required_fields(input_dict, (other_name,)) |
| entry = containing_collection.fixed_entry |
| other_entry = containing_collection.resolve_link(input_dict[other_name]) |
| related_manager = cls._get_related_manager(entry.instance) |
| related_manager.add(other_entry.instance) |
| return other_entry.instance |
| |
| |
| def update(self, input_dict): |
| pass |
| |
| |
| class RelationshipCollection(Collection): |
| def __init__(self, request=None, fixed_entry=None): |
| if request is None: |
| request = fixed_entry._request |
| super(RelationshipCollection, self).__init__(request) |
| |
| assert issubclass(self.entry_class, Relationship) |
| self.related_classes = self.entry_class.related_classes |
| self.fixed_name = None |
| self.fixed_entry = None |
| self.unfixed_name = None |
| self.related_manager = None |
| |
| if fixed_entry is not None: |
| self._set_fixed_entry(fixed_entry) |
| entry_uri_arg = self.fixed_entry._uri_args().values()[0] |
| self._query_params[self.fixed_name] = entry_uri_arg |
| |
| |
| def _set_fixed_entry(self, entry): |
| """Set the fixed entry for this collection. |
| |
| The entry must be an instance of one of the related entry classes. This |
| method must be called before a relationship is used. It gets called |
| either from the constructor (when collections are instantiated from |
| other resource handling code) or from read_query_parameters() (when a |
| request is made directly for the collection. |
| """ |
| names = self.related_classes.keys() |
| if isinstance(entry, self.related_classes[names[0]]): |
| self.fixed_name, self.unfixed_name = names |
| else: |
| assert isinstance(entry, self.related_classes[names[1]]) |
| self.unfixed_name, self.fixed_name = names |
| self.fixed_entry = entry |
| self.unfixed_class = self.related_classes[self.unfixed_name] |
| self.related_manager = self.entry_class._get_related_manager( |
| entry.instance) |
| |
| |
| def _query_parameters_accepted(self): |
| return [(name, 'Show relationships for this %s' % entry_class.__name__) |
| for name, entry_class |
| in self.related_classes.iteritems()] |
| |
| |
| def _resolve_query_param(self, name, uri_arg): |
| entry_class = self.related_classes[name] |
| return entry_class.from_uri_args(self._request, uri_arg) |
| |
| |
| def read_query_parameters(self, query_params): |
| super(RelationshipCollection, self).read_query_parameters(query_params) |
| if not self._query_params: |
| raise exceptions.BadRequest( |
| 'You must specify one of the parameters %s and %s' |
| % tuple(self.related_classes.keys())) |
| query_items = self._query_params.items() |
| fixed_entry = self._resolve_query_param(*query_items[0]) |
| self._set_fixed_entry(fixed_entry) |
| |
| if len(query_items) > 1: |
| other_fixed_entry = self._resolve_query_param(*query_items[1]) |
| self.related_manager = self.related_manager.filter( |
| pk=other_fixed_entry.instance.id) |
| |
| |
| def _entry_from_instance(self, instance): |
| unfixed_entry = self.unfixed_class(self._request, instance) |
| entries = {self.fixed_name: self.fixed_entry, |
| self.unfixed_name: unfixed_entry} |
| return self.entry_class(**entries) |
| |
| |
| def _fresh_queryset(self): |
| return self.related_manager.all() |
