🔍 Code Extractor

A utility function that analyzes arguments and keyword arguments to determine if the new or deprecated .opts method signature is being used, returning flags and processed options accordingly.

Purpose

This function serves as a migration helper during the deprecation of an old .opts method signature. It inspects the provided args and kwargs to determine whether the new opts.apply_groups approach should be used, and extracts/processes the options accordingly. It handles multiple signature patterns including dict-based options, group-based kwargs, and explicit options parameters.

Source Code

def deprecated_opts_signature(args, kwargs):
    """
    Utility to help with the deprecation of the old .opts method signature

    Returns whether opts.apply_groups should be used (as a bool) and the
    corresponding options.
    """
    from .options import Options
    groups = set(Options._option_groups)
    opts = {kw for kw in kwargs if kw != 'clone'}
    apply_groups = False
    options = None
    new_kwargs = {}
    if len(args) > 0 and isinstance(args[0], dict):
        apply_groups = True
        if (not set(args[0]).issubset(groups) and
            all(isinstance(v, dict) and (not set(v).issubset(groups) or not v)
                for v in args[0].values())):
            apply_groups = False
        elif set(args[0].keys()) <= groups:
            new_kwargs = args[0]
        else:
            options = args[0]
    elif opts and opts.issubset(set(groups)):
        apply_groups = True
    elif kwargs.get('options', None) is not None:
        apply_groups = True
    elif not args and not kwargs:
        apply_groups = True

    return apply_groups, options, new_kwargs

Parameters

Parameter Details

args: Positional arguments passed to the .opts method. Expected to be a tuple that may contain a dictionary as the first element. This dictionary could represent either grouped options (where keys are option group names) or nested option structures.

kwargs: Keyword arguments passed to the .opts method. Expected to be a dictionary that may contain option group names as keys, an 'options' key with explicit options, or a 'clone' key. Used to determine if the new signature pattern is being used.

Return Value

Returns a tuple of three elements: (1) apply_groups (bool) - indicates whether opts.apply_groups should be used with the new signature, (2) options (dict or None) - the extracted options dictionary if using the old signature format, (3) new_kwargs (dict) - processed keyword arguments for the new signature format, empty dict if not applicable.

Dependencies

• options

Required Imports

from .options import Options

Conditional/Optional Imports

These imports are only needed under specific conditions:

from .options import Options

Usage Example

# Example 1: Old signature with nested dict
args = ({'plot': {'width': 400}},)
kwargs = {}
apply_groups, options, new_kwargs = deprecated_opts_signature(args, kwargs)
# Returns: (False, {'plot': {'width': 400}}, {})

# Example 2: New signature with group kwargs
args = ()
kwargs = {'plot': {'width': 400}, 'style': {'color': 'red'}}
apply_groups, options, new_kwargs = deprecated_opts_signature(args, kwargs)
# Returns: (True, None, {})

# Example 3: New signature with grouped dict
args = ({'plot': {'width': 400}},)
kwargs = {}
apply_groups, options, new_kwargs = deprecated_opts_signature(args, kwargs)
# Returns: (True, None, {'plot': {'width': 400}})

# Example 4: Empty call
args = ()
kwargs = {}
apply_groups, options, new_kwargs = deprecated_opts_signature(args, kwargs)
# Returns: (True, None, {})

Best Practices

• This function is intended for internal use during API migration and should not be used in new code
• The function relies on Options._option_groups being properly defined with valid group names
• When apply_groups is True, use the new opts.apply_groups method; when False, use the old signature
• The function handles multiple edge cases including empty args/kwargs, which defaults to apply_groups=True
• Check the returned options value for None before using it, as it may not be set depending on the signature pattern
• The 'clone' keyword is explicitly excluded from option group detection to avoid false positives

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function merge_options_to_dict 40.0% similar

  Merges a collection of Option objects or partial option dictionaries into a single unified dictionary by iterating through the collection and combining their key-value pairs.

  From: /tf/active/vicechatdev/patches/util.py

• function is_param_method 38.7% similar

  Checks whether an object is a method on a Parameterized object, with optional verification of parameter dependencies.

  From: /tf/active/vicechatdev/patches/util.py

• function validate_dynamic_argspec 37.7% similar

  Validates that a callback function has an appropriate signature to work with DynamicMap by checking its arguments against key dimensions (kdims) and stream parameters.

  From: /tf/active/vicechatdev/patches/util.py

• function merge_option_dicts 36.6% similar

  Performs a deep merge of two nested dictionaries where the top-level values are themselves dictionaries, preserving values from both dictionaries at the nested level.

  From: /tf/active/vicechatdev/patches/util.py

• function argspec 36.1% similar

  Extracts and normalizes function argument specifications from various callable types, removing implicit 'self' or 'cls' parameters from methods.

  From: /tf/active/vicechatdev/patches/util.py