wrapt 2.2.2: Configure WRAPT_DISABLE_EXTENSIONS environment strings and decorator enabled flags without silent C extension deactivation or lost introspection

# Notes: wrapt Configuration and Decorator Enablement Mechanics

## search_known_solution Result
`search_known_solution` for `pkg:pypi/wrapt` found existing sample `sha256:61d02a30076981ae851aad530bd2d9dbce05537be4411337993c75500740cdd6` ("Subclass the right object proxy base in wrapt 2.x so iteration works"), which focuses on proxy base class selection (`BaseObjectProxy` vs `ObjectProxy` vs `AutoObjectProxy`) and iteration dunder dispatch. This sample targets a completely distinct trap: the environment variable truthiness parsing of `WRAPT_DISABLE_EXTENSIONS`, import-time backend freezing, and static vs dynamic `enabled` behavior in `wrapt.decorator`.

## What a naive model would write instead
A model would set `os.environ["WRAPT_DISABLE_EXTENSIONS"] = "false"` or `"0"` in configuration files expecting to keep compiled C extensions enabled, and would use `@wrapt.decorator(enabled=False)` expecting `func.__wrapped__` and wrapper introspection properties to exist on the returned function.

## How the wrong version fails
Passing boolean-like strings like `"false"` or `"0"` fails silently with a green build while silently downgrading wrapt to the un-accelerated pure-Python fallback, whereas referencing `__wrapped__` or proxy metadata on a decorator disabled with static `enabled=False` fails loudly at runtime with `AttributeError: 'function' object has no attribute '__wrapped__'`.

{"case":{"caseId":"case:sha256:4eba70fb934a8aa11c46e6af89e0e03e2b60697f77b414f70537efe9bf673aa0","contract":["assert setting WRAPT_DISABLE_EXTENSIONS to 'false' or '0' string evaluates truthy in Python and silently disables C extensions","assert unsetting WRAPT_DISABLE_EXTENSIONS or setting empty string keeps C extensions enabled with module _wrappers","assert mutating os.environ after initial wrapt import does not alter extension state without sys.modules cache invalidation","assert @wrapt.decorator with static enabled=False returns raw undecorated function with no FunctionWrapper and no __wrapped__ attribute","assert @wrapt.decorator with dynamic callable enabled returns FunctionWrapper preserving __wrapped__ and allowing runtime toggling"],"goal":"Configure WRAPT_DISABLE_EXTENSIONS environment strings and decorator enabled flags without silent C extension deactivation or lost introspection","kind":"HOW","packages":["pkg:pypi/wrapt@2.2.2"],"schemaVersion":1,"symbols":["wrapt.decorator","wrapt.BaseObjectProxy","wrapt.FunctionWrapper","wrapt.__wrapt__"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/wrapt@2.2.2"],"schemaVersion":1,"symbols":["wrapt.decorator","wrapt.BaseObjectProxy","wrapt.FunctionWrapper","wrapt.__wrapt__"],"verifierAdapter":"python@1"}

wrapt==2.2.2

"""Configuration and wrapper activation mechanics for wrapt.

This module illustrates two critical configuration traps in wrapt:
1. The WRAPT_DISABLE_EXTENSIONS environment variable uses Python truthiness
   checks ('not os.environ.get("WRAPT_DISABLE_EXTENSIONS")'). Thus, passing
   string values like "false" or "0" evaluates as truthy in Python, silently
   disabling C extensions. Extensions are enabled only when the environment
   variable is unset or set to an empty string ("").
2. Passing static enabled=False to @wrapt.decorator returns the raw unwrapped
   function without a FunctionWrapper proxy, stripping __wrapped__ introspection.
   To toggle decorator activation dynamically at runtime while preserving proxy
   introspection, enabled must be passed as a zero-argument callable.
"""

import os
import sys


def reload_wrapt_with_env(env_val):
    """Purge all wrapt modules from sys.modules and reload with the specified environment.

    wrapt freezes extension selection at initial import time in wrapt.__wrapt__.
    Runtime mutations of os.environ after import have no effect without clearing
    the sys.modules cache.
    """
    for mod_name in list(sys.modules.keys()):
        if mod_name == "wrapt" or mod_name.startswith("wrapt."):
            del sys.modules[mod_name]

    if env_val is None:
        os.environ.pop("WRAPT_DISABLE_EXTENSIONS", None)
    else:
        os.environ["WRAPT_DISABLE_EXTENSIONS"] = env_val

    import wrapt

    return wrapt


def is_c_extension_active(wrapt_module):
    """Return whether the loaded wrapt module is using the compiled C extension."""
    return getattr(wrapt_module.__wrapt__, "_using_c_extension", False)


def make_static_disabled_decorator(wrapper_fn):
    """Create a decorator with static enabled=False.

    Returns the raw unwrapped target function at decoration time without
    wrapping in a FunctionWrapper or providing __wrapped__.
    """
    import wrapt

    return wrapt.decorator(enabled=False)(wrapper_fn)


def make_dynamic_toggleable_decorator(wrapper_fn, is_active_fn):
    """Create a decorator with dynamic callable enabled=is_active_fn.

    Wraps the target in a FunctionWrapper, retaining __wrapped__ introspection
    while evaluating is_active_fn at invocation time to conditionally bypass
    the wrapper logic.
    """
    import wrapt

    return wrapt.decorator(enabled=is_active_fn)(wrapper_fn)

import os
import sys
import types

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from src.config import (
    is_c_extension_active,
    make_dynamic_toggleable_decorator,
    make_static_disabled_decorator,
    reload_wrapt_with_env,
)

# ---------------------------------------------------------------------------
# Trap 1: WRAPT_DISABLE_EXTENSIONS truthiness and environment string coercion
# ---------------------------------------------------------------------------

# In wrapt.__wrapt__, extension loading is gated by:
#   _use_extensions = not os.environ.get("WRAPT_DISABLE_EXTENSIONS")
# In Python, any non-empty string is truthy. Therefore, configurations passing
# "false", "0", or "no" intending to keep C extensions ENABLED actually DISABLE them.

# 1a. Passing "false" string disables C extensions
w_false = reload_wrapt_with_env("false")
assert is_c_extension_active(w_false) is False, (
    "Expected WRAPT_DISABLE_EXTENSIONS='false' to disable C extensions due to Python truthiness"
)
assert w_false.BaseObjectProxy.__module__ == "wrapt.wrappers"

# 1b. Passing "0" string disables C extensions
w_zero = reload_wrapt_with_env("0")
assert is_c_extension_active(w_zero) is False, (
    "Expected WRAPT_DISABLE_EXTENSIONS='0' to disable C extensions"
)
assert w_zero.BaseObjectProxy.__module__ == "wrapt.wrappers"

# 1c. Passing "no" string disables C extensions
w_no = reload_wrapt_with_env("no")
assert is_c_extension_active(w_no) is False, (
    "Expected WRAPT_DISABLE_EXTENSIONS='no' to disable C extensions"
)
assert w_no.BaseObjectProxy.__module__ == "wrapt.wrappers"

# 1d. Passing empty string keeps C extensions ENABLED
w_empty = reload_wrapt_with_env("")
assert is_c_extension_active(w_empty) is True, (
    "Expected empty string WRAPT_DISABLE_EXTENSIONS='' to keep C extensions enabled"
)
assert w_empty.BaseObjectProxy.__module__ == "_wrappers"

# 1e. Unset environment variable keeps C extensions ENABLED
w_unset = reload_wrapt_with_env(None)
assert is_c_extension_active(w_unset) is True, (
    "Expected unset WRAPT_DISABLE_EXTENSIONS to keep C extensions enabled"
)
assert w_unset.BaseObjectProxy.__module__ == "_wrappers"


# ---------------------------------------------------------------------------
# Trap 2: Import-time evaluation and sys.modules freezing
# ---------------------------------------------------------------------------

# Environment variable check executes at wrapt import time. Mutating os.environ
# after import has no effect without full sys.modules invalidation.
os.environ["WRAPT_DISABLE_EXTENSIONS"] = "1"
assert is_c_extension_active(w_unset) is True, (
    "Mutating os.environ after initial import should not alter already-imported wrapt instance"
)

# Restoring clean environment
os.environ.pop("WRAPT_DISABLE_EXTENSIONS", None)
wrapt = reload_wrapt_with_env(None)


# ---------------------------------------------------------------------------
# Trap 3: Static enabled=False vs Dynamic callable enabled in @wrapt.decorator
# ---------------------------------------------------------------------------

wrapper_log = []


def sample_wrapper(wrapped, instance, args, kwargs):
    wrapper_log.append("intercepted")
    return wrapped(*args, **kwargs) + 100


# 3a. Static enabled=False returns the raw function directly, stripping FunctionWrapper
static_decorated_fn = make_static_disabled_decorator(sample_wrapper)(lambda x: x + 1)

assert type(static_decorated_fn) is types.FunctionType, (
    "Static enabled=False should return raw function, not a FunctionWrapper"
)
assert not isinstance(static_decorated_fn, wrapt.FunctionWrapper), (
    "Static enabled=False must not create a FunctionWrapper instance"
)
assert not hasattr(static_decorated_fn, "__wrapped__"), (
    "Static enabled=False function must not expose __wrapped__ attribute"
)

try:
    _ = static_decorated_fn.__wrapped__
    raise AssertionError("Expected AttributeError when accessing __wrapped__ on static disabled decorator")
except AttributeError:
    pass

assert static_decorated_fn(5) == 6
assert wrapper_log == [], "Static disabled wrapper must never execute wrapper body"


# 3b. Dynamic callable enabled=lambda: is_active preserves FunctionWrapper & introspection
is_active = False


def check_active():
    return is_active


dynamic_decorated_fn = make_dynamic_toggleable_decorator(sample_wrapper, check_active)(lambda x: x + 1)

assert isinstance(dynamic_decorated_fn, wrapt.FunctionWrapper), (
    "Callable enabled must create a FunctionWrapper proxy"
)
assert hasattr(dynamic_decorated_fn, "__wrapped__"), (
    "Callable enabled wrapper must expose __wrapped__ attribute"
)
assert callable(dynamic_decorated_fn.__wrapped__)

# Call while inactive (bypasses wrapper body)
assert dynamic_decorated_fn(5) == 6
assert wrapper_log == [], "Inactive dynamic wrapper should bypass wrapper logic"

# Toggle state at runtime without recreating wrapper or re-decorating
is_active = True
assert dynamic_decorated_fn(5) == 106
assert wrapper_log == ["intercepted"], "Active dynamic wrapper should execute wrapper logic"

print("CONTRACT PASS: wrapt environment truthiness and decorator enablement verified")