pipolars.PIClient¶

class pipolars.PIClient[source]¶

Bases: object

Main client for extracting PI System data as Polars DataFrames.

This is the primary interface for the PIPolars library. It provides a high-level API for querying PI Points, AF Attributes, and Event Frames, returning data as Polars DataFrames.

Example

>>> # Connect to PI Server
>>> with PIClient("my-pi-server") as client:
...     # Get recorded values as DataFrame
...     df = client.recorded_values("SINUSOID", start="*-1d", end="*")
...     print(df)
...
...     # Get multiple tags at once
...     df = client.recorded_values(
...         ["TAG1", "TAG2", "TAG3"],
...         start="*-1h",
...         end="*"
...     )
...
...     # Get summary statistics
...     summaries = client.summaries(
...         "SINUSOID",
...         start="*-7d",
...         end="*",
...         summary_types=[SummaryType.AVERAGE, SummaryType.MAXIMUM]
...     )

>>> # Using configuration
>>> config = PIConfig(
...     server=PIServerConfig(host="my-pi-server"),
...     cache=CacheConfig(backend=CacheBackend.SQLITE),
... )
>>> client = PIClient(config=config)

__init__(server=None, config=None, enable_cache=True)[source]¶

Initialize the PI client.

Parameters:

server (str | PIServerConfig | None) – PI Server hostname or configuration
config (PIConfig | None) – Full PIPolars configuration
enable_cache (bool) – Whether to enable caching

Methods

`__init__`([server, config, enable_cache])	Initialize the PI client.
`cache_stats`()	Get cache statistics.
`clear_cache`()	Clear all cached data.
`connect`()	Connect to the PI Server.
`disconnect`()	Disconnect from the PI Server.
`interpolated_values`(tags, start, end[, ...])	Get interpolated values at regular intervals.
`last`(tags[, hours, days, minutes])	Get recorded values for the last N hours/days/minutes.
`plot_values`(tag, start, end[, intervals, ...])	Get values optimized for plotting.
`query`(tags)	Create a query builder for the specified tags.
`recorded_values`(tags, start, end[, ...])	Get recorded values for one or more tags.
`search_tags`(pattern[, max_results])	Search for PI Points matching a pattern.
`snapshot`(tag)	Get the current snapshot value for a tag.
`snapshots`(tags)	Get current snapshot values for multiple tags.
`summaries`(tag, start, end, interval[, ...])	Get summary statistics over multiple intervals.
`summary`(tags, start, end[, summary_types])	Get summary statistics for one or more tags.
`tag_exists`(tag)	Check if a tag exists.
`tag_info`(tag)	Get metadata for a tag.
`today`(tags, **kwargs)	Get recorded values for today.

Attributes

`config`	Get the client configuration.
`is_connected`	Check if connected to PI Server.
`server_name`	Get the connected server name.

__init__(server=None, config=None, enable_cache=True)[source]¶

Initialize the PI client.

Parameters:

server (str | PIServerConfig | None) – PI Server hostname or configuration
config (PIConfig | None) – Full PIPolars configuration
enable_cache (bool) – Whether to enable caching

property config: PIConfig¶: Get the client configuration.

property is_connected: bool¶: Check if connected to PI Server.

property server_name: str | None¶: Get the connected server name.

connect()[source]¶

Connect to the PI Server.

Returns:: Self for method chaining
Return type:: PIClient

disconnect()[source]¶

Disconnect from the PI Server.

__enter__()[source]¶

Context manager entry.

__exit__(exc_type, exc_val, exc_tb)[source]¶

Context manager exit.

query(tags)[source]¶

Create a query builder for the specified tags.

Parameters:: tags (str | list[str]) – Single tag or list of tags to query
Returns:: PIQuery builder for method chaining
Return type:: PIQuery

Example

>>> df = client.query("SINUSOID") \
...     .time_range("*-1d", "*") \
...     .recorded() \
...     .to_dataframe()

snapshot(tag)[source]¶

Get the current snapshot value for a tag.

Parameters:: tag (str) – PI Point name
Returns:: DataFrame with single row containing current value
Return type:: DataFrame

snapshots(tags)[source]¶

Get current snapshot values for multiple tags.

Parameters:: tags (list[str]) – List of PI Point names
Returns:: DataFrame with current values for all tags
Return type:: DataFrame

recorded_values(tags, start, end, max_count=0, include_quality=False, pivot=False)[source]¶

Get recorded values for one or more tags.

Parameters:

tags (str | list[str]) – Single tag or list of tags
start (PITimestamp) – Start time
end (PITimestamp) – End time
max_count (int) – Maximum values per tag (0 = no limit)
include_quality (bool) – Include quality column
pivot (bool) – Pivot to wide format (tags as columns)

Returns:

DataFrame with recorded values

Return type:

pl.DataFrame

interpolated_values(tags, start, end, interval='1h', include_quality=False, pivot=False)[source]¶

Get interpolated values at regular intervals.

Parameters:

tags (str | list[str]) – Single tag or list of tags
start (PITimestamp) – Start time
end (PITimestamp) – End time
interval (str) – Time interval (e.g., “1h”, “15m”, “1d”)
include_quality (bool) – Include quality column
pivot (bool) – Pivot to wide format

Returns:

DataFrame with interpolated values

Return type:

pl.DataFrame

plot_values(tag, start, end, intervals=640, include_quality=False)[source]¶

Get values optimized for plotting.

Parameters:

tag (str) – PI Point name
start (PITimestamp) – Start time
end (PITimestamp) – End time
intervals (int) – Number of intervals
include_quality (bool) – Include quality column

Returns:

DataFrame with plot-optimized values

Return type:

pl.DataFrame

summary(tags, start, end, summary_types=SummaryType.AVERAGE)[source]¶

Get summary statistics for one or more tags.

Parameters:

tags (str | list[str]) – Single tag or list of tags
start (PITimestamp) – Start time
end (PITimestamp) – End time
summary_types (SummaryType | list[SummaryType]) – Summary type(s) to calculate

Returns:

DataFrame with summary statistics

Return type:

pl.DataFrame

summaries(tag, start, end, interval, summary_types=SummaryType.AVERAGE)[source]¶

Get summary statistics over multiple intervals.

Parameters:

tag (str) – PI Point name
start (PITimestamp) – Start time
end (PITimestamp) – End time
interval (str) – Interval for each summary
summary_types (SummaryType | list[SummaryType]) – Summary type(s) to calculate

Returns:

DataFrame with time-series summary statistics

Return type:

pl.DataFrame

search_tags(pattern, max_results=1000)[source]¶

Search for PI Points matching a pattern.

Parameters:

pattern (str) – Search pattern (supports wildcards)
max_results (int) – Maximum results

Returns:

List of matching tag names

Return type:

list[str]

tag_exists(tag)[source]¶

Check if a tag exists.

Parameters:: tag (str) – PI Point name
Returns:: True if the tag exists
Return type:: bool

tag_info(tag)[source]¶

Get metadata for a tag.

Parameters:: tag (str) – PI Point name
Returns:: Dictionary with tag metadata
Return type:: dict[str, Any]

cache_stats()[source]¶

Get cache statistics.

Returns:: Dictionary with cache stats
Return type:: dict[str, Any]

clear_cache()[source]¶

Clear all cached data.

last(tags, hours=0, days=0, minutes=0, **kwargs)[source]¶

Get recorded values for the last N hours/days/minutes.

Parameters:

tags (str | list[str]) – Single tag or list of tags
hours (int) – Number of hours
days (int) – Number of days
minutes (int) – Number of minutes
**kwargs (Any) – Additional arguments for recorded_values

Returns:

DataFrame with recorded values

Return type:

DataFrame

Example

>>> df = client.last("SINUSOID", hours=24)
>>> df = client.last(["TAG1", "TAG2"], days=7)

today(tags, **kwargs)[source]¶

Get recorded values for today.

Parameters:

tags (str | list[str]) – Single tag or list of tags
**kwargs (Any) – Additional arguments for recorded_values

Returns:

DataFrame with today’s values

Return type:

DataFrame