PIconnect.PI module#

class PIconnect.PI.PIServer(server: str | None = None, username: str | None = None, password: str | None = None, domain: str | None = None, authentication_mode: AuthenticationMode = AuthenticationMode.PI_USER_AUTHENTICATION, timeout: int | None = None)#

Bases: object

PIServer is a connection to an OSIsoft PI Server.

Parameters:

  • (str (password)

  • optional) (the maximum seconds an operation can take)

  • (str

  • optional)

  • (str

  • optional)

  • todo (domain, auth)

  • (int (timeout)

  • optional)

Note

If the specified server is unknown a warning is thrown and the connection is redirected to the default server, as if no server was passed. The list of known servers is available in the PIServer.servers dictionary.

servers Dictionary of known servers, as reported by the SDK#

Dictionary of known servers, as reported by the SDK

default_server Default server, as reported by the SDK#

Default server, as reported by the SDK

search(query: str | List[str], source: str | None = None) → List[PIPoint]#

Search PIPoints on the PIServer.

Parameters:

  • [str]) (query (str or)

  • (str (source)

  • optional) (Defaults to None. Point source to limit the results)

Returns:

list

Return type:

A list of PIPoint objects as a result of the query

Todo

Reject searches while not connected

property server_name#

Name of the connected server.

version = '0.2.2'#
class PIconnect.PI.PIPoint(pi_point: PIPoint)#

Bases: PISeriesContainer

Reference to a PI Point to get data and corresponding metadata from the server.

Parameters:

(AF.PI.PIPoint) (pi_point)

property created#

Return the creation datetime of a point.

property current_value: Any#

Return the current value of the attribute.

property description#

Return the description of the PI Point.

Todo

Add setter to alter displayed description

filtered_summaries(start_time: str | datetime, end_time: str | datetime, interval: str, filter_expression: str, summary_types: SummaryType, calculation_basis: CalculationBasis = CalculationBasis.TIME_WEIGHTED, filter_evaluation: ExpressionSampleType = ExpressionSampleType.EXPRESSION_RECORDED_VALUES, filter_interval: str | None = None, time_type: TimestampCalculation = TimestampCalculation.AUTO) → <MagicMock id='140363398592752'>#

Return one or more summary values for each interval within a time range.

Parameters:

  • datetime) (end_time (str or) – from which to retrieve the values. This is parsed, together with end_time, using AF.Time.AFTimeRange.

  • datetime) – until which to retrieve values. This is parsed, together with start_time, using AF.Time.AFTimeRange.

  • (str) (interval) – data. This is parsed using AF.Time.AFTimeSpan.Parse.

  • (str (filter_interval) – data to include in the results. See Filtering values for more information on filter queries.

  • optional) (String containing the interval at) – data to include in the results. See Filtering values for more information on filter queries.

  • PIConsts.SummaryType) (summary_types (int or) – of the data within the requested time range.

  • PIConsts.CalculationBasis (calculation_basis (int or) – Event weighting within an interval. See Event weighting and CalculationBasis for more information. Defaults to CalculationBasis.TIME_WEIGHTED.

  • optional) – Event weighting within an interval. See Event weighting and CalculationBasis for more information. Defaults to CalculationBasis.TIME_WEIGHTED.

  • PIConsts.ExpressionSampleType (filter_evaluation (int or) – Determines whether the filter is applied to the raw events in the database, of if it is applied to an interpolated series with a regular interval. Defaults to ExpressionSampleType.EXPRESSION_RECORDED_VALUES.

  • optional) – Determines whether the filter is applied to the raw events in the database, of if it is applied to an interpolated series with a regular interval. Defaults to ExpressionSampleType.EXPRESSION_RECORDED_VALUES.

  • (str – which to extract apply the filter. This is parsed using AF.Time.AFTimeSpan.Parse.

  • optional) – which to extract apply the filter. This is parsed using AF.Time.AFTimeSpan.Parse.

  • PIConsts.TimestampCalculation (time_type (int or) – Timestamp to return for each of the requested summaries. See Summary timestamps and TimestampCalculation for more information. Defaults to TimestampCalculation.AUTO.

  • optional) – Timestamp to return for each of the requested summaries. See Summary timestamps and TimestampCalculation for more information. Defaults to TimestampCalculation.AUTO.

Returns:

pandas.DataFrame – and the summary name as column name.

Return type:

Dataframe with the unique timestamps as row index

interpolated_value(time: str | datetime) → <MagicMock name='mock.__getitem__()' id='140363388746352'>#

Return a PISeries with an interpolated value at the given time.

Parameters:

  • ----------eters

  • ----------

  • ----------eters

  • ---------- –

    time (str, datetime): String containing the date, and possibly time,

    for which to retrieve the value. This is parsed, using AF.Time.AFTime.

Returns:

PISeries – the index

Return type:

A PISeries with a single row, with the corresponding time as

interpolated_values(start_time: str | datetime, end_time: str | datetime, interval: str, filter_expression: str = '') → <MagicMock name='mock.__getitem__()' id='140363388746352'>#

Return a PISeries of interpolated data.

Data is returned between start_time and end_time at a fixed interval. All three values are parsed by AF.Time and the first two allow for time specification relative to “now” by use of the asterisk.

filter_expression is an optional string to filter the returned values, see OSIsoft PI documentation for more information.

The AF SDK allows for inclusion of filtered data, with filtered values marked as such. At this point PIconnect does not support this and filtered values are always left out entirely.

Parameters:

  • datetime) (end_time (str or) – from which to retrieve the values. This is parsed, together with end_time, using AF.Time.AFTimeRange.

  • datetime) – until which to retrieve values. This is parsed, together with start_time, using AF.Time.AFTimeRange.

  • (str) (interval) – data. This is parsed using AF.Time.AFTimeSpan.Parse.

  • (str (filter_expression) – data to include in the results. See Filtering values for more information on filter queries.

  • optional) (Defaults to ''. Query on which) – data to include in the results. See Filtering values for more information on filter queries.

Returns:

PISeries

Return type:

Timeseries of the values returned by the SDK

property last_update#

Return the time at which the last value for this PI Point was recorded.

property name: str#

Return the name of the PI Point.

property raw_attributes: Dict[str, Any]#

Return a dictionary of the raw attributes of the PI Point.

recorded_value(time: str | datetime, retrieval_mode: RetrievalMode = RetrievalMode.AUTO) → <MagicMock name='mock.__getitem__()' id='140363388746352'>#

Return a PISeries with the recorded value at or close to the given time.

Parameters:

(str) (time) – for which to retrieve the value. This is parsed, using AF.Time.AFTime.

:param retrieval_mode (int or PIConsts.RetrievalMode): which value to return if no value available at the exact requested

time.

:type retrieval_mode (int or PIConsts.RetrievalMode): Flag determining

Returns:

PISeries – the index

Return type:

A PISeries with a single row, with the corresponding time as

recorded_values(start_time: str | datetime, end_time: str | datetime, boundary_type: str = 'inside', filter_expression: str = '')#

Return a PISeries of recorded data.

Data is returned between the given start_time and end_time, inclusion of the boundaries is determined by the boundary_type attribute. Both start_time and end_time are parsed by AF.Time and allow for time specification relative to “now” by use of the asterisk.

By default the boundary_type is set to ‘inside’, which returns from the first value after start_time to the last value before end_time. The other options are ‘outside’, which returns from the last value before start_time to the first value before end_time, and ‘interpolate’, which interpolates the first value to the given start_time and the last value to the given end_time.

filter_expression is an optional string to filter the returned values, see OSIsoft PI documentation for more information.

The AF SDK allows for inclusion of filtered data, with filtered values marked as such. At this point PIconnect does not support this and filtered values are always left out entirely.

Parameters:

  • datetime) (end_time (str or) – from which to retrieve the values. This is parsed, together with end_time, using AF.Time.AFTimeRange.

  • datetime) – until which to retrieve values. This is parsed, together with start_time, using AF.Time.AFTimeRange.

  • (str (filter_expression) – __boundary_types dictionary to describe how to handle the boundaries of the time range.

  • optional) (Defaults to ''. Query on which) – __boundary_types dictionary to describe how to handle the boundaries of the time range.

  • (str – data to include in the results. See Filtering values for more information on filter queries.

  • optional) – data to include in the results. See Filtering values for more information on filter queries.

Returns:

PISeries

Return type:

Timeseries of the values returned by the SDK

Raises:

ValueError – If the provided boundary_type is not a valid key a: ValueError is raised.

summaries(start_time: str | datetime, end_time: str | datetime, interval: str, summary_types: SummaryType, calculation_basis: CalculationBasis = CalculationBasis.TIME_WEIGHTED, time_type: TimestampCalculation = TimestampCalculation.AUTO) → <MagicMock id='140363397159808'>#

Return one or more summary values for each interval within a time range.

Parameters:

  • datetime) (end_time (str or) – from which to retrieve the values. This is parsed, together with end_time, using AF.Time.AFTimeRange.

  • datetime) – until which to retrieve values. This is parsed, together with start_time, using AF.Time.AFTimeRange.

  • (str) (interval) – data. This is parsed using AF.Time.AFTimeSpan.Parse.

  • PIConsts.SummaryType) (summary_types (int or) – of the data within the requested time range.

  • PIConsts.CalculationBasis (calculation_basis (int or) – Event weighting within an interval. See Event weighting and CalculationBasis for more information. Defaults to CalculationBasis.TIME_WEIGHTED.

  • optional) – Event weighting within an interval. See Event weighting and CalculationBasis for more information. Defaults to CalculationBasis.TIME_WEIGHTED.

  • PIConsts.TimestampCalculation (time_type (int or) – Timestamp to return for each of the requested summaries. See Summary timestamps and TimestampCalculation for more information. Defaults to TimestampCalculation.AUTO.

  • optional) – Timestamp to return for each of the requested summaries. See Summary timestamps and TimestampCalculation for more information. Defaults to TimestampCalculation.AUTO.

Returns:

pandas.DataFrame – and the summary name as column name.

Return type:

Dataframe with the unique timestamps as row index

summary(start_time: str | datetime, end_time: str | datetime, summary_types: SummaryType, calculation_basis: CalculationBasis = CalculationBasis.TIME_WEIGHTED, time_type: TimestampCalculation = TimestampCalculation.AUTO) → <MagicMock id='140363397277424'>#

Return one or more summary values over a single time range.

Parameters:

  • datetime) (end_time (str or) – from which to retrieve the values. This is parsed, together with end_time, using AF.Time.AFTimeRange.

  • datetime) – until which to retrieve values. This is parsed, together with start_time, using AF.Time.AFTimeRange.

  • PIConsts.SummaryType) (summary_types (int or) – of the data within the requested time range.

  • PIConsts.CalculationBasis (calculation_basis (int or) – Event weighting within an interval. See Event weighting and CalculationBasis for more information. Defaults to CalculationBasis.TIME_WEIGHTED.

  • optional) – Event weighting within an interval. See Event weighting and CalculationBasis for more information. Defaults to CalculationBasis.TIME_WEIGHTED.

  • PIConsts.TimestampCalculation (time_type (int or) – Timestamp to return for each of the requested summaries. See Summary timestamps and TimestampCalculation for more information. Defaults to TimestampCalculation.AUTO.

  • optional) – Timestamp to return for each of the requested summaries. See Summary timestamps and TimestampCalculation for more information. Defaults to TimestampCalculation.AUTO.

Returns:

pandas.DataFrame – and the summary name as column name.

Return type:

Dataframe with the unique timestamps as row index

property units_of_measurement: str | None#

Return the units of measument in which values for this PI Point are reported.

update_value(value: Any, time: str | datetime | None = None, update_mode: UpdateMode = UpdateMode.NO_REPLACE, buffer_mode: BufferMode = BufferMode.BUFFER_IF_POSSIBLE) → None#

Update value for existing PI object.

Parameters:

  • value (value type should be in cohesion with PI object or) – it will raise PIException: [-10702] STATE Not Found

  • (datetime (time) – it raises PIException: [-11046] Target Date in Future.

  • optional) (it is not possible to set future value,) – it raises PIException: [-11046] Target Date in Future.

You can combine update_mode and time to change already stored value.

version = '0.3.0'#
On this page
Show Source