|
| 1 | +"""Optional native implementation of library-managed Git operations. |
| 2 | +
|
| 3 | +Installing ``GitPython[gix]`` makes the ``gix`` module available. Unsupported |
| 4 | +operations return ``NotImplemented`` *before* doing work and use the existing |
| 5 | +CLI implementation. Native failures are never retried as CLI mutations. |
| 6 | +""" |
| 7 | + |
| 8 | +from collections import Counter |
| 9 | +from importlib import import_module |
| 10 | +import logging |
| 11 | +import os |
| 12 | +from threading import Lock |
| 13 | +from typing import Any, Callable, Dict, List, Sequence, Tuple |
| 14 | + |
| 15 | +from git.compat import safe_decode |
| 16 | +from git.exc import GitCommandError |
| 17 | + |
| 18 | +_selection = os.environ.get("GIT_PYTHON_BACKEND") |
| 19 | +if _selection not in (None, "cli", "gix"): |
| 20 | + raise ValueError("GIT_PYTHON_BACKEND must be 'cli' or 'gix'") |
| 21 | +gix: Any = None |
| 22 | +if _selection != "cli": |
| 23 | + try: |
| 24 | + gix = import_module("gix") |
| 25 | + except ModuleNotFoundError as exc: |
| 26 | + if exc.name != "gix" or _selection == "gix": |
| 27 | + raise |
| 28 | + |
| 29 | +name = "gix" if gix is not None else "cli" |
| 30 | +_counts: Counter = Counter() |
| 31 | +_lock = Lock() |
| 32 | +_logger = logging.getLogger("git.backend") |
| 33 | + |
| 34 | + |
| 35 | +def record(method: str, outcome: str) -> None: |
| 36 | + with _lock: |
| 37 | + _counts[method, outcome] += 1 |
| 38 | + _logger.debug("%s: %s", method, outcome) |
| 39 | + |
| 40 | + |
| 41 | +def statistics() -> Dict[Tuple[str, str], int]: |
| 42 | + """Return counts by operation and native/fallback reason for this process.""" |
| 43 | + with _lock: |
| 44 | + return dict(_counts) |
| 45 | + |
| 46 | + |
| 47 | +class _Unsupported(Exception): |
| 48 | + """A capability decision made before a native mutation.""" |
| 49 | + |
| 50 | + |
| 51 | +def _fallback(method: str, reason: str) -> Any: |
| 52 | + record(method, "CLI: " + reason) |
| 53 | + return NotImplemented |
| 54 | + |
| 55 | + |
| 56 | +def _repository(command: Any, env: Dict[str, Any], *, query_config: bool = False) -> Any: |
| 57 | + if command._git_options or command._persistent_git_options: |
| 58 | + raise _Unsupported("global command options") |
| 59 | + overrides = {**command.environment(), **env} |
| 60 | + effective = {**os.environ, **overrides} |
| 61 | + path = overrides.get("GIT_DIR") |
| 62 | + if not path: |
| 63 | + raise _Unsupported("repository not bound") |
| 64 | + if not os.path.isabs(path): |
| 65 | + path = os.path.join(command.working_dir or os.getcwd(), path) |
| 66 | + for key in ("GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_NAMESPACE"): |
| 67 | + if effective.get(key): |
| 68 | + raise _Unsupported("storage environment") |
| 69 | + supported = {"GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE"} |
| 70 | + supported.update( |
| 71 | + "GIT_%s_%s" % (role, field) for role in ("AUTHOR", "COMMITTER") for field in ("NAME", "EMAIL", "DATE") |
| 72 | + ) |
| 73 | + if any(key not in supported and value != os.environ.get(key) for key, value in overrides.items()): |
| 74 | + raise _Unsupported("command environment") |
| 75 | + options = gix.OpenOptions().open_path_as_is(True).bail_if_untrusted(True).strict_config(True) |
| 76 | + if not query_config: |
| 77 | + options = options.config_overrides( |
| 78 | + ["core.fsmonitor=false", "gc.auto=0", "maintenance.auto=false", "core.hooksPath=" + os.devnull] |
| 79 | + ) |
| 80 | + repo = gix.open_opts(path, options) |
| 81 | + if repo.config_snapshot().string("extensions.refStorage") == b"reftable": |
| 82 | + raise _Unsupported("reftable (GIX-1)") |
| 83 | + if effective.get("GIT_WORK_TREE"): |
| 84 | + workdir = effective["GIT_WORK_TREE"] |
| 85 | + if not os.path.isabs(workdir): |
| 86 | + workdir = os.path.join(command.working_dir or os.getcwd(), workdir) |
| 87 | + repo.set_workdir(workdir) |
| 88 | + return repo |
| 89 | + |
| 90 | + |
| 91 | +_HANDLERS: Dict[str, Callable[[Any, List[str], Dict[str, Any]], bytes]] = {} |
| 92 | + |
| 93 | + |
| 94 | +def dispatch( |
| 95 | + command: Any, method: str, args: Tuple[Any, ...], kwargs: Dict[str, Any], config: Sequence[str] = () |
| 96 | +) -> Any: |
| 97 | + if gix is None: |
| 98 | + return NotImplemented |
| 99 | + handler = _HANDLERS.get(method) |
| 100 | + if handler is None: |
| 101 | + return _fallback(method, "not converted") |
| 102 | + allowed = {"env", "stdout_as_string", "strip_newline_in_stdout", "with_extended_output"} |
| 103 | + if method == "merge_base": |
| 104 | + allowed.add("all") |
| 105 | + if method in ("hash_object", "mktree", "commit_tree"): |
| 106 | + allowed.add("istream") |
| 107 | + if kwargs.keys() - allowed: |
| 108 | + return _fallback(method, "command/process options") |
| 109 | + if config and method != "commit_tree": |
| 110 | + return _fallback(method, "configuration overrides") |
| 111 | + if config: |
| 112 | + kwargs = dict(kwargs, _config=config) |
| 113 | + kwargs = dict(kwargs, env={**command.environment(), **(kwargs.get("env") or {})}) |
| 114 | + try: |
| 115 | + args_list = command._unpack_args([arg for arg in args if arg is not None]) |
| 116 | + repo = _repository(command, kwargs.get("env", {}), query_config=method == "config") |
| 117 | + output = handler(repo, args_list, kwargs) |
| 118 | + except _Unsupported as exc: |
| 119 | + return _fallback(method, str(exc)) |
| 120 | + except GitCommandError: |
| 121 | + record(method, "native") |
| 122 | + raise |
| 123 | + except gix.Error as exc: |
| 124 | + _logger.debug("%s native read: %s", method, exc) |
| 125 | + return _fallback(method, "native read diagnostics") |
| 126 | + record(method, "native") |
| 127 | + if kwargs.get("strip_newline_in_stdout", True) and output.endswith(b"\n"): |
| 128 | + output = output[:-1] |
| 129 | + result = safe_decode(output) if kwargs.get("stdout_as_string", True) else output |
| 130 | + return (0, result, "") if kwargs.get("with_extended_output") else result |
0 commit comments