vstools: deobfuscate proxy module (#339)

- Fix duplicated/missing symbols in `__all__`
- Add more documentation and comments things
- Make `(un)register_on_creation` thread safe
- Add `has_environment`, `get_policy`, `get_policy_api`
- Deprecate `clear_cache`, `EnvironmentProxy.policy`,
`EnvironmentProxy.policy_api`, `VSCoreProxy.register_on_destroy`,
`VSCoreProxy.unregister_on_destroy`
- Improve typing a bit

Author: Ichunjo

pyproject.toml

@@ -51,7 +51,7 @@ dependencies = [
     "numpy>=2.0.0",
     "rich>=15.0.0",
     "psutil>=7.0.0",
-    "typing_extensions>=4.15.0; python_version<'3.13'",
+    "typing_extensions>=4.15.0; python_version<'3.15'",
     # VapourSynth plugins
     "vapoursynth-akarin>=1.4.1",
     "vapoursynth-fmtconv>=31",
@@ -346,6 +346,7 @@ warn_unreachable = true
 
 allow_redefinition = true
 implicit_reexport = false
+enable_incomplete_feature = ["TypeForm"]
 strict = true
 
 show_column_numbers = true

stubs/vapoursynth/__init__.pyi

@@ -280,8 +280,8 @@ class EnvironmentPolicyAPI:
 
 def register_policy(policy: EnvironmentPolicy) -> None: ...
 def has_policy() -> bool: ...
-def register_on_destroy(callback: Callable[..., None]) -> None: ...
-def unregister_on_destroy(callback: Callable[..., None]) -> None: ...
+def register_on_destroy(callback: Callable[[], None]) -> None: ...
+def unregister_on_destroy(callback: Callable[[], None]) -> None: ...
 def _try_enable_introspection(version: int | None = None) -> bool: ...
 
 @final

uv.lock

@@ -137,7 +137,7 @@ def cache_clear() -> None:
         for token in ExprToken:
             token.get_value.cache_clear()
 
-    vs.core.register_on_destroy(cache_clear)
+    vs.register_on_destroy(cache_clear)
 
 
 vs.register_on_creation(_cache_clear_expr_token)

vsexprtools/exprop.py

@@ -1,13 +1,14 @@
 import sys
 
-__all__ = ["TypeIs", "TypeVar", "deprecated"]
+__all__ = ["TypeForm", "TypeIs", "TypeVar", "deprecated"]
 
 if sys.version_info < (3, 13):
-    import typing_extensions
-
-    TypeIs = typing_extensions.TypeIs
-    TypeVar = typing_extensions.TypeVar
-    deprecated = typing_extensions.deprecated
+    from typing_extensions import TypeIs, TypeVar, deprecated
 else:
     from typing import TypeIs, TypeVar
     from warnings import deprecated
+
+if sys.version_info < (3, 15):
+    from typing_extensions import TypeForm
+else:
+    from typing import TypeForm

vsjetpack/types.py

@@ -1,2 +1,34 @@
+"""
+Drop-in replacement for ``import vapoursynth`` that re-exports the upstream API
+and layers additional functionality on top.
+
+Key additions:
+
+- Lazy / proxied core access
+
+    Allows holding references like ``core.std.BlankClip`` without triggering core creation
+    or locking into an environment policy.
+
+    * ``core.proxied``: A weakref-backed proxy to the current active core.
+    * ``core.lazy``: A completely lazy proxy resolving only on function invocation.
+
+- Core lifecycle hooks
+
+    ``register_on_creation`` / ``unregister_on_creation`` react to core instantiation.
+
+- Policy and environment introspection
+
+    Retrieve environment policies via GC graph walking and check active environment status.
+
+- Interactive compatibility
+
+    Stubs ``__file__`` and the ``__vapoursynth__`` module for Jupyter notebooks, REPLs,
+    and IDE interactive windows so VSScript environment policies resolve correctly.
+
+- Extended preset video formats
+
+    Exports missing bit-depth and subsampling variant constants.
+"""
+
 from .objects import *
 from .vs_vars import *

vstools/vs_proxy/__init__.py

@@ -1,15 +1,15 @@
 from __future__ import annotations
 
+import logging
 import weakref
 from abc import ABC, ABCMeta
 from collections.abc import Callable, Mapping, MutableMapping, MutableSequence, MutableSet
 from enum import Flag
 from functools import partial
 from itertools import chain
-from logging import getLogger
 from typing import TYPE_CHECKING, Any, Self
 
-from jetpytools import Singleton, classproperty
+from jetpytools import Singleton, classproperty, to_arr
 
 from vsjetpack import is_from_vs_module
 
@@ -18,7 +18,7 @@
 __all__ = ["VSDebug", "VSObject", "VSObjectABC", "VSObjectABCMeta", "VSObjectMeta"]
 
 
-log = getLogger(__name__)
+log = logging.getLogger(__name__)
 
 
 def _get_mangle_name(name: str) -> str:
@@ -131,7 +131,7 @@ def vsdel_partial_register() -> None:
             )
 
         setattr(obj, prefix + partial_attr, vsdel_partial_register)
-        core.register_on_destroy(vsdel_partial_register)
+        register_on_destroy(vsdel_partial_register)
 
     setattr(obj, prefix + register_attr, del_register)
     register_on_creation(del_register)
@@ -161,7 +161,14 @@ def __new__[MetaSelf: VSObjectMeta](
             mname = _get_mangle_name(name)
 
             original_slots = tuple(namespace.get("__slots__", ()))
-            extra_slots = tuple(f"{mname}{slot}" for slot in _objregisters)
+            extra_slots = [f"{mname}{slot}" for slot in _objregisters]
+
+            # Collect all slots defined in parent classes to check if __weakref__ is already defined
+            all_base_slots = set(chain.from_iterable(to_arr(getattr(base, "__slots__", ())) for base in bases))
+
+            if "__weakref__" not in original_slots and "__weakref__" not in all_base_slots:
+                extra_slots.append("__weakref__")
+
             namespace["__slots__"] = (*extra_slots, *original_slots)
 
             for reg in _clsregisters:
@@ -246,17 +253,15 @@ def __init__(self, *, env_life: bool = True, core_fetch: bool = False, use_loggi
                 trying to find the code path that is locking you into a EnvironmentPolicy.
         """
         if use_logging:
-            import logging
-
             VSDebug._print_func = logging.debug
         else:
             VSDebug._print_func = print
 
         if env_life:
-            register_on_creation(VSDebug._print_env_live, True)
+            register_on_creation(VSDebug._print_env_live)
 
         if core_fetch:
-            register_on_creation(VSDebug._print_stack, True)
+            register_on_creation(VSDebug._print_stack)
 
     @staticmethod
     def _print_stack(core_id: int) -> None:
@@ -266,7 +271,7 @@ def _print_stack(core_id: int) -> None:
     def _print_env_live(core_id: int) -> None:
         VSDebug._print_func(f"New core created with id: {core_id}")
 
-        core.register_on_destroy(VSDebug._print_core_destroy, False)
+        register_on_destroy(partial(VSDebug._print_core_destroy, core.env.env_id, core_id))
         register_on_destroy(partial(VSDebug._print_destroy, core.env.env_id, core_id))
 
     @staticmethod