From 493d72751383c7c80282c36581fbd5f67de08f06 Mon Sep 17 00:00:00 2001 From: Ruslan Kuprieiev Date: Wed, 21 Jun 2023 22:02:43 +0300 Subject: [PATCH] docs: api-reference: add config to open/read/dvcfs/etc (#4628) Fixes #4627 --- content/docs/api-reference/dvcfilesystem.md | 2 + content/docs/api-reference/exp_show.md | 6 +++ content/docs/api-reference/metrics_show.md | 6 +++ content/docs/api-reference/open.md | 53 ++++++++++++++++++++- content/docs/api-reference/params_show.md | 6 +++ content/docs/api-reference/read.md | 9 +++- 6 files changed, 80 insertions(+), 2 deletions(-) diff --git a/content/docs/api-reference/dvcfilesystem.md b/content/docs/api-reference/dvcfilesystem.md index f18fbffea6..7ba7180998 100644 --- a/content/docs/api-reference/dvcfilesystem.md +++ b/content/docs/api-reference/dvcfilesystem.md @@ -29,6 +29,8 @@ The optional `rev` argument can be passed to open a filesystem from a certain Git commit (any [revision](https://git-scm.com/docs/revisions) such as a branch or a tag name, a commit hash, or an [experiment name]). +The optional `config` argument can be passed through to the DVC project. + [experiment name]: /doc/command-reference/exp/run#-n ## Opening a file diff --git a/content/docs/api-reference/exp_show.md b/content/docs/api-reference/exp_show.md index f520062b49..fca127cbce 100644 --- a/content/docs/api-reference/exp_show.md +++ b/content/docs/api-reference/exp_show.md @@ -9,6 +9,7 @@ def exp_show( num: int = 1, param_deps: bool = False, force: bool = False, + config: Optional[dict] = None, ) -> List[Dict]: ``` @@ -69,6 +70,11 @@ the Git `HEAD`. - `param_deps` - whether to retrieve only params that are stage dependencies. _Default_: `False`. +- `config` - [config](/doc/command-reference/config) dictionary to pass to the + DVC project. This is merged with the existing project config and can be used + to, for example, provide credentials to the `remote`. See + [dvc.api.open](/doc/api-reference/open) for examples. + ## Example: Create a Pandas DataFrame The format returned by `dvc.api.exp_show()` can be directly converted to a diff --git a/content/docs/api-reference/metrics_show.md b/content/docs/api-reference/metrics_show.md index 5b7499176a..f0545664aa 100644 --- a/content/docs/api-reference/metrics_show.md +++ b/content/docs/api-reference/metrics_show.md @@ -8,6 +8,7 @@ def metrics_show( *targets: str, repo: Optional[str] = None, rev: Optional[str] = None, + config: Optional[dict] = None, ) -> Dict: ``` @@ -55,6 +56,11 @@ The function parameters (below) let you restrict what's retrieved. [experiment](/doc/command-reference/exp) name). If `repo` is not a Git repo, this option is ignored. _Default_: `None` (current working tree will be used) +- `config` - [config](/doc/command-reference/config) dictionary to pass to the + DVC project. This is merged with the existing project config and can be used + to, for example, provide credentials to the `remote`. See + [dvc.api.open](/doc/api-reference/open) for examples. + ## Example: Filter by one or more targets `targets` can be a single name (string): diff --git a/content/docs/api-reference/open.md b/content/docs/api-reference/open.md index 392896a08a..3d17d75736 100644 --- a/content/docs/api-reference/open.md +++ b/content/docs/api-reference/open.md @@ -8,7 +8,8 @@ def open(path: str, rev: str = None, remote: str = None, mode: str = "r", - encoding: str = None) + encoding: str = None, + config: dict = None) ``` ## Usage @@ -84,11 +85,16 @@ call – no _context manager_ involved. Neither function utilizes disc space. only be used in text mode. Defaults to `"utf-8"`. Mirrors the namesake parameter in builtin `open()`. +- `config` - [config] dictionary to pass to the DVC project. This is merged with + the existing project config and can be used to, for example, provide + credentials to the `remote`. + [revision]: https://git-scm.com/docs/revisions [experiment name]: /doc/command-reference/exp/run#-n [dvc remote]: /doc/user-guide/data-management/remote-storage [default remote]: /doc/command-reference/remote/default [codec]: https://docs.python.org/3/library/codecs.html#standard-encodings +[config]: /doc/command-reference/config ## Exceptions @@ -199,3 +205,48 @@ import dvc.api with dvc.api.open('data/nlp/words_ru.txt', encoding='koi8_r') as f: # ... Process Russian words ``` + +## Example: Specify credentials for specific remote + +See [remote modify](/doc/command-reference/remote/modify) for full list of +remote-specific config options. + +```py +import dvc.api + +config = { + 'remote': { + 'myremote': { + 'access_key_id': 'mykey', + 'secret_access_key': 'mysecretkey', + 'session_token': 'mytoken', + }, + }, +} + +with dvc.api.open('data', config=config) as f: + # ... Process data +``` + +## Example: Change default remote and specify credentials for it + +See [remote modify](/doc/command-reference/remote/modify) for full list of +remote-specific config options. + +```py +import dvc.api + +config = { + 'core': {'remote': 'myremote'}, + 'remote': { + 'myremote': { + 'access_key_id': 'mykey', + 'secret_access_key': 'mysecretkey', + 'session_token': 'mytoken', + }, + }, +} + +with dvc.api.open('data', config=config) as f: + # ... Process data +``` diff --git a/content/docs/api-reference/params_show.md b/content/docs/api-reference/params_show.md index 08e0f51e07..10ab0606a5 100644 --- a/content/docs/api-reference/params_show.md +++ b/content/docs/api-reference/params_show.md @@ -10,6 +10,7 @@ def params_show( repo: Optional[str] = None, rev: Optional[str] = None, deps: bool = False, + config: Optional[dict] = None, ) -> Dict: ``` @@ -67,6 +68,11 @@ The function parameters (below) let you restrict what's retrieved. - `deps` - whether to retrieve only params that are stage dependencies. Accepts `True` or `False` (_default_). +- `config` - [config](/doc/command-reference/config) dictionary to pass to the + DVC project. This is merged with the existing project config and can be used + to, for example, provide credentials to the `remote`. See + [dvc.api.open](/doc/api-reference/open) for examples. + ## Example: Filter by stage name(s) `stages` can be a single name (string): diff --git a/content/docs/api-reference/read.md b/content/docs/api-reference/read.md index 44dc16251b..9988497509 100644 --- a/content/docs/api-reference/read.md +++ b/content/docs/api-reference/read.md @@ -14,7 +14,8 @@ def read(path: str, rev: str = None, remote: str = None, mode: str = "r", - encoding: str = None) + encoding: str = None, + config: dict = None) ``` ## Usage @@ -75,11 +76,17 @@ Python's [`open()`] built-in, which is used under the hood. only be used in text mode. Defaults to `"utf-8"`. Mirrors the namesake parameter in builtin `open()`. +- `config` - [config] dictionary to pass to the DVC project. This is merged with + the existing project config and can be used to, for example, provide + credentials to the `remote`. See [dvc.api.open](/doc/api-reference/open) for + examples. + [revision]: https://git-scm.com/docs/revisions [experiment name]: /doc/command-reference/exp/run#-n [dvc remote]: /doc/user-guide/data-management/remote-storage [default remote]: /doc/command-reference/remote/default [codec]: https://docs.python.org/3/library/codecs.html#standard-encodings +[config]: /doc/command-reference/config ## Exceptions