Client

pingthings.admin.client ¶

CLASS	DESCRIPTION
`AdminClient`
`AsyncAdminClient`

FUNCTION	DESCRIPTION
`connect`	Connect to the admin platform.

Classes¶

AdminClient ¶

AdminClient(
    pyo3_client,
    loop: ClientEventLoop,
    creds: dict[str, str],
)

Bases: object

METHOD	DESCRIPTION
`add_streams_to_my_collection`	Adds streams to a My Collection. If any of the provided streams are already in the
`connect`	Establish a connection to the admin API.
`create_event`	Creates an event.
`create_my_collection`	Creates a new My Collection for the currently authenticated user.
`create_permalink`	Generate a permanent link that can be used for visualization in MR plotter.
`delete_event`	Deletes an event by its ID.
`delete_my_collection`	Deletes a My Collection and all of its child collections. Streams that are
`delete_permalink`	Permanently remove the permalink entry.
`get_event`	Retrieves an event by its ID.
`get_permalink`	Retrieve the data stored by the permalink.
`list_events`	Return all events that match the given criteria paginated by `offset` and `limit`.
`list_my_collections`	Return all custom collections you have created.
`remove_streams_from_my_collection`	Removes streams from a My Collection. If any of the provided streams are not in the
`run_coroutine_to_completion`	Ensure that a coroutine is completely ran.
`update_my_collection`	Updates a My Collection with the provided patch.
`update_permalink`	Modify the data in a permalink.

Functions¶

add_streams_to_my_collection ¶

add_streams_to_my_collection(
    my_collection_uuid: str | UUID,
    stream_uuids: list[str | UUID],
)

Adds streams to a My Collection. If any of the provided streams are already in the collection, they will be ignored.

connect `staticmethod` ¶

connect(
    profile: Optional[str],
    endpoint: Optional[str],
    api_key: Optional[str],
)

Establish a connection to the admin API.

The adminapi is a set of capabilities that are not directly involved with timeseries manipulation like the pingthings.timeseries.Client. This can include features that are admin-level user specific as well as other functionality like custom collection creation and management among others.

PARAMETER	DESCRIPTION
`profile` ¶	The name of a profile containing the required connection information as found in the user's predictive grid credentials file `${HOME}/.predictivegrid/credentials.yaml`. TYPE: `Optional[str]`
`endpoint` ¶	The address and port of the admin endpoint to connect to, e.g. `192.168.1.1:4411`, if not set, will look for the environment variable `$BTRDB_ENDPOINTS` TYPE: `Optional[str]`
`api_key` ¶	The API key used to authenticate requests, if not set, the key is found in the environment variable `$BTRDB_API_KEY`. TYPE: `Optional[str]`

create_event ¶

create_event(
    start_time: datetime | int,
    end_time: Optional[datetime | int] = None,
    stream_uuids: Optional[
        list[str] | list[UUID] | list[str | UUID]
    ] = None,
    group_names: Optional[list[str]] = None,
    source: str | None = None,
    type: str | None = None,
    message: str | None = None,
    title: str | None = None,
) -> dict

Creates an event.

PARAMETER	DESCRIPTION
`start_time` ¶	The start time of the event (datetime.datetime or int representing nanoseconds since epoch) TYPE: `datetime \| int`
`end_time` ¶	The end time of the event (optional, datetime.datetime or int representing nanoseconds since epoch). TYPE: `Optional[datetime \| int]` DEFAULT: `None`
`stream_uuids` ¶	List of stream UUIDs (optional) TYPE: `Optional[list[str] \| list[UUID] \| list[str \| UUID]]` DEFAULT: `None`
`group_names` ¶	List of group names (optional). If not provided, the event will be visible to all groups that the user creating the event is a member of. TYPE: `Optional[list[str]]` DEFAULT: `None`
`source` ¶	What created/identified the event? (optional) TYPE: `str \| None` DEFAULT: `None`
`type` ¶	What kind of event? (optional) TYPE: `str \| None` DEFAULT: `None`
`message` ¶	Longer form description of the event (optional) TYPE: `str \| None` DEFAULT: `None`
`title` ¶	A short title for the event (optional) TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict`	A dictionary representing the created event.

create_my_collection ¶

create_my_collection(
    name: str,
    description: Optional[str] = None,
    parent_my_collection_uuid: Optional[str | UUID] = None,
) -> dict

Creates a new My Collection for the currently authenticated user.

PARAMETER	DESCRIPTION
`name` ¶	The name of the collection TYPE: `str`
`description` ¶	An optional description of the collection TYPE: `Optional[str]` DEFAULT: `None`
`parent_my_collection_uuid` ¶	An optional UUID of a different my collection to use as the parent of the new collection TYPE: `Optional[str \| UUID]` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict`	A dictionary representing the newly created My Collection. It will contain
`dict`	the following keys: - `uuid`: The UUID of the collection - `name`: The name of the collection - `description`: The description of the collection - `parent_my_collection_uuid`: The UUID of the parent collection, or an empty string if there is no parent - stream_uuids: A list of UUIDs of streams that are in the collection

create_permalink ¶

create_permalink(
    data: str, bookmark: bool = False, public: bool = True
) -> Permalink

Generate a permanent link that can be used for visualization in MR plotter.

PARAMETER	DESCRIPTION
`data` ¶	A json string representing the serialized form for MR plotter to render. TYPE: `str`
`bookmark` ¶	Should this permalink be a user-only bookmark? TYPE: `bool` DEFAULT: `False`
`public` ¶	Can all users access this permalink if provided to them (note, this will not give them access to Streams they do not have access to)? TYPE: `bool` DEFAULT: `True`

Returns Core data that represents the permalink for MR plotter to render.

delete_event ¶

delete_event(event_id: str)

Deletes an event by its ID.

PARAMETER	DESCRIPTION
`event_id` ¶	The ID of the event to delete. TYPE: `str`

delete_my_collection ¶

delete_my_collection(my_collection_uuid: str | UUID)

Deletes a My Collection and all of its child collections. Streams that are contained in the collection or any of its children will NOT be deleted.

delete_permalink ¶

delete_permalink(permalink_uuid: str | UUID) -> None

Permanently remove the permalink entry.

PARAMETER	DESCRIPTION
`permalink_uuid` ¶	Identifier of the permalink to remove TYPE: `str \| UUID`

get_event ¶

get_event(event_id: str) -> Optional[dict]

Retrieves an event by its ID.

PARAMETER	DESCRIPTION
`event_id` ¶	The ID of the event to retrieve. TYPE: `str`

RETURNS	DESCRIPTION
`Optional[dict]`	A dictionary representing the event, or None if not found.

get_permalink ¶

get_permalink(permalink_uuid: str | UUID) -> Permalink

Retrieve the data stored by the permalink.

PARAMETER	DESCRIPTION
`permalink_uuid` ¶	Unique identifier of the permalink TYPE: `str \| UUID`

RETURNS	DESCRIPTION
`Permalink`	The permalink and resulting data stored by the permalink.

list_events ¶

list_events(
    start_time: Optional[datetime | int] = None,
    end_time: Optional[datetime | int] = None,
    source_contains: Optional[str] = None,
    type_contains: Optional[str] = None,
    message_contains: Optional[str] = None,
    limit: int = 100,
    offset: int = 0,
    sort_by: str = "start_time",
    sort_desc: bool = False,
    title_contains: Optional[str] = None,
    created_by_contains: Optional[str] = None,
    full_text_search: Optional[str] = None,
) -> tuple[list[dict[str, Any]], int]

Return all events that match the given criteria paginated by offset and limit.

PARAMETER	DESCRIPTION
`start_time` ¶	Events must start at this time or greater than this time. TYPE: `Optional[datetime \| int]` DEFAULT: `None`
`end_time` ¶	Events must end at this time or before this time. TYPE: `Optional[datetime \| int]` DEFAULT: `None`
`source_contains` ¶	Substring case-insensitive filter for the event source. TYPE: `Optional[str]` DEFAULT: `None`
`type_contains` ¶	Substring case-insensitive filter for the event type. TYPE: `Optional[str]` DEFAULT: `None`
`message_contains` ¶	The event must contain this string subset, this uses a case-insensitive substring search. TYPE: `Optional[str]` DEFAULT: `None`
`limit` ¶	How many events to return at once TYPE: `int` DEFAULT: `100`
`offset` ¶	Pagination offset TYPE: `int` DEFAULT: `0`
`sort_by` ¶	What event parameter to sort by? TYPE: `str` DEFAULT: `'start_time'`
`sort_desc` ¶	Should the results be returned descending order by the `sort_by` parameter? TYPE: `bool` DEFAULT: `False`
`title_contains` ¶	Substring case-insensitive filter for the event title. TYPE: `Optional[str]` DEFAULT: `None`
`created_by_contains` ¶	Substring case-insensitive filter for the user that created the event. TYPE: `Optional[str]` DEFAULT: `None`
`full_text_search` ¶	Substring case-insensitive filter across all text fields (title, message, source, type, created_by). TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`tuple[list[dict[str, Any]], int]`	A tuple containing the list of events matching the given criteria and the total count of matching events.

Examples:

Find all events that contain the word 'voltage' (case insensitive):

>>> AdminClient.list_events(message_contains="voltage")

list_my_collections ¶

list_my_collections() -> list[dict]

Return all custom collections you have created.

RETURNS	DESCRIPTION
`list[dict]`	All custom collections you have created.

remove_streams_from_my_collection ¶

remove_streams_from_my_collection(
    my_collection_uuid: str | UUID,
    stream_uuids: list[str | UUID],
)

Removes streams from a My Collection. If any of the provided streams are not in the collection, they will be ignored.

run_coroutine_to_completion ¶

run_coroutine_to_completion(co: Coroutine[Any, Any, Any])

Ensure that a coroutine is completely ran.

update_my_collection ¶

update_my_collection(
    my_collection_uuid: str | UUID, patch: dict[str, str]
) -> dict

Updates a My Collection with the provided patch.

PARAMETER DESCRIPTION

my_collection_uuid ¶

The UUID of the collection to update

TYPE: str | UUID

patch ¶

A dictionary of fields to update. Only fields contained in the dictionary will be updated; all other fields will remain unchanged.

The list of fields that can be updated are: - name: Must be set to a non-empty string - description: Can be set to any string or None - parent_my_collection_uuid: Can be set to a UUID of a different My Collection, or None to make the collection top-level

TYPE: dict[str, str]

RETURNS	DESCRIPTION
`dict`	A dictionary representing the updated My Collection. It will contain
`dict`	the same keys as the `create_my_collection` method.

update_permalink ¶

update_permalink(
    permalink_uuid: str,
    data: str,
    bookmark: bool = False,
    public: bool = True,
    collection_id: str | None = None,
) -> Permalink

Modify the data in a permalink.

PARAMETER	DESCRIPTION
`permalink_uuid` ¶	The identifier of the permalink to modify TYPE: `str`
`data` ¶	Core information that represents the MR plotter view of the data TYPE: `str`
`bookmark` ¶	Should this permalink be a user-only bookmark? TYPE: `bool` DEFAULT: `False`
`public` ¶	Can all users access this permalink if provided to them (note, this will not give them access to Streams they do not have access to)? TYPE: `bool` DEFAULT: `True`
`collection_id` ¶	Nested folder structure like MyCollections. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Permalink`	The updated permalink

AsyncAdminClient ¶

AsyncAdminClient(pyo3_client, creds: dict[str, str])

Bases: object

METHOD	DESCRIPTION
`list_events`	Return all events that match the given criteria paginated by `offset` and `limit`.

Functions¶

list_events `async` ¶

list_events(
    start_time: Optional[datetime | int] = None,
    end_time: Optional[datetime | int] = None,
    source_contains: Optional[str] = None,
    type_contains: Optional[str] = None,
    message_contains: Optional[str] = None,
    limit: int = 100,
    offset: int = 0,
    sort_by: str = "start_time",
    sort_desc: bool = False,
    title_contains: Optional[str] = None,
    created_by_contains: Optional[str] = None,
    full_text_search: Optional[str] = None,
) -> tuple[list[dict[str, Any]], int]

Return all events that match the given criteria paginated by offset and limit.

PARAMETER	DESCRIPTION
`start_time` ¶	Events must start at this time or greater than this time. TYPE: `Optional[datetime \| int]` DEFAULT: `None`
`end_time` ¶	Events must end at this time or before this time. TYPE: `Optional[datetime \| int]` DEFAULT: `None`
`source_contains` ¶	Substring case-insensitive filter for the event source. TYPE: `Optional[str]` DEFAULT: `None`
`type_contains` ¶	Substring case-insensitive filter for the event type. TYPE: `Optional[str]` DEFAULT: `None`
`message_contains` ¶	The event must contain this string subset, this uses a case-insensitive substring search. TYPE: `Optional[str]` DEFAULT: `None`
`limit` ¶	How many events to return at once TYPE: `int` DEFAULT: `100`
`offset` ¶	Pagination offset TYPE: `int` DEFAULT: `0`
`sort_by` ¶	What event parameter to sort by? TYPE: `str` DEFAULT: `'start_time'`
`sort_desc` ¶	Should the results be returned descending order by the `sort_by` parameter? TYPE: `bool` DEFAULT: `False`
`title_contains` ¶	Substring case-insensitive filter for the event title. TYPE: `Optional[str]` DEFAULT: `None`
`created_by_contains` ¶	Substring case-insensitive filter for the user that created the event. TYPE: `Optional[str]` DEFAULT: `None`
`full_text_search` ¶	Substring case-insensitive filter across all text fields (id, title, message, source, type, created_by). TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`tuple[list[dict[str, Any]], int]`	A tuple of (list of events matching the given criteria, total count of matching events).

Examples:

Find all events that contain the word 'voltage' (case insensitive):

>>> await AsyncAdminClient.list_events(message_contains="voltage")

Functions¶

connect ¶

connect(
    profile: Optional[str] = None,
    endpoint: Optional[str] = None,
    api_key: Optional[str] = None,
)

Connect to the admin platform.

Different Endpoint to the Timeseries Client

The endpoint used for the admin client may be different from the timeseries client.

PARAMETER	DESCRIPTION
`profile` ¶	The btrdb profile to use when connecting TYPE: `Optional[str]` DEFAULT: `None`
`endpoint` ¶	The address and port of the admin system to connect to, e.g. `192.168.1.1:2224`, if not set, will look for the environment variable `$BTRDB_ENDPOINTS` TYPE: `Optional[str]` DEFAULT: `None`
`api_key` ¶	The API key to use for authentication. If not set, the key is looked up from the environment variable `$BTRDB_API_KEY`. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
	An instance of the Client class.

Example

import pingthings
admin = pingthings.admin.connect('your_profile', 'localhost:2224', 'your-api-key')
my_collections = admin.list_my_collections()

Client

pingthings.admin.client ¶

Classes¶

AdminClient ¶

Functions¶

add_streams_to_my_collection ¶

connect `staticmethod` ¶

create_event ¶

create_my_collection ¶

create_permalink ¶

delete_event ¶

delete_my_collection ¶

delete_permalink ¶

get_event ¶

get_permalink ¶

list_events ¶

list_my_collections ¶

remove_streams_from_my_collection ¶

run_coroutine_to_completion ¶

update_my_collection ¶

update_permalink ¶

AsyncAdminClient ¶

Functions¶

list_events `async` ¶

Functions¶

connect ¶

`profile` ¶

`endpoint` ¶

`api_key` ¶

Client

pingthings.admin.client ¶

Classes¶

AdminClient ¶

Functions¶

add_streams_to_my_collection ¶

connect staticmethod ¶

create_event ¶

create_my_collection ¶

create_permalink ¶

delete_event ¶

delete_my_collection ¶

delete_permalink ¶

get_event ¶

get_permalink ¶

list_events ¶

list_my_collections ¶

remove_streams_from_my_collection ¶

run_coroutine_to_completion ¶

update_my_collection ¶

update_permalink ¶

AsyncAdminClient ¶

Functions¶

list_events async ¶

Functions¶

connect ¶

profile ¶

endpoint ¶

api_key ¶

connect `staticmethod` ¶

list_events `async` ¶

`profile` ¶

`endpoint` ¶

`api_key` ¶