SQLite Solution Reader

The SQLite solution reader imports a PLEXOS solution ZIP into SQLite and materializes derived result tables for analysis. Import it explicitly to distinguish it from the DuckDB-backed solution wrapper:

from plexosdb.solution_reader import PlexosSolution

PlexosSolution: primary API for PLEXOS solution ZIP import and analysis.

class plexosdb.solution_reader.solution.PlexosSolution

Bases: object

Fluent interface for importing and querying a PLEXOS solution.

Two entry points are available:

• from_zip() — bind to a PLEXOS solution ZIP file and use to_sqlite() to import it. Both XML metadata and BIN payloads are parsed during import.

• from_sqlite() — open an already-imported SQLite database directly, without needing the original ZIP file.

Typical use with a ZIP:

with PlexosSolution.from_zip("mysolution.zip") as sol:
    result = sol.to_sqlite("output.sqlite")
    sol.materialize_table("Generator")

Re-opening an existing database (no ZIP needed):

sol = PlexosSolution.from_sqlite("output.sqlite")
show_db_tables(sol)
sol.materialize_table("Generator")
sol.close()

Initialise an empty PlexosSolution with no source configured.

classmethod from_zip(path, *, model_name=None)

Create a PlexosSolution bound to a PLEXOS solution ZIP.

Parameters:

• path (str | Path) – Path to the PLEXOS solution ZIP file.

• model_name (str | None) – Optional hint for selecting the correct XML when multiple XML files exist inside the archive.

Return type:

PlexosSolution

classmethod from_sqlite(path)

Open an existing PLEXOS solution SQLite database without a source ZIP.

Useful for reading and querying a database that was previously created with to_sqlite() or plexos_to_sqlite(). No ZIP file is required — the XML metadata and BIN payloads are already stored in SQLite.

Parameters:

path (str | Path) – Path to an existing PLEXOS solution SQLite file.

Raises:

FileNotFoundError – If path does not exist.

Return type:

PlexosSolution

to_sqlite(database=None, *, if_exists='reuse', materialize='none', decode_bin_values=True)

Import the solution ZIP into a SQLite database.

Parameters:

• database (str | Path | None) – Filesystem path for the SQLite file. None (default) or the special string ':memory:' create an in-memory database (if_exists is ignored in that case).

• if_exists (Literal['fail', 'reuse', 'replace']) –

  Controls behaviour when database already exists on disk:

  'fail'

  Raise FileExistsError.

  'reuse'

  Open the existing file, decode BIN values if missing, and attach derived-table schemas. No re-import is performed.

  'replace'

  Delete the file and create a fresh database.

• decode_bin_values (bool) – If True (default), decode the BIN payload files from the solution ZIP into t_data_values. Set to False to skip BIN decoding — useful when only the table catalog or XML metadata tables are needed, which avoids writing potentially millions of rows and is significantly faster for large solutions.

• materialize (Literal['none', 'all'] | ~collections.abc.Sequence[str]) –

  Which derived tables to materialize after import:

  'none'

  Do not materialize any tables (default).

  'all'

  Materialize all available derived tables.

  sequence of strings

  Materialize only the named tables.

Returns:

Contains the database path (None for in-memory) and the list of table names in the main schema after import.

Return type:

SQLiteResult

info()

Return metadata about the solution archive.

Raises:

RuntimeError – If no ZIP path has been configured (see from_zip()).

Return type:

SolutionInfo

list_tables(*, schema='report')

List tables available under the given schema.

Parameters:

schema (Literal['raw', 'processed', 'data', 'report']) –

'raw'

All tables present in the main SQLite schema.

'processed'

Core PLEXOS entity tables (class, object, membership, property).

'data'

Derived analysis tables (whether materialized or not).

'report'

Same as data — derived tables exposed under the report schema.

Return type:

list[TableInfo]

materialize_table(name, *, schema='report', if_exists='reuse')

Materialize one derived table into the attached schema.

Parameters:

• name (str) – Name of the derived table to materialize (e.g. 'Generator').

• schema (Literal['data', 'report']) – Target schema: 'data' or 'report'.

• if_exists (Literal['fail', 'reuse', 'replace']) – 'reuse' (default) — return without re-materializing if the table already exists. 'fail' — raise FileExistsError. 'replace' — drop the existing table and re-materialize.

Return type:

MaterializeResult

property connection: Connection

The active SQLite connection.

Raises:

RuntimeError – If to_sqlite() has not been called yet.

close()

Close the active SQLite connection.

Return type:

None

property source: Path | None

Path to the source ZIP file, or None for from_sqlite() instances.

property name: str

Display name for the solution.

Returns the stem of the source ZIP when available, then the stem of the SQLite database, then 'unknown'.

Display Helpers

DuckDB-style table catalog display helper.

Public surface:

• show_db_tables() — print a PLEXOS solution catalog in box format

plexosdb.solution_reader.display.show_db_tables(client, *, max_rows=20)

Print the table catalog of a PLEXOS solution in DuckDB-style box format.

Collects all physical tables from attached SQLite schemas together with logical derived result tables (data / report) from the solution metadata, sorts them by schema then name, and prints the result as a Unicode box table — the same visual style used by DuckDB.

This function must be called after PlexosSolution.to_sqlite() has been invoked (i.e. after the SQLite connection has been opened).

Parameters:

• client (PlexosSolution) – A PlexosSolution instance with an active connection.

• max_rows (int) – Maximum number of rows to show before truncating with · rows. When the result exceeds max_rows, the first and last max_rows // 2 rows are displayed. Defaults to 20.

Return type:

None

Examples

from plexosdb import PlexosSolution, show_db_tables

sol = PlexosSolution.from_zip("my_solution.zip")
sol.to_sqlite("output.sqlite", if_exists="replace", decode_bin_values=False)

show_db_tables(sol)

Result Types

Result and metadata types for the PlexosSolution API.

class plexosdb.solution_reader.types.SolutionInfo(source, xml_entry, model_name=None)

Bases: object

Metadata about a PLEXOS solution archive.

Parameters:

• source (Path)

• xml_entry (str)

• model_name (str | None)

source: Path

xml_entry: str

model_name: str | None = None

class plexosdb.solution_reader.types.SQLiteResult(database, tables=<factory>)

Bases: object

Result returned by PlexosSolution.to_sqlite().

Parameters:

• database (Path | None)

• tables (list[str])

database: Path | None

Filesystem path of the SQLite file, or None for an in-memory database.

tables: list[str]

Names of all tables present in the main SQLite schema after import.

property is_in_memory: bool

Return True when the database lives in memory only.

class plexosdb.solution_reader.types.TableInfo(name, schema, table_type)

Bases: object

Metadata about one table or view in a solution schema.

Parameters:

• name (str)

• schema (str)

• table_type (str)

name: str

schema: str

table_type: str

'BASE TABLE' or 'VIEW'.

class plexosdb.solution_reader.types.MaterializeResult(name, schema, created)

Bases: object

Result returned by PlexosSolution.materialize_table().

Parameters:

• name (str)

• schema (str)

• created (bool)

name: str

schema: str

created: bool

True when the table was newly created; False when it was skipped because it already existed and if_exists='reuse' was in effect.

See Inspecting a PLEXOS Solution for a complete ZIP-to-SQLite workflow.