Working SSO for Aspen Web API

Fixed

The URL for Equinor's Aspen Web API has been modified to point to a new API endpoint that supports Kerberos authentication. There is no need to use NTLM authentication for Aspen Web API connections anymore.

Fix handling of missing data

Fixed

Missing data from ODBC handlers are now returned as NaN instead of None. This fixes a couple of cache-related potential crash situations when consecutive reads alternate between returning None and valid data.

Add method for raw SQL queries

This release introduces experimental new functionality that allows advanced users to perform raw SQL queries. Results can be returned as dataframe or cursor object. More details in the manual.

Added

• New client method query_sql() for performing raw SQL queries to ODBC handlers and for aspenone.

Fix empty columns for missing data

In some cases read() would return a completely empty dataframe without column name if a tag has no data in the timeframe specified. This would happen even for completely valid tags.

This release improves the situation somewhat as it should guarantee that a column with the tagname is included in the result. The content of the column can consist of None, NaN or be completely empty. The result depends on the handler, whether the tag is queried alone or alongside other tags that do have data for the time frame, and even the tag itself.

At least for now it is up to the user to handle these various cases appropriately.

Fixed

• Improved return values from read() for tags with no data in specified time frame.
• Added requests_ntlm as requirement.

Fix long sample times

Fixed

• Handling of sample times one day or longer should now work as expected.

Allow host + port specification

For some installations, the relevant Windows registry entries containing mapping from ODBC datasource to host and port do not exist. E.g. servers or old installations.

This release allows the user to explicitly specify the parameters host and port on client creation, thus skipping the registry search. If only host is provided, port will be set to a default value (10014 for IP21, 5450 for PI).

Added

• Optional arguments host and port to IMSClient class. Only relevant for ODBC handlers.

Raw data added

Support for reading raw data.

Due to structural difference in time-vector for raw data compared to fixed-interval data such as INT, VAR etc, the cache is disabled for raw data. The caching mechanism will be rewritten for a later release.

Added

• ReaderType.RAW now supported as read_type for all handlers.

Changed

• Rewritten tag reading mechanism by moving responsibility for limiting amount of data points returned from client to handler. Client now investigates length of returned result to determine start time of next query, instead of querying predetermined fixed-length intervals. This makes a more unified read algorithm for fixed-length intervals (such as INT) and uneven time series (such as RAW).
• Reduced max rows per query from PI Web API to default value 10000.

Fixed

• Warn instead of crash when user tries to read an invalid tag.

Snapshots added

Support for reading snapshots/final/last values.

Added

• ReaderType.SNAPSHOT now supported as read_type for all handlers.

Changed

• Renamed the read() input argument stop_time to end_time. This may break some scripts if stop_time was used as keyword argument.
• The read() input arguments start_time, end_time and ts are now keyword arguments instead of positional. ts has a default value of 60 seconds, while the time arguments are default null.

Web APIs

The main change in this release is the added support for connecting to PI Web API and AspenTech Process Data REST Web API. This means that in most cases it is no longer required to install the proprietary ODBC drivers, which in many cases turns out to be be quite painful. Simply select one of the two new handlers and connect to the REST APIs. In addition time zone handling has been improved, and the client presents the backends in a more unified way to the user.

Added

• Add two more handlers for the Web APIs: piwebapi and aspenone.
• Add tagreader class method list_servers() to cover all four handlers.
• Add a user manual, reduce amount of content in quickstart.

Changed

• Rename IMSClient method read_tags() to read().
• Improve handling of timezones when calling read():
  • Queries to servers are always done in UTC.
  • Time zone aware timestamps are converted to UTC before query.
  • Time zone naive timestamps are assumed to belong in the timezone specified by the input argument tz (default "Europe/Oslo").
  • Returned data points are converted to the timezone specified by tz.
• Aggregated data (AVG, MIN, MAX etc) timestamps are are always anchored at the start of the aggregation interval.

Deprecated

• Deprecate tagreader class methods list_pi_servers() and list_aspen_servers() (replaced with list_servers()).
• Deprecate the IMSClient method read_tags() (renamed to read()).

Better map handling

Improved handling of tags with maps for Aspen IP.21.

Fixed

• Allow tag search with tagname and description.
• Fix fetching of correct unit for tags with map.
• Fix fetching of correct description for tags with map.