From 480c82dea2f35057a2769b339ecdf60dd923bd05 Mon Sep 17 00:00:00 2001 From: critical-path <37241479+critical-path@users.noreply.github.com> Date: Thu, 3 May 2018 17:31:14 -0400 Subject: [PATCH] Include numpy-style docstrings for Analytics and Datasets services (#227) * Update analytics.py Addresses #195. * Update datasets.py Addresses #195. * Update datasets.py * Update datasets.py --- mapbox/services/analytics.py | 49 +++++++++- mapbox/services/datasets.py | 181 ++++++++++++++++++++++++++--------- 2 files changed, 184 insertions(+), 46 deletions(-) diff --git a/mapbox/services/analytics.py b/mapbox/services/analytics.py index 5428b70..d1007fd 100644 --- a/mapbox/services/analytics.py +++ b/mapbox/services/analytics.py @@ -7,7 +7,19 @@ class Analytics(Service): - """Access to Analytics API V1""" + """Access to Analytics API V1 + + Attributes + ---------- + api_name : str + The API's name. + + api_version : str + The API's version number. + + valid_resource_types : list + The possible values for the resource being requested. + """ api_name = 'analytics' api_version = 'v1' @@ -44,6 +56,41 @@ def _validate_id(self, resource_type, id): return id def analytics(self, resource_type, username, id=None, start=None, end=None): + """Returns the request counts per day for a given resource and period. + + Parameters + ---------- + resource_type : str + The resource being requested. + + Possible values are "tokens", "styles", "tilesets", and "accounts". + + username : str + The username for the account that owns the resource. + + id : str, optional + The id for the resource. + + If resource_type is "tokens", then id is the complete token. + If resource_type is "styles", then id is the style id. + If resource_type is "tilesets", then id is a map id. + If resource_type is "accounts", then id is not required. + + start, end : str, optional + ISO-formatted start and end dates. + + If provided, the start date must be earlier than the end date, + and the maximum length of time between the start and end dates + is one year. + + If not provided, the length of time between the start and end + dates defaults to 90 days. + + Returns + ------- + requests.Response + """ + resource_type = self._validate_resource_type(resource_type) username = self._validate_username(username) start, end = self._validate_period(start, end) diff --git a/mapbox/services/datasets.py b/mapbox/services/datasets.py index 064f27e..fa7f225 100644 --- a/mapbox/services/datasets.py +++ b/mapbox/services/datasets.py @@ -8,7 +8,16 @@ class Datasets(Service): - """Access to the Datasets API V1""" + """Access to the Datasets API V1 + + Attributes + ---------- + api_name : str + The API's name. + + api_version : str + The API's version number. + """ api_name = 'datasets' api_version = 'v1' @@ -23,73 +32,123 @@ def _attribs(self, name=None, description=None): return a def create(self, name=None, description=None): - """Create a new dataset. + """Creates a new, empty dataset. - Returns a :class:`requests.Response` containing the attributes - of the new dataset as a JSON object. + Parameters + ---------- + name : str, optional + The name of the dataset. - :param name: the dataset name (optional). - :param description: the dataset description (optional). + description : str, optional + The description of the dataset. + + Returns + ------- + request.Response + The response contains the properties of a new dataset as a JSON object. """ + uri = URITemplate(self.baseuri + '/{owner}').expand( owner=self.username) return self.session.post(uri, json=self._attribs(name, description)) def list(self): - """List datasets. + """Lists all datasets for a particular account. - Returns a :class:`requests.Response` containing a list of - objects describing datasets. + Returns + ------- + request.Response + The response contains a list of JSON objects describing datasets. """ + uri = URITemplate(self.baseuri + '/{owner}').expand( owner=self.username) return self.session.get(uri) def read_dataset(self, dataset): - """Read the attributes of a dataset. + """Retrieves (reads) a single dataset. - Returns a :class:`requests.Response` containing the attributes - as a JSON object. The attributes: owner (a Mapbox account), - id (dataset id), created (Unix timestamp), modified - (timestamp), name (string), and description (string). + Parameters + ---------- + dataset : str + The dataset id. - :param dataset: the dataset identifier string. + Returns + ------- + request.Response + The response contains the properties of the retrieved dataset as a JSON object. """ + uri = URITemplate(self.baseuri + '/{owner}/{id}').expand( owner=self.username, id=dataset) return self.session.get(uri) def update_dataset(self, dataset, name=None, description=None): - """Update the name and description of a dataset. + """Updates a single dataset. + + Parameters + ---------- + dataset : str + The dataset id. - Returns a :class:`requests.Response` containing the updated - attributes as a JSON object. + name : str, optional + The name of the dataset. - :param dataset: the dataset identifier string. - :param name: the dataset name. - :param description: the dataset description. + description : str, optional + The description of the dataset. + + Returns + ------- + request.Response + The response contains the properties of the updated dataset as a JSON object. """ + uri = URITemplate(self.baseuri + '/{owner}/{id}').expand( owner=self.username, id=dataset) return self.session.patch(uri, json=self._attribs(name, description)) def delete_dataset(self, dataset): - """Delete a dataset. + """Deletes a single dataset, including all of the features that it contains. + + Parameters + ---------- + dataset : str + The dataset id. - :param dataset: the dataset identifier string. + Returns + ------- + HTTP status code. """ + uri = URITemplate(self.baseuri + '/{owner}/{id}').expand( owner=self.username, id=dataset) return self.session.delete(uri) def list_features(self, dataset, reverse=False, start=None, limit=None): - """Get features of a dataset. + """Lists features in a dataset. + + Parameters + ---------- + dataset : str + The dataset id. + + reverse : str, optional + List features in reverse order. + + Possible value is "true". - Returns a :class:`requests.Response` containing the features of - the dataset as a GeoJSON feature collection. + start : str, optional + The id of the feature after which to start the list (pagination). - :param dataset: the dataset identifier string. + limit : str, optional + The maximum number of features to list (pagination). + + Returns + ------- + request.Response + The response contains the features of a dataset as a GeoJSON FeatureCollection. """ + uri = URITemplate(self.baseuri + '/{owner}/{id}/features').expand( owner=self.username, id=dataset) @@ -103,42 +162,74 @@ def list_features(self, dataset, reverse=False, start=None, limit=None): return self.session.get(uri, params=params) def read_feature(self, dataset, fid): - """Read a dataset feature. + """Retrieves (reads) a feature in a dataset. + + Parameters + ---------- + dataset : str + The dataset id. - Returns a :class:`requests.Response` containing a GeoJSON - representation of the feature. + fid : str + The feature id. - :param dataset: the dataset identifier string. - :param fid: the feature identifier string. + Returns + ------- + request.Response + The response contains a GeoJSON representation of the feature. """ + uri = URITemplate( self.baseuri + '/{owner}/{did}/features/{fid}').expand( owner=self.username, did=dataset, fid=fid) return self.session.get(uri) def update_feature(self, dataset, fid, feature): - """Create or update a dataset feature. - - The semantics of HTTP PUT apply: if the dataset has no feature - with the given `fid` a new feature will be created. Returns a - :class:`requests.Response` containing a GeoJSON representation - of the new or updated feature. - - :param dataset: the dataset identifier string. - :param fid: the feature identifier string. - :param feature: a GeoJSON feature object. + """Inserts or updates a feature in a dataset. + + Parameters + ---------- + dataset : str + The dataset id. + + fid : str + The feature id. + + If the dataset has no feature with the given feature id, + then a new feature will be created. + + feature : dict + The GeoJSON feature object. + + This should be one individual GeoJSON feature and not a + GeoJSON FeatureCollection. + + Returns + ------- + request.Response + The response contains a GeoJSON representation of the new or updated feature. """ + uri = URITemplate( self.baseuri + '/{owner}/{did}/features/{fid}').expand( owner=self.username, did=dataset, fid=fid) return self.session.put(uri, json=feature) def delete_feature(self, dataset, fid): - """Delete a dataset feature. + """Removes a feature from a dataset. + + Parameters + ---------- + dataset : str + The dataset id. + + fid : str + The feature id. - :param dataset: the dataset identifier string. - :param fid: the feature identifier string. + Returns + ------- + HTTP status code. """ + uri = URITemplate( self.baseuri + '/{owner}/{did}/features/{fid}').expand( owner=self.username, did=dataset, fid=fid)