meerschaum.utils.venv

  1#! /usr/bin/env python3
  2# -*- coding: utf-8 -*-
  3# vim:fenc=utf-8
  4
  5"""
  6Manage virtual environments.
  7"""
  8
  9from __future__ import annotations
 10
 11import sys
 12import pathlib
 13
 14from meerschaum.utils.typing import Optional, Union, Dict, List, Tuple
 15from meerschaum.utils.threading import RLock, get_ident
 16
 17__all__ = sorted([
 18    'activate_venv', 'deactivate_venv', 'init_venv',
 19    'inside_venv', 'is_venv_active', 'venv_exec',
 20    'venv_executable', 'venv_exists', 'venv_target_path',
 21    'Venv', 'get_venvs', 'verify_venv', 'get_module_venv',
 22])
 23__pdoc__ = {'Venv': True}
 24
 25LOCKS = {
 26    'sys.path': RLock(),
 27    'active_venvs': RLock(),
 28    'venvs_active_counts': RLock(),
 29}
 30
 31active_venvs = set()
 32active_venvs_counts: Dict[str, int] = {}
 33active_venvs_order: List[Optional[str]] = []
 34threads_active_venvs: Dict[int, 'set[str]'] = {}
 35CREATE_NEW_PROCESS_GROUP = 0x00000200
 36
 37
 38def activate_venv(
 39    venv: Optional[str] = 'mrsm',
 40    color: bool = True,
 41    force: bool = False,
 42    init_if_not_exists: bool = True,
 43    debug: bool = False,
 44    **kw
 45) -> bool:
 46    """
 47    Create a virtual environment (if it doesn't exist) and add it to `sys.path` if necessary.
 48
 49    Parameters
 50    ----------
 51    venv: Optional[str], default 'mrsm'
 52        The virtual environment to activate.
 53
 54    color: bool, default True
 55        If `True`, include color in debug text.
 56
 57    init_if_not_exists: bool, default True
 58        If `True`, create the virtual environment if it does not exist.
 59
 60    force: bool, default False
 61        If `True`, do not exit early even if the venv is currently active.
 62
 63    debug: bool, default False
 64        Verbosity toggle.
 65
 66    Returns
 67    -------
 68    A bool indicating whether the virtual environment was successfully activated.
 69
 70    """
 71    thread_id = get_ident()
 72    if active_venvs_order and active_venvs_order[0] == venv:
 73        if not force:
 74            return True
 75
 76    import sys
 77    import os
 78    if venv is not None and init_if_not_exists:
 79        init_venv(venv=venv, debug=debug)
 80
 81    with LOCKS['active_venvs']:
 82        if thread_id not in threads_active_venvs:
 83            threads_active_venvs[thread_id] = {}
 84        active_venvs.add(venv)
 85        if venv not in threads_active_venvs[thread_id]:
 86            threads_active_venvs[thread_id][venv] = 1
 87        else:
 88            threads_active_venvs[thread_id][venv] += 1
 89
 90        target_path = venv_target_path(venv, debug=debug, allow_nonexistent=True)
 91        if not target_path.exists() and venv is not None and init_if_not_exists:
 92            init_venv(venv=venv, force=True, debug=debug)
 93
 94        if not target_path.exists():
 95            if init_if_not_exists:
 96                return False
 97            raise EnvironmentError(f"Could not activate virtual environment '{venv}'.")
 98
 99        target = target_path.as_posix()
100
101        if venv in active_venvs_order:
102            try:
103                sys.path.remove(target)
104            except Exception:
105                pass
106            try:
107                active_venvs_order.remove(venv)
108            except Exception:
109                pass
110
111        if venv is not None:
112            sys.path.insert(0, target)
113        else:
114            if sys.path and sys.path[0] in (os.getcwd(), ''):
115                sys.path.insert(1, target)
116            else:
117                sys.path.insert(0, target)
118        try:
119            active_venvs_order.insert(0, venv)
120        except Exception:
121            pass
122
123    return True
124
125
126def deactivate_venv(
127    venv: str = 'mrsm',
128    color: bool = True,
129    debug: bool = False,
130    previously_active_venvs: Union['set[str]', List[str], None] = None,
131    force: bool = False,
132    **kw
133) -> bool:
134    """
135    Remove a virtual environment from `sys.path` (if it's been activated).
136
137    Parameters
138    ----------
139    venv: str, default 'mrsm'
140        The virtual environment to deactivate.
141
142    color: bool, default True
143        If `True`, include color in debug text.
144
145    debug: bool, default False
146        Verbosity toggle.
147
148    previously_active_venvs: Union[Set[str], List[str], None]
149        If provided, skip deactivating if a virtual environment is in this iterable.
150
151    force: bool, default False
152        If `True`, forcibly deactivate the virtual environment.
153        This may cause issues with other threads, so be careful!
154
155    Returns
156    -------
157    Return a bool indicating whether the virtual environment was successfully deactivated.
158
159    """
160    import sys
161    thread_id = get_ident()
162    if venv is None:
163        if venv in active_venvs:
164            active_venvs.remove(venv)
165        return True
166
167    if previously_active_venvs and venv in previously_active_venvs and not force:
168        return True
169
170    with LOCKS['active_venvs']:
171        if venv in threads_active_venvs.get(thread_id, {}):
172            new_count = threads_active_venvs[thread_id][venv] - 1
173            if new_count > 0 and not force:
174                threads_active_venvs[thread_id][venv] = new_count
175                return True
176            else:
177                del threads_active_venvs[thread_id][venv]
178
179        if not force:
180            for other_thread_id, other_venvs in threads_active_venvs.items():
181                if other_thread_id == thread_id:
182                    continue
183                if venv in other_venvs:
184                    return True
185        else:
186            to_delete = [other_thread_id for other_thread_id in threads_active_venvs]
187            for other_thread_id in to_delete:
188                del threads_active_venvs[other_thread_id]
189
190        if venv in active_venvs:
191            active_venvs.remove(venv)
192
193    if sys.path is None:
194        return False
195
196    target = venv_target_path(venv, allow_nonexistent=True, debug=debug).as_posix()
197    with LOCKS['sys.path']:
198        if target in sys.path:
199            try:
200                sys.path.remove(target)
201            except Exception:
202                pass
203            try:
204                active_venvs_order.remove(venv)
205            except Exception:
206                pass
207
208    return True
209
210
211def is_venv_active(
212    venv: str = 'mrsm',
213    color : bool = True,
214    debug: bool = False
215) -> bool:
216    """
217    Check if a virtual environment is active.
218
219    Parameters
220    ----------
221    venv: str, default 'mrsm'
222        The virtual environment to check.
223
224    color: bool, default True
225        If `True`, include color in debug text.
226
227    debug: bool, default False
228        Verbosity toggle.
229
230    Returns
231    -------
232    A bool indicating whether the virtual environment `venv` is active.
233
234    """
235    return venv in active_venvs
236
237
238verified_venvs = set()
239def verify_venv(
240    venv: str,
241    debug: bool = False,
242) -> None:
243    """
244    Verify that the virtual environment matches the expected state.
245    """
246    import platform
247    import os
248    import shutil
249    import sys
250    from meerschaum.config._paths import VIRTENV_RESOURCES_PATH
251    from meerschaum.utils.process import run_process
252    from meerschaum.utils.misc import make_symlink, is_symlink
253    from meerschaum.utils.warnings import warn
254
255    venv_path = VIRTENV_RESOURCES_PATH / venv
256    bin_path = venv_path / (
257        'bin' if platform.system() != 'Windows' else "Scripts"
258    )
259    current_python_versioned_name = (
260        'python' + str(sys.version_info.major) + '.' + str(sys.version_info.minor)
261        + ('' if platform.system() != 'Windows' else '.exe')
262    )
263
264    if not (bin_path / current_python_versioned_name).exists():
265        init_venv(venv, verify=False, force=True, debug=debug)
266        current_python_in_venv_path = pathlib.Path(venv_executable(venv=venv))
267        current_python_in_sys_path = pathlib.Path(venv_executable(venv=None))
268        if not current_python_in_venv_path.exists():
269            if is_symlink(current_python_in_venv_path):
270                try:
271                    current_python_in_venv_path.unlink()
272                except Exception as e:
273                    print(f"Unable to remove symlink {current_python_in_venv_path}:\n{e}")
274            try:
275                make_symlink(current_python_in_sys_path, current_python_in_venv_path)
276            except Exception:
277                print(
278                    f"Unable to create symlink {current_python_in_venv_path} "
279                    + f"to {current_python_in_sys_path}."
280                )
281        files_to_inspect = sorted(os.listdir(bin_path), reverse=True)
282    else:
283        files_to_inspect = [current_python_versioned_name]
284
285    def get_python_version(python_path: pathlib.Path) -> Union[str, None]:
286        """
287        Return the version for the python binary at the given path.
288        """
289        try:
290            ### It might be a broken symlink, so skip on errors.
291            if debug:
292                print(f"Getting python version for {python_path}")
293            proc = run_process(
294                [str(python_path), '-V'],
295                as_proc=True,
296                capture_output=True,
297            )
298            stdout, stderr = proc.communicate(timeout=1.0)
299        except Exception as e:
300            ### E.g. the symlink may be broken.
301            if is_symlink(python_path):
302                try:
303                    python_path.unlink()
304                except Exception as _e:
305                    print(f"Unable to remove broken symlink {python_path}:\n{e}\n{_e}")
306            return None
307        return stdout.decode('utf-8').strip().replace('Python ', '')
308
309    ### Ensure the versions are symlinked correctly.
310    for filename in files_to_inspect:
311        if not filename.startswith('python'):
312            continue
313        python_path = bin_path / filename
314        version = get_python_version(python_path)
315        if version is None:
316            continue
317        try:
318            major_version = version.split('.', maxsplit=1)[0]
319            minor_version = version.split('.', maxsplit=2)[1]
320        except IndexError:
321            return
322        python_versioned_name = (
323            'python' + major_version + '.' + minor_version
324            + ('' if platform.system() != 'Windows' else '.exe')
325        )
326
327        ### E.g. python3.10 actually links to Python 3.10.
328        if filename == python_versioned_name:
329            try:
330                real_path = pathlib.Path(os.path.realpath(python_path))
331                real_path_exists = real_path.exists()
332            except Exception:
333                real_path_exists = False
334
335            if not real_path_exists:
336                try:
337                    python_path.unlink()
338                except Exception:
339                    pass
340                init_venv(venv, verify=False, force=True, debug=debug)
341                if not python_path.exists():
342                    raise FileNotFoundError(f"Unable to verify Python symlink:\n{python_path}")
343
344            if python_path == real_path:
345                continue
346
347            try:
348                python_path.unlink()
349            except Exception:
350                pass
351            success, msg = make_symlink(real_path, python_path)
352            if not success:
353                warn(msg, color=False)
354            continue
355
356        python_versioned_path = bin_path / python_versioned_name
357        if python_versioned_path.exists():
358            ### Avoid circular symlinks.
359            if get_python_version(python_versioned_path) == version:
360                continue
361            python_versioned_path.unlink()
362        shutil.move(python_path, python_versioned_path)
363
364
365tried_virtualenv = False
366def init_venv(
367    venv: str = 'mrsm',
368    verify: bool = True,
369    force: bool = False,
370    debug: bool = False,
371) -> bool:
372    """
373    Initialize the virtual environment.
374
375    Parameters
376    ----------
377    venv: str, default 'mrsm'
378        The name of the virtual environment to create.
379
380    verify: bool, default True
381        If `True`, verify that the virtual environment is in the expected state.
382
383    force: bool, default False
384        If `True`, recreate the virtual environment, even if already initalized.
385
386    Returns
387    -------
388    A `bool` indicating success.
389    """
390    if not force and venv in verified_venvs:
391        return True
392    if not force and venv_exists(venv, debug=debug):
393        if verify:
394            verify_venv(venv, debug=debug)
395            verified_venvs.add(venv)
396        return True
397
398    import io
399    from contextlib import redirect_stdout
400    import sys
401    import platform
402    import os
403    import shutil
404    import time
405
406    from meerschaum._internal.static import STATIC_CONFIG
407    from meerschaum.config._paths import (
408        VIRTENV_RESOURCES_PATH,
409        VENVS_CACHE_RESOURCES_PATH,
410    )
411    from meerschaum.utils.packages import is_uv_enabled
412
413    venv_path = VIRTENV_RESOURCES_PATH / venv
414    vtp = venv_target_path(venv=venv, allow_nonexistent=True, debug=debug)
415    docker_home_venv_path = pathlib.Path('/home/meerschaum/venvs/mrsm')
416    lock_path = VENVS_CACHE_RESOURCES_PATH / (venv + '.lock')
417    work_dir_env_var = STATIC_CONFIG['environment']['work_dir']
418
419    def update_lock(active: bool):
420        try:
421            if not active:
422                if debug:
423                    print(f"Releasing lock: '{lock_path}'")
424                lock_path.unlink()
425            else:
426                if debug:
427                    print(f"Acquiring lock: '{lock_path}'")
428                lock_path.touch()
429        except Exception:
430            pass
431
432    def wait_for_lock():
433        if platform.system() == 'Windows':
434            return
435        max_lock_seconds = 30.0
436        sleep_message_seconds = 5.0
437        step_sleep_seconds = 0.1
438        init_venv_check_start = time.perf_counter()
439        last_print = init_venv_check_start
440        while ((time.perf_counter() - init_venv_check_start) < max_lock_seconds):
441            if not lock_path.exists():
442                break
443
444            now = time.perf_counter()
445            if debug or (now - last_print) > sleep_message_seconds:
446                print(f"Lock exists for venv '{venv}', sleeping...")
447                last_print = now
448            time.sleep(step_sleep_seconds)
449        update_lock(False)
450
451    if (
452        not force
453        and venv == 'mrsm'
454        and os.environ.get(work_dir_env_var, None) is not None
455        and docker_home_venv_path.exists()
456    ):
457        wait_for_lock()
458        shutil.move(docker_home_venv_path, venv_path)
459        if verify:
460            verify_venv(venv, debug=debug)
461            verified_venvs.add(venv)
462        return True
463
464    from meerschaum.utils.packages import run_python_package, attempt_import, _get_pip_os_env
465    global tried_virtualenv
466    try:
467        import venv as _venv
468        uv = attempt_import('uv', venv=None, debug=debug) if is_uv_enabled() else None
469        virtualenv = None
470    except ImportError:
471        _venv = None
472        uv = None
473        virtualenv = None
474
475    _venv_success = False
476    temp_vtp = VENVS_CACHE_RESOURCES_PATH / str(venv)
477    ### NOTE: Disable site-packages movement for now.
478    rename_vtp = False and vtp.exists() and not temp_vtp.exists()
479
480    wait_for_lock()
481    update_lock(True)
482
483    if rename_vtp:
484        if debug:
485            print(f"Moving '{vtp}' to '{temp_vtp}'...")
486        shutil.move(vtp, temp_vtp)
487
488    if uv is not None:
489        _venv_success = run_python_package(
490            'uv',
491            ['venv', venv_path.as_posix(), '-q', '--no-project', '--allow-existing', '--seed'],
492            venv=None,
493            env=_get_pip_os_env(),
494            debug=debug,
495        ) == 0
496
497    if _venv is not None and not _venv_success:
498        f = io.StringIO()
499        with redirect_stdout(f):
500            _venv_success = run_python_package(
501                'venv',
502                [venv_path.as_posix()] + (
503                    ['--symlinks']
504                    if platform.system() != 'Windows'
505                    else []
506                ),
507                venv=None, debug=debug
508            ) == 0
509        if not _venv_success:
510            print(f"Please install python3-venv.\n{f.getvalue()}\nFalling back to virtualenv...")
511        if not venv_exists(venv, debug=debug):
512            _venv = None
513    if not _venv_success:
514        virtualenv = attempt_import(
515            'virtualenv',
516            venv=None,
517            lazy=False,
518            install=(not tried_virtualenv),
519            warn=False,
520            check_update=False,
521            color=False,
522            debug=debug,
523        )
524        if virtualenv is None:
525            print(
526                "Failed to import `venv` or `virtualenv`! "
527                + "Please install `virtualenv` via pip then restart Meerschaum."
528            )
529            if rename_vtp and temp_vtp.exists():
530                if debug:
531                    print(f"Moving '{temp_vtp}' back to '{vtp}'...")
532                shutil.move(temp_vtp, vtp)
533            update_lock(False)
534            return False
535
536        tried_virtualenv = True
537        try:
538            python_folder = (
539                'python' + str(sys.version_info.major) + '.' + str(sys.version_info.minor)
540            )
541            dist_packages_path = (
542                VIRTENV_RESOURCES_PATH /
543                venv / 'local' / 'lib' / python_folder / 'dist-packages'
544            )
545            local_bin_path = VIRTENV_RESOURCES_PATH / venv / 'local' / 'bin'
546            bin_path = VIRTENV_RESOURCES_PATH / venv / 'bin'
547            vtp = venv_target_path(venv=venv, allow_nonexistent=True, debug=debug)
548            if bin_path.exists():
549                try:
550                    shutil.rmtree(bin_path)
551                except Exception:
552                    import traceback
553                    traceback.print_exc()
554            virtualenv.cli_run([venv_path.as_posix()])
555            if dist_packages_path.exists():
556                vtp.mkdir(exist_ok=True, parents=True)
557                for file_path in dist_packages_path.glob('*'):
558                    shutil.move(file_path, vtp)
559                shutil.rmtree(dist_packages_path)
560                #  shutil.move(dist_packages_path, vtp)
561                bin_path.mkdir(exist_ok=True, parents=True)
562                for file_path in local_bin_path.glob('*'):
563                    shutil.move(file_path, bin_path)
564                #  shutil.move(local_bin_path, bin_path)
565                shutil.rmtree(local_bin_path)
566
567        except Exception:
568            import traceback
569            traceback.print_exc()
570            if rename_vtp and temp_vtp.exists():
571                shutil.move(temp_vtp, vtp)
572            update_lock(False)
573            return False
574    if verify:
575        verify_venv(venv, debug=debug)
576        verified_venvs.add(venv)
577
578    if rename_vtp and temp_vtp.exists():
579        if debug:
580            print(f"Cleanup: move '{temp_vtp}' back to '{vtp}'.")
581        shutil.move(temp_vtp, vtp)
582
583    update_lock(False)
584    return True
585
586
587def venv_executable(venv: Optional[str] = 'mrsm') -> str:
588    """
589    The Python interpreter executable for a given virtual environment.
590    """
591    from meerschaum.config._paths import VIRTENV_RESOURCES_PATH
592    import sys
593    import platform
594    return (
595        sys.executable if venv is None
596        else str(
597            VIRTENV_RESOURCES_PATH
598            / venv
599            / (
600                'bin' if platform.system() != 'Windows'
601                else 'Scripts'
602            ) / (
603                'python'
604                + str(sys.version_info.major)
605                + '.'
606                + str(sys.version_info.minor)
607            )
608        )
609    )
610
611
612def venv_exec(
613    code: str,
614    venv: Optional[str] = 'mrsm',
615    env: Optional[Dict[str, str]] = None,
616    with_extras: bool = False,
617    as_proc: bool = False,
618    capture_output: bool = True,
619    debug: bool = False,
620) -> Union[bool, Tuple[int, bytes, bytes], 'subprocess.Popen']:
621    """
622    Execute Python code in a subprocess via a virtual environment's interpeter.
623    Return `True` if the code successfully executes, `False` on failure.
624
625    Parameters
626    ----------
627    code: str
628        The Python code to excecute.
629
630    venv: str, default 'mrsm'
631        The virtual environment to use to get the path for the Python executable.
632        If `venv` is `None`, use the default `sys.executable` path.
633
634    env: Optional[Dict[str, str]], default None
635        Optionally specify the environment variables for the subprocess.
636        Defaults to `os.environ`.
637
638    with_extras: bool, default False
639        If `True`, return a tuple of the exit code, stdout bytes, and stderr bytes.
640
641    as_proc: bool, default False
642        If `True`, return the `subprocess.Popen` object instead of executing.
643
644    Returns
645    -------
646    By default, return a bool indicating success.
647    If `as_proc` is `True`, return a `subprocess.Popen` object.
648    If `with_extras` is `True`, return a tuple of the exit code, stdout bytes, and stderr bytes.
649
650    """
651    import os
652    import subprocess
653    import platform
654    from meerschaum.utils.debug import dprint
655    from meerschaum.utils.process import _child_processes
656
657    executable = venv_executable(venv=venv)
658    cmd_list = [executable, '-c', code]
659    if env is None:
660        env = os.environ
661    if debug:
662        dprint(str(cmd_list))
663    if not with_extras and not as_proc:
664        return subprocess.call(cmd_list, env=env) == 0
665
666    stdout, stderr = (None, None) if not capture_output else (subprocess.PIPE, subprocess.PIPE)
667    group_kwargs = (
668        {
669            'preexec_fn': os.setsid,
670        } if platform.system() != 'Windows'
671        else {
672            'creationflags': CREATE_NEW_PROCESS_GROUP,
673        }
674    )
675    process = subprocess.Popen(
676        cmd_list,
677        stdout=stdout,
678        stderr=stderr,
679        stdin=sys.stdin,
680        env=env,
681        **group_kwargs
682    )
683    if as_proc:
684        _child_processes.append(process)
685        return process
686    stdout, stderr = process.communicate()
687    exit_code = process.returncode
688    return exit_code, stdout, stderr
689
690
691def venv_exists(venv: Union[str, None], debug: bool = False) -> bool:
692    """
693    Determine whether a virtual environment has been created.
694    """
695    target_path = venv_target_path(venv, allow_nonexistent=True, debug=debug)
696    return target_path.exists()
697
698
699def venv_target_path(
700    venv: Union[str, None],
701    allow_nonexistent: bool = False,
702    debug: bool = False,
703) -> pathlib.Path:
704    """
705    Return a virtual environment's site-package path.
706
707    Parameters
708    ----------
709    venv: Union[str, None]
710        The virtual environment for which a path should be returned.
711
712    allow_nonexistent: bool, default False
713        If `True`, return a path even if it does not exist.
714
715    Returns
716    -------
717    The `pathlib.Path` object for the virtual environment's path.
718
719    """
720    import os
721    import sys
722    import platform
723    import site
724    from meerschaum.config._paths import VIRTENV_RESOURCES_PATH
725    from meerschaum._internal.static import STATIC_CONFIG
726
727    ### Check sys.path for a user-writable site-packages directory.
728    if venv is None:
729
730        ### Return the known value for the portable environment.
731        environment_runtime = STATIC_CONFIG['environment']['runtime']
732        if os.environ.get(environment_runtime, None) == 'portable':
733            python_version_folder = (
734                'python' + str(sys.version_info.major) + '.' + str(sys.version_info.minor)
735            )
736            executable_path = pathlib.Path(sys.executable)
737            site_packages_path = (
738                (
739                    executable_path.parent.parent / 'lib' / python_version_folder / 'site-packages'
740                ) if platform.system() != 'Windows' else (
741                    executable_path.parent / 'Lib' / 'site-packages'
742                )
743            )
744            if not site_packages_path.exists():
745                raise EnvironmentError(f"Could not find '{site_packages_path}'. Does it exist?")
746            return site_packages_path
747
748        if not inside_venv():
749            user_site_packages = site.getusersitepackages()
750            if user_site_packages is None:
751                raise EnvironmentError("Could not determine user site packages.")
752
753            site_path = pathlib.Path(user_site_packages)
754            if not site_path.exists():
755
756                ### Windows does not have `os.geteuid()`.
757                if platform.system() == 'Windows' or os.geteuid() != 0:
758                    site_path.mkdir(parents=True, exist_ok=True)
759                    return site_path
760
761                ### Allow for dist-level paths (running as root).
762                for possible_dist in site.getsitepackages():
763                    dist_path = pathlib.Path(possible_dist)
764                    if not dist_path.exists():
765                        continue
766                    return dist_path
767                
768                raise EnvironmentError("Could not determine the dist-packages directory.")
769
770            return site_path
771
772    venv_root_path = (
773        (VIRTENV_RESOURCES_PATH / venv)
774        if venv is not None
775        else pathlib.Path(sys.prefix)
776    )
777    target_path = venv_root_path
778
779    ### Ensure 'lib' or 'Lib' exists.
780    lib = 'lib' if platform.system() != 'Windows' else 'Lib'
781    if not allow_nonexistent:
782        if not venv_root_path.exists() or lib not in os.listdir(venv_root_path):
783            print(f"Failed to find lib directory for virtual environment '{venv}'.")
784            import traceback
785            traceback.print_stack()
786            sys.exit(1)
787    target_path = target_path / lib
788
789    ### Check if a 'python3.x' folder exists.
790    python_folder = 'python' + str(sys.version_info.major) + '.' + str(sys.version_info.minor)
791    if target_path.exists():
792        target_path = (
793            (target_path / python_folder)
794            if python_folder in os.listdir(target_path)
795            else target_path
796        )
797    else:
798        target_path = (
799            (target_path / python_folder)
800            if platform.system() != 'Windows'
801            else target_path
802        )
803
804    ### Ensure 'site-packages' exists.
805    if allow_nonexistent or 'site-packages' in os.listdir(target_path): ### Windows
806        target_path = target_path / 'site-packages'
807    else:
808        import traceback
809        traceback.print_stack()
810        print(f"Failed to find site-packages directory for virtual environment '{venv}'.")
811        print("This may be because you are using a different Python version.")
812        print("Try deleting the following directory and restarting Meerschaum:")
813        print(VIRTENV_RESOURCES_PATH)
814        sys.exit(1)
815
816    return target_path
817
818
819def inside_venv() -> bool:
820    """
821    Determine whether current Python interpreter is running inside a virtual environment.
822    """
823    import sys
824    return (
825        hasattr(sys, 'real_prefix') or (
826            hasattr(sys, 'base_prefix')
827                and sys.base_prefix != sys.prefix
828        )
829    )
830
831
832def get_venvs() -> List[str]:
833    """
834    Return a list of all the virtual environments.
835    """
836    import os
837    from meerschaum.config._paths import VIRTENV_RESOURCES_PATH
838    venvs = []
839    for filename in os.listdir(VIRTENV_RESOURCES_PATH):
840        path = VIRTENV_RESOURCES_PATH / filename
841        if not path.is_dir():
842            continue
843        if not venv_exists(filename):
844            continue
845        venvs.append(filename)
846    return venvs
847
848
849def get_module_venv(module) -> Union[str, None]:
850    """
851    Return the virtual environment where an imported module is installed.
852
853    Parameters
854    ----------
855    module: ModuleType
856        The imported module to inspect.
857
858    Returns
859    -------
860    The name of a venv or `None`.
861    """
862    from meerschaum.config.paths import VIRTENV_RESOURCES_PATH
863    module_path = pathlib.Path(module.__file__).resolve()
864    try:
865        rel_path = module_path.relative_to(VIRTENV_RESOURCES_PATH)
866    except ValueError:
867        return None
868
869    return rel_path.as_posix().split('/', maxsplit=1)[0]
870
871
872from meerschaum.utils.venv._Venv import Venv