pygitweb 0.1.0__py3-none-any.whl

pygitweb/git_helpers_test.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Generator
+from pathlib import Path
+from unittest.mock import patch
+
+import pygit2
+import pytest
+
+from pygitweb.config import settings
+from pygitweb.git_helpers import (
+	_config_cache,
+	config_to_bool,
+	config_to_int,
+	get_blob_at_ref_path,
+	get_blob_unified_diff,
+	get_commit_history,
+	get_commit_unified_diff,
+	get_commits_in_range,
+	get_readme_at_ref_path,
+	get_tree_at_ref_path,
+	git_get_file_or_project_config,
+	git_get_heads_list,
+	git_get_project_config,
+	git_get_project_description,
+	git_get_references,
+	git_get_remotes_info,
+	git_get_tags_list,
+	git_get_type,
+	git_parse_project_config,
+	hash_set_multi,
+	parse_commit,
+	parse_tag,
+)
+
+
+def _run_git(repo_dir: Path, *args: str) -> str:
+	completed: subprocess.CompletedProcess[str] = subprocess.run(
+		["git", *args],
+		cwd=repo_dir,
+		capture_output=True,
+		text=True,
+		check=True,
+	)
+	return completed.stdout.strip()
+
+
+class TestGitHelpers:
+	class TestPure:
+		def test_hash_set_multi_promotes_to_list(self) -> None:
+			data: dict[str, object] = {}
+			hash_set_multi(data, "k", "v1")
+			hash_set_multi(data, "k", "v2")
+			assert data["k"] == ["v1", "v2"]
+
+		@pytest.mark.parametrize(
+			("value", "expected"),
+			[("true", True), ("0", False), (None, True)],
+		)
+		def test_config_to_bool(self, value: str | None, expected: bool) -> None:
+			assert config_to_bool(value) is expected
+
+		@pytest.mark.parametrize(
+			("value", "expected"),
+			[("2k", 2048), ("3M", 3145728), ("123", "123"), (None, 0)],
+		)
+		def test_config_to_int(self, value: str | None, expected: int | str) -> None:
+			assert config_to_int(value) == expected
+
+	class TestRepoReadonly:
+		@pytest.fixture(scope="class")
+		def repo_ctx(self, tmp_path_factory: pytest.TempPathFactory) -> Generator[dict[str, str], None, None]:
+			project_root: Path = tmp_path_factory.mktemp("git-helpers")
+			repo_dir: Path = project_root / "sample"
+			repo_dir.mkdir()
+
+			_run_git(repo_dir, "init", "-b", "main")
+			_run_git(repo_dir, "config", "user.name", "Alice")
+			_run_git(repo_dir, "config", "user.email", "alice@example.com")
+			_run_git(repo_dir, "remote", "add", "origin", "https://example.com/repo.git")
+			_run_git(repo_dir, "remote", "set-url", "--push", "origin", "ssh://example.com/repo.git")
+			_run_git(repo_dir, "config", "gitweb.owner", "alice")
+			_run_git(repo_dir, "config", "--add", "gitweb.category", "infra")
+			_run_git(repo_dir, "config", "--add", "gitweb.category", "tools")
+
+			(repo_dir / "README.md").write_text("Root README\n", encoding="utf-8")
+			(repo_dir / "docs").mkdir()
+			(repo_dir / "docs" / "README").write_text("Docs README\n", encoding="utf-8")
+			(repo_dir / "docs" / "guide.txt").write_text("hello\n", encoding="utf-8")
+			(repo_dir / "src").mkdir()
+			(repo_dir / "src" / "app.py").write_text("print('v1')\n", encoding="utf-8")
+			_run_git(repo_dir, "add", ".")
+			_run_git(repo_dir, "commit", "-m", "initial commit")
+
+			first_commit: str = _run_git(repo_dir, "rev-parse", "HEAD")
+			(repo_dir / "docs" / "guide.txt").write_text("hello\nworld\n", encoding="utf-8")
+			(repo_dir / "src" / "app.py").write_text("print('v2')\n", encoding="utf-8")
+			_run_git(repo_dir, "add", ".")
+			_run_git(repo_dir, "commit", "-m", "update docs and app")
+			second_commit: str = _run_git(repo_dir, "rev-parse", "HEAD")
+
+			_run_git(
+				repo_dir,
+				"tag",
+				"-a",
+				"v1.0",
+				"-m",
+				"release v1.0",
+				second_commit,
+			)
+			_run_git(repo_dir, "tag", "lightweight", first_commit)
+			_run_git(repo_dir, "branch", "feature/readme", second_commit)
+
+			git_dir: Path = repo_dir / ".git"
+			(git_dir / "description").write_text("Repo description\n", encoding="utf-8")
+
+			ctx: dict[str, str] = {
+				"project": "sample/.git",
+				"first_commit": first_commit,
+				"second_commit": second_commit,
+			}
+
+			_config_cache.clear()
+			with patch.object(settings, "PROJECTROOT", str(project_root)):
+				yield ctx
+			_config_cache.clear()
+
+		def test_git_get_type(self, repo_ctx: dict[str, str]) -> None:
+			assert git_get_type(repo_ctx["project"], "HEAD") == "commit"
+			assert git_get_type(repo_ctx["project"], "HEAD^{tree}") == "tree"
+
+		def test_git_parse_and_get_project_config(self, repo_ctx: dict[str, str]) -> None:
+			cfg: dict[str, object] = git_parse_project_config(repo_ctx["project"], "gitweb")
+			assert cfg["gitweb.owner"] == "alice"
+			assert cfg["gitweb.category"] == ["infra", "tools"]
+			assert git_get_project_config(repo_ctx["project"], "owner") == "alice"
+			assert git_get_project_config(repo_ctx["project"], "category") == ["infra", "tools"]
+
+		def test_git_get_file_or_project_config_prefers_file(self, repo_ctx: dict[str, str]) -> None:
+			assert git_get_file_or_project_config(repo_ctx["project"], "description") == "Repo description"
+			assert git_get_project_description(repo_ctx["project"]) == "Repo description"
+
+		def test_references_heads_tags_and_remotes(self, repo_ctx: dict[str, str]) -> None:
+			heads: list[tuple[str, str, str]] = git_get_heads_list(repo_ctx["project"])
+			head_names: set[str] = {name for name, _ref, _oid in heads}
+			assert {"main", "feature/readme"} <= head_names
+
+			refs: list[tuple[str, str]] = git_get_references(repo_ctx["project"])
+			assert any(name == "refs/heads/main" for name, _oid in refs)
+
+			tags: list[tuple[str, str, str]] = git_get_tags_list(repo_ctx["project"])
+			tag_names: set[str] = {name for name, _ref, _oid in tags}
+			assert {"v1.0", "lightweight"} <= tag_names
+
+			remotes: list[dict[str, object]] = git_get_remotes_info(repo_ctx["project"])
+			assert remotes == [
+				{
+					"name": "origin",
+					"url": "https://example.com/repo.git",
+					"push_url": "ssh://example.com/repo.git",
+				}
+			]
+
+		def test_parse_commit_and_parse_tag(self, repo_ctx: dict[str, str]) -> None:
+			commit_data: dict[str, object] = parse_commit(repo_ctx["project"], repo_ctx["second_commit"])
+			assert commit_data["subject"] == "update docs and app"
+			assert commit_data["author"] == "Alice"
+			assert isinstance(commit_data["parent"], list)
+
+			repo = pygit2.Repository(str(Path(settings.PROJECTROOT) / repo_ctx["project"]))
+			tag_oid: str = str(repo.references["refs/tags/v1.0"].target)
+			tag_data: dict[str, object] = parse_tag(repo_ctx["project"], tag_oid)
+			assert tag_data["type"] == "tag"
+			assert tag_data["message"] == "release v1.0\n"
+
+		def test_tree_blob_and_readme_resolution(self, repo_ctx: dict[str, str]) -> None:
+			tree_result = get_tree_at_ref_path(repo_ctx["project"], "HEAD", "docs")
+			assert tree_result is not None
+			tree, ref_oid = tree_result
+			assert ref_oid == repo_ctx["second_commit"]
+			assert tree["guide.txt"].type_str == "blob"
+
+			blob_result = get_blob_at_ref_path(repo_ctx["project"], "HEAD", "docs/guide.txt")
+			assert blob_result is not None
+			blob, _resolved_ref = blob_result
+			assert blob.data.decode("utf-8") == "hello\nworld\n"
+
+			readme_root = get_readme_at_ref_path(repo_ctx["project"], "HEAD", "")
+			assert readme_root == ("README.md", "Root README\n")
+			readme_docs = get_readme_at_ref_path(repo_ctx["project"], "HEAD", "docs")
+			assert readme_docs == ("README", "Docs README\n")
+
+		def test_commit_history_and_ranges(self, repo_ctx: dict[str, str]) -> None:
+			all_history: list[dict[str, object]] = get_commit_history(repo_ctx["project"], max_count=10)
+			assert [entry["oid"] for entry in all_history] == [repo_ctx["second_commit"], repo_ctx["first_commit"]]
+
+			path_history: list[dict[str, object]] = get_commit_history(
+				repo_ctx["project"],
+				path="docs/guide.txt",
+				max_count=10,
+			)
+			assert [entry["oid"] for entry in path_history] == [repo_ctx["second_commit"], repo_ctx["first_commit"]]
+
+			in_range: list[str] = get_commits_in_range(repo_ctx["project"], "HEAD", repo_ctx["first_commit"])
+			assert in_range == [repo_ctx["second_commit"]]
+
+		def test_blob_and_commit_unified_diff(self, repo_ctx: dict[str, str]) -> None:
+			blob_diff = get_blob_unified_diff(
+				repo_ctx["project"],
+				repo_ctx["first_commit"],
+				"src/app.py",
+				repo_ctx["second_commit"],
+				"src/app.py",
+			)
+			assert blob_diff is not None
+			assert "-print('v1')" in blob_diff
+			assert "+print('v2')" in blob_diff
+
+			commit_diff, oid_short = get_commit_unified_diff(repo_ctx["project"], "HEAD")
+			assert "docs/guide.txt" in commit_diff
+			assert "src/app.py" in commit_diff
+			assert oid_short == repo_ctx["second_commit"][:7]

pygitweb/gravatar.py

@@ -0,0 +1,16 @@
+"""Gravatar avatar URLs (https://gravatar.com)."""
+
+from __future__ import annotations
+
+import hashlib
+from urllib.parse import urlencode
+
+_GRAVATAR_BASE = "https://www.gravatar.com/avatar"
+
+
+def gravatar_url(email: str, *, size: int = 64) -> str:
+	"""Return a Gravatar image URL for ``email`` (``d=404`` when no profile exists)."""
+	normalized = email.strip().lower().encode("utf-8")
+	digest = hashlib.md5(normalized).hexdigest()  # noqa: S324
+	params = urlencode({"s": str(size), "d": "404"})
+	return f"{_GRAVATAR_BASE}/{digest}?{params}"

pygitweb/gravatar_test.py

@@ -0,0 +1,10 @@
+from pygitweb.gravatar import gravatar_url
+
+
+def test_gravatar_url_known_hash() -> None:
+	url = gravatar_url("test@example.com", size=80)
+	assert url == "https://www.gravatar.com/avatar/55502f40dc8b7c769880b10874abc9d0?s=80&d=404"
+
+
+def test_gravatar_url_normalizes_email() -> None:
+	assert gravatar_url("  Test@Example.COM  ") == gravatar_url("test@example.com")

pygitweb/hooks_install.py

@@ -0,0 +1,278 @@
+"""
+Install, remove, and inspect pygittools hook samples in a project's hooks directory.
+
+A "sample" is a file in `pygittools/hook_samples/` whose name encodes the target git
+hook as the prefix before the first dot (e.g. `post-receive.notify` installs as
+`<hooks_dir>/post-receive`). The hooks directory is whichever path pygit2 reports for
+the repo (`<repo>/.git/hooks` for non-bare, `<repo>/hooks` for bare).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import stat
+from enum import StrEnum
+from pathlib import Path
+from typing import TypedDict
+
+import pygit2
+
+import pygittools
+from pygitweb.config import settings
+
+SAMPLES_DIR: Path = Path(pygittools.__file__).parent / "hook_samples"
+
+_VERSION_RE: re.Pattern[str] = re.compile(r"""^__VERSION__\s*=\s*(['"])(.*?)\1""", re.MULTILINE)
+
+_SAMPLE_LABELS: dict[str, str] = {
+	"post-commit.notify": "Post-commit Notify",
+	"post-receive.notify": "Post-receive Notify",
+	"pre-commit.ruff": "Ruff Pre-commit",
+	"commit-msg.pattern": "Commit Message Pattern",
+	"pre-receive.protected-pattern": "Protected Branch Commit Messages",
+	"post-commit.push-remotes": "Post-commit Push Remotes",
+}
+
+
+HOOK_BUNDLES: dict[str, list[str]] = {
+	# "Update Hook" wires both server (post-receive on push) and client (post-commit on local
+	# commit) sides into the long-poll change queue, so subscribers wake regardless of where
+	# the commit was made.
+	"update": ["post-commit.notify", "post-receive.notify"],
+}
+
+_BUNDLE_LABELS: dict[str, str] = {
+	"update": "Update Hook",
+}
+
+
+class HookStatus(StrEnum):
+	INSTALLED = "installed"
+	NOT_INSTALLED = "not_installed"
+	DIFFERENT = "different"
+
+
+class HookSample(TypedDict):
+	name: str
+	target: str
+	source: str
+	label: str
+
+
+class HookBundle(TypedDict):
+	name: str
+	label: str
+	members: list[HookSample]
+
+
+class InstalledHookInfo(TypedDict):
+	name: str
+	label: str
+	target: str
+	status: str
+	version: str | None
+
+
+def read_hook_version(path: Path) -> str | None:
+	"""Return the __VERSION__ string from a hook file, if present."""
+	try:
+		text: str = path.read_text(encoding="utf-8")
+	except OSError:
+		return None
+	match: re.Match[str] | None = _VERSION_RE.search(text)
+	if match is None:
+		return None
+	return match.group(2)
+
+
+def get_installed_version(project: str, sample_name: str) -> str | None:
+	sample: HookSample | None = get_sample(sample_name)
+	if sample is None:
+		raise KeyError(f"Unknown hook sample: {sample_name}")
+	target: Path = _target_path(project, sample)
+	if target.is_file():
+		version: str | None = read_hook_version(target)
+		if version is not None:
+			return version
+	return read_hook_version(Path(sample["source"]))
+
+
+def list_installed_hooks(project: str) -> list[InstalledHookInfo]:
+	"""Return pygittools hook samples that are installed or conflict with a custom hook."""
+	installed: list[InstalledHookInfo] = []
+	for sample in list_samples():
+		st: HookStatus = status(project, sample["name"])
+		if st == HookStatus.NOT_INSTALLED:
+			continue
+		version: str | None = None
+		if st == HookStatus.INSTALLED:
+			version = get_installed_version(project, sample["name"])
+		else:
+			version = read_hook_version(_target_path(project, sample))
+		installed.append({
+			"name": sample["name"],
+			"label": sample["label"],
+			"target": sample["target"],
+			"status": st.value,
+			"version": version,
+		})
+	return installed
+
+
+def list_installable_hooks(project: str) -> list[HookSample]:
+	"""Return pygittools hook samples that can still be installed in this project."""
+	installable: list[HookSample] = []
+	for sample in list_samples():
+		if status(project, sample["name"]) == HookStatus.NOT_INSTALLED:
+			installable.append(sample)
+	return installable
+
+
+def list_samples() -> list[HookSample]:
+	if not SAMPLES_DIR.is_dir():
+		return []
+	samples: list[HookSample] = []
+	for entry in sorted(SAMPLES_DIR.iterdir()):
+		if not entry.is_file() or "." not in entry.name or entry.name.lower().endswith(".md"):
+			continue
+		target: str = entry.name.split(".", 1)[0]
+		samples.append({
+			"name": entry.name,
+			"target": target,
+			"source": str(entry),
+			"label": _SAMPLE_LABELS.get(entry.name, entry.name),
+		})
+	return samples
+
+
+def get_sample(name: str) -> HookSample | None:
+	for sample in list_samples():
+		if sample["name"] == name:
+			return sample
+	return None
+
+
+def _hooks_dir(project: str) -> Path:
+	repo: pygit2.Repository = pygit2.Repository(os.path.join(settings.PROJECTROOT, project))
+	return Path(repo.path) / "hooks"
+
+
+def _target_path(project: str, sample: HookSample) -> Path:
+	return _hooks_dir(project) / sample["target"]
+
+
+def status(project: str, sample_name: str) -> HookStatus:
+	sample: HookSample | None = get_sample(sample_name)
+	if sample is None:
+		raise KeyError(f"Unknown hook sample: {sample_name}")
+	target: Path = _target_path(project, sample)
+	if not target.is_file():
+		return HookStatus.NOT_INSTALLED
+	try:
+		installed_bytes: bytes = target.read_bytes()
+		source_bytes: bytes = Path(sample["source"]).read_bytes()
+	except OSError:
+		return HookStatus.NOT_INSTALLED
+	return HookStatus.INSTALLED if installed_bytes == source_bytes else HookStatus.DIFFERENT
+
+
+def is_installed(project: str, sample_name: str) -> bool:
+	return status(project, sample_name) == HookStatus.INSTALLED
+
+
+def install(project: str, sample_name: str) -> HookStatus:
+	"""Copy the sample to the hooks dir. Refuses to overwrite a file with different content."""
+	sample: HookSample | None = get_sample(sample_name)
+	if sample is None:
+		raise KeyError(f"Unknown hook sample: {sample_name}")
+	current: HookStatus = status(project, sample_name)
+	if current == HookStatus.DIFFERENT:
+		return current
+	target: Path = _target_path(project, sample)
+	target.parent.mkdir(parents=True, exist_ok=True)
+	shutil.copyfile(sample["source"], target)
+	try:
+		mode: int = target.stat().st_mode
+		target.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+	except OSError:
+		pass
+	return status(project, sample_name)
+
+
+def remove(project: str, sample_name: str) -> HookStatus:
+	"""Delete the hook file only if its content still matches the sample (preserves custom hooks)."""
+	sample: HookSample | None = get_sample(sample_name)
+	if sample is None:
+		raise KeyError(f"Unknown hook sample: {sample_name}")
+	current: HookStatus = status(project, sample_name)
+	if current == HookStatus.INSTALLED:
+		_target_path(project, sample).unlink(missing_ok=True)
+	return status(project, sample_name)
+
+
+def list_bundles() -> list[HookBundle]:
+	bundles: list[HookBundle] = []
+	for name, member_names in HOOK_BUNDLES.items():
+		members: list[HookSample] = []
+		for member_name in member_names:
+			sample: HookSample | None = get_sample(member_name)
+			if sample is not None:
+				members.append(sample)
+		bundles.append({
+			"name": name,
+			"label": _BUNDLE_LABELS.get(name, name),
+			"members": members,
+		})
+	return bundles
+
+
+def get_bundle(name: str) -> HookBundle | None:
+	for bundle in list_bundles():
+		if bundle["name"] == name:
+			return bundle
+	return None
+
+
+def bundle_status(project: str, bundle_name: str) -> HookStatus:
+	"""Aggregate status for a bundle: DIFFERENT if any member conflicts, INSTALLED if all are,
+	otherwise NOT_INSTALLED (treats partial installs as not-installed so re-clicking install
+	completes the bundle)."""
+	bundle: HookBundle | None = get_bundle(bundle_name)
+	if bundle is None:
+		raise KeyError(f"Unknown hook bundle: {bundle_name}")
+	if not bundle["members"]:
+		return HookStatus.NOT_INSTALLED
+	statuses: list[HookStatus] = [status(project, member["name"]) for member in bundle["members"]]
+	if any(s == HookStatus.DIFFERENT for s in statuses):
+		return HookStatus.DIFFERENT
+	if all(s == HookStatus.INSTALLED for s in statuses):
+		return HookStatus.INSTALLED
+	return HookStatus.NOT_INSTALLED
+
+
+def install_bundle(project: str, bundle_name: str) -> HookStatus:
+	"""Install every member of the bundle. Refuses (no-op) if any target holds a different file."""
+	bundle: HookBundle | None = get_bundle(bundle_name)
+	if bundle is None:
+		raise KeyError(f"Unknown hook bundle: {bundle_name}")
+	for member in bundle["members"]:
+		if status(project, member["name"]) == HookStatus.DIFFERENT:
+			return HookStatus.DIFFERENT
+	for member in bundle["members"]:
+		install(project, member["name"])
+	return bundle_status(project, bundle_name)
+
+
+def remove_bundle(project: str, bundle_name: str) -> HookStatus:
+	"""Remove every member of the bundle. Refuses (no-op) if any target holds a different file."""
+	bundle: HookBundle | None = get_bundle(bundle_name)
+	if bundle is None:
+		raise KeyError(f"Unknown hook bundle: {bundle_name}")
+	for member in bundle["members"]:
+		if status(project, member["name"]) == HookStatus.DIFFERENT:
+			return HookStatus.DIFFERENT
+	for member in bundle["members"]:
+		remove(project, member["name"])
+	return bundle_status(project, bundle_name)