cmem-plugin-git 1.0.0__py3-none-any.whl

cmem_plugin_git/parameters.py

@@ -0,0 +1,180 @@
+"""What the three tasks have in common: parameters, schema and small helpers"""
+
+import base64
+import binascii
+import json
+from typing import Any
+
+from cmem_plugin_base.dataintegration.context import ExecutionContext
+from cmem_plugin_base.dataintegration.description import PluginParameter
+from cmem_plugin_base.dataintegration.entity import EntityPath, EntitySchema
+from cmem_plugin_base.dataintegration.parameter.password import Password, PasswordParameterType
+
+from cmem_plugin_git.autocompletion import FolderParameterType, RefParameterType
+from cmem_plugin_git.remote import (
+    DEFAULT_AUTHOR,
+    DEFAULT_USERNAME,
+    GitRemote,
+    clean_identity_part,
+)
+
+LIST_TYPE_URI = "https://vocab.eccenca.com/plugin/git/File"
+LIST_PATHS = ["path", "name", "size", "mode", "blob_id", "commit_id", "url"]
+
+URL_DESCRIPTION = (
+    "The HTTP(S) address of the repository. The address of its web page "
+    "works as well as its clone URL, with or without a trailing '.git'."
+)
+
+
+def list_schema() -> EntitySchema:
+    """Describe what the list task hands to the next task."""
+    return EntitySchema(
+        type_uri=LIST_TYPE_URI,
+        paths=[EntityPath(path=name) for name in LIST_PATHS],
+    )
+
+
+def secret(value: str | Password) -> str:
+    """Read a parameter that may arrive as a password or as plain text."""
+    return value if isinstance(value, str) else value.decrypt()
+
+
+def connection_parameters(
+    ref_label: str,
+    ref_description: str,
+    access_description: str,
+    url_description: str = URL_DESCRIPTION,
+    url_optional: bool = False,
+) -> list[PluginParameter]:
+    """Build the parameters that say which repository and which revision to use.
+
+    The repository URL is required everywhere except where a caller passes
+    ``url_optional=True``, which also gives it an empty default so it can be
+    left blank.
+    """
+    return [
+        PluginParameter(
+            name="url",
+            label="Repository URL",
+            description=url_description,
+            default_value="" if url_optional else None,
+        ),
+        PluginParameter(
+            name="token",
+            label="Access token",
+            description=access_description,
+            param_type=PasswordParameterType(),
+            default_value="",
+        ),
+        PluginParameter(
+            name="ref",
+            label=ref_label,
+            description=ref_description,
+            param_type=RefParameterType(),
+            default_value="",
+        ),
+        PluginParameter(
+            name="username",
+            label="User name",
+            description="The user name sent with the access token. GitHub ignores it, GitLab "
+            "checks it, and the default is the value GitLab accepts for a repository token.",
+            default_value=DEFAULT_USERNAME,
+            advanced=True,
+        ),
+    ]
+
+
+def selection_parameters(note: str = "") -> list[PluginParameter]:
+    """Build the parameters that say which files of the revision to work with.
+
+    ``note`` is appended to every description, for a caller where these
+    parameters do not always apply - such as Download Git files, where they
+    are ignored whenever the input drives the selection instead.
+    """
+    suffix = f" {note}" if note else ""
+    return [
+        PluginParameter(
+            name="path",
+            label="Folder",
+            description="The folder inside the repository to read from. "
+            "Leave it empty to start at the top of the repository." + suffix,
+            param_type=FolderParameterType(),
+            default_value="",
+        ),
+        PluginParameter(
+            name="regex",
+            label="Regular expression",
+            description="A regular expression the file name has to match. "
+            "An empty expression matches every file." + suffix,
+            default_value="",
+        ),
+        PluginParameter(
+            name="no_subfolder",
+            label="No subfolder",
+            description="If enabled, only files directly in the selected folder are used, "
+            "and its subfolders are left alone." + suffix,
+            default_value=False,
+        ),
+    ]
+
+
+def preview_of(paths: list[str], warnings: list[str], limit: int = 10) -> str:
+    """Render what a preview action found, as Markdown."""
+    if not paths and not warnings:
+        return "No file matches this configuration."
+    lines = [f"Found {len(paths)} file(s)."]
+    if paths:
+        lines += ["", "| File |", "| ---- |"]
+        lines += [f"| `{path}` |" for path in paths[:limit]]
+        if len(paths) > limit:
+            lines.append(f"| ... and {len(paths) - limit} more |")
+    if warnings:
+        lines += ["", "Skipped:", ""]
+        lines += [f"- {warning}" for warning in warnings[:limit]]
+    return "\n".join(lines)
+
+
+def remote_of(url: str, token: str | Password, username: str) -> GitRemote:
+    """Build the remote a task talks to."""
+    return GitRemote(url=url, token=secret(token), username=username)
+
+
+def _claims(token: str) -> dict[str, Any]:
+    """Read the payload of an access token
+
+    The token is the plugin's own credential rather than something it
+    authenticates, so the payload is decoded and its signature is not checked.
+    """
+    parts = token.split(".")
+    expected_parts = 3
+    if len(parts) != expected_parts:
+        return {}
+    payload = parts[1]
+    payload += "=" * (-len(payload) % 4)
+    try:
+        decoded = json.loads(base64.urlsafe_b64decode(payload))
+    except (binascii.Error, ValueError, UnicodeDecodeError):
+        return {}
+    return decoded if isinstance(decoded, dict) else {}
+
+
+def identity_of(context: ExecutionContext, name: str = "", mail: str = "") -> str:
+    """Decide who authors a commit
+
+    Configured values win. Otherwise the executing user's name and mail address
+    are read from their access token, which a deployment may or may not put
+    there, and the package identity is used when they are not available.
+    """
+    chosen_name = clean_identity_part(name)
+    chosen_mail = clean_identity_part(mail)
+    if not (chosen_name and chosen_mail):
+        user = getattr(context, "user", None)
+        claims = _claims(user.token()) if user is not None else {}
+        chosen_name = chosen_name or clean_identity_part(
+            str(claims.get("name") or claims.get("preferred_username") or "")
+        )
+        chosen_mail = chosen_mail or clean_identity_part(str(claims.get("email") or ""))
+    if chosen_name and chosen_mail:
+        return f"{chosen_name} <{chosen_mail}>"
+    return DEFAULT_AUTHOR