From 17b9b1571e8e758e25517de44d0bb49a94cf70a0 Mon Sep 17 00:00:00 2001
From: David de la Iglesia Castro <daviddelaiglesiacastro@gmail.com>
Date: Wed, 24 Aug 2022 10:28:45 +0200
Subject: [PATCH] api: Add details for`params_show` `stages` syntax.

Explain `stages` syntax for cases where the api is used from a directory different to the one the `dvc.yam` is located.
---
 dvc/api/params.py             |  4 ++++
 tests/func/api/test_params.py | 22 ++++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/dvc/api/params.py b/dvc/api/params.py
index 294a88efe..3218ea4ec 100644
--- a/dvc/api/params.py
+++ b/dvc/api/params.py
@@ -37,6 +37,10 @@ def params_show(
             stages to retrieve parameters from.
             Defaults to `None`.
             If `None`, all parameters from all stages will be retrieved.
+            If this method is called from a different location to the one where
+            the `dvc.yaml` is found, the relative path to the `dvc.yaml` must
+            be provided as a prefix with the syntax `{relpath}:{stage}`.
+            For example: `subdir/dvc.yaml:stage-0` or `../dvc.yaml:stage-1`.
         rev (str, optional): Name of the `Git revision`_ to retrieve parameters
             from.
             Defaults to `None`.
diff --git a/tests/func/api/test_params.py b/tests/func/api/test_params.py
index 85e82ae88..909161a7c 100644
--- a/tests/func/api/test_params.py
+++ b/tests/func/api/test_params.py
@@ -1,3 +1,4 @@
+import os
 from textwrap import dedent
 
 import pytest
@@ -95,6 +96,27 @@ def test_params_show_stages(params_repo):
         api.params_show(stages="stage-0")
 
 
+def test_params_show_stage_addressing(tmp_dir, dvc):
+    for subdir in {"subdir1", "subdir2"}:
+        subdir = tmp_dir / subdir
+        subdir.mkdir()
+        with subdir.chdir():
+            subdir.gen("params.yaml", "foo: 1")
+
+            dvc.run(name="stage-0", cmd="echo stage-0", params=["foo"])
+
+    for s in {"subdir1", "subdir2"}:
+        dvcyaml = os.path.join(s, "dvc.yaml")
+        assert api.params_show(stages=f"{dvcyaml}:stage-0") == {"foo": 1}
+
+    with subdir.chdir():
+        nested = subdir / "nested"
+        nested.mkdir()
+        with nested.chdir():
+            dvcyaml = os.path.join("..", "dvc.yaml")
+            assert api.params_show(stages=f"{dvcyaml}:stage-0") == {"foo": 1}
+
+
 def test_params_show_revs(params_repo):
     assert api.params_show(rev="HEAD~1") == {
         "params.yaml:foo": 1,