Skip to main content

Xplain Python Package

A Python client library for the Xplain data analytics platform. This package provides a comprehensive API for object-oriented data analysis, query execution, statistical modeling, and data import operations.

Features

  • Session Management - Connect to Xplain servers, manage sessions, and share session state across clients
  • Object-Oriented Data Model - Navigate hierarchical object trees with XObjects, Dimensions, and Attributes
  • Query Engine - Build and execute queries with aggregations, group-bys, and selections using Query_config
  • Statistical Modeling - Run logistic regression, OLS, probit, GLM, Poisson, and negative binomial models via statsmodels
  • Predictive Modeling - Build and manage predictive models with independent variable analysis
  • Data Import - Import data from PostgreSQL, MySQL, Oracle, SQL Server, Snowflake, BigQuery, and other JDBC databases
  • Batch Processing - Generate and execute XGenScripts for time-partitioned parallel data import
  • Visualization - Render collapsible object trees in Jupyter notebooks using pyecharts

Requirements

  • Python >= 3.9
  • An Xplain server instance

Installation

From PyPI

pip install xplain

From Source (Development)

git clone <repository-url>
cd xplainpy
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Optional Dependencies

# For MCP server integration
pip install -e ".[mcp]"

# For development/testing
pip install -e ".[dev]"

Quick Start

Connect to Xplain Server

import xplain

# Credentials come from arguments, XPLAIN_* environment variables or a profile in ~/.xplainpyrc
# (see README_PROFILES.md). The session logs out when the block ends.
with xplain.connect("local", startup="MyConfig") as session:
    session.show_tree()

xplain.connect(...) is the recommended entry point. Without a profile, pass the credentials directly: xplain.connect(url=..., user=..., password=..., startup="MyConfig"). That works without ~/.xplainpyrc (also when a sandbox hides the file). Xsession(url=..., user=..., password=...) still works and is also a context manager; call close() (or terminate()) when you do not use with. Every server call has a timeout (timeout=(10, 600) seconds by default; pass timeout=None to wait forever) and TLS verification is controlled with verify= (it becomes True by default in 0.1.0).

CLI Session Startup

# Connect using the default profile from ~/.xplainpyrc
xplain connect

# Load a saved startup configuration
xplain startup MyConfig.xstartup

# The .xstartup extension is optional
xplain startup MyConfig

# Load a local XView JSON file
xplain startup ./views/my_view.xview

# Initialize the current server session
xplain init-xplain-session --output json

Execute Queries

from xplain import Xsession, Query_config

session = Xsession(url="http://myhost:8080", user="myuser", password="mypassword")
session.startup("MyConfig")

# Build a query using Query_config (also available as xplain.QueryConfig)
query = Query_config()
query.add_aggregation(object_name="Orders", dimension_name="Amount", type="SUM")
query.add_groupby(object_name="Orders", dimension_name="Category", attribute_name="ProductType")

# Execute and get results as a pandas DataFrame
#   leaves_only=True drops the subtotal rows that multi-group-by results contain
#   strict=True raises NotFoundError for selection states that do not exist (otherwise: a warning)
df = session.execute_query(query, leaves_only=True, strict=True)
print(df)

Correctness pitfalls

Some server semantics produce plausible but wrong numbers if you do not know them. The most important:

  • A selection on a child object does not restrict its parents in execute_query; count distinct parents with COUNTENTITY on the child.
  • execute_query ignores global selections (select()) unless you pass use_global_selections=True.
  • Selection states are full labels ("J45 Asthma", not "J45"); unknown states are ignored by the server.
  • COUNT counts records (nulls included); threshold=k on aggregation dimensions means >= k and must be an integer.

The full list, with examples, is in docs/pitfalls.rst.

Using xplain with LLM coding agents

The package ships an agent skill (helpers, pitfalls and verified recipes) and an llms.txt:

xplain skill path        # where the bundled skill lives
xplain skill install     # copy it to ~/.claude/skills/xplainpy (use --target for other agents)

In a validation study with Claude models on 20 analysis tasks, the skill raised the success rate of the smallest model (Haiku) from 25% to 96% and cut the number of agent turns by 2.5-7x across Haiku, Sonnet and Opus.

Open an Attribute

# Get counts grouped by an attribute
df = session.open_attribute(
    object_name="Person",
    dimension_name="Gender",
    attribute_name="Gender"
)
print(df)

Navigate the Object Tree

# Get an XObject and explore its structure
obj = session.get_xobject("Orders")
print(obj.get_dimensions())       # List dimension names
print(obj.get_child_objects())     # List child object names

# Add an aggregation dimension
obj.add_aggregation_dimension(
    dimension_name="#Prescriptions",
    aggregation={"aggregationType": "COUNT", "object": "Prescription"},
    floating_semantics=False
)

Import Data from a Database

from xplain import Xsession
from xplain.tools import Connection, Xtable_config, Xview

session = Xsession(url="http://myhost:8080", user="admin", password="secret")

# Create a database connection
conn = Connection(
    xsession=session,
    databaseType="POSTGRESQL",
    url="db.example.com",
    user="analyst",
    password="dbpassword",
    databaseName="warehouse",
    portNumber=5432
)

# Test the connection
result = conn.test_connection()
print(result)  # {'status': 'success', 'result': 'db connection validated successfully'}

# List available tables
tables = conn.get_tables()

# Configure an XTable import
config = Xtable_config(
    xsession=session,
    connection=conn,
    db_table_name="sales_data",
    object_name="Sales",
    primary_key="transaction_id",
    foreign_keys=["customer_id"]
)

# Review the auto-mapped dimensions
print(config.show_dimension_configurations())

# Import the XTable
config.import_xtable()

# Create a view with parent-child relationships
view = Xview(session)
view.insert_xtable(xtable="Sales", as_root=True, auto_generate_attributes=True)
view.insert_xtable(xtable="Customers", as_root=False, parent="Sales")
view.save("sales_view", "PUBLIC")

# Load the view as a session
session.startup_from_xview_config(view)

Statistical Modeling

# Run a logistic regression
df = session.execute_query(query)
result = session.run_statsmodels(df, formula="outcome ~ age + gender + treatment", model_type="logit")
print(result.summary())

# Build a formula dynamically
formula = session.build_formula(response="outcome", predictors=["age", "gender", "treatment"])

Package Structure

xplain/
    __init__.py          # Package exports (connect, Xsession, XplainSession, QueryConfig, errors, ...)
    config.py            # connect(), create_session(), profiles (~/.xplainpyrc)
    xsession.py          # Core session management and Web API client
    session_client.py    # XplainClient: one method per server operation (generated from OpenAPI)
    unified_session.py   # XplainSession: the client methods in 8 namespaces (generated delegates)
    errors.py            # XplainError and subclasses
    xobject.py           # XObject class for data objects
    dimension.py         # Dimension class
    attribute.py         # Attribute class with hierarchy support
    query_config.py      # Query configuration builder
    skills/xplainpy/     # Agent skill for LLMs (xplain skill path / install)
    llms.txt             # Short orientation for LLMs
    cli/                 # The `xplain` command line tool
    tools/
        __init__.py      # Tools exports
        connection.py    # Database connection management
        xtable_config.py # XTable import configuration
        xview.py         # XView configuration builder
        xattribute_config.py  # Hierarchical attribute configuration
        importer.py      # High-level import orchestrator
        xgenscript.py    # XGenScript generation for batch processing

Core Classes

Class Description
Xsession Main session class for connecting to Xplain and executing operations
XObject Represents a data object in the Xplain object tree
Dimension Represents a dimension attached to an XObject
Attribute Represents an attribute within a dimension, with hierarchy support
Query_config / QueryConfig Builder for constructing query configurations
XplainSession Unified client with namespaced methods (returned by connect())
XplainClient One method per server operation
XplainError Base exception; subclasses AuthenticationError, SessionNotStartedError, NotFoundError, QueryError
Connection Database connection management for data import
Xtable_config Configuration for importing database tables as XTables
Xview Builder for XView configurations defining data view structure
Importer High-level orchestrator for data import workflows

Authentication

Xplain supports multiple authentication methods:

# Standard credentials
session = Xsession(url="http://host:8080", user="user", password="pass")

# JWT authentication
session = Xsession(
    url="http://host:8080",
    jwt_dispatch_url="https://auth.example.com/dispatch",
    jwt_cookie_name="auth_token",
    jwt_token="eyJhbGciOi..."
)

# Reuse existing HTTP session
session = Xsession(url="http://host:8080", http_session_id="EXISTING_JSESSIONID")

# Errors are typed: all derive from xplain.XplainError (a RuntimeError)
try:
    session.startup("Missing")
except xplain.SessionNotStartedError as e:
    print(e.status, e.server_message)

Optional OIDC login for XOE behind Keycloak (device login: sign in once in a browser, then a cached refresh token):

session = xplain.connect(url="https://xoe.example.com", startup="MyConfig",
                         oidc_issuer="https://keycloak.example.com/realms/xplain", oidc_client_id="xplain-python-sdk")

Password, JWT and session-id logins are unchanged; OIDC is used only when both oidc_* settings are given. See docs/authentication.rst for the Keycloak setup.

Testing

# Unit tests (no server needed); these gate CI
python3 -m pytest test/unit

# Legacy suite (several tests need a live server or have stale mocks)
python3 -m pytest --ignore=test/xoedevtest --ignore=test/gfl

# Live integration tests against the xoedevtest profile
python3 -m pytest test/xoedevtest

Documentation

Full documentation is available in the docs/ directory. Build with Sphinx:

cd docs
make html

Changelog

See CHANGELOG.md for 0.0.44 and later. Older entries:

2025-02-27

  • Added download_selections method
  • Bugfix: show_tree
  • Added: run_statsmodels, create_contingency_table, build_formula
  • Added: collapsible_tree, http_get, http_post, run_py

2024-07-02

  • Enabled JWT authentication

2024-03-12

  • Replaced print messages with logging
  • Bugfix: POST payload issue with missing json.dumps
  • Bugfix: Session hijacking issue in pyodide environment
  • Added http_post and http_get methods

2023-12-20

  • SSL verify false by login

2023-09-06

  • Bugfix: get_instance_as_dataframe doesn't download the exported CSV

2023-07-31

  • Added aggregation_name parameter to query_config.add_aggregation

2023-06-06

  • Bugfix: build_predictive_model returns error by reading result

2023-05-11

  • Added validate_db

2023-05-05

  • Added Xsession.list_files() and Xsession.read_file()
  • Xsession.startup(file_name) - file extension now optional

License

Xplain Data GmbH. All rights reserved.

Metadata

Release files for xplain 0.0.44

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xplain 0.0.44
File Size Uploaded Provenance Actions
xplain-0.0.44.tar.gz 345.6 kB Without provenance Details for xplain-0.0.44.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xplain 0.0.44
File Interpreter ABI Platform Actions
xplain-0.0.44-py3-none-any.whl Python 3 none any Details for xplain-0.0.44-py3-none-any.whl

Total release size: 711.1 kB

Release files / xplain-0.0.44.tar.gz

Download URL xplain-0.0.44.tar.gz
Size 345.6 kB
Tags Source
SHA-256 checksum
How to use checksums
91233f48e89f83b20aa5dc57d84912ece3119c1e1ecbc76d324e8253252be0e9
BLAKE2b-256 checksum
How to use checksums
65ecafd55a2c3431ac6df35b0b367a20e8789f5f6d25103a767a888d90f612b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.2

Release files / xplain-0.0.44-py3-none-any.whl

Download URL xplain-0.0.44-py3-none-any.whl
Size 365.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a8db43235100009f1039ef12a9b3f342429ec8989c4e819a8b37e2d4c80860bd
BLAKE2b-256 checksum
How to use checksums
a3b934160d6f0d92552c62c9866920a827834e276a49321526e575973e09ecf8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.2

Security for xplain 0.0.44

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.44 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page