Python API Reference

Index

class Client
- def connect_to_cluster
- def list_healthy_clusters
class Cluster
- def name
class Conn
- def name
- def prepare_script
class ScriptExecutor
class TableSub
class Row
class CryptoOptions
- def encrypt_options

class Client
```
Client(self, token: str, server_url: str = 'work.withpixie.ai', use_encryption: bool = False, channel_fn: Callable[[str], grpc.Channel] = None, conn_channel_fn: Callable[[str], grpc.aio._base_channel.Channel] = None )
```
Client is the main entry point to the Pixie API.
To setup the client, you need to generate an API token and pass it in as the first argument. See: https://docs.px.dev/using-pixie/api-quick-start/ for more info.
- def connect_to_cluster
```
def connect_to_cluster(self, cluster: Union[str, pxapi.client.Cluster]) -> pxapi.client.Conn
```
  Connect to a cluster.
  Returns a connection object that you can use to create ScriptExecutors. You may pass in a ClusterID string or a Cluster object that comes from list_healthy_clusters().
- def list_healthy_clusters
```
def list_healthy_clusters(self) -> List[pxapi.client.Cluster]
```
  Lists all of the healthy clusters that you can access.
class Cluster
```
Cluster(self, cluster_id: str, cluster_info: src.api.proto.cloudpb.cloudapi_pb2.ClusterInfo )
```
Cluster contains information users need about a specific cluster.
Mainly a convenience wrapper around the protobuf message so you can access the name in a simple format.
- def name
```
def name(self) -> str
```
  Returns the name if that info exists, otherwise returns the id.

class Conn

Conn(self, token: str, pixie_url: str, cluster_id: str, use_encryption: bool = True, cluster_info: src.api.proto.cloudpb.cloudapi_pb2.ClusterInfo = None, channel_fn: Callable[[str], grpc.aio._base_channel.Channel] = None )

The logical representation of a connection.

Holds the authorization information and handles the creation of an authorized gRPC channel.

def name
```
def name(self) -> str
```
Get the name of the cluster for this connection.
def prepare_script
```
def prepare_script(self, script_str: str) -> pxapi.client.ScriptExecutor
```
Create a new ScriptExecutor for the script to run on this connection.

class ScriptExecutor
```
ScriptExecutor(self, conn: pxapi.client.Conn, pxl: str, use_encryption: bool)
```
ScriptExecutor encapsulates the connection logic to Pixie instances.
If you want to get Pixie data, you will need to initialize ScriptExecutor with the clusters and PxL script then call results() for the desired table name and iterate the results.
Note: you can only invoke results(), run(),and run_async() once on a ScriptExecutor object. If you need to exeucte a script multiple times, you must create a new ScriptExecutor object and setup any data processing again. We rely on iterators that must close when a script stops running and cannot allow multiple runs per object.
- def add_callback
```
def add_callback(self, table_name: str, fn: Callable[[pxapi.data.Row], NoneType]) -> None
```
  Adds a callback fn that will be invoked on every row of table_name as they arrive.
  Callbacks are not invoked until you call run() (or run_async()) on the object.
  If you add_callback on a table not produced by the script, run()(or run_async()) will raise a ValueError when the underlying gRPC channel closes.
  The internals of ScriptExecutor use the python async api and the callback fn will be called concurrently while the ScriptExecutor is running. Note that callbacks themselves should not be async functions.
  Callbacks will block the rest of script execution so expensive and unending callbacks should not be used.
  Raises: ValueError: If called on a table that's already been passed as arg to subscribe or add_callback. ValueError: If called after run() or run_async() for a particular ScriptExecutor
- def results
```
def results(self, table_name: str) -> Generator[pxapi.data.Row, NoneType, NoneType]
```
  Runs script and return results for the table. Examples: for row in script.results("http_table"): print(row) Raises: ValueError: If table_name is never sent during lifetime of script. ValueError: If called after run() or run_async() for a particular ScriptExecutor.
- def run
```
def run(self) -> None
```
  Executes the script synchronously.
  Calls run_async() but hides the asyncio details from users. If any errors occur over the lifetime of any connection, this will raise an error.
  Raises: ValueError: If any callbacks are on tables that a ScriptExecutor never receives. ValueError: If called after run() or run_async() for a particular ScriptExecutor.
- def run_async
```
def run_async(self) -> None
```
  Runs the script asynchronously using asyncio.
  Same as run() except you can directly control whether other tasks should be run concurrently while the script is running.
  Raises: ValueError: If any callbacks are on tables that a ScriptExecutor never receives. ValueError: If called after run() or run_async() for a particular ScriptExecutor.
- def subscribe
```
def subscribe(self, table_name: str) -> pxapi.client.TableSub
```
  Returns an async generator that outputs rows for the table.
  Raises: ValueError: If called on a table that's already been passed as arg to subscribe or add_callback. ValueError: If called after run() or run_async() for a particular ScriptExecutor
- def subscribe_all_tables
```
def subscribe_all_tables(self) -> Callable[[], AsyncGenerator[pxapi.client.TableSub, NoneType]]
```
  Returns an async generator that outputs table subscriptions as they arrive.
  You can use this generator to call PxL scripts without knowing the tables that are output beforehand. If you do know the tables beforehand, you should subscribe, add_callback or even results instead to prevent your api from keeping data for tables that you don't use.
  This generator will only start iterating after run_async() has been called. For the best performance, you will want to call the consumer of the object returned by subscribe_all_tables concurrently with run_async()
class TableSub
```
TableSub(self, name: str, table_gen: AsyncGenerator[Union[pxapi.data._TableStream, Literal['ERROR']], NoneType] )
```
TableSub is an async generator that yields rows for table.
You should avoid directly initializing TableSub objects. Instead, you should create a ScriptExecutor object and ScriptExecutor.subscribe() to a specific table or ScriptExecutor.subscribe_all_tables(). This avoids the complexity involved in creating this object.
For more advanced users: the TableSub object is a promise that a table with the specified name will be yielded by the table_gen. If the table does not get yielded, the async generator will throw an error when the table_gen exits.
class Row
```
Row(self, table: pxapi.data._TableStream, data: List[Any])
```
Row represents a row of data for a particular table. You can easily access data in the row by using the column name from the associated table.
Specifically designed to avoid allocation memory for the relation for each row.
Examples:
tableA = Table("a", relation=(("cola",int), ("colb", int), ("colc", string))) row = Row(tableA, [1,2,"three"]) row["cola"] 1 row["colb"] 2 row["colc"] "three" row { "cola": 1, "colb": 2, "colc": "three" }

class CryptoOptions

CryptoOptions(self)

def encrypt_options

def encrypt_options(self) -> src.api.proto.vizierpb.vizierapi_pb2.EncryptionOptions

This site uses cookies to provide you with a better user experience. By using Pixie, you consent to our use of cookies.

Python API Reference

Index

class Client

def connect_to_cluster

def list_healthy_clusters

class Cluster

def name

class Conn

def name

def prepare_script

class ScriptExecutor

def add_callback

def results

def run

def run_async

def subscribe

def subscribe_all_tables

class TableSub

class Row

class CryptoOptions

def encrypt_options