Documentation update

- Defaults List
- Packages
- Extending configs
- Configuring experiments

examples/advanced/defaults_list_interpolation/conf/config.yaml

@@ -0,0 +1,4 @@
+defaults:
+  - db: mysql
+  - server: apache
+  - optional server_db: ${server}_${db}

examples/advanced/defaults_list_interpolation/conf/db/mysql.yaml

@@ -0,0 +1 @@
+name: mysql

examples/advanced/defaults_list_interpolation/conf/db/sqlite.yaml

@@ -0,0 +1 @@
+name: sqlite

examples/advanced/defaults_list_interpolation/conf/server/apache.yaml

@@ -0,0 +1,2 @@
+name: apache
+workers: 10

examples/advanced/defaults_list_interpolation/conf/server/nginx.yaml

@@ -0,0 +1 @@
+name: nginx

examples/advanced/defaults_list_interpolation/conf/server_db/apache_sqlite.yaml

@@ -0,0 +1,2 @@
+# @package server
+workers: 5

examples/advanced/defaults_list_interpolation/my_app.py

@@ -0,0 +1,13 @@
+# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved
+from omegaconf import DictConfig, OmegaConf
+
+import hydra
+
+
+@hydra.main(config_path="conf", config_name="config")
+def my_app(cfg: DictConfig) -> None:
+    print(OmegaConf.to_yaml(cfg))
+
+
+if __name__ == "__main__":
+    my_app()

examples/advanced/nested_defaults_list/conf/config.yaml

@@ -0,0 +1,4 @@
+defaults:
+  - server/apache
+
+debug: false

examples/advanced/nested_defaults_list/conf/config2.yaml

@@ -0,0 +1,5 @@
+defaults:
+  - server/apache
+  - override server/db: sqlite
+
+debug: false

examples/advanced/nested_defaults_list/conf/server/apache.yaml

@@ -0,0 +1,4 @@
+defaults:
+  - db: mysql
+
+name: apache

examples/advanced/nested_defaults_list/conf/server/db/mysql.yaml

@@ -0,0 +1 @@
+name: mysql

examples/advanced/nested_defaults_list/conf/server/db/sqlite.yaml

@@ -0,0 +1 @@
+name: sqlite

examples/advanced/nested_defaults_list/my_app.py

@@ -0,0 +1,13 @@
+# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved
+from omegaconf import DictConfig, OmegaConf
+
+import hydra
+
+
+@hydra.main(config_path="conf", config_name="config")
+def my_app(cfg: DictConfig) -> None:
+    print(OmegaConf.to_yaml(cfg))
+
+
+if __name__ == "__main__":
+    my_app()

examples/patterns/configuring_experiments/conf/config.yaml

@@ -0,0 +1,3 @@
+defaults:
+  - db: mysql
+  - server: apache

examples/patterns/configuring_experiments/conf/db/mysql.yaml

@@ -0,0 +1 @@
+name: mysql

examples/patterns/configuring_experiments/conf/db/sqlite.yaml

@@ -0,0 +1 @@
+name: sqlite

examples/patterns/configuring_experiments/conf/experiment/aplite.yaml

@@ -0,0 +1,7 @@
+# @package _global_
+defaults:
+  - override /db: sqlite
+
+
+server:
+  port: 8080

examples/patterns/configuring_experiments/conf/experiment/nglite.yaml

@@ -0,0 +1,7 @@
+# @package _global_
+defaults:
+  - override /server: nginx
+  - override /db: sqlite
+
+server:
+  port: 8080

examples/patterns/configuring_experiments/conf/server/apache.yaml

@@ -0,0 +1,2 @@
+name: apache
+port: 80

examples/patterns/configuring_experiments/conf/server/nginx.yaml

@@ -0,0 +1,2 @@
+name: nginx
+port: 80

examples/patterns/configuring_experiments/my_app.py

@@ -0,0 +1,13 @@
+# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved
+from omegaconf import DictConfig, OmegaConf
+
+import hydra
+
+
+@hydra.main(config_path="conf", config_name="config")
+def my_app(cfg: DictConfig) -> None:
+    print(OmegaConf.to_yaml(cfg))
+
+
+if __name__ == "__main__":
+    my_app()

examples/patterns/extending_configs/conf/config.yaml

@@ -0,0 +1,2 @@
+defaults:
+  - db: ???

examples/patterns/extending_configs/conf/db/base_mysql.yaml

@@ -0,0 +1,4 @@
+host: localhost
+port: 3306
+user: ???
+password: ???

examples/patterns/extending_configs/conf/db/mysql_extending_from_another_group.yaml

@@ -0,0 +1,7 @@
+defaults:
+  - /db_schema/base_mysql@_here_
+
+user: omry
+password: secret
+port: 3307
+encoding: utf8

examples/patterns/extending_configs/conf/db/mysql_extending_from_this_group.yaml

@@ -0,0 +1,7 @@
+defaults:
+  - base_mysql
+
+user: omry
+password: secret
+port: 3307
+encoding: utf8

examples/patterns/extending_configs/conf/db_schema/base_mysql.yaml

@@ -0,0 +1,4 @@
+host: localhost
+port: 3306
+user: ???
+password: ???

examples/patterns/extending_configs/my_app.py

@@ -0,0 +1,13 @@
+# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved
+from omegaconf import DictConfig, OmegaConf
+
+import hydra
+
+
+@hydra.main(config_path="conf", config_name="config")
+def my_app(cfg: DictConfig) -> None:
+    print(OmegaConf.to_yaml(cfg))
+
+
+if __name__ == "__main__":
+    my_app()

hydra/_internal/defaults_list.py

@@ -383,7 +383,7 @@ def _update_overrides(
             if legacy_hydra_override:
                 # DEPRECATED: remove in 1.2
                 d.override = True
-                url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/default_list_override"
+                url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/defaults_list_override"
                 msg = dedent(
                     f"""\
                     In {parent.get_config_path()}: Invalid overriding of {d.group}:

hydra/conf/__init__.py

@@ -6,23 +6,6 @@
 
 from hydra.core.config_store import ConfigStore
 
-hydra_defaults = [
-    # Hydra's logging config
-    {"hydra/hydra_logging": "default"},
-    # Job's logging config
-    {"hydra/job_logging": "default"},
-    # Launcher config
-    {"hydra/launcher": "basic"},
-    # Sweeper config
-    {"hydra/sweeper": "basic"},
-    # Output directory
-    {"hydra/output": "default"},
-    # --help template
-    {"hydra/help": "default"},
-    # --hydra-help template
-    {"hydra/hydra_help": "default"},
-]
-
 
 @dataclass
 class HelpConf:
@@ -106,8 +89,17 @@ class RuntimeConf:
 
 @dataclass
 class HydraConf:
-
-    defaults: List[Any] = field(default_factory=lambda: hydra_defaults.copy())
+    defaults: List[Any] = field(
+        default_factory=lambda: [
+            {"output": "default"},
+            {"launcher": "basic"},
+            {"sweeper": "basic"},
+            {"help": "default"},
+            {"hydra_help": "default"},
+            {"hydra_logging": "default"},
+            {"job_logging": "default"},
+        ]
+    )
 
     # Normal run output configuration
     run: RunDir = RunDir()
@@ -152,7 +144,7 @@ class HydraConf:
     # Typical command lines to manipulate hydra.verbose:
     # hydra.verbose=true
     # hydra.verbose=[hydra,__main__]
-    # TODO: good use case for Union support in OmegaConf
+    # TODO: good use ca se for Union support in OmegaConf
     verbose: Any = False
 
     # Composition choices dictionary
@@ -171,16 +163,6 @@ class HydraConf:
 cs.store(
     group="hydra",
     name="config",
-    node=HydraConf(
-        defaults=[
-            {"hydra_logging": "default"},
-            {"job_logging": "default"},
-            {"launcher": "basic"},
-            {"sweeper": "basic"},
-            {"output": "default"},
-            {"help": "default"},
-            {"hydra_help": "default"},
-        ]
-    ),
+    node=HydraConf(),
     provider="hydra",
 )

plugins/hydra_ray_launcher/tests/test_ray_launcher.py

@@ -1,4 +1,4 @@
-# # Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved
+# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved
 import sys
 
 import pytest

tests/defaults_list/test_defaults_tree.py

@@ -752,7 +752,7 @@ def test_legacy_hydra_overrides_from_primary_config(
         """\
         Invalid overriding of hydra/help:
         Default list overrides requires 'override' keyword.
-        See https://hydra.cc/docs/next/upgrades/1.0_to_1.1/default_list_override for more information."""
+        See https://hydra.cc/docs/next/upgrades/1.0_to_1.1/defaults_list_override for more information."""
     )
     with warns(expected_warning=UserWarning, match=re.escape(msg)):
         _test_defaults_tree_impl(

tests/test_config_loader.py

@@ -44,15 +44,8 @@ class TopLevelConfig:
 
 hydra_load_list: List[LoadTrace] = [
     LoadTrace(
-        config_path="hydra/hydra_logging/default",
-        package="hydra.hydra_logging",
-        parent="hydra/config",
-        search_path="pkg://hydra.conf",
-        provider="hydra",
-    ),
-    LoadTrace(
-        config_path="hydra/job_logging/default",
-        package="hydra.job_logging",
+        config_path="hydra/output/default",
+        package="hydra",
         parent="hydra/config",
         search_path="pkg://hydra.conf",
         provider="hydra",
@@ -72,22 +65,29 @@ class TopLevelConfig:
         provider="hydra",
     ),
     LoadTrace(
-        config_path="hydra/output/default",
-        package="hydra",
+        config_path="hydra/help/default",
+        package="hydra.help",
         parent="hydra/config",
         search_path="pkg://hydra.conf",
         provider="hydra",
     ),
     LoadTrace(
-        config_path="hydra/help/default",
-        package="hydra.help",
+        config_path="hydra/hydra_help/default",
+        package="hydra.hydra_help",
         parent="hydra/config",
         search_path="pkg://hydra.conf",
         provider="hydra",
     ),
     LoadTrace(
-        config_path="hydra/hydra_help/default",
-        package="hydra.hydra_help",
+        config_path="hydra/hydra_logging/default",
+        package="hydra.hydra_logging",
+        parent="hydra/config",
+        search_path="pkg://hydra.conf",
+        provider="hydra",
+    ),
+    LoadTrace(
+        config_path="hydra/job_logging/default",
+        package="hydra.job_logging",
         parent="hydra/config",
         search_path="pkg://hydra.conf",
         provider="hydra",
@@ -600,15 +600,8 @@ def test_override_hydra_config_group_from_config_file() -> None:
     )
     expected = [
         LoadTrace(
-            config_path="hydra/hydra_logging/hydra_debug",
-            package="hydra.hydra_logging",
-            parent="hydra/config",
-            search_path="pkg://hydra.conf",
-            provider="hydra",
-        ),
-        LoadTrace(
-            config_path="hydra/job_logging/disabled",
-            package="hydra.job_logging",
+            config_path="hydra/output/default",
+            package="hydra",
             parent="hydra/config",
             search_path="pkg://hydra.conf",
             provider="hydra",
@@ -628,22 +621,29 @@ def test_override_hydra_config_group_from_config_file() -> None:
             provider="hydra",
         ),
         LoadTrace(
-            config_path="hydra/output/default",
-            package="hydra",
+            config_path="hydra/help/default",
+            package="hydra.help",
             parent="hydra/config",
             search_path="pkg://hydra.conf",
             provider="hydra",
         ),
         LoadTrace(
-            config_path="hydra/help/default",
-            package="hydra.help",
+            config_path="hydra/hydra_help/default",
+            package="hydra.hydra_help",
             parent="hydra/config",
             search_path="pkg://hydra.conf",
             provider="hydra",
         ),
         LoadTrace(
-            config_path="hydra/hydra_help/default",
-            package="hydra.hydra_help",
+            config_path="hydra/hydra_logging/hydra_debug",
+            package="hydra.hydra_logging",
+            parent="hydra/config",
+            search_path="pkg://hydra.conf",
+            provider="hydra",
+        ),
+        LoadTrace(
+            config_path="hydra/job_logging/disabled",
+            package="hydra.job_logging",
             parent="hydra/config",
             search_path="pkg://hydra.conf",
             provider="hydra",