Deprecate gitignore.io token support and add gitignore_extend() (#…

…271)

* enable gitignore() in our own .kraken.py

* deprecation: Deprecate `gitignore(gitignore_io_tokens, gitignore_io_allow_http_request_backfill)`

* remove CI job for gitignore-io tokens

* feature: Add `kraken.std.git.gitignore_extend()` function

* fmt

.changelog/_unreleased.toml

@@ -0,0 +1,11 @@
+[[entries]]
+id = "7db61e19-eb5b-4385-a854-9523fb256d5c"
+type = "deprecation"
+description = "Deprecate `gitignore(gitignore_io_tokens, gitignore_io_allow_http_request_backfill)`"
+author = "@NiklasRosenstein"
+
+[[entries]]
+id = "17854ad9-56e6-41a9-9d69-a4a55a830682"
+type = "feature"
+description = "Add `kraken.std.git.gitignore_extend()` function"
+author = "@NiklasRosenstein"

.github/workflows/on-commit.yaml

@@ -11,19 +11,6 @@ env:
 
 jobs:
 
-  # == Validate data embedded in the Kraken standard library ==
-
-  gitignore-io-up-to-date:
-    runs-on: arc-amd64-small
-    steps:
-    - uses: actions/checkout@v4
-    - uses: NiklasRosenstein/slap@gha/install/v1
-    - uses: actions/setup-python@v5
-      with: { python-version: "3.10" }
-    - run: slap config --venv-type=uv && slap install --link --no-venv-check ${{ matrix.only }}
-    - run: python -m kraken.std.git.gitignore.gitignore_io
-    - run: git diff --exit-code
-
   # == Documentation ==
 
   documentation:

.gitignore

@@ -1,6 +1,10 @@
+# GENERATED-CONTENT-START
+# Kraken
+/build
+# GENERATED-CONTENT-END
+
 /.vscode
 /dist
-build/
 .venv/
 .venvs/
 *.egg-info/

.kraken.py

@@ -4,8 +4,9 @@
 
 import os
 
+from kraken.build import project
 from kraken.std import python
-from kraken.std.git import git_describe
+from kraken.std.git import git_describe, gitignore
 
 
 def configure_project() -> None:
@@ -86,13 +87,8 @@ def configure_project() -> None:
             )
 
 
-from kraken.build import project
-
-try:
-    project.subproject("docs")
-except ImportError:
-    pass
-
+gitignore()
+project.subproject("docs")
 for subproject in [project.subproject("kraken-build"), project.subproject("kraken-wrapper")]:
     with subproject.as_current():
         configure_project()

kraken-build/src/kraken/build/tests/test_import.py

@@ -4,7 +4,7 @@
 
 
 def test_import_current_context_and_project_from_kraken_build() -> None:
-    """ Test that you can import the current Kraken build context and project from `kraken.build`. """
+    """Test that you can import the current Kraken build context and project from `kraken.build`."""
 
     with pytest.raises(RuntimeError):
         from kraken.build import context

kraken-build/src/kraken/build/utils/import_helper.py

@@ -5,8 +5,8 @@
 
 
 class _KrakenBuildModuleWrapper:
-    """ A wrapper for the `kraken.build` module to allow build-scripts to always import the current (i.e. their own)
-    project and the Kraken build context. """
+    """A wrapper for the `kraken.build` module to allow build-scripts to always import the current (i.e. their own)
+    project and the Kraken build context."""
 
     def __init__(self, module: types.ModuleType) -> None:
         self.__module = module
@@ -21,5 +21,5 @@ def __getattr__(self, name: str) -> Any:
 
     @staticmethod
     def install(module_name: str) -> None:
-        """ Install the wrapper around the given module. """
+        """Install the wrapper around the given module."""
         sys.modules[module_name] = _KrakenBuildModuleWrapper(sys.modules[module_name])  # type: ignore[assignment]

kraken-build/src/kraken/std/git/__init__.py

@@ -5,6 +5,7 @@
 from collections.abc import Sequence
 from pathlib import Path
 from typing import Literal
+import warnings
 
 from kraken.core import Project
 from kraken.std.util.check_file_contents_task import CheckFileContentsTask
@@ -20,6 +21,7 @@
     "git_describe",
     "GitVersion",
     "gitignore",
+    "gitignore_extend",
 ]
 
 
@@ -39,6 +41,17 @@ def gitignore(
     Creates a #GitignoreSyncTask and #CheckFileContentsTask for the given project.
     """
 
+    # DEPRECATE: We want to get rid of gitignore.io tokens feature.
+    if gitignore_io_tokens:
+        warnings.warn(
+            "gitignore(gitignore_io_tokens) is deprecated and will be removed in a future version", DeprecationWarning
+        )
+    if gitignore_io_allow_http_request_backfill:
+        warnings.warn(
+            "gitignore(gitignore_io_allow_http_request_backfill) is deprecated and will be removed in a future version",
+            DeprecationWarning,
+        )
+
     project = project or Project.current()
     task = project.task(name, tasks.GitignoreSyncTask, group=group)
     task.file.set(Path(gitignore_file))
@@ -48,3 +61,42 @@ def gitignore(
     task.gitignore_io_allow_http_request_backfill.set(gitignore_io_allow_http_request_backfill)
     task.where.set(where)
     return task, task.create_check(group=check_group)
+
+
+def gitignore_extend(
+    *,
+    project: Project | None = None,
+    patterns: Sequence[str],
+    dedup: bool = True,
+) -> None:
+    """
+    Extend the Gitignore task's generated content section by the given *pattern*s.
+
+    Args:
+        project: The project to look for the Gitignore task configuraton in. If it is not specified, it will be
+                 searched in the currently active project and any of its parents (often the Gitignore tasks only exist
+                 on the root project).
+        patterns: The patterns to add to the config.
+        dedup: If enabled, do not add any patterns that are already present.
+    """
+
+    if project is None:
+        projects = []
+        project = Project.current()
+        while project:
+            projects.append(project)
+            project = project.parent
+
+    else:
+        projects = [project]
+
+    task: tasks.GitignoreSyncTask | None
+    for project in projects:
+        task = next((t for t in project.tasks().values() if isinstance(t, tasks.GitignoreSyncTask)), None)
+        if task is not None:
+            break
+
+    if task is None:
+        raise ValueError("Could not find GitignoreSyncTask")
+
+    task.generated_content.setmap(lambda x: [*x, *(p for p in patterns if p not in x)] if dedup else [*x, *patterns])

kraken-build/src/kraken/std/git/gitignore/gitignore_io.py

@@ -1,4 +1,6 @@
 """
+DEPRECATED: This module will be removed in a future version.
+
 This module provides a thin client for the gitignore.io API to retrieve template `.gitignore` files.
 
 Run this module to update the `gitignore-io-tokens.json.gz` file.