From 650dd64e7ef74efd480ed20bbcd3e760c0b0d31a Mon Sep 17 00:00:00 2001 From: Ruslan Kuprieiev Date: Fri, 16 Jun 2023 02:08:05 +0300 Subject: [PATCH] docs: api-reference: add config to open/read/dvcfs/etc Fixes #4627 --- content/docs/api-reference/dvcfilesystem.md | 2 + content/docs/api-reference/exp_show.md | 1 + content/docs/api-reference/metrics_show.md | 1 + content/docs/api-reference/open.md | 53 ++++++++++++++++++++- content/docs/api-reference/params_show.md | 1 + content/docs/api-reference/read.md | 9 +++- 6 files changed, 65 insertions(+), 2 deletions(-) diff --git a/content/docs/api-reference/dvcfilesystem.md b/content/docs/api-reference/dvcfilesystem.md index f18fbffea63..7ba7180998f 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 f520062b497..f6576e7dfe3 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]: ``` diff --git a/content/docs/api-reference/metrics_show.md b/content/docs/api-reference/metrics_show.md index 5b7499176a8..e49ad3dcab8 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: ``` diff --git a/content/docs/api-reference/open.md b/content/docs/api-reference/open.md index 392896a08af..3d17d75736f 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 08e0f51e07f..077369444dc 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: ``` diff --git a/content/docs/api-reference/read.md b/content/docs/api-reference/read.md index 44dc16251bd..9988497509b 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