bia)dZddlZddlmZmZmZddlmZmZddl m Z m Z m Z ddl mZGdd eee ZGd d ee e Zy) zKernel Provisioner ClassesN)ABCABCMetaabstractmethod)AnyUnion)InstanceLoggingConfigurableUnicode)KernelConnectionInfoc eZdZy)KernelProvisionerMetaN)__name__ __module__ __qualname__g/home/cdr/jupyterlab/.venv/lib/python3.12/site-packages/jupyter_client/provisioning/provisioner_base.pyrrsrrc*eZdZUdZeddZeed<eddZ e e efed<iZ e ed<eed efd Zed edzfd Zed edzfd Zed ed dfdZed%ded dfdZed%ded dfdZedee ded e fdZed%ded dfdZd%ded dfdZded ee effdZded dfdZd ee effdZded dfdZ d&de!d e!fdZ"d'de!d e!fdZ#de d e dzfd Z$d!ee e fd dfd"Z%d#ee e fd ee e ffd$Z&y)(KernelProvisionerBasea Abstract base class defining methods for KernelProvisioner classes. A majority of methods are abstract (requiring implementations via a subclass) while some are optional and others provide implementations common to all instances. Subclasses should be aware of which methods require a call to the superclass. Many of these methods model those of :class:`subprocess.Popen` for parity with previous versions where the kernel process was managed directly. z$jupyter_client.kernelspec.KernelSpecT) allow_none kernel_specN kernel_idconnection_inforeturncy)z Returns true if this provisioner is currently managing a process. This property is asserted to be True immediately following a call to the provisioner's :meth:`launch_kernel` method. Nrselfs r has_processz!KernelProvisionerBase.has_process#s rc Kyw)z Checks if kernel process is still running. If running, None is returned, otherwise the process's integer-valued exit code is returned. This method is called from :meth:`KernelManager.is_alive`. Nrrs rpollzKernelProvisionerBase.poll.  c Kyw)z Waits for kernel process to terminate. This method is called from `KernelManager.finish_shutdown()` and `KernelManager.kill_kernel()` when terminating a kernel gracefully or immediately, respectively. Nrrs rwaitzKernelProvisionerBase.wait8s  r#signumc Kyw)z Sends signal identified by signum to the kernel process. This method is called from `KernelManager.signal_kernel()` to send the kernel process a signal. Nr)rr&s r send_signalz!KernelProvisionerBase.send_signalCr"r#restartc Kyw)aL Kill the kernel process. This is typically accomplished via a SIGKILL signal, which cannot be caught. This method is called from `KernelManager.kill_kernel()` when terminating a kernel immediately. restart is True if this operation will precede a subsequent launch_kernel request. Nrrr)s rkillzKernelProvisionerBase.killMs  r#c Kyw)a Terminates the kernel process. This is typically accomplished via a SIGTERM signal, which can be caught, allowing the kernel provisioner to perform possible cleanup of resources. This method is called indirectly from `KernelManager.finish_shutdown()` during a kernel's graceful termination. restart is True if this operation precedes a start launch_kernel request. Nrr+s r terminatezKernelProvisionerBase.terminateZs  r#cmdkwargsc Kyw)z Launch the kernel process and return its connection information. This method is called from `KernelManager.launch_kernel()` during the kernel manager's start kernel sequence. Nr)rr/r0s r launch_kernelz#KernelProvisionerBase.launch_kernelhr"r#c Kyw)a" Cleanup any resources allocated on behalf of the kernel provisioner. This method is called from `KernelManager.cleanup_resources()` as part of its shutdown kernel sequence. restart is True if this operation precedes a start launch_kernel request. Nrr+s rcleanupzKernelProvisionerBase.cleanupr  r#c Kyw)a Allows the provisioner to determine if the kernel's shutdown has been requested. This method is called from `KernelManager.request_shutdown()` as part of its shutdown sequence. This method is optional and is primarily used in scenarios where the provisioner may need to perform other operations in preparation for a kernel's shutdown. Nrr+s rshutdown_requestedz(KernelProvisionerBase.shutdown_requested~r5r#cK|jdtjj}|j |j ||j |||d<|Sw)a( Perform any steps in preparation for kernel process launch. This includes applying additional substitutions to the kernel launch command and environment. It also includes preparation of launch parameters. NOTE: Subclass implementations are advised to call this method as it applies environment variable substitutions from the local environment and calls the provisioner's :meth:`_finalize_env()` method to allow each provisioner the ability to cleanup the environment variables that will be used by the kernel. This method is called from `KernelManager.pre_start_kernel()` as part of its start kernel sequence. Returns the (potentially updated) keyword arguments that are passed to :meth:`launch_kernel()`. env)poposenvironcopyupdate/_KernelProvisionerBase__apply_env_substitutions _finalize_env)rr0r9s r pre_launchz KernelProvisionerBase.pre_launchsX$jj +002 411#67 3u  sA'A)c Kyw)z Perform any steps following the kernel process launch. This method is called from `KernelManager.post_start_kernel()` as part of its start kernel sequence. Nr)rr0s r post_launchz!KernelProvisionerBase.post_launchs  r#cNKi}|j|d<|j|d<|Sw)a Captures the base information necessary for persistence relative to this instance. This enables applications that subclass `KernelManager` to persist a kernel provisioner's relevant information to accomplish functionality like disaster recovery or high availability by calling this method via the kernel manager's `provisioner` attribute. NOTE: The superclass method must always be called first to ensure proper serialization. rrrrrprovisioner_infos rget_provisioner_infoz*KernelProvisionerBase.get_provisioner_infos5,.(,%.2.B.B*+s#%rGc4K|d|_|d|_yw)a Loads the base information necessary for persistence relative to this instance. The inverse of `get_provisioner_info()`, this enables applications that subclass `KernelManager` to re-establish communication with a provisioner that is managing a (presumably) remote kernel from an entirely different process that the original provisioner. NOTE: The superclass method must always be called first to ensure proper deserialization. rrNrErFs rload_provisioner_infoz+KernelProvisionerBase.load_provisioner_infos"*+6/0ABs recommendedc|S)aE Returns the time allowed for a complete shutdown. This may vary by provisioner. This method is called from `KernelManager.finish_shutdown()` during the graceful phase of its kernel shutdown sequence. The recommended value will typically be what is configured in the kernel manager. rrrKs rget_shutdown_wait_timez,KernelProvisionerBase.get_shutdown_wait_times rc|S)z Returns the expected upper bound for a kernel (re-)start to complete. This may vary by provisioner. The recommended value will typically be what is configured in the kernel restarter. rrMs rget_stable_start_timez+KernelProvisionerBase.get_stable_start_times rpathcy)a1 Returns the path resolved relative to kernel working directory. For example, path `my_code.py` for a kernel started in `/tmp/` should result in `/tmp/my_code.py`, while path `~/test.py` for a kernel started in `/home/my_user/` should resolve to the (fully specified) `/home/my_user/test.py` path. The provisioner may choose not to resolve any paths, or restrict the resolution to paths local to the kernel working directory to prevent path traversal and exposure of file system layout. Nr)rrQs r resolve_pathz"KernelProvisionerBase.resolve_pathsrr9c|jjrG|jjjjdr|j ddyyy)z Ensures env is appropriate prior to launch. This method is called from `KernelProvisionerBase.pre_launch()` during the kernel's start sequence. NOTE: Subclasses should be sure to call super()._finalize_env(env) pythonPYTHONEXECUTABLEN)rlanguagelower startswithr:)rr9s rr@z#KernelProvisionerBase._finalize_envsP    $ $)9)9)B)B)H)H)J)U)UV^)_ GG& -*` $rsubstitution_valuesci}|jr\ddlm}|jj}|j D]-\}}|j |||j |i/|S)aq Walks entries in the kernelspec's env stanza and applies substitutions from current env. This method is called from `KernelProvisionerBase.pre_launch()` during the kernel's start sequence. Returns the substituted list of env entries. NOTE: This method is private and is not intended to be overridden by provisioners. r)Template)rstringr\r9itemsr>safe_substitute)rrZsubstituted_envr\ templated_envkvs r__apply_env_substitutionsz/KernelProvisionerBase.__apply_env_substitutionsso    ' !,,00M%++- ^1&&8A;+F+FGZ+['\] ^r)F)g@)g$@)'rrr__doc__rrr__annotations__r rrstrrr propertyrboolrintr!r%r(r,r.listr2r4r7dictrArCrHrJfloatrNrPrSr@r?rrrrrsA  FSWXKX%,Td%CIuS'\"C,.O).  T   C$J   C$J        $  4      t       tCy C DX    T  d          c3h2 # $   DcN   CD CT C % % %  t  .c3h .D .T#s(^PTUXZ]U]P^rr) metaclass)rer;abcrrrtypingrrtraitlets.configrr r connectr typerrrrrrtsG  ,,CC* GT*=%> }C!4@U}r