profile_io

sqllocks_spindle.inference.profile_io

Profile I/O — export, import, and manage portable domain profiles.

Provides :class:ProfileIO for exporting domain profiles to standalone JSON files, importing them into other domains, listing available profiles, and inferring distribution profiles from raw DataFrames.

Classes

ExportedProfile dataclass

A portable profile that can be imported into any domain.

Attributes:

Name	Type	Description
name	str	Profile identifier (e.g. "default", "high_volume").
description	str	Human-readable description of what this profile represents.
source_domain	str	Name of the domain this profile was exported from (or "inferred" when created via :meth:ProfileIO.from_dataframe).
distributions	dict[str, dict[str, float]]	Mapping of "table.column" keys to value→weight dicts.
ratios	dict[str, float]	Mapping of ratio names to float multipliers.
metadata	dict[str, Any]	Arbitrary extra information (row counts, column types, etc.).

ProfileIO

Export, import, and list domain profiles.

All public methods are stateless — no configuration is stored on the instance. Instantiate with ProfileIO() and call methods directly.

Example::

io = ProfileIO()
io.export_profile(RetailDomain(), Path("retail_profile.json"))
io.import_profile(Path("retail_profile.json"), HealthcareDomain(), save_as="from_retail")
io.list_profiles(RetailDomain())

Methods:

export_profile(domain, output_path, profile_name='default')

Export a domain's active profile to a standalone JSON file.

Parameters:

Name	Type	Description	Default
domain	Any	A :class:~sqllocks_spindle.domains.base.Domain instance whose _profile dict will be serialised.	required
output_path	str | Path	Destination file path (created if it does not exist).	required
profile_name	str	Label stored in the exported metadata.	'default'

Returns:

Type	Description
Path	The resolved :class:Path the profile was written to.

import_profile(profile_path, target_domain, save_as=None)

Import an exported profile into a target domain's profiles/ directory.

The imported file is converted to the standard domain profile format (i.e. metadata is stripped; only name, description, distributions, and ratios are kept).

Parameters:

Name	Type	Description	Default
profile_path	str | Path	Path to an exported profile JSON file.	required
target_domain	Any	The domain instance to import into.	required
save_as	str | None	Override the profile name (and filename). When None the name is taken from the file's "name" field.	None

Returns:

Type	Description
str	The name the profile was saved as.

list_profiles(domain)

List all profiles available for a domain.

Parameters:

Name	Type	Description	Default
domain	Any	A :class:~sqllocks_spindle.domains.base.Domain instance.	required

Returns:

Type	Description
list[dict[str, str | int]]	A list of dicts with keys name, description,
list[dict[str, str | int]]	distributions (count), and ratios (count).

from_dataframe(df, table_name='table', name='inferred')

Create a profile by inferring distributions from a DataFrame.

Categorical columns (object dtype or low cardinality) are converted into normalised distribution weights. High-cardinality columns are skipped.

Parameters:

Name	Type	Description	Default
df	DataFrame	The source DataFrame.	required
table_name	str	Prefix for distribution keys ("table_name.column").	'table'
name	str	Name to assign to the resulting profile.	'inferred'

Returns:

Name	Type	Description
An	ExportedProfile	class:ExportedProfile ready to be serialised or imported.