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