conda-features 0.1.0__py3-none-any.whl

conda_features/__init__.py

@@ -0,0 +1,75 @@
+"""Feature management for conda.
+
+Install this distribution in the Python environment running conda. During
+development, ``pixi run python -m conda feature --help`` uses that environment.
+
+User commands::
+
+    conda feature list
+    conda feature explain sample
+    conda feature enable sample --dry-run
+    conda feature enable sample --yes
+    conda feature configure sample plugins.sample_limit=4 --yes
+    conda feature disable sample --yes
+    conda feature disable --all --yes
+
+Use ``--prefix PATH`` for an existing environment, ``--system`` for the conda
+installation, or ``--user`` (the default). Providers declare supported scopes.
+``--file PATH`` selects a standalone user-scope file, with environment-variable
+overrides still applied. Use a conda-recognized name (``.condarc``, ``condarc``,
+or a YAML extension). Its parent directory must exist. Other scopes use
+conda's normal configuration search path. ``--json`` produces one JSON result.
+Exit codes are 0 for success or preview, 1 for an operation error, and 2 for
+argument parsing errors. Noninteractive mutations require ``--yes``.
+
+Providers register their settings with conda's ``conda_settings`` hook and
+yield ``conda_features.models.Feature`` objects from a Pluggy hook. Register
+the provider module in their pyproject.toml::
+
+    [project.entry-points.conda_features]
+    my-provider = "my_provider.features"
+
+An example declaration::
+
+    from conda_features.models import Feature
+    from conda_features.hooks import hookimpl
+
+    @hookimpl
+    def conda_features():
+        yield Feature(
+            name="sample",
+            description="Enable the provider's optional behavior",
+            enabled_setting="plugins.sample_enabled",
+            settings=("plugins.sample_limit",),
+        )
+
+The provider reads its boolean setting to control behavior. This plugin does
+not intercept provider execution. Declarations must be cheap to import and
+must not access the network, credentials, or files. Installed providers are
+trusted Python code, not sandboxed data. Only expose non-secret settings.
+Required settings check for missing values, not login or service availability.
+Status reports the selected file's saved choice separately from the effective
+boolean setting and readiness. Runtime activity is unknown, even when a setting
+is enabled and a prerequisite is blocked. Providers enforce their own checks.
+
+Enable refuses unmet dependencies instead of implicitly opting into them.
+Disable preserves other settings and installed packages. Changes take effect
+on the next invocation. Repeating a persisted operation requires no write.
+An explicit disable is saved even if a temporary override already disables it.
+Writes preserve comments and unrelated settings, use atomic file replacement,
+and reject previews whose destination changed. A sidecar lock coordinates this
+plugin's writers, but external editors do not honor it.
+
+Deployment providers can omit enabled_setting and declare steps such as
+InstallPackages, SetSetting, and EnsureChannel. Feature coordinates their
+planning, application, reverse-order disable, and recovery receipts.
+Provider-specific steps implement Step or ManagedBlock. Plans carry public
+changes and private apply data. The CLI confirms before applying. The separate
+conda-features-examples package deploys real PyPI support and shell completion,
+including installation of missing prerequisites. Bulk disable handles boolean
+features and identifies deployments that need individual disable commands.
+
+Without an installed provider, list reports an empty catalog. Authentication,
+cross-environment dependency scanning, telemetry, migrations, export, and
+doctor integration are not implemented.
+"""

conda_features/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line parsing, dispatch, and rendering."""

conda_features/cli/apply.py

@@ -0,0 +1,26 @@
+"""Apply a portable intent document to an explicitly selected destination."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def configure_parser(parser):
+    parser.add_argument("manifest", type=Path)
+
+
+def execute(args, catalog, ctx, path, scope):
+    from ..operations.intent import IntentError, plan_intent
+    from .common import confirm_and_apply
+
+    if not (args.user or args.system or args.prefix or args.file):
+        raise IntentError(
+            "Applying intent requires an explicit --user, --system, --prefix, or --file destination."
+        )
+    try:
+        document = json.loads(args.manifest.read_text())
+    except (OSError, ValueError) as exc:
+        raise IntentError("Cannot read feature intent JSON.") from exc
+    plan = plan_intent(document, catalog, ctx, path, scope)
+    return confirm_and_apply(args, catalog, ctx, plan)

conda_features/cli/cleanup.py

@@ -0,0 +1,16 @@
+"""Remove obsolete opt-ins for unconditional graduated features."""
+
+from __future__ import annotations
+
+
+def configure_parser(parser):
+    parser.add_argument("feature")
+
+
+def execute(args, catalog, ctx, path, scope):
+    from .common import confirm_and_apply, select_feature
+
+    feature = select_feature(catalog, args.feature)
+    return confirm_and_apply(
+        args, catalog, ctx, feature.cleanup(catalog, ctx, path, scope)
+    )

conda_features/cli/commands.py

@@ -0,0 +1,35 @@
+"""Load the selected subcommand and render its result."""
+
+import json
+import sys
+from argparse import Namespace
+from importlib import import_module
+
+from conda import CondaError
+from conda.base.context import context
+
+from ..operations.discovery import discover
+from ..operations.intent import IntentError
+from ..operations.validation import validate_catalog
+from .output import render
+from .targets import target
+
+
+def execute(args: Namespace) -> int:
+    try:
+        catalog = discover()
+        path, scope, ctx = target(args)
+        validate_catalog(catalog, ctx)
+        command = import_module(f".{args.operation}", package=__package__)
+        result = command.execute(args, catalog, ctx, path, scope)
+    except (CondaError, OSError, ValueError, TypeError, OverflowError) as exc:
+        message = str(exc)
+        if args.operation in ("export", "apply") and not isinstance(exc, IntentError):
+            message = "Intent operation failed. Inspect the local configuration and providers. Review with --dry-run and pass --yes only after approving the changes. Configuration values are omitted from this error."
+        if context.json:
+            print(json.dumps({"error": message}))
+        else:
+            print(message, file=sys.stderr)
+        return 1
+    render(result)
+    return 0

conda_features/cli/common.py

@@ -0,0 +1,90 @@
+"""Shared feature selection and confirmed configuration writes."""
+
+import sys
+from pathlib import Path
+
+from conda import CondaError
+from conda.base.context import context
+from conda.common.configuration import YamlRawParameter
+
+from ..models import Catalog, Feature
+from ..operations.configuration import apply_change
+from ..operations.dependencies import guard_plan, projected_context, verify_guard
+from ..operations.settings import fingerprint
+from .targets import target
+
+
+def select_feature(catalog: Catalog, name: str) -> Feature:
+    if name not in catalog:
+        raise CondaError(f"Unknown feature: {name}")
+    return catalog[name][1]
+
+
+def confirm_and_apply(args, catalog, ctx, plan):
+    guard_plan(args, catalog, plan)
+    result = {
+        key: plan[key]
+        for key in (
+            "operation",
+            "features",
+            "scope",
+            "path",
+            "changes",
+            "checked_environments",
+            "discovery",
+            "remove",
+        )
+        if key in plan
+    }
+    if args.dry_run:
+        result["message"] = "Preview only. No changes made."
+    elif not plan["changes"]:
+        result["message"] = "No changes needed."
+    else:
+        if not context.always_yes:
+            if context.json or not sys.stdin.isatty():
+                raise CondaError(
+                    "Review with --dry-run, then pass --yes to apply noninteractively."
+                )
+            print(f"Configuration: {plan['path']} ({plan['scope']})", file=sys.stderr)
+            if plan["checked_environments"]:
+                print(
+                    "Checked environments: " + ", ".join(plan["checked_environments"]),
+                    file=sys.stderr,
+                )
+            print(plan["discovery"], file=sys.stderr)
+            for key, new_value in plan["changes"].items():
+                print(f"  {key} = {new_value}", file=sys.stderr)
+            print("Proceed? [y/N] ", end="", file=sys.stderr, flush=True)
+            if sys.stdin.readline().strip().lower() not in ("y", "yes"):
+                raise CondaError("Cancelled. No changes made.")
+        verify_guard(plan)
+        if "plans" in plan:
+            current = ctx
+            expected = plan["fingerprint"]
+            for child in plan["plans"]:
+                if fingerprint(Path(child["path"])) != expected:
+                    raise CondaError(
+                        "Configuration changed after preview. Review the plan again."
+                    )
+                child["fingerprint"] = expected
+                next_context = projected_context(child, current)
+                catalog[child["features"][-1]][1].apply(child, current)
+                expected = fingerprint(Path(child["path"]))
+                current = next_context
+        elif len(plan["features"]) == 1:
+            catalog[plan["features"][0]][1].apply(plan, ctx)
+        else:
+            apply_change(plan, ctx)
+        YamlRawParameter.cache_clear()
+        _, _, updated = target(args)
+        result["status"] = [
+            catalog[name][1].status(
+                catalog, updated, plan["scope"], path=Path(plan["path"])
+            )
+            for name in plan["features"]
+        ]
+        result["message"] = (
+            "Configuration updated. Takes effect in the next conda invocation."
+        )
+    return result

conda_features/cli/configure.py

@@ -0,0 +1,22 @@
+"""Validate and change a feature's declared settings."""
+
+from conda import CondaError
+
+
+def configure_parser(parser):
+    parser.add_argument("feature")
+    parser.add_argument("settings", nargs="+", metavar="KEY=VALUE")
+
+
+def execute(args, catalog, ctx, path, scope):
+    from .common import confirm_and_apply, select_feature
+
+    feature = select_feature(catalog, args.feature)
+    settings = {}
+    for item in args.settings:
+        key, separator, new_value = item.partition("=")
+        if not separator or not key or key in settings:
+            raise CondaError("Provide distinct declared settings as KEY=VALUE.")
+        settings[key] = new_value
+    plan = feature.configure(catalog, ctx, path, scope, settings)
+    return confirm_and_apply(args, catalog, ctx, plan)

conda_features/cli/diagnose.py

@@ -0,0 +1,13 @@
+"""Inspect local feature readiness and retained deployment receipts."""
+
+from __future__ import annotations
+
+
+def configure_parser(parser):
+    pass
+
+
+def execute(args, catalog, ctx, path, scope):
+    from ..operations.diagnostics import diagnose
+
+    return diagnose(catalog, ctx, path, scope)

conda_features/cli/disable.py

@@ -0,0 +1,44 @@
+"""Preview and disable one feature or all features at a scope."""
+
+
+def configure_parser(parser):
+    parser.add_argument("feature", nargs="?")
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Disable all declared features at this scope.",
+    )
+
+
+def execute(args, catalog, ctx, path, scope):
+    from ..operations.configuration import plan_change
+    from .common import confirm_and_apply, select_feature
+
+    if args.all:
+        deployments = [
+            name
+            for name, (_, feature) in catalog.items()
+            if feature.enabled_setting is None and scope in feature.scopes
+        ]
+        boolean_catalog = {
+            name: item
+            for name, item in catalog.items()
+            if item[1].enabled_setting is not None
+        }
+        plan = plan_change(
+            boolean_catalog,
+            ctx,
+            path,
+            scope,
+            "disable",
+            args.feature,
+            all_features=True,
+        )
+    else:
+        plan = select_feature(catalog, args.feature).disable(catalog, ctx, path, scope)
+    result = confirm_and_apply(args, catalog, ctx, plan)
+    if args.all and deployments:
+        result["message"] += (
+            " Disable deployment features individually: " + ", ".join(deployments) + "."
+        )
+    return result

conda_features/cli/enable.py

@@ -0,0 +1,22 @@
+"""Preview and enable an installed feature."""
+
+
+def configure_parser(parser):
+    parser.add_argument("feature")
+    parser.add_argument(
+        "--with-dependencies",
+        action="store_true",
+        help="Preview prerequisite opt-ins at the selected scope.",
+    )
+
+
+def execute(args, catalog, ctx, path, scope):
+    from .common import confirm_and_apply, select_feature
+
+    feature = select_feature(catalog, args.feature)
+    plan = (
+        feature.enable(catalog, ctx, path, scope, with_dependencies=True)
+        if args.with_dependencies
+        else feature.enable(catalog, ctx, path, scope)
+    )
+    return confirm_and_apply(args, catalog, ctx, plan)

conda_features/cli/explain.py

@@ -0,0 +1,11 @@
+"""Explain a feature's configured state and prerequisites."""
+
+
+def configure_parser(parser):
+    parser.add_argument("feature")
+
+
+def execute(args, catalog, ctx, path, scope):
+    from .common import select_feature
+
+    return select_feature(catalog, args.feature).status(catalog, ctx, scope, path=path)

conda_features/cli/export.py

@@ -0,0 +1,26 @@
+"""Export portable choices as one versioned JSON document."""
+
+from __future__ import annotations
+
+
+def configure_parser(parser):
+    parser.add_argument(
+        "features",
+        nargs="*",
+        help="Feature IDs to export. Defaults to all saved choices at this scope.",
+    )
+
+
+def execute(args, catalog, ctx, path, scope):
+    from .common import select_feature
+
+    names = args.features or list(catalog)
+    entries = [
+        select_feature(catalog, name).export_intent(catalog, ctx, path, scope)
+        for name in names
+    ]
+    return {
+        "version": 1,
+        "scope": scope,
+        "features": [entry for entry in entries if entry is not None],
+    }

conda_features/cli/list.py

@@ -0,0 +1,14 @@
+"""List installed feature declarations and their state."""
+
+
+def configure_parser(parser):
+    pass
+
+
+def execute(args, catalog, ctx, path, scope):
+    return {
+        "features": [
+            feature.status(catalog, ctx, scope, path=path)
+            for _, feature in catalog.values()
+        ]
+    }

conda_features/cli/migrate.py

@@ -0,0 +1,16 @@
+"""Preview migration to a provider-declared replacement."""
+
+from __future__ import annotations
+
+
+def configure_parser(parser):
+    parser.add_argument("feature")
+
+
+def execute(args, catalog, ctx, path, scope):
+    from .common import confirm_and_apply, select_feature
+
+    feature = select_feature(catalog, args.feature)
+    return confirm_and_apply(
+        args, catalog, ctx, feature.migrate(catalog, ctx, path, scope)
+    )

conda_features/cli/output.py

@@ -0,0 +1,74 @@
+"""Human-readable and JSON command output."""
+
+import json
+
+from conda.base.context import context
+
+
+def render(result: dict) -> None:
+    if context.json or (
+        result.get("version") == 1 and "features" in result and "scope" in result
+    ):
+        print(json.dumps(result, default=str))
+    elif "problems" in result:
+        for problem in result["problems"]:
+            print(f"{problem['feature']}: {problem['message']} {problem['action']}")
+        if not result["problems"]:
+            print("No local feature readiness problems found.")
+        print(result["message"])
+    elif "changes" in result:
+        print(f"Configuration: {result['path']} ({result['scope']})")
+        if "checked_environments" in result:
+            print(
+                "Checked environments: "
+                + (", ".join(result["checked_environments"]) or "none")
+            )
+            print(result["discovery"])
+        for key, new_value in result["changes"].items():
+            print(f"  {key} = {new_value}")
+        print(result["message"])
+    elif isinstance(result.get("features"), list):
+        if not result["features"]:
+            print("No feature providers installed.")
+        else:
+            print(
+                "Feature  Maturity  Requested  Effective setting  Readiness  Description"
+            )
+            for feature in result["features"]:
+                print(
+                    "  ".join(
+                        str(feature[key])
+                        for key in (
+                            "name",
+                            "maturity",
+                            "requested",
+                            "effective",
+                            "readiness",
+                            "description",
+                        )
+                    )
+                )
+    else:
+        print(f"{result['name']}: {result['description']}")
+        for key in ("provider", "maturity", "requested", "readiness"):
+            print(f"{key.capitalize()}: {result[key]}")
+        print(f"Effective setting: {result['effective']}")
+        print("Runtime: unknown (provider execution is not observed)")
+        if result.get("lifecycle") not in (None, "available"):
+            print(f"Lifecycle: {result['lifecycle']}")
+        if result.get("replacement"):
+            print(
+                f"Replacement: {result['replacement']}. Use feature migrate to preview the change."
+            )
+        if result.get("graduation") == "unconditional":
+            print(
+                "Functionality is now unconditional. Cleanup removes only the obsolete opt-in, not the functionality."
+            )
+        for key, sources in result["sources"].items():
+            print(f"{key}: sources {', '.join(sources) or 'default'}")
+        for reason in result["reasons"]:
+            print(reason)
+        if result["settings"]:
+            print("Configurable settings: " + ", ".join(result["settings"]))
+        if result["guidance"]:
+            print(result["guidance"])

conda_features/cli/parser.py

@@ -0,0 +1,50 @@
+"""Argument definitions for the feature subcommand."""
+
+from argparse import ArgumentParser
+from importlib import import_module
+
+from conda.cli.helpers import add_output_and_prompt_options
+
+
+def configure_parser(parser: ArgumentParser) -> None:
+    parser.description = "Manage features declared by installed providers. Deployment providers may install prerequisites after confirmation."
+    parser.epilog = "Providers register a conda_features hook in the conda_features entry-point group. See help(conda_features) in Python for setup and usage."
+    commands = parser.add_subparsers(dest="operation", required=True)
+    for name in (
+        "list",
+        "explain",
+        "enable",
+        "disable",
+        "configure",
+        "diagnose",
+        "repair",
+        "migrate",
+        "cleanup",
+        "export",
+        "apply",
+    ):
+        command = commands.add_parser(name)
+        add_output_and_prompt_options(command)
+        command.add_argument(
+            "--check-prefix",
+            action="append",
+            default=[],
+            metavar="PATH",
+            help="Also check this environment before mutation. Does not write to it.",
+        )
+        scope = command.add_mutually_exclusive_group()
+        scope.add_argument(
+            "--user", action="store_true", help="Use user configuration (default)."
+        )
+        scope.add_argument(
+            "--system",
+            action="store_true",
+            help="Use this conda installation's configuration.",
+        )
+        scope.add_argument(
+            "-p", "--prefix", help="Target an existing conda environment."
+        )
+        scope.add_argument(
+            "--file", help="Use an explicit user-scope configuration file."
+        )
+        import_module(f".{name}", package=__package__).configure_parser(command)

conda_features/cli/repair.py

@@ -0,0 +1,16 @@
+"""Retry a saved feature choice using its normal deployment plan."""
+
+from __future__ import annotations
+
+
+def configure_parser(parser):
+    parser.add_argument("feature")
+
+
+def execute(args, catalog, ctx, path, scope):
+    from .common import confirm_and_apply, select_feature
+
+    feature = select_feature(catalog, args.feature)
+    return confirm_and_apply(
+        args, catalog, ctx, feature.repair(catalog, ctx, path, scope)
+    )

conda_features/cli/targets.py

@@ -0,0 +1,28 @@
+"""Resolve configuration destinations using conda contexts."""
+
+from argparse import Namespace
+from pathlib import Path
+
+from conda import CondaError
+from conda.base.context import Context, context, user_rc_path
+from conda.common.configuration import CONDARC_FILENAMES, YAML_EXTENSIONS
+
+
+def target(args: Namespace) -> tuple[Path, str, Context]:
+    if args.file:
+        path = Path(args.file).expanduser().absolute()
+        if path.name not in CONDARC_FILENAMES and path.suffix not in YAML_EXTENSIONS:
+            raise CondaError(
+                "Configuration filename must be .condarc, condarc, or have a YAML extension."
+            )
+        return path, "user", Context(search_path=(path,))
+    if args.prefix:
+        prefix = Path(args.prefix).expanduser().absolute()
+        if not (prefix / "conda-meta").is_dir():
+            raise CondaError("The target prefix must be an existing conda environment.")
+        path, scope = prefix / ".condarc", "environment"
+    elif args.system:
+        path, scope = Path(context.root_prefix) / ".condarc", "system"
+    else:
+        path, scope = Path(user_rc_path).expanduser().absolute(), "user"
+    return path, scope, Context(argparse_args=args)

conda_features/hooks.py

@@ -0,0 +1,22 @@
+"""Pluggy interface for installed feature providers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pluggy import HookimplMarker, HookspecMarker
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from .models import Feature
+
+hookimpl = HookimplMarker("conda_features")
+hookspec = HookspecMarker("conda_features")
+
+
+class FeatureSpecs:
+    @hookspec
+    def conda_features(self) -> Iterable[Feature]:
+        """Yield local feature declarations without performing setup or I/O."""
+        raise NotImplementedError