chore(fill): deprecate --flat-output flag

docs/CHANGELOG.md

@@ -37,6 +37,7 @@ Users can select any of the artifacts depending on their testing needs for their
 - 🐞 `fill` no longer writes generated fixtures into an existing, non-empty output directory; it must now be empty or `--clean` must be used to delete it first ([#1608](https://github.com/ethereum/execution-spec-tests/pull/1608)).
 - 🐞 zkEVM marked tests have been removed from `tests-deployed` tox environment into its own separate workflow `tests-deployed-zkevm` and are filled by `evmone-t8n` ([#1617](https://github.com/ethereum/execution-spec-tests/pull/1617)).
 - ✨ Field `postStateHash` is now added to all `blockchain_test` and `blockchain_test_engine` tests that use `exclude_full_post_state_in_output` in place of `postState`. Fixes `evmone-blockchaintest` test consumption and indirectly fixes coverage runs for these tests ([#1667](https://github.com/ethereum/execution-spec-tests/pull/1667)).
+- 🔀 Deprecated the `--flat-output` flag. This flag will be removed in a future version [1632](https://github.com/ethereum/execution-spec-tests/pull/1632).
 
 #### `consume`
 

docs/filling_tests/filling_tests_command_line.md

@@ -159,7 +159,7 @@ Arguments defining filler location and output:
                         in '.tar.gz', then the specified tarball is additionally created (the fixtures
                         are still written to the specified path without the '.tar.gz' suffix). Can be
                         deleted. Default: './fixtures'.
-  --flat-output         Output each test case in the directory without the folder structure.
+  --flat-output         [DEPRECATED] Output each test case in the directory without the folder structure. This flag will be removed in a future version.
   --single-fixture-per-file
                         Don't group fixtures in JSON files by test function; write each fixture to its
                         own file. This can be used to increase the granularity of --verify-fixtures.

src/pytest_plugins/filler/filler.py

@@ -193,7 +193,8 @@ def pytest_addoption(parser: pytest.Parser):
         action="store_true",
         dest="flat_output",
         default=False,
-        help="Output each test case in the directory without the folder structure.",
+        help="[DEPRECATED] Output each test case in the directory without the folder structure. "
+        "This flag will be removed in a future version.",
     )
     test_group.addoption(
         "--single-fixture-per-file",
@@ -321,6 +322,16 @@ def pytest_configure(config):
     # Modify the block gas limit if specified.
     if config.getoption("block_gas_limit"):
         EnvironmentDefaults.gas_limit = config.getoption("block_gas_limit")
+    if config.option.collectonly:
+        return
+
+    # Show a deprecation warning for the flat-output flag
+    if config.getoption("flat_output"):
+        warnings.warn(
+            "The --flat-output flag is deprecated and will be removed in a future version.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
 
     # Initialize fixture output configuration
     config.fixture_output = FixtureOutput.from_config(config)