Adds @zen decorator for task functions

docs/source/api_reference.rst

@@ -12,9 +12,9 @@ Encyclopedia Hydrazennica.
 All reference documentation includes detailed Examples sections. Please scroll to the 
 bottom of any given reference page to see the examples.
 
-*************************
-Launching Jobs with Hydra
-*************************
+**************************************
+Creating and Launching Jobs with Hydra
+**************************************
 
 hydra-zen provides users the ability to launch a Hydra job via a 
 Python function instead of from a commandline interface.
@@ -25,7 +25,8 @@ Python function instead of from a commandline interface.
    :toctree: generated/
 
    launch
-
+   zen
+   wrapper.Zen
 
 *********************************
 Creating and Working with Configs

docs/source/changes.rst

@@ -10,6 +10,66 @@ chronological order. All previous releases should still be available on pip.
 
 .. _v0.8.0:
 
+---------------------
+0.9.0rc2 - 2022-10-19
+---------------------
+
+.. note:: This is documentation for an unreleased version of hydra-zen. You can try out this version pre-release version using `pip install --pre hydra-zen`
+
+
+Release Highlights
+------------------
+This release adds the :func:`~hydra_zen.zen` decorator, which enables users to use Hydra-agnostic task functions for their Hydra app; the decorator will automatically extract, resolve, and instantiate fields from an input config based on the function's signature. 
+
+This encourages users to eliminate Hydra-specific boilerplate code from their projects and to instead opt for task functions with explicit signatures, including functions from third parties.
+
+E.g., :func:`~hydra_zen.zen` enables us to replace the following Hydra-specific task function:
+
+.. code-block:: python
+   :caption: The "old school" way of designing a task function for a Hydra app
+
+   import hydra
+   from hydra.utils import instantiate
+
+   @hydra.main(config_name="my_app", config_path=None, version_base="1.2")
+   def trainer_task_fn(cfg):
+      model = instantiate(cfg.model)
+      data = instantiate(cfg.data)
+      partial_optim = instantiate(cfg.partial_optim)
+      trainer = instantiate(cfg.trainer)
+
+      optim = partial_optim(model.parameters())
+      trainer(model, optim, data).fit(cfg.num_epochs)
+
+   if __name__ == "__main__":
+      trainer_task_fn()      
+
+with a Hydra-agnostic task function that has an explicit signature:
+
+.. code-block:: python
+   :caption: Using `zen` to design a Hydra-agnostic task function
+
+   from hydra_zen import zen
+
+   @zen
+   def trainer_task_fn(model, data, partial_optim, trainer, num_epochs: int):
+      # All config-field extraction & instantiation is automated/mediated by zen
+      optim = partial_optim(model.parameters())
+      trainer(model, optim, data).fit(num_epochs)
+
+   if __name__ == "__main__":
+      trainer_task_fn.hydra_main(config_name="my_app", config_path=None)
+
+
+There are plenty more bells and whistles to :func:`~hydra_zen.zen`, refer to :pull:`310` and its reference documentation for more details.
+
+New Features
+------------
+- Adds the :func:`~hydra_zen.zen` decorator (see :pull:`310`)
+- Adds the :func:`~hydra_zen.wrapper.Zen` decorator-class (see :pull:`310`)
+
+.. _v0.8.0:
+
 ------------------
 0.8.0 - 2022-09-13
 ------------------

docs/source/generated/hydra_zen.wrapper.Zen.rst

@@ -0,0 +1,22 @@
+hydra\_zen.wrapper.Zen
+======================
+
+.. currentmodule:: hydra_zen.wrapper
+
+.. autoclass:: Zen
+
+
+   .. automethod:: __init__
+   .. automethod:: __call__
+   .. automethod:: validate
+   .. automethod:: hydra_main
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~Zen.__init__
+      ~Zen.__call__
+      ~Zen.validate
+      ~Zen.hydra_main

docs/source/generated/hydra_zen.zen.rst

@@ -0,0 +1,6 @@
+hydra\_zen.zen
+===============
+
+.. currentmodule:: hydra_zen
+
+.. autofunction:: zen

pyproject.toml

@@ -111,6 +111,7 @@ python =
 
 
 [testenv]
+passenv = *
 deps = pytest
        hypothesis
 commands = pytest \

src/hydra_zen/__init__.py

@@ -21,6 +21,7 @@
 )
 from .structured_configs._implementations import get_target
 from .structured_configs._type_guards import is_partial_builds, uses_zen_processing
+from .wrapper import zen
 
 __all__ = [
     "builds",
@@ -39,6 +40,7 @@
     "launch",
     "is_partial_builds",
     "uses_zen_processing",
+    "zen",
 ]
 
 if not TYPE_CHECKING:

src/hydra_zen/_compatibility.py

@@ -36,6 +36,7 @@ def _get_version(ver_str: str) -> Version:
 OMEGACONF_VERSION: Final = _get_version(omegaconf.__version__)
 HYDRA_VERSION: Final = _get_version(hydra.__version__)
 
+SUPPORTS_VERSION_BASE = HYDRA_VERSION >= (1, 2, 0)
 
 # OmegaConf issue 830 describes a bug associated with structured configs
 # composed via inheritance, where the child's attribute is a default-factory
@@ -70,6 +71,8 @@ def _get_version(ver_str: str) -> Version:
     range,
 }
 
+HYDRA_SUPPORTS_LIST_INSTANTIATION = HYDRA_VERSION >= Version(1, 1, 2)
+
 
 if HYDRA_SUPPORTS_BYTES:  # pragma: no cover
     HYDRA_SUPPORTED_PRIMITIVES.add(bytes)

src/hydra_zen/_hydra_overloads.py

@@ -23,7 +23,7 @@
 import pathlib
 from dataclasses import is_dataclass
 from functools import wraps
-from typing import IO, Any, Callable, Type, TypeVar, Union, cast, overload
+from typing import IO, Any, Callable, Dict, List, Type, TypeVar, Union, cast, overload
 
 from hydra.utils import instantiate as hydra_instantiate
 from omegaconf import MISSING, DictConfig, ListConfig, OmegaConf
@@ -88,7 +88,15 @@ def instantiate(
 
 @overload
 def instantiate(
-    config: Union[HasTarget, ListConfig, DictConfig, DataClass_, Type[DataClass_]],
+    config: Union[
+        HasTarget,
+        ListConfig,
+        DictConfig,
+        DataClass_,
+        Type[DataClass_],
+        Dict[Any, Any],
+        List[Any],
+    ],
     *args: Any,
     **kwargs: Any
 ) -> Any:  # pragma: no cover

src/hydra_zen/_launch.py

@@ -13,7 +13,7 @@
 from hydra.types import HydraContext, RunMode
 from omegaconf import DictConfig, ListConfig, OmegaConf
 
-from hydra_zen._compatibility import HYDRA_VERSION
+from hydra_zen._compatibility import SUPPORTS_VERSION_BASE
 from hydra_zen._hydra_overloads import instantiate
 from hydra_zen.typing._implementations import DataClass, InstOrType
 
@@ -238,7 +238,7 @@ def launch(
         job_name=job_name,
         **(
             {}
-            if (HYDRA_VERSION < (1, 2, 0) or version_base is _NotSet)
+            if (not SUPPORTS_VERSION_BASE or version_base is _NotSet)
             else {"version_base": version_base}
         )
     ):

src/hydra_zen/structured_configs/_type_guards.py

@@ -2,13 +2,14 @@
 # SPDX-License-Identifier: MIT
 # pyright: strict
 from functools import partial
-from typing import Any
+from typing import TYPE_CHECKING, Any, Type, Union
 
 from typing_extensions import TypeGuard
 
 from hydra_zen._compatibility import HYDRA_SUPPORTS_PARTIAL
 from hydra_zen.funcs import get_obj, zen_processing
 from hydra_zen.typing import Builds, Just, PartialBuilds
+from hydra_zen.typing._implementations import DataClass_
 
 from ._globals import (
     JUST_FIELD_NAME,
@@ -19,7 +20,7 @@
     ZEN_TARGET_FIELD_NAME,
 )
 
-__all__ = ["is_partial_builds", "uses_zen_processing"]
+__all__ = ["is_partial_builds", "uses_zen_processing", "is_dataclass"]
 
 # We need to check if things are Builds, Just, PartialBuilds to a higher
 # fidelity than is provided by `isinstance(..., <Protocol>)`. I.e. we want to
@@ -53,6 +54,15 @@ def is_just(x: Any) -> TypeGuard[Just[Any]]:
     return False
 
 
+if TYPE_CHECKING:  # pragma: no cover
+
+    def is_dataclass(obj: Any) -> TypeGuard[Union[DataClass_, Type[DataClass_]]]:
+        ...
+
+else:
+    from dataclasses import is_dataclass
+
+
 def is_old_partial_builds(x: Any) -> bool:  # pragma: no cover
     # We don't care about coverage here.
     # This will only be used in `get_target` and we'll be sure to cover that branch

src/hydra_zen/wrapper/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2022 Massachusetts Institute of Technology
+# SPDX-License-Identifier: MIT
+
+# pyright: strict
+
+from ._implementations import Zen, zen
+
+__all__ = ["zen", "Zen"]