Implement prepend and append as additional import modes.

docs/source/changes.md

@@ -26,6 +26,7 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
 - {pull}`579` fixes an interaction with `--pdb` and `--trace` and task that return. The
   debugging modes swallowed the return and `None` was returned. Closes {issue}`574`.
 - {pull}`581` simplifies the code for tracebacks and unpublishes some utility functions.
+- {pull}`585` implements two more import modes, `prepend` and `append`.
 
 ## 0.4.6 - 2024-03-13
 

src/_pytask/build.py

@@ -27,6 +27,7 @@
 from _pytask.exceptions import ResolvingDependenciesError
 from _pytask.outcomes import ExitCode
 from _pytask.path import HashPathCache
+from _pytask.path import ImportMode
 from _pytask.pluginmanager import get_plugin_manager
 from _pytask.pluginmanager import hookimpl
 from _pytask.pluginmanager import storage
@@ -79,6 +80,8 @@ def build(  # noqa: C901, PLR0912, PLR0913
     expression: str = "",
     force: bool = False,
     ignore: Iterable[str] = (),
+    import_mode: Literal["prepend", "append", "importlib"]
+    | ImportMode = ImportMode.importlib,
     marker_expression: str = "",
     max_failures: float = float("inf"),
     n_entries_in_table: int = 15,
@@ -132,6 +135,8 @@ def build(  # noqa: C901, PLR0912, PLR0913
     ignore
         A pattern to ignore files or directories. Refer to ``pathlib.Path.match`` for
         more info.
+    import_mode
+        The import mode used to import task modules.
     marker_expression
         Same as ``-m`` on the command line. Select tasks via marker expressions.
     max_failures
@@ -192,6 +197,7 @@ def build(  # noqa: C901, PLR0912, PLR0913
             "expression": expression,
             "force": force,
             "ignore": ignore,
+            "import_mode": import_mode,
             "marker_expression": marker_expression,
             "max_failures": max_failures,
             "n_entries_in_table": n_entries_in_table,

src/_pytask/collect.py

@@ -206,7 +206,9 @@ def pytask_collect_file(
 ) -> list[CollectionReport] | None:
     """Collect a file."""
     if any(path.match(pattern) for pattern in session.config["task_files"]):
-        mod = import_path(path, session.config["root"])
+        mod = import_path(
+            path, root=session.config["root"], mode=session.config["import_mode"]
+        )
 
         collected_reports = []
         for name, obj in inspect.getmembers(mod):

src/_pytask/config.py

@@ -7,6 +7,7 @@
 from typing import TYPE_CHECKING
 from typing import Any
 
+from _pytask.path import ImportMode
 from _pytask.pluginmanager import hookimpl
 from _pytask.shared import parse_markers
 from _pytask.shared import parse_paths
@@ -110,6 +111,8 @@ def pytask_parse_config(config: dict[str, Any]) -> None:
         config["pm"].trace.root.setwriter(print)
         config["pm"].enable_tracing()
 
+    config["import_mode"] = ImportMode(config["import_mode"])
+
 
 @hookimpl
 def pytask_post_parse(config: dict[str, Any]) -> None:

src/_pytask/parameters.py

@@ -13,7 +13,9 @@
 from sqlalchemy.engine import make_url
 from sqlalchemy.exc import ArgumentError
 
+from _pytask.click import EnumChoice
 from _pytask.config_utils import set_defaults_from_config
+from _pytask.path import ImportMode
 from _pytask.path import import_path
 from _pytask.pluginmanager import hookimpl
 from _pytask.pluginmanager import register_hook_impls_from_modules
@@ -138,7 +140,7 @@ def _hook_module_callback(
                     "Please provide a valid path."
                 )
                 raise click.BadParameter(msg)
-            module = import_path(path, ctx.params["root"])
+            module = import_path(path, root=ctx.params["root"])
             parsed_modules.append(module.__name__)
         else:
             spec = importlib.util.find_spec(module_name)
@@ -177,12 +179,19 @@ def pytask_add_hooks(pm: PluginManager) -> None:
     callback=_hook_module_callback,
 )
 
+_IMPORT_MODE_OPTION = click.Option(
+    ["--import-mode"],
+    type=EnumChoice(ImportMode),
+    default=ImportMode.importlib,
+    help="Choose the import mode.",
+)
+
 
 @hookimpl(trylast=True)
 def pytask_extend_command_line_interface(cli: click.Group) -> None:
     """Register general markers."""
     for command in ("build", "clean", "collect", "dag", "profile"):
-        cli.commands[command].params.extend((_DATABASE_URL_OPTION,))
+        cli.commands[command].params.extend((_DATABASE_URL_OPTION, _IMPORT_MODE_OPTION))
     for command in ("build", "clean", "collect", "dag", "markers", "profile"):
         cli.commands[command].params.extend(
             (_CONFIG_OPTION, _HOOK_MODULE_OPTION, _PATH_ARGUMENT)