API reference¶
Auto-generated from the docstrings in svg_to_drawio. See Python API for usage examples.
Top-level functions¶
svg_to_drawio.convert_file(svg_path, out_path=None, *, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert a single SVG file into a .drawio file and return the output path.
svg_to_drawio.convert_to_string(svg_path, *, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert a single SVG file into draw.io XML and return the result as a string.
svg_to_drawio.convert_svg_string(svg_text, *, base_dir=None, title='diagram', source_label=None, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert SVG markup already loaded in memory into draw.io XML.
svg_to_drawio.convert_svg_bytes(svg_bytes, *, base_dir=None, title='diagram', source_label=None, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert SVG bytes already loaded in memory into draw.io XML.
svg_to_drawio.convert_file_result(svg_path, out_path=None, *, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert a single SVG file and return a rich conversion result.
svg_to_drawio.convert_to_string_result(svg_path, *, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert a single SVG file to XML and return a rich conversion result.
svg_to_drawio.convert_svg_string_result(svg_text, *, base_dir=None, title='diagram', source_label=None, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert SVG markup already loaded in memory and return a rich conversion result.
svg_to_drawio.convert_svg_bytes_result(svg_bytes, *, base_dir=None, title='diagram', source_label=None, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert SVG bytes already loaded in memory and return a rich conversion result.
svg_to_drawio.analyze_file(svg_path, *, flatten=False, max_elements=None, rendering_options=None)
¶
Analyze one SVG file and return a structured diagnostics report.
svg_to_drawio.merge_files(input_paths, output_path, *, mode='pages', columns=None, output_dir=None, recursive=False, overwrite=False, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Combine every SVG found in input_paths into one merged .drawio file.
output_path is resolved the same way the CLI's --merge-output is: a relative value
(or bare filename) is placed inside output_dir when given, the .drawio extension is
appended automatically if missing, and an absolute path is used as-is. Existing output
is skipped unless overwrite=True.
Conversion result¶
svg_to_drawio.ConversionResult(xml, report, source_path=None, output_path=None)
dataclass
¶
Complete result of one SVG conversion run.
compatibility_score
property
¶
Expose the underlying report score directly on the conversion result.
fallback_count
property
¶
Expose the fallback count directly on the conversion result.
warning_count
property
¶
Expose the warning count directly on the conversion result.
to_dict()
¶
Serialize the result into a JSON-friendly dictionary.
Rendering options and presets¶
svg_to_drawio.RenderingOptions(gradient_policy='auto', filter_policy='auto', text_metrics_policy='auto')
dataclass
¶
Fine-grained rendering choices shared by the CLI, API, and desktop app.
should_force_filter_fallback(filter_ref)
¶
Return whether a filter should always be rendered through embedded SVG.
should_force_gradient_fallback()
¶
Return whether multi-stop gradients should always prefer embedded SVG fallback.
should_prefer_native_filter()
¶
Return whether unsupported filters should be ignored to keep native output.
should_prefer_native_gradient()
¶
Return whether multi-stop gradients should stay native whenever possible.
to_dict()
¶
Serialize the policy set into a JSON-friendly dictionary.
svg_to_drawio.rendering_preset_options(preset)
¶
Return the rendering policy bundle associated with one user-facing preset.
svg_to_drawio.rendering_preset_label(preset)
¶
Return the public label for one rendering preset.
svg_to_drawio.detect_rendering_preset(options)
¶
Return the preset key matching the given options, or None for custom mixes.
Capabilities¶
svg_to_drawio.all_capabilities()
¶
Return the registered public capability descriptors in label order.
svg_to_drawio.capability_descriptor(capability_key)
¶
Return one registered capability descriptor.
svg_to_drawio.capability_keys()
¶
Return the stable set of public capability keys accepted by user-facing APIs.
svg_to_drawio.rendering_preflight_lines(options)
¶
Summarize the current rendering policies in plain English for the CLI and desktop app.
Quality gates¶
svg_to_drawio.QualityGateOptions(fail_on_warning=False, fail_on_fallback=False, min_score=None, require_native=())
dataclass
¶
User-configurable compatibility thresholds for automated runs.
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
svg_to_drawio.QualityGateViolation(source_path, message)
dataclass
¶
One compatibility rule that a conversion report did not satisfy.
svg_to_drawio.evaluate_quality_gates(reports, options)
¶
Evaluate a batch of conversion reports against the configured quality thresholds.
Converter¶
svg_to_drawio.Converter()
¶
Convert SVG files into draw.io XML by walking the SVG element tree.
analyze_file(svg_path, *, flatten=False, max_elements=None, rendering_options=None)
¶
Analyze one SVG file without writing output, returning its structured report.
convert_file(svg_path, out_path=None, *, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert one SVG file into a .drawio file and return the output path.
convert_file_for_merge(svg_path, *, flatten=False, max_elements=None, rendering_options=None)
¶
Parse one SVG file into raw draw.io cells, without serializing or writing output.
Used by ConversionService.merge(): the combined .drawio document is built from
several files' cells at once, so post-processing (legend/background) is applied once
on the final merged result instead of once per source file.
convert_file_result(svg_path, out_path=None, *, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert one SVG file, write it to disk, and return a rich conversion result.
convert_svg_bytes_result(svg_bytes, *, base_dir=None, title='diagram', source_label=None, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert SVG bytes already loaded in memory and return a rich conversion result.
Parses the raw bytes directly so an <?xml encoding="..."?> declaration (or a
UTF-16 BOM) is honored by the XML parser, the same way ET.parse already honors
it for file-path-based conversions. Forcing a UTF-8 decode first would raise a raw
UnicodeDecodeError on a validly-encoded non-UTF-8 SVG instead of parsing it.
convert_svg_string_result(svg_text, *, base_dir=None, title='diagram', source_label=None, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert SVG markup already loaded in memory and return a rich conversion result.
convert_to_string(svg_path, *, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert one SVG file and return the draw.io XML as a string.
convert_to_string_result(svg_path, *, flatten=False, max_elements=None, rendering_options=None, post_process=None)
¶
Convert one SVG file and return a rich in-memory conversion result.
get_report()
¶
Return a detached report for the most recent conversion run.
next_id()
¶
Return the next unique draw.io cell identifier.
reset()
¶
Reset all per-file conversion state.
Batch conversion service¶
svg_to_drawio.ConversionService(converter_factory=None)
¶
Shared high-level service for converting SVG files and directories.
convert(input_paths, options, *, reporter=None, cancellation_token=None)
¶
Convert every planned SVG and emit progress events along the way.
convert_parallel(input_paths, options, *, max_workers=4, reporter=None, cancellation_token=None)
¶
Convert every planned SVG in parallel while keeping batch semantics stable.
merge(input_paths, options, *, mode, output_path, columns=None, reporter=None, cancellation_token=None)
¶
Convert every planned SVG into one merged .drawio file (multi-page or grid layout).
plan(input_paths, options)
¶
Expand input files and directories into concrete conversion jobs.
svg_to_drawio.ConversionOptions(output_dir=None, recursive=False, overwrite=False, flatten=False, max_elements=None, use_cache=True, rendering=RenderingOptions(), post_process=None)
dataclass
¶
User-configurable settings for a batch conversion run.
svg_to_drawio.ConversionSummary(total, converted, skipped, failed, cancelled=False, reports=list())
dataclass
¶
svg_to_drawio.CancellationToken()
¶
svg_to_drawio.ConversionEvent(kind, message, completed, total, source_path=None, output_path=None, error=None, summary=None, report=None)
dataclass
¶
Progress event emitted during a batch conversion run.
svg_to_drawio.ConversionEventKind
¶
Bases: StrEnum
High-level events emitted while converting files.
svg_to_drawio.watch_svg_files(input_paths, options, reporter=None, poll_interval=1.0, stop_event=None, backend='auto')
¶
Watch SVG files for modifications and re-convert when changes are detected.
Runs an initial conversion of all discovered files, then either uses an event-driven watcher when available or falls back to polling.
svg_to_drawio.resolve_watch_backend(backend)
¶
Resolve the requested watch backend into a concrete implementation name.
svg_to_drawio.event_watch_available()
¶
Return whether the optional watchdog backend is available.
Post-processing¶
svg_to_drawio.PostProcessOptions(legend=False, background=None)
dataclass
¶
Diagnostics and compatibility¶
svg_to_drawio.ConversionReport(source_path='', output_path=None, generated_at=(lambda: datetime.now(UTC).isoformat())(), analyze_only=False, cached=False, truncated=False, fallback_count=0, emitted_cells=0, issues=list(), assets=list(), preview_annotations=list(), dependencies=list(), feature_observations=list())
dataclass
¶
Mutable diagnostic report for one input SVG file.
compatibility_matrix
property
¶
Return a beginner-friendly compatibility matrix for the converted file.
compatibility_overview
property
¶
Return a short beginner-friendly compatibility summary.
compatibility_score
property
¶
Return a coarse compatibility score suitable for summaries and reports.
error_count
property
¶
Return the number of error-level issues recorded for this file.
warning_count
property
¶
Return the number of warning-level issues recorded for this file.
add_asset(href, status, *, resolved_path=None, mime_type=None, message=None)
¶
Append a deduplicated asset reference to the report.
add_dependency(dependency_path)
¶
Track one file path that should invalidate the conversion cache when it changes.
add_issue(code, severity, message, *, element_tag=None, element_id=None, fallback_used=False)
¶
Append a deduplicated issue to the report.
add_preview_annotation(*, status, label, message, feature_key, x, y, width, height, element_tag=None, element_id=None)
¶
Append a deduplicated preview overlay region to the report.
clone()
¶
Return a detached copy suitable for events or cache snapshots.
from_dict(payload)
classmethod
¶
Rehydrate a serialized conversion report.
record_feature_observation(observation)
¶
Append or increment a deduplicated user-facing feature observation.
short_status()
¶
Return a compact human-readable status line for logs and the CLI.
to_dict()
¶
Serialize the full report into a JSON-friendly dictionary.
svg_to_drawio.CompatibilityOverview(level, headline, summary)
dataclass
¶
High-level beginner-friendly summary of a conversion report.
to_dict()
¶
Serialize the overview into a JSON-friendly dictionary.
svg_to_drawio.CompatibilityRow(feature_key, label, description, status, status_label, message, count, details)
dataclass
¶
Aggregated, user-facing view of one feature family.
to_dict()
¶
Serialize the aggregated row into a JSON-friendly dictionary.