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 withCOUNTENTITYon the child. execute_queryignores global selections (select()) unless you passuse_global_selections=True.- Selection states are full labels (
"J45 Asthma", not"J45"); unknown states are ignored by the server. COUNTcounts records (nulls included);threshold=kon aggregation dimensions means>= kand 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_selectionsmethod - 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_postandhttp_getmethods
2023-12-20
- SSL verify false by login
2023-09-06
- Bugfix:
get_instance_as_dataframedoesn't download the exported CSV
2023-07-31
- Added
aggregation_nameparameter toquery_config.add_aggregation
2023-06-06
- Bugfix:
build_predictive_modelreturns error by reading result
2023-05-11
- Added
validate_db
2023-05-05
- Added
Xsession.list_files()andXsession.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.