arioso.translation#

Parameter translation layer.

Translates between the unified affordance names and each platform’s native parameter names, applying type coercions along the way.

Module Attributes

ALWAYS_RAISE_UNSUPPORTED

Affordances that always raise on an unsupported platform, regardless of that platform's own on_unsupported_param policy.

Functions

`check_supported_params`(kwargs, config, *[, ...])	Warn or raise for kwargs not declared in a platform's `supported_affordances`.
`make_generate_func`(config)	Build a generate() callable from a platform config.
`make_kwargs_trans`(param_map, *[, ...])	Build a kwargs translation function from a platform's param_map.

arioso.translation.ALWAYS_RAISE_UNSUPPORTED = ('lyrics',)#: Affordances that always raise on an unsupported platform, regardless of that platform’s own on_unsupported_param policy. Losing these silently is losing content, not a quality knob – e.g. an instrumental with none of the caller’s words in it, with no signal that happened. See thorwhalen/arioso#3.

arioso.translation.check_supported_params(kwargs, config, *, always_raise=('lyrics',))[source]#

Warn or raise for kwargs not declared in a platform’s supported_affordances.

on_unsupported_param was, until thorwhalen/arioso#3, only ever enforced inside make_kwargs_trans() – reached solely by the REST-fallback generate built by make_generate_func(). Every platform that ships a custom adapter.py (which is all 14, as of this writing) never went through that translator: its Adapter.generate(..., **kwargs) absorbed and silently dropped anything unsupported, regardless of the config’s declared policy. Call this once, uniformly, before dispatching to any adapter – see arioso.generate/arioso.generate_many.

This only validates; it does not translate or drop keys itself. The caller’s kwargs are passed to the adapter unchanged either way.

Parameters:

kwargs (dict) – The unified-name kwargs about to be passed to an adapter (must not include prompt).
config (dict) – The platform’s PLATFORM_CONFIG dict.
always_raise (tuple) – Affordance names that raise unconditionally when unsupported, overriding the platform’s own policy.

Return type:

None

arioso.translation.make_generate_func(config)[source]#

Build a generate() callable from a platform config.

This is the fallback when no custom adapter.py is provided. For REST API platforms, it builds the HTTP function from the config and wraps it with parameter translation and output normalization.

Parameters:: config (dict) – A PLATFORM_CONFIG dict.
Return type:: Callable
Returns:: A callable that accepts unified affordance kwargs and returns a Song.

arioso.translation.make_kwargs_trans(param_map, *, on_unsupported='warn', passthrough=())[source]#

Build a kwargs translation function from a platform’s param_map.

The returned function transforms:

{common_name: value, ...}  ->  {native_name: coerced_value, ...}

Parameters:

param_map (dict) – Dict mapping common affordance names to native config dicts. Each value has keys: native_name (str), coerce (optional callable), adapter_handled (optional bool).
on_unsupported (str) – What to do with params not in param_map. One of ‘warn’, ‘raise’, or ‘ignore’.
passthrough – Adapter-only keyword names (a config’s adapter_params) passed through untranslated and unwarned.

Return type:

Callable[[dict], dict]

Returns:

A function that translates outer kwargs to inner kwargs.