Skip to content
This repository has been archived by the owner on Aug 2, 2022. It is now read-only.

Commit

Permalink
Include numpy-style docstrings for Analytics and Datasets services (#227
Browse files Browse the repository at this point in the history 
)

* Update analytics.py

Addresses #195.

* Update datasets.py

Addresses #195.

* Update datasets.py

* Update datasets.py
  • Loading branch information
@critical-path @sgillies
critical-path authored and sgillies committed May 3, 2018
1 parent b9bf3b3 commit 480c82d
Show file tree
Hide file tree
Showing 2 changed files with 184 additions and 46 deletions.
49 changes: 48 additions & 1 deletion mapbox/services/analytics.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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)
Expand Down
181 changes: 136 additions & 45 deletions mapbox/services/datasets.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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)

Expand All @@ -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)
Expand Down

0 comments on commit 480c82d

Please sign in to comment.