confingy.fingy

fingy

Functions for transforming fingys, which are any python object that can be serialized/deserialized by confingy. This includes any class wrapped with confingy.track or confingy.lazy, as well as dataclasses and built-in types.

serialize_fingy

serialize_fingy(fingy: Any) -> dict[str, Any]

Serialize a fingy to a JSON-compatible dictionary.

Parameters:

Name	Type	Description	Default
fingy	Any	The object to serialize	required

Returns:

Type	Description
dict[str, Any]	A dictionary that can be saved to JSON

Source code in src/confingy/fingy.py

def serialize_fingy(fingy: Any) -> dict[str, Any]:
    """
    Serialize a fingy to a JSON-compatible dictionary.

    Args:
        fingy: The object to serialize

    Returns:
        A dictionary that can be saved to JSON
    """
    context = SerializationContext()

    # Register handlers using the central registry
    for handler in HandlerRegistry.get_default_handlers():
        context.register_handler(handler)

    result = context.serialize(fingy)
    return result if result is not None else {}

deserialize_fingy

deserialize_fingy(
    data: dict[str, Any],
    expected_type: Optional[type] = None,
    strict: bool = True,
) -> Any

Deserialize a dictionary back to a fingy.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	The dictionary to deserialize	required
expected_type	Optional[type]	Optional type hint for the expected result	None
strict	bool	If True (default), raise an error when serialized configs contain kwargs that no longer exist in the class signature. If False, emit a warning and ignore the extra kwargs. Similar to PyTorch's load_state_dict strict parameter.	True

Returns:

Type	Description
Any	The reconstructed object

Source code in src/confingy/fingy.py

def deserialize_fingy(
    data: dict[str, Any],
    expected_type: Optional[type] = None,
    strict: bool = True,
) -> Any:
    """
    Deserialize a dictionary back to a fingy.

    Args:
        data: The dictionary to deserialize
        expected_type: Optional type hint for the expected result
        strict: If True (default), raise an error when serialized configs contain
            kwargs that no longer exist in the class signature. If False, emit
            a warning and ignore the extra kwargs. Similar to PyTorch's
            load_state_dict strict parameter.

    Returns:
        The reconstructed object
    """
    context = DeserializationContext(strict=strict)

    # Register all handlers using the central registry
    for handler in HandlerRegistry.get_default_handlers():
        context.register_handler(handler)

    return context.deserialize(data, expected_type)

save_fingy

save_fingy(fingy: Any, filename: str) -> None

Save a fingy to a JSON file.

Parameters:

Name	Type	Description	Default
fingy	Any	The fingy object to save	required
filename	str	Path to the output file	required

Source code in src/confingy/fingy.py

def save_fingy(fingy: Any, filename: str) -> None:
    """
    Save a fingy to a JSON file.

    Args:
        fingy: The fingy object to save
        filename: Path to the output file
    """
    logger.debug(f"Saving fingy to {filename}")
    serialized = serialize_fingy(fingy)

    with open(filename, "w") as f:
        json.dump(serialized, f, indent=2, sort_keys=True)

load_fingy

load_fingy(filename: str, strict: bool = True) -> Any

Load and deserialize a fingy from a JSON file.

Parameters:

Name	Type	Description	Default
filename	str	Path to the JSON file	required
strict	bool	If True (default), raise an error when serialized configs contain kwargs that no longer exist in the class signature. If False, emit a warning and ignore the extra kwargs.	True

Returns:

Type	Description
Any	The deserialized fingy object (may contain lazy instances)

Source code in src/confingy/fingy.py

def load_fingy(filename: str, strict: bool = True) -> Any:
    """
    Load and deserialize a fingy from a JSON file.

    Args:
        filename: Path to the JSON file
        strict: If True (default), raise an error when serialized configs contain
            kwargs that no longer exist in the class signature. If False, emit
            a warning and ignore the extra kwargs.

    Returns:
        The deserialized fingy object (may contain lazy instances)
    """
    logger.debug(f"Loading fingy from {filename}")

    with open(filename) as f:
        data = json.load(f)

    return deserialize_fingy(data, strict=strict)

prettify_fingy

prettify_fingy(fingy: Any) -> dict[str, Any]

Prettify a fingy object.

This function serializes a fingy object and then transforms it into a more readable format by collapsing _confingy_* metadata fields into a simple string representation of the form {module}.{class} and preserving the actual field values.

Parameters:

Name	Type	Description	Default
fingy	Any	The fingy object to prettify	required

Returns:

Type	Description
dict[str, Any]	A dictionary with collapsed metadata that's easier to read

Examples:

Input fingy object that serializes to:

{
    "_confingy_class": "TrainingConfig",
    "_confingy_module": "__main__",
    "_confingy_dataclass": true,
    "_confingy_fields": {
        "dataset": {
            "_confingy_class": "MyDataset",
            "_confingy_module": "__main__",
            "_confingy_init": {
                "size": 100
            }
        }
    }
}

Output:

{
    "__main__.TrainingConfig": {
        "dataset": {
            "__main__.MyDataset": {
                "size": 100
            }
        }
    }
}

Source code in src/confingy/fingy.py

def prettify_fingy(fingy: Any) -> dict[str, Any]:
    """
    Prettify a fingy object.

    This function serializes a fingy object and then transforms it into a more
    readable format by collapsing `_confingy_*` metadata fields into a simple string
    representation of the form `{module}.{class}` and preserving the actual field values.

    Args:
        fingy: The fingy object to prettify

    Returns:
        A dictionary with collapsed metadata that's easier to read

    Examples:
        Input fingy object that serializes to:
        ```json
        {
            "_confingy_class": "TrainingConfig",
            "_confingy_module": "__main__",
            "_confingy_dataclass": true,
            "_confingy_fields": {
                "dataset": {
                    "_confingy_class": "MyDataset",
                    "_confingy_module": "__main__",
                    "_confingy_init": {
                        "size": 100
                    }
                }
            }
        }
        ```

        Output:
        ```json
        {
            "__main__.TrainingConfig": {
                "dataset": {
                    "__main__.MyDataset": {
                        "size": 100
                    }
                }
            }
        }
        ```
    """
    serialized = serialize_fingy(fingy)
    return prettify_serialized_fingy(serialized)

prettify_serialized_fingy

prettify_serialized_fingy(data: Any) -> Any

Transform confingy serialized data into a prettier format.

This function recursively processes serialized confingy data, collapsing metadata fields into readable string representations while preserving the actual content. See prettify_fingy for examples.

Parameters:

Name	Type	Description	Default
data	Any	The serialized data to transform	required

Returns:

Type	Description
Any	Transformed data with collapsed metadata

Source code in src/confingy/fingy.py

def prettify_serialized_fingy(data: Any) -> Any:
    """
    Transform confingy serialized data into a prettier format.

    This function recursively processes serialized confingy data, collapsing metadata
    fields into readable string representations while preserving the actual content.
    See [prettify_fingy][confingy.fingy.prettify_fingy] for examples.

    Args:
        data: The serialized data to transform

    Returns:
        Transformed data with collapsed metadata
    """
    # Base cases
    if data is None or isinstance(data, int | float | str | bool):
        return data

    # Handle lists and tuples
    if isinstance(data, list | tuple):
        result = [prettify_serialized_fingy(item) for item in data]
        return tuple(result) if isinstance(data, tuple) else result

    # Handle dictionaries
    if isinstance(data, dict):
        # Check if this dictionary represents a confingy object
        if SerializationKeys.CLASS in data and SerializationKeys.MODULE in data:
            # This is a confingy object - collapse it
            class_name = data.get(SerializationKeys.CLASS)
            module_name = data.get(SerializationKeys.MODULE)

            # Special handling for type objects
            if class_name == "type" and SerializationKeys.NAME in data:
                return f"{module_name}.{data[SerializationKeys.NAME]}"

            # Special handling for enum members
            if data.get(SerializationKeys.ENUM):
                return f"{module_name}.{class_name}.{data[SerializationKeys.NAME]}"

            key = f"{module_name}.{class_name}"

            # Determine what the nested content should be
            if SerializationKeys.FIELDS in data:
                # Dataclass - use fields
                nested_content = prettify_serialized_fingy(
                    data[SerializationKeys.FIELDS]
                )
            elif SerializationKeys.INIT in data:
                # Tracked class - use init args
                nested_content = prettify_serialized_fingy(data[SerializationKeys.INIT])
            elif SerializationKeys.CONFIG in data:
                # Lazy object - use config
                nested_content = prettify_serialized_fingy(
                    data[SerializationKeys.CONFIG]
                )
            elif SerializationKeys.NAME in data:
                # Type or callable with qualified name
                return f"{module_name}.{data[SerializationKeys.NAME]}"
            elif SerializationKeys.UNSERIALIZABLE in data:
                # Unserializable object
                return data[SerializationKeys.UNSERIALIZABLE]
            elif data.get(SerializationKeys.CALLABLE) == "method":
                # Bound method
                obj = prettify_serialized_fingy(data.get(SerializationKeys.OBJECT, {}))
                method = data.get(SerializationKeys.METHOD, "unknown")
                if isinstance(obj, dict) and len(obj) == 1:
                    # If obj is a collapsed dict with single key, extract it
                    obj_key = next(iter(obj.keys()))
                    return f"{obj_key}.{method}"
                return f"{obj}.{method}"
            elif data.get(SerializationKeys.CALLABLE) == "function":
                # Function
                return f"{module_name}.{data.get(SerializationKeys.NAME, 'unknown')}"
            else:
                # Unknown structure, try to extract any meaningful content
                nested_content = {
                    k: prettify_serialized_fingy(v)
                    for k, v in data.items()
                    if not k.startswith("_confingy_")
                }
                if not nested_content:
                    # No non-metadata content
                    return key

            # Return the collapsed representation
            if isinstance(nested_content, dict) and nested_content or nested_content:
                return {key: nested_content}
            else:
                return key
        else:
            # Regular dictionary - recursively process values
            return {k: prettify_serialized_fingy(v) for k, v in data.items()}

    # For any other type, return as-is
    return data

transpile_fingy

transpile_fingy(
    fingy_data: dict[str, Any] | str | Path,
) -> str

Transpile a serialized fingy back into Python code.

Parameters:

Name	Type	Description	Default
fingy_data	dict[str, Any] | str | Path	Either a dictionary of serialized confingy fingy data, a JSON string, or a path to a JSON file	required

Returns:

Type	Description
str	Python code as a string

Examples:

from confingy import serialize_fingy, transpile_fingy
config = MyConfig(...)
serialized = serialize_fingy(config)
python_code = transpile_fingy(serialized)
print(python_code)

Source code in src/confingy/fingy.py

def transpile_fingy(fingy_data: dict[str, Any] | str | Path) -> str:
    """
    Transpile a serialized fingy back into Python code.

    Args:
        fingy_data: Either a dictionary of serialized confingy fingy data,
                    a JSON string, or a path to a JSON file

    Returns:
        Python code as a string

    Examples:
        ```python
        from confingy import serialize_fingy, transpile_fingy
        config = MyConfig(...)
        serialized = serialize_fingy(config)
        python_code = transpile_fingy(serialized)
        print(python_code)
        ```
    """
    transpiler = _ConfingyTranspiler()
    return transpiler.transpile(fingy_data)