Added get_summary_values on DataApi class

Author: osimloeff

CONTRIBUTING.md

@@ -0,0 +1,49 @@
+
+Contributing to any PI Web API client library for Python
+============================
+
+
+How to contribute
+-----------------
+
+The preferred workflow for contributing to scikit-learn is to fork the
+main repository on GitHub, clone, and develop on a branch. Steps:
+
+1. Fork the project repository by clicking on the 'Fork' button near the top right of the page. This creates
+   a copy of the code under your GitHub user account. For more details on
+   how to fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/).
+
+2. Clone your fork of the osimloeff repo from your GitHub account to your local disk:
+
+   ```bash
+   $ git clone [email protected]:YourLogin/PI-Web-API-Client-Python.git
+   $ cd PI-Web-API-Client-Python
+   ```
+
+3. Create a ``feature`` branch to hold your development changes:
+
+   ```bash
+   $ git checkout -b my-feature
+   ```
+
+   Always use a ``feature`` branch. It's good practice to never work on the ``master`` branch!
+
+4. Develop the feature on your feature branch. Add changed files using ``git add`` and then ``git commit`` files:
+
+   ```bash
+   $ git add modified_files
+   $ git commit
+   ```
+
+   to record your changes in Git, then push the changes to your GitHub account with:
+
+   ```bash
+   $ git push -u origin my-feature
+   ```
+
+5. Follow [these instructions](https://help.github.com/articles/creating-a-pull-request-from-a-fork) or [this video](https://www.youtube.com/watch?v=YTbRzhQju4c)
+to create a pull request from your fork. This will send an email to the committers.
+
+(If any of the above seems like magic to you, please look up the
+[Git documentation](https://git-scm.com/documentation) on the web, or ask a friend or another contributor for help.)
+

README.md

@@ -50,6 +50,11 @@ All classes and methods are described on the [DOCUMENTATION](DOCUMENTATION.md).
 
  - Is is highly recommended to turn debug mode on in case you are using PI Web API 2017 R2+ in order to receive more detailed exception errors. This can be achieved by creating or editing the DebugMode attribute's value to TRUE from the System Configuration element.
  - The X-Requested-With header is added to work with CSRF defences.
+
+
+## Contributing
+
+We welcome new contributors of all experience levels. Please follow our [this page](https://github.com/osimloeff/PI-Web-API-Client-Python/blob/master/CONTRIBUTING.MD) to learn how to do it.
 
 ## Examples
 

docs/api/DataApi.md

@@ -5,6 +5,7 @@ Method | HTTP request | Description
 [**get_recorded_values**](DataApi.md#get_recorded_values) |  Returns a pandas dataframe with compressed values for the requested time range from the source provider.
 [**get_interpolated_values**](DataApi.md#get_interpolated_values) | Retrieves a pandas dataframe with interpolated values over the specified time range at the specified sampling interval.
 [**get_plot_values**](DataApi.md#get_plot_values*) | Retrieves a pandas dataframe with values over the specified time range suitable for plotting over the number of intervals (typically represents pixels).
+[**get_summary_values**](DataApi.md#get_summary_values*) | Returns a data frame with the summary over the specified time range for the stream.
 [**get_multiple_recorded_values**](DataApi.md#get_multiple_recorded_values) | Returns an array of pandas dataframe with recorded values of the specified streams.
 [**get_multiple_interpolated_values**](DataApi.md#get_multiple_interpolated_values) | Returns a dataframe with interpolated values of the specified streams over the specified time range at the specified sampling interval.
 [**get_multiple_plot_values**](DataApi.md#get_multiple_plot_values) |  Returns a pandas dataframe with values of the specified streams over the specified time range suitable for plotting over the number of intervals (typically represents pixels).
@@ -93,6 +94,35 @@ Pandas Dataframe
 [[Back to top]](#) [[Back to API list]](../../DOCUMENTATION.md#documentation-for-api-endpoints) [[Back to Model list]](../../DOCUMENTATION.md#documentation-for-models) [[Back to DOCUMENTATION]](../../DOCUMENTATION.md)
 
 
+# **get_summary_values**
+> get_summary('path', 'calculation_basis', 'end_time', 'filter_expression', 'sample_interval', 'sample_type', 'selected_fields', 'start_time', 'summary_duration', 'summary_type', 'time_type', 'time_zone')
+
+Returns a data frame with the summary over the specified time range for the stream.
+
+### Parameters
+
+Name | Type | Description | Notes
+------------- | ------------- | ------------- | -------------
+ **path** | **list[str]**| The paths of  multiple streams (for a PI Point use "pi:\\servername\pointname" or "af:\\afservername\database\element|attribute" for an attribute). | [required]
+ **calculation_basis** | **str**| Specifies the method of evaluating the data over the time range. The default is 'TimeWeighted'.. | [optional]
+ **end_time** | **str**| An optional end time. The default is '*' for element attributes and points. For event frame attributes, the default is the event frame's end time, or '*' if that is not set. Note that if endTime is earlier than startTime, the resulting values will be in time-descending order.. | [optional]
+ **filter_expression** | **str**| A string containing a filter expression. Expression variables are relative to the attribute. Use '.' to reference the containing attribute.. | [optional]
+ **sample_interval** | **str**| When the sampleType is Interval, sampleInterval specifies how often the filter expression is evaluated when computing the summary for an interval.. | [optional]
+ **sample_type** | **str**| Defines the evaluation of an expression over a time range. The default is 'ExpressionRecordedValues'.. | [optional]
+ **selected_fields** | **str**| List of fields to be returned in the response, separated by semicolons (;). If this parameter is not specified, all available fields will be returned.. | [optional]
+ **start_time** | **str**| An optional start time. The default is '*-1d' for element attributes and points. For event frame attributes, the default is the event frame's start time, or '*-1d' if that is not set.. | [optional]
+ **summary_duration** | **str**| The duration of each summary interval. If specified in hours, minutes, seconds, or milliseconds, the summary durations will be evenly spaced UTC time intervals. Longer interval types are interpreted using wall clock rules and are time zone dependent.. | [optional]
+ **summary_type** | **list[str]**| Specifies the kinds of summaries to produce over the range. The default is 'Total'. Multiple summary types may be specified by using multiple instances of summaryType.. | [optional]
+ **time_type** | **str**| Specifies how to calculate the timestamp for each interval. The default is 'Auto'.. | [optional]
+ **time_zone** | **str**| The time zone in which the time string will be interpreted. This parameter will be ignored if a time zone is specified in the time string. If no time zone is specified in either places, the PI Web API server time zone will be used.. | [optional]
+
+
+### Return type
+
+[**PIItemsSummaryValue**](../models/PIItemsSummaryValue.md)
+
+[[Back to top]](#) [[Back to API list]](../../DOCUMENTATION.md#documentation-for-api-endpoints) [[Back to Model list]](../../DOCUMENTATION.md#documentation-for-models) [[Back to DOCUMENTATION]](../../DOCUMENTATION.md)
+
 
 # **get_multiple_recorded_values**
 > get_multiple_recorded_values('path', 'boundary_type', 'end_time', 'filter_expression', 'include_filtered_values', 'max_count', 'selected_fields', 'start_time', 'time_zone')

osisoft/pidevclub/piwebapi/api/data_api.py

@@ -92,7 +92,87 @@ def convert_multiple_streams_to_df(self, items, gatherInOneDataFrame, web_ids, s
 				dfs[key] = df
 			return dfs
 
+	def convert_summary_to_df(self, items, selected_fields):
 
+		if (items is None):
+			raise Exception('The returned data is Null or None')
+
+		streamsLength = len(items)
+		if (streamsLength == 0):
+			raise Exception('The returned data is Null or None')
+
+
+		addValues = False
+		addTimeStamp = False
+		addUnitAbbr = False
+		addGood = False
+		addQuestionable = False
+		addSubstituted = False
+		value = []
+		timestamp = []
+		unitsAbbreviation = []
+		good = []
+		questionable = []
+		substituted = []
+		summaryType = []
+
+		if (selected_fields != None and selected_fields != ""):
+			if ("timestamp" in selected_fields):
+				addTimeStamp = True
+			if ("value" in selected_fields):
+				addValues = True
+
+			if ("questionable" in selected_fields):
+				addQuestionable = True
+
+			if ("unitabbr" in selected_fields):
+				addUnitAbbr = True
+
+			if ("good" in selected_fields):
+				addGood = True
+
+			if ("substituted" in selected_fields):
+				addSubstituted = True
+		else:
+			addValues = True
+			addTimeStamp = True
+			addUnitAbbr = True
+			addGood = True
+			addQuestionable = True
+			addSubstituted = True
+
+
+		for	item in items:
+			summaryType.append(item.type)
+			if (addValues == True):
+				value.append(item.value.value)
+			if (addTimeStamp == True):
+				timestamp.append(item.value.timestamp)
+			if (addUnitAbbr == True):
+				unitsAbbreviation.append(item.value.units_abbreviation)
+			if (addGood == True):
+				good.append(item.value.good)
+			if (addQuestionable == True):
+				questionable.append(item.value.questionable)
+			if addSubstituted == True:
+				substituted.append(item.value.substituted)
+
+		data = {}
+		data['SummaryType'] = summaryType
+		if (addValues == True):
+			data['Value'] = value;
+		if (addTimeStamp == True):
+			data['Timestamp'] = timestamp;
+		if (addUnitAbbr == True):
+			data['UnitsAbbreviation'] = unitsAbbreviation;
+		if (addGood == True):
+			data['Good'] = good;
+		if (addQuestionable == True):
+			data['Questionable'] = questionable;
+		if (addSubstituted == True):
+			data['Substituted'] = substituted;
+		df = pd.DataFrame(data)
+		return df
 
 	def convert_to_df(self, items, selected_fields):
 
@@ -171,7 +251,7 @@ def convert_to_df(self, items, selected_fields):
 		if (addSubstituded == True):
 			data['Substituted'] = substituted;
 		df = pd.DataFrame(data)
-		return  df
+		return df
 
 	def get_recorded_values(self, path, boundary_type=None, desired_units=None, end_time="*", filter_expression=None, include_filtered_values=None, max_count=None, selected_fields=None, start_time="*-1h", time_zone=None):
 		if (path is None):
@@ -206,6 +286,18 @@ def get_plot_values(self, path, desired_units=None, end_time="*", intervals = 10
 		df = self.convert_to_df(res.items, selected_fields)
 		return df
 
+	def get_summary_values(self, path, calculation_basis='TimeWeighted', end_time="*", filter_expression=None, sample_interval=None, sample_type='ExpressionRecordedValues', selected_fields=None, start_time="*-1d", summary_duration=None, summary_type=['Total'], time_type='Auto', time_zone=None):
+		if (path is None):
+			print("The variable path cannot be null.")
+			return
+
+		web_id = self.convert_path_to_web_id(path)
+		res = self.streamApi.get_summary(web_id, calculation_basis, end_time, filter_expression,
+										 sample_interval, sample_type, selected_fields, start_time, summary_duration,
+										 summary_type, time_type, time_zone)
+		df = self.convert_summary_to_df(res.items, selected_fields)
+		return df
+
 	def get_multiple_interpolated_values(self, paths, end_time="*", filter_expression=None, include_filtered_values=None, interval="1h", selected_fields=None, sort_field=None, sort_order=None, start_time="*-1d", sync_time=None, sync_time_boundary_type=None, time_zone=None, web_id_type=None):
 		if (paths is None):
 			print("The variable paths cannot be null.")

setup.py

@@ -18,7 +18,7 @@
 from setuptools import setup, find_packages
 
 NAME = "osisoft.pidevclub.piwebapi"
-VERSION = "1.11.0"
+VERSION = "1.11.1"
 # To install the library, run the following
 #
 # python setup.py install

test/test_data.py

@@ -72,6 +72,14 @@ def test_data_recorded(self):
         df12 = client.data.get_plot_values("af:\\\\PISRV1\\Universities\\UC Davis\\Buildings\\Academic Surge Building\\Electricity|AnnualUsage", None, "*", 20, None, "*-40d", None)
         pass
 
+    def test_data_summary(self):
+        client = self.getPIWebApiClient()
+        df1 = client.data.get_summary_values("pi:\\\\PISRV1\\sinusoid", start_time="*-1d", end_time="*",
+                                             summary_type=['Average'], summary_duration='1h')
+        df2 = client.data.get_summary_values("pi:\\\\PISRV1\\sinusoid", start_time="*-1d", end_time="*",
+                                             summary_type=['Average', 'Total'], summary_duration='1h')
+        pass
+
     def test_getExceptionError(self):
         client = self.getPIWebApiClient()
         paths=["pi:\\\\PISRV1\\sinusoid", "pi:\\\\PISRV1\\sinusoidu", "pi:\\\\PISRV1\\cdt158"]