triplets.cli

CLI tools for the triplets package.

triplets.cli.cim_spreadsheet

CIM Spreadsheet Converter CLI Tool

Command-line tool for converting between CIM XML (Common Information Model) and spreadsheet formats (Excel/CSV).

This tool provides bidirectional conversion: - CIM to Spreadsheet: Convert CIM XML files to Excel or CSV format - Spreadsheet to CIM: Convert Excel or CSV files back to CIM XML

The tool automatically detects the conversion direction based on file extensions, making it simple to use without explicit direction specification.

Installation

Install the triplets package with optional dependencies:

pip install triplets[optional]

Or install from source:

git clone https://github.com/Haigutus/triplets.git
cd triplets
pip install -e .[optional]

Using uv (recommended):

uv pip install -e .[optional]

The optional extra includes openpyxl for Excel support.

Usage

After installation, the tool can be invoked in three ways:

  1. As a command-line tool (recommended):

    cim-spreadsheet -i input_file -o output_file

  2. As a Python module:

    python -m triplets.tools.cim_spreadsheet_cli -i input_file -o output_file

  3. Programmatically in Python code:

    from triplets.tools.cim_spreadsheet_cli import cim_to_spreadsheet, spreadsheet_to_cim

# Convert CIM to Excel
cim_to_spreadsheet('model.xml', 'output.xlsx')

# Convert Excel to CIM
spreadsheet_to_cim('data.xlsx', 'cim_output/')

Examples

Convert CIM XML to Excel:

cim-spreadsheet -i model.xml -o output.xlsx

Convert CIM XML to CSV (auto-zipped):

cim-spreadsheet -i model.xml -o output.zip -f csv

Convert Excel back to CIM XML:

cim-spreadsheet -i output.xlsx -o cim_output/

Disable multivalue mode (keep duplicate ID+KEY pairs as separate rows):

cim-spreadsheet -i model.xml -o output.xlsx --no-multivalue

Select specific sheets to convert:

cim-spreadsheet -i data.xlsx -o output/ --sheets ACLineSegment Substation

Include raw triplets sheet:

cim-spreadsheet -i data.xlsx -o output/ --triplets-sheet RawData

Explicitly specify conversion direction:

cim-spreadsheet -i model.xml -o output.xlsx -d to-spreadsheet

Force ZIP output for Excel:

cim-spreadsheet -i model.xml -o output.zip -f excel -z

Disable ZIP output for CSV:

cim-spreadsheet -i model.xml -o csv_dir/ -f csv --no-zip

Features

  • Auto-detection of conversion direction from file extensions

  • Support for both Excel (.xlsx) and CSV formats

  • ZIP compression support for output files

  • Multivalue mode enabled by default (aggregates/unpacks duplicate ID+KEY pairs into lists)

  • Sheet/file selection for both Excel and CSV formats

  • Raw triplets import from dedicated Excel sheet or CSV file

  • Handles zipped input/output files automatically

See also

cim-diff

Tool for comparing CIM XML files

triplets.rdf_parser

Core module for RDF/CIM data manipulation

triplets.cli.cim_spreadsheet.cim_to_spreadsheet(cim_path, output_path, format=None, zip_output=None, multivalue=True)[source]

Convert CIM XML to spreadsheet format (Excel or CSV).

Handles all orchestration including file I/O, format detection, zipping, and conversion through the core rdf_parser functions.

Parameters:

  • cim_path (str) – Path to input CIM XML file or ZIP containing XML files

  • output_path (str) – Path to output file (for Excel/zipped CSV) or directory (for CSV)

  • format ({'excel', 'csv'}, optional) – Output format. If None, auto-detected from output_path extension. Defaults to ‘excel’ if ambiguous.

  • zip_output (bool, optional) – Whether to ZIP the output. If None, defaults to True for CSV format, False for Excel format.

  • multivalue (bool, default True) – If True, aggregate duplicate (ID, KEY) pairs into lists in the output. Use False to keep duplicate pairs as separate rows.

Raises:

ImportError – If openpyxl is not installed and Excel format is requested

Examples

>>> cim_to_spreadsheet('model.xml', 'output.xlsx')
>>> cim_to_spreadsheet('model.zip', 'output.zip', format='csv')
>>> cim_to_spreadsheet('model.xml', 'output.xlsx', multivalue=True)
triplets.cli.cim_spreadsheet.spreadsheet_to_cim(input_path, output_path, format=None, rdf_map=None, export_type=None, multivalue=True, zip_output=None, sheets=None, triplets_sheet=None)[source]

Convert spreadsheet format (Excel or CSV) to CIM XML.

Handles all orchestration including file I/O, format detection, unzipping, sheet selection, raw triplets import, and conversion through core rdf_parser functions.

Parameters:

  • input_path (str) – Path to input Excel file, CSV directory, or ZIP archive

  • output_path (str) – Path to output directory where CIM XML files will be written

  • format ({'excel', 'csv'}, optional) – Input format. If None, auto-detected from input_path extension. Defaults to ‘excel’ if ambiguous.

  • rdf_map (str, optional) – Path to RDF map JSON file for custom mappings during export

  • export_type ({'xml_per_instance', 'xml_per_instance_zip_per_all', 'xml_per_instance_zip_per_xml'}, optional) – How to package the CIM XML output. If None, defaults to ‘xml_per_instance_zip_per_all’ if zip_output=True, else ‘xml_per_instance’

  • multivalue (bool, default True) – If True, unpack list values into separate triplets during conversion. Use False to keep list values as-is in single triplets.

  • zip_output (bool, optional) – Whether to ZIP the output. Defaults to True.

  • sheets (list of str, optional) – Specific sheet/file names to convert. For Excel, these are sheet names. For CSV, these are base filenames (without .csv extension). If None, converts all sheets/files except triplets_sheet.

  • triplets_sheet (str, optional) – Name of sheet/file containing raw triplets (ID, KEY, VALUE columns) to include in the output. For Excel, this is a sheet name. For CSV, this is a base filename (without .csv extension). This sheet is not processed as tableview data.

Returns:

Export result from rdf_parser.export_to_cimxml()

Return type:

result

Raises:

  • ImportError – If openpyxl is not installed and Excel format is specified

  • ValueError – If CSV format is used with a file (requires directory or ZIP) If no Excel file found in ZIP archive If triplets sheet is missing required columns

Examples

>>> spreadsheet_to_cim('data.xlsx', 'output/')
>>> spreadsheet_to_cim('data.zip', 'output/', sheets=['ACLineSegment', 'Substation'])
>>> spreadsheet_to_cim('data.xlsx', 'output/', triplets_sheet='RawData')
triplets.cli.cim_spreadsheet.detect_conversion_direction(input_path, output_path)[source]

Auto-detect conversion direction from file extensions.

Examines input and output file paths to determine whether the conversion should be CIM-to-spreadsheet or spreadsheet-to-CIM.

Parameters:

  • input_path (str) – Input file or directory path

  • output_path (str) – Output file or directory path

Returns:

Either ‘to-spreadsheet’ or ‘to-cim’

Return type:

str

Raises:

ValueError – If conversion direction cannot be determined from file extensions

Notes

Detection logic:

  • If input is .xml/.rdf (or ZIP containing such files), direction is ‘to-spreadsheet’

  • If input is .xlsx/.xls/.csv (or directory with CSVs), direction is ‘to-cim’

  • If ambiguous from input, checks output path for spreadsheet extensions or directory-like patterns

  • Raises ValueError if direction cannot be determined

Examples

>>> detect_conversion_direction('model.xml', 'output.xlsx')
'to-spreadsheet'
>>> detect_conversion_direction('data.xlsx', 'output/')
'to-cim'
triplets.cli.cim_spreadsheet.main()[source]

CLI entry point for cim-spreadsheet tool.

Parses command-line arguments and executes the appropriate conversion (CIM-to-spreadsheet or spreadsheet-to-CIM) with auto-detection of conversion direction.

Command-Line Usage

Basic conversion (auto-detect direction):

cim-spreadsheet -i input_file -o output_file

Explicit direction:

cim-spreadsheet -i model.xml -o output.xlsx -d to-spreadsheet
cim-spreadsheet -i data.xlsx -o output/ -d to-cim

Format specification:

cim-spreadsheet -i model.xml -o output.zip -f csv
cim-spreadsheet -i data.zip -o output/ -f csv

Advanced options:

cim-spreadsheet -i model.xml -o output.xlsx --no-multivalue  # disable multivalue mode
cim-spreadsheet -i data.xlsx -o output/ --sheets Sheet1 Sheet2
cim-spreadsheet -i data.xlsx -o output/ --triplets-sheet RawData
cim-spreadsheet -i model.xml -o output.xlsx -z  # force ZIP

Exit Codes

0 : Successful conversion 1 : Error during conversion (see stderr for details)

See also

cim_to_spreadsheet

Function for CIM to spreadsheet conversion

spreadsheet_to_cim

Function for spreadsheet to CIM conversion

detect_conversion_direction

Auto-detection logic

triplets.cli.cim_diff

CIM Diff Tool

Command-line tool for comparing CIM XML (Common Information Model) files and displaying differences in unified diff format.

This tool compares CIM files at the semantic level (object-by-object based on ID, KEY, VALUE triplets) rather than as plain XML text. This makes it much more useful for identifying actual data changes while ignoring irrelevant formatting or ordering differences.

Installation

Install the triplets package:

pip install triplets

Or install from source:

git clone https://github.com/Haigutus/triplets.git
cd triplets
pip install -e .

Using uv (recommended):

uv pip install -e .

Usage

After installation, the tool can be invoked in three ways:

  1. As a command-line tool (recommended):

    cim-diff original.xml modified.xml

  2. As a Python module:

    python -m triplets.tools.cim_diff_cli original.xml modified.xml

  3. Programmatically in Python code:

    from triplets import rdf_parser

# Load both files
original = rdf_parser.load_all_to_dataframe(['original.xml'])
modified = rdf_parser.load_all_to_dataframe(['modified.xml'])

# Print diff
rdf_parser.print_triplets_diff(original, modified, exclude_objects=['NamespaceMap', 'Distribution'])

Features

  • Semantic comparison at triplet level (ID, KEY, VALUE)

  • Unified diff format output for easy reading

  • Support for ZIP archives (single or nested)

  • Default exclusions for metadata objects (NamespaceMap, Distribution)

  • Custom exclusion lists for filtering out specific object types

  • Handles large CIM files efficiently

Examples

Basic diff between two CIM files:

$ cim-diff original.xml modified.xml

Diff with custom exclusions:

$ cim-diff original.xml modified.xml -ex Terminal ConnectivityNode

Diff without default exclusions:

$ cim-diff original.xml modified.xml --no-default-exclusions

Diff between ZIP archives:

$ cim-diff original.zip modified.zip

Add custom exclusions on top of defaults:

$ cim-diff original.xml modified.xml -ex CustomType1 CustomType2

Output Format

The tool outputs differences in unified diff format:

--- Objects in original_file
+++ Objects in modified_file
- ObjectID ObjectType.attribute oldValue
+ ObjectID ObjectType.attribute newValue

Lines starting with ‘-’ indicate values removed (in original but not in modified). Lines starting with ‘+’ indicate values added (in modified but not in original).

Default Exclusions

By default, the following object types are excluded from comparison as they typically contain auto-generated metadata that changes between exports:

  • NamespaceMap : XML namespace mappings (contains UUIDs)

  • Distribution : File distribution metadata

Use –no-default-exclusions to include these in the comparison.

See also

cim-spreadsheet

Tool for converting between CIM XML and spreadsheet formats

triplets.rdf_parser.print_triplets_diff

Core diff function

triplets.cli.cim_diff.main()[source]

CLI entry point for cim-diff tool.

Parses command-line arguments and executes comparison of two CIM XML files, displaying differences in unified diff format.

Command-Line Usage

Basic usage:

cim-diff original.xml modified.xml

With custom exclusions:

cim-diff original.xml modified.xml -ex Terminal ACLineSegment

Without default exclusions:

cim-diff original.xml modified.xml --no-default-exclusions

Combined exclusions:

cim-diff original.xml modified.xml -ex CustomType --no-default-exclusions
param original_file:

Path to original CIM XML file or ZIP archive

type original_file:

str (positional)

param changed_file:

Path to modified CIM XML file or ZIP archive

type changed_file:

str (positional)

param -ex:

Object type names (without namespace/prefix) to exclude from diff. These are added to default exclusions unless –no-default-exclusions is used.

type -ex:

list of str, optional

param –exclude_objects:

Object type names (without namespace/prefix) to exclude from diff. These are added to default exclusions unless –no-default-exclusions is used.

type –exclude_objects:

list of str, optional

param –no-default-exclusions:

Disable default exclusions (NamespaceMap, Distribution)

type –no-default-exclusions:

flag, optional

param Exit Codes:

param ———-:

param 0:

type 0:

Successful comparison (differences shown on stdout)

Notes

The diff is performed on the semantic triplet level (ID, KEY, VALUE), not on raw XML text. This means:

  • XML formatting differences are ignored

  • Element ordering differences are ignored

  • Only actual data value changes are shown

  • Object type filtering happens before comparison

See also

triplets.rdf_parser.load_all_to_dataframe

Loads CIM XML into triplet format

triplets.rdf_parser.print_triplets_diff

Prints differences between triplet DataFrames