mkdocstrings-github 0.6.0__tar.gz → 0.6.1__tar.gz

{mkdocstrings_github-0.6.0 → mkdocstrings_github-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-github
-Version: 0.6.0
+Version: 0.6.1
 Summary: A GitHub Action handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT

{mkdocstrings_github-0.6.0 → mkdocstrings_github-0.6.1}/docs/changelog.md

@@ -2,6 +2,38 @@
 
 <!-- version list -->
 
+## v0.6.1 (2025-11-10)
+
+### Build System
+
+- **deps**: Update dependency inline-snapshot to ~=0.31.0
+  ([#38](https://github.com/watermarkhu/mkdocstrings-github/pull/38),
+  [`df160a0`](https://github.com/watermarkhu/mkdocstrings-github/commit/df160a0f10f19d0ac589d2a4e13d9260d4b93fe0))
+
+- **deps**: Update dependency pytest to v9
+  ([#40](https://github.com/watermarkhu/mkdocstrings-github/pull/40),
+  [`f338dbc`](https://github.com/watermarkhu/mkdocstrings-github/commit/f338dbcbf70dd89a1559ead510896816a0ed1ce0))
+
+- **deps**: Update dependency python-semantic-release to ~=10.5.0
+  ([#41](https://github.com/watermarkhu/mkdocstrings-github/pull/41),
+  [`e1a78c7`](https://github.com/watermarkhu/mkdocstrings-github/commit/e1a78c753faa67b937737fc22e4826ba609bcc70))
+
+### Chores
+
+- **deps**: Update dependency mkdocstrings-python to ~=1.19.0
+  ([#42](https://github.com/watermarkhu/mkdocstrings-github/pull/42),
+  [`7f92d5d`](https://github.com/watermarkhu/mkdocstrings-github/commit/7f92d5d0613007a7f1cc0cde76ba2159d8f30efd))
+
+### Testing
+
+- Fix test_get_repository_name_no_remotes for CI environment
+  ([#39](https://github.com/watermarkhu/mkdocstrings-github/pull/39),
+  [`a04e7c7`](https://github.com/watermarkhu/mkdocstrings-github/commit/a04e7c78b7b2caf91b48f8d257b84c3e3e549bf3))
+
+- Improve test coverage to 99% ([#39](https://github.com/watermarkhu/mkdocstrings-github/pull/39),
+  [`a04e7c7`](https://github.com/watermarkhu/mkdocstrings-github/commit/a04e7c78b7b2caf91b48f8d257b84c3e3e549bf3))
+
+
 ## v0.6.0 (2025-10-27)
 
 ### Build System

{mkdocstrings_github-0.6.0 → mkdocstrings_github-0.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocstrings-github"
-version = "0.6.0"
+version = "0.6.1"
 description = "A GitHub Action handler for mkdocstrings"
 authors = [
     { name = "Mark Hu", email = "watermarkhu@gmail.com" }
@@ -39,18 +39,18 @@ dev = [
     "ruff~=0.14.0",
     "prek>=0.2.1",
     "pydantic~=2.12",
-    "pytest~=8.4.1",
+    "pytest~=9.0.0",
     "pytest-cov~=7.0.0",
     "beautifulsoup4>=4.13.3",
-    "inline-snapshot~=0.30.0",
-    "python-semantic-release~=10.4.1",
+    "inline-snapshot~=0.31.0",
+    "python-semantic-release~=10.5.0",
 ]
 docs = [
     "mkdocs-material~=9.5",
     "mkdocs-callouts~=1.15",
     "mkdocs-git-revision-date-localized-plugin~=1.3",
     "mkdocs-minify-plugin~=0.8",
-    "mkdocstrings-python~=1.18.2",
+    "mkdocstrings-python~=1.19.0",
     "mike~=2.1",
     "griffe-pydantic~=1.1.7",
 ]

mkdocstrings_github-0.6.1/test/test_coverage.py

@@ -0,0 +1,356 @@
+"""Tests to improve code coverage for uncovered lines."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest.mock import Mock
+
+import pytest
+from mkdocs.exceptions import PluginError
+
+from mkdocstrings_handlers.github.objects import (
+    Input,
+    PermissionLevel,
+    Workflow,
+    _get_member,
+)
+from mkdocstrings_handlers.github.rendering import (
+    anchor_id,
+    as_string,
+    filter_parameters,
+    format_action_signature,
+)
+
+if TYPE_CHECKING:
+    from mkdocstrings_handlers.github import GitHubHandler
+
+
+class TestRendering:
+    """Test rendering module functions."""
+
+    def test_as_string_with_bool_false(self):
+        """Test as_string with boolean False value."""
+        assert as_string(False) == "false"
+
+    def test_as_string_with_bool_true(self):
+        """Test as_string with boolean True value."""
+        assert as_string(True) == "true"
+
+    def test_as_string_with_int(self):
+        """Test as_string with integer value."""
+        assert as_string(42) == "42"
+
+    def test_as_string_with_float(self):
+        """Test as_string with float value."""
+        assert as_string(3.14) == "3.14"
+
+    def test_as_string_with_none(self):
+        """Test as_string with None value."""
+        assert as_string(None) == ""
+
+    def test_as_string_with_string(self):
+        """Test as_string with string value."""
+        assert as_string("test") == "test"
+
+    def test_as_string_with_unsupported_type(self):
+        """Test as_string raises TypeError for unsupported types."""
+        with pytest.raises(TypeError, match="Unsupported type"):
+            as_string([1, 2, 3])  # type: ignore
+
+    def test_filter_parameters_optional(self):
+        """Test filter_parameters with optional filter."""
+        params = [
+            Input(name="required", required=True),
+            Input(name="optional", required=False),
+        ]
+        filtered = filter_parameters(params, optional=True)
+        assert len(filtered) == 1
+        assert filtered[0].name == "optional"
+
+    def test_filter_parameters_description(self):
+        """Test filter_parameters with description filter."""
+        params = [
+            Input(name="with_desc", description="Has description"),
+            Input(name="without_desc", description=""),
+        ]
+        # When description=True, it filters OUT parameters without description
+        # So we keep only parameters WITH description
+        filtered = filter_parameters(params, description=True)
+        assert len(filtered) == 1
+        assert filtered[0].name == "with_desc"
+
+    def test_filter_parameters_default(self):
+        """Test filter_parameters with default filter."""
+        params = [
+            Input(name="with_default", default="value"),
+            Input(name="without_default", default=None),
+        ]
+        # When default=True, it filters OUT parameters without default
+        # So we keep only parameters WITH default
+        filtered = filter_parameters(params, default=True)
+        assert len(filtered) == 1
+        assert filtered[0].name == "with_default"
+
+    def test_anchor_id(self):
+        """Test anchor_id with spaces."""
+        result = anchor_id("my name", "input", "parent id")
+        assert result == "parent-id--input.my-name"
+
+    def test_format_action_signature_non_repo(self):
+        """Test format_action_signature when git_repo is not a Repo instance."""
+        from mkdocstrings_handlers.github.config import GitHubOptions
+
+        # Test with ref version when git_repo is not a Repo
+        context = Mock()
+        context.environment.globals = {"git_repo": "not_a_repo"}
+
+        options = GitHubOptions(signature_version="ref")
+        result = format_action_signature(context, ".", "owner/repo", options)
+        assert result == "owner/repo@unknown"
+
+    def test_format_action_signature_exception_handling(self):
+        """Test format_action_signature when accessing head.ref.name raises exception."""
+        import git
+
+        from mkdocstrings_handlers.github.config import GitHubOptions
+
+        # Create a mock that is a Repo instance but raises exception when accessing head.ref.name
+        context = Mock()
+
+        # Create an actual Repo type mock with side effect
+        mock_repo = Mock(spec=git.Repo)
+        type(mock_repo.head.ref).name = Mock(side_effect=Exception("Test exception"))
+
+        context.environment.globals = {"git_repo": mock_repo}
+
+        options = GitHubOptions(signature_version="ref")
+        result = format_action_signature(context, ".", "owner/repo", options)
+        assert result == "owner/repo@unknown"
+
+
+class TestObjects:
+    """Test objects module functions and classes."""
+
+    def test_get_member_raises_key_error(self):
+        """Test _get_member raises KeyError when key is missing and no default."""
+        with pytest.raises(KeyError, match="Missing key"):
+            _get_member({}, "missing_key", error_message="Missing key")
+
+    def test_permission_level_from_label_invalid(self):
+        """Test PermissionLevel.from_label raises ValueError for invalid label."""
+        with pytest.raises(ValueError, match="No Permission with label"):
+            PermissionLevel.from_label("invalid")
+
+    def test_permission_level_gt_not_implemented(self):
+        """Test PermissionLevel.__gt__ returns NotImplemented for non-PermissionLevel."""
+        result = PermissionLevel.read.__gt__("string")
+        assert result == NotImplemented
+
+    def test_workflow_from_file_no_workflow_call(self, tmp_path):
+        """Test Workflow.from_file returns None when workflow_call is not present."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  push:
+    branches: [main]
+"""
+        )
+
+        result = Workflow.from_file(workflow_file, "test.yml")
+        assert result is None
+
+    def test_workflow_invalid_permission_level_string(self, tmp_path):
+        """Test Workflow.from_file raises ValueError for invalid permission string."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+permissions: invalid-level
+"""
+        )
+
+        with pytest.raises(ValueError, match="Unknown permission level"):
+            Workflow.from_file(workflow_file, "test.yml")
+
+    def test_workflow_invalid_permission_type(self, tmp_path):
+        """Test Workflow.from_file raises ValueError for invalid permission type."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+permissions: 123
+"""
+        )
+
+        with pytest.raises(ValueError, match="permissions must be a string or a dictionary"):
+            Workflow.from_file(workflow_file, "test.yml")
+
+    def test_workflow_invalid_job_permission_type(self, tmp_path):
+        """Test Workflow.from_file raises ValueError for invalid job permission type."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions: 123
+"""
+        )
+
+        with pytest.raises(ValueError, match="permissions must be a string or a dictionary"):
+            Workflow.from_file(workflow_file, "test.yml")
+
+
+class TestHandler:
+    """Test handler module functions."""
+
+    def test_get_releases_exception_handling(self):
+        """Test get_releases handles exception when getting git tags fails."""
+        from mkdocstrings_handlers.github.config import GitHubConfig
+        from mkdocstrings_handlers.github.handler import GitHubHandler
+
+        # Create a mock repo that raises exception when accessing tags
+        mock_repo = Mock()
+        mock_repo.tags = Mock(side_effect=Exception("Git error"))
+
+        handler = GitHubHandler(config=GitHubConfig(), repo=mock_repo)
+
+        # Should handle exception gracefully without raising
+        handler.get_releases()
+        assert handler.semver == ""
+        assert handler.major == ""
+
+    def test_get_releases_with_invalid_version_tag(self, tmp_path):
+        """Test get_releases handles tags with invalid version format."""
+        import git
+
+        from mkdocstrings_handlers.github.config import GitHubConfig
+        from mkdocstrings_handlers.github.handler import GitHubHandler
+
+        # Create a temporary git repo with a commit
+        repo = git.Repo.init(tmp_path)
+
+        # Create a file and commit it so we have a valid HEAD
+        test_file = tmp_path / "test.txt"
+        test_file.write_text("test")
+        repo.index.add([str(test_file)])
+        repo.index.commit("Initial commit")
+
+        # Create tags with invalid version format (including semver-like tags with invalid versions)
+        repo.create_tag("invalid-tag")
+        repo.create_tag("another-invalid")
+        repo.create_tag("v1.2.3")  # Valid semver
+        repo.create_tag("v99.99.99")  # Valid semver
+
+        handler = GitHubHandler(config=GitHubConfig(), repo=repo)
+        handler.get_releases()
+
+        # Should use the latest valid semver tag
+        assert handler.semver == "v99.99.99"
+        assert handler.major == ""
+
+    def test_get_releases_with_tags_triggering_invalid_version(self):
+        """Test get_releases handles tags that trigger InvalidVersion exception."""
+        from mkdocstrings_handlers.github.config import GitHubConfig
+        from mkdocstrings_handlers.github.handler import GitHubHandler
+
+        # Create a mock repo with tags that will trigger InvalidVersion
+        mock_tag1 = Mock()
+        mock_tag1.name = "vinvalid"  # Matches major pattern but invalid version
+
+        mock_tag2 = Mock()
+        mock_tag2.name = "v1"  # Valid major tag
+
+        mock_repo = Mock()
+        mock_repo.tags = [mock_tag1, mock_tag2]
+
+        handler = GitHubHandler(config=GitHubConfig(), repo=mock_repo)
+        handler.get_releases()
+
+        # Should gracefully handle the invalid version and use the valid one
+        assert handler.major == "v1"
+
+    def test_get_options_invalid(self, handler: GitHubHandler):
+        """Test get_options raises PluginError for invalid options."""
+        with pytest.raises(PluginError, match="Invalid options"):
+            handler.get_options({"invalid_option": "value", "heading_level": "not_an_int"})
+
+    def test_get_repository_name_no_remotes(self, tmp_path):
+        """Test get_repository_name raises error when no valid remote is found."""
+        import os
+
+        import git
+
+        from mkdocstrings_handlers.github.config import GitHubConfig
+        from mkdocstrings_handlers.github.handler import GitHubHandler
+
+        # Create a temporary git repo without any remotes
+        repo = git.Repo.init(tmp_path)
+
+        handler = GitHubHandler(config=GitHubConfig(), repo=repo)
+
+        # Temporarily clear GITHUB_ACTIONS and GITHUB_REPOSITORY env vars
+        # to ensure the test actually checks the remote URL logic
+        github_actions = os.environ.pop("GITHUB_ACTIONS", None)
+        github_repo = os.environ.pop("GITHUB_REPOSITORY", None)
+
+        try:
+            with pytest.raises(
+                PluginError,
+                match="Could not determine GitHub repository owner/name from any git remote URL",
+            ):
+                handler.get_repository_name()
+        finally:
+            # Restore environment variables
+            if github_actions is not None:
+                os.environ["GITHUB_ACTIONS"] = github_actions
+            if github_repo is not None:
+                os.environ["GITHUB_REPOSITORY"] = github_repo
+
+
+class TestWorkflowPermissions:
+    """Test workflow permission handling."""
+
+    def test_workflow_job_permission_string(self, tmp_path):
+        """Test Workflow with job-level permission strings."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions: read-all
+"""
+        )
+
+        workflow = Workflow.from_file(workflow_file, "test.yml")
+        assert workflow is not None
+        assert workflow.permission_read_all
+
+    def test_workflow_job_permission_write_all(self, tmp_path):
+        """Test Workflow with write-all permission."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+permissions: write-all
+"""
+        )
+
+        workflow = Workflow.from_file(workflow_file, "test.yml")
+        assert workflow is not None
+        assert workflow.permission_write_all

mkdocstrings_github-0.6.1/test/test_signature_ref.py

@@ -0,0 +1,51 @@
+"""Test signature with ref version to improve coverage."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mkdocstrings_handlers.github import GitHubHandler
+
+
+def test_action_signature_with_ref(session_handler: GitHubHandler) -> None:
+    """Test action signature with ref version to cover rendering.py line 29."""
+    from test.helpers import render
+
+    # This will use the actual git repo and access git_repo.head.ref.name
+    html = render(
+        session_handler,
+        ".",
+        {
+            "signature_version": "ref",
+            "show_signature": True,
+            "show_heading": False,
+            "show_description": False,
+            "show_source": False,
+        },
+    )
+
+    # The signature should contain the current branch name (could be HEAD, main, master, etc.)
+    assert "@" in html
+    # Verify we're actually rendering the signature
+    assert "uses:" in html or "@" in html
+
+
+def test_workflow_signature_with_ref(session_handler: GitHubHandler) -> None:
+    """Test workflow signature with ref version."""
+    from test.helpers import render
+
+    html = render(
+        session_handler,
+        ".github/workflows/reusable-workflow.yml",
+        {
+            "signature_version": "ref",
+            "show_signature": True,
+            "show_heading": False,
+            "show_description": False,
+            "show_source": False,
+        },
+    )
+
+    # The signature should contain the current branch name
+    assert "@" in html