diff --git a/sendgrid/helpers/stats/stats.py b/sendgrid/helpers/stats/stats.py index 8fe1399a2..b866093b5 100644 --- a/sendgrid/helpers/stats/stats.py +++ b/sendgrid/helpers/stats/stats.py @@ -1,6 +1,14 @@ class Stats(object): + """ + Object for building query params for a global email statistics request + """ def __init__( self, start_date=None): + """Create a Stats object + + :param start_date: Date of when stats should begin in YYYY-MM-DD format, defaults to None + :type start_date: string, optional + """ self._start_date = None self._end_date = None self._aggregated_by = None @@ -14,11 +22,18 @@ def __init__( self.start_date = start_date def __str__(self): + """Get a JSON representation of this object. + + :rtype: string + """ return str(self.get()) def get(self): """ - :return: response stats dict + Get a JSON-ready representation of Stats + + :returns: This GlobalStats, ready for use in a request body. + :rtype: response stats dict """ stats = {} if self.start_date is not None: @@ -39,63 +54,136 @@ def get(self): @property def start_date(self): + """Date of when stats should begin in YYYY-MM-DD format + + :rtype: string + """ return self._start_date @start_date.setter def start_date(self, value): + """Date of when stats should begin in YYYY-MM-DD format + + :param value: Date representing when stats should begin + :type value: string + """ self._start_date = value @property def end_date(self): + """Date of when stats should end in YYYY-MM-DD format + + :rtype: string + """ return self._end_date @end_date.setter def end_date(self, value): + """Date of when stats should end in YYYY-MM-DD format + + :param value: Date representing when stats should end + :type value: string + """ self._end_date = value @property def aggregated_by(self): + """Chosen period (e.g. 'day', 'week', 'month') for how stats get grouped + + :rtype: string + """ return self._aggregated_by @aggregated_by.setter def aggregated_by(self, value): + """Chosen period (e.g. 'day', 'week', 'month') for how stats get grouped + + :param value: Period for how keys will get formatted + :type value: string + """ self._aggregated_by = value @property def sort_by_metric(self): + """Metric to sort stats by + + :rtype: string + """ return self._sort_by_metric @sort_by_metric.setter def sort_by_metric(self, value): + """Metric to sort stats by + + :param value: Chosen metric stats will by sorted by + :type value: string + """ self._sort_by_metric = value @property def sort_by_direction(self): + """Direction data will be sorted, either 'asc' or 'desc' + + :rtype: string + """ return self._sort_by_direction @sort_by_direction.setter def sort_by_direction(self, value): + """Direction data will be sorted, either 'asc' or 'desc' + + :param value: Direction of data, either 'asc' or 'desc' + :type value: string + """ self._sort_by_direction = value @property def limit(self): + """Max amount of results to be returned + + :rtype: int + """ return self._limit @limit.setter def limit(self, value): + """Max amount of results to be returned + + :param value: Max amount of results + :type value: int + """ self._limit = value @property def offset(self): + """Number of places a starting point of a data set will move + + :rtype: int + """ return self._offset @offset.setter def offset(self, value): + """Number of places a starting point of a data set will move + + :param value: Number of positions to move from starting point + :type value: int + """ self._offset = value class CategoryStats(Stats): + """ + object for building query params for a category statistics request + """ def __init__(self, start_date=None, categories=None): + """Create a CategoryStats object + + :param start_date: Date of when stats should begin in YYYY-MM-DD format, defaults to None + :type start_date: string, optional + :param categories: list of categories to get results of, defaults to None + :type categories: list(string), optional + """ self._categories = None super(CategoryStats, self).__init__() @@ -107,7 +195,9 @@ def __init__(self, start_date=None, categories=None): def get(self): """ - :return: response stats dict + Get a JSON-ready representation of this CategoryStats. + + :return: response category stats dict """ stats = {} if self.start_date is not None: @@ -131,16 +221,35 @@ def get(self): @property def categories(self): + """List of categories + + :rtype: list(Category) + """ return self._categories def add_category(self, category): + """Appends a category to this object's category list + + :param category: Category to append to CategoryStats + :type category: Category + """ if self._categories is None: self._categories = [] self._categories.append(category) class SubuserStats(Stats): + """ + object of building query params for a subuser statistics request + """ def __init__(self, start_date=None, subusers=None): + """Create a SubuserStats object + + :param start_date: Date of when stats should begin in YYYY-MM-DD format, defaults to None + :type start_date: string, optional + :param subusers: list of subusers to get results of, defaults to None + :type subusers: list(string), optional + """ self._subusers = None super(SubuserStats, self).__init__() @@ -152,7 +261,9 @@ def __init__(self, start_date=None, subusers=None): def get(self): """ - :return: response stats dict + Get a JSON-ready representation of this SubuserStats. + + :return: response subuser stats dict """ stats = {} if self.start_date is not None: @@ -176,47 +287,98 @@ def get(self): @property def subusers(self): + """List of subusers + + :rtype: list(Subuser) + """ return self._subusers def add_subuser(self, subuser): + """Appends a subuser to this object's subuser list + + :param subuser: Subuser to append to SubuserStats + :type subuser: Subuser + """ if self._subusers is None: self._subusers = [] self._subusers.append(subuser) class Category(object): - + """ + Represents a searchable statistics category to be used in a CategoryStats object + """ def __init__(self, name=None): + """Create a Category object + + :param name: name of category, defaults to None + :type name: string, optional + """ self._name = None if name is not None: self._name = name @property def name(self): + """Get name of category + + :rtype: string + """ return self._name @name.setter def name(self, value): + """Set name of category + + :param value: name of the statistical category + :type value: string + """ self._name = value def get(self): + """ + Get a string representation of Category. + + :return: string of the category's name + """ return self.name class Subuser(object): - + """ + Represents a searchable subuser to be used in a SubuserStats object + """ def __init__(self, name=None): + """Create a Subuser object + + :param name: name of subuser, defaults to None + :type name: string, optional + """ self._name = None if name is not None: self._name = name @property def name(self): + """Get name of the subuser + + :rtype: string + """ return self._name @name.setter def name(self, value): + """Set name of the subuser + + :param value: name of the subuser + :type value: string + """ self._name = value def get(self): + """ + Get a string representation of Subuser. + + :return: string of the subuser's name + """ return self.name