android-notify 1.59.3__py3-none-any.whl → 1.60.0__py3-none-any.whl

venv/Lib/site-packages/docutils/writers/xetex/__init__.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+# :Author: Günter Milde <milde@users.sf.net>
+# :Revision: $Revision: 10196 $
+# :Date: $Date: 2025-08-07 08:35:37 +0200 (Do, 07. Aug 2025) $
+# :Copyright: © 2010 Günter Milde.
+# :License: Released under the terms of the `2-Clause BSD license`_, in short:
+#
+#    Copying and distribution of this file, with or without modification,
+#    are permitted in any medium without royalty provided the copyright
+#    notice and this notice are preserved.
+#    This file is offered as-is, without any warranty.
+#
+# .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
+
+"""
+XeLaTeX document tree Writer.
+
+A variant of Docutils' standard 'latex2e' writer producing LaTeX output
+suited for processing with the Unicode-aware TeX engines
+LuaTeX and XeTeX.
+"""
+
+from __future__ import annotations
+
+__docformat__ = 'reStructuredText'
+
+from docutils import frontend
+from docutils.writers import latex2e
+from docutils.writers.latex2e import PreambleCmds
+
+
+class Writer(latex2e.Writer):
+    """A writer for Unicode-aware LaTeX variants (XeTeX, LuaTeX)"""
+
+    supported = ('latex', 'tex', 'xetex', 'xelatex', 'luatex', 'lualatex')
+    """Formats this writer supports."""
+
+    default_template = 'xelatex.tex'
+    default_preamble = """\
+% Linux Libertine (free, wide coverage, not only for Linux)
+\\setmainfont{Linux Libertine O}
+\\setsansfont{Linux Biolinum O}
+\\setmonofont[HyphenChar=None,Scale=MatchLowercase]{DejaVu Sans Mono}"""
+
+    config_section = 'xetex writer'
+    config_section_dependencies = ('writers', 'latex writers')
+
+    # use a copy of the parent spec with some modifications:
+    settings_spec = frontend.filter_settings_spec(
+        latex2e.Writer.settings_spec,
+        # removed settings
+        'font_encoding',
+        # changed settings:
+        template=('Template file. Default: "%s".' % default_template,
+                  ['--template'],
+                  {'default': default_template, 'metavar': '<file>'}),
+        latex_preamble=('Customization by LaTeX code in the preamble. '
+                        'Default: select "Linux Libertine" fonts.',
+                        ['--latex-preamble'],
+                        {'metavar': '<preamble>',
+                         'default': default_preamble}),
+        )
+
+    def __init__(self) -> None:
+        latex2e.Writer.__init__(self)
+        self.settings_defaults.update({'fontencoding': ''})  # use default (TU)
+        self.translator_class = XeLaTeXTranslator
+
+
+class Babel(latex2e.Babel):
+    """Language specifics for XeTeX.
+
+    Use `polyglossia` instead of `babel` and adapt settings.
+    """
+    language_codes = latex2e.Babel.language_codes.copy()
+    # Additionally supported or differently named languages:
+    language_codes.update({
+        # code        Polyglossia-name  comment
+        'cop':        'coptic',
+        'de':         'german',         # new spelling (de_1996)
+        'de-1901':    'ogerman',        # old spelling
+        'dv':         'divehi',         # Maldivian
+        'dsb':        'lsorbian',
+        'el-polyton': 'polygreek',
+        'fa':         'farsi',
+        'grc':        'ancientgreek',
+        'ko':         'korean',
+        'hsb':        'usorbian',
+        'sh-Cyrl':    'serbian',        # Serbo-Croatian, Cyrillic script
+        'sh-Latn':    'croatian',       # Serbo-Croatian, Latin script
+        'sq':         'albanian',
+        'sr':         'serbian',        # Cyrillic script (sr-Cyrl)
+        'th':         'thai',
+        'vi':         'vietnamese',
+        # zh-Latn:    ???               # Chinese Pinyin
+        })
+    # normalize (downcase) keys
+    language_codes = {k.lower(): v for k, v in language_codes.items()}
+
+    # Languages without Polyglossia support:
+    for key in ('af',           # 'afrikaans',
+                'de-AT',        # 'naustrian',
+                'de-AT-1901',   # 'austrian',
+                # TODO: use variant=... for English variants
+                'en-CA',        # 'canadian',
+                'en-GB',        # 'british',
+                'en-NZ',        # 'newzealand',
+                'en-US',        # 'american',
+                'fr-CA',        # 'canadien',
+                'grc-ibycus',   # 'ibycus', (Greek Ibycus encoding)
+                'sr-Latn',      # 'serbian script=latin'
+                ):
+        del language_codes[key.lower()]
+
+    warn_msg = 'Language "%s" not supported by LaTeX (polyglossia)'
+
+    def __init__(self, language_code, reporter) -> None:
+        self.language_code = language_code
+        self.reporter = reporter
+        self.language = self.language_name(language_code)
+        self.otherlanguages = {}
+        self.warn_msg = 'Language "%s" not supported by Polyglossia.'
+        self.quote_index = 0
+        self.quotes = ('"', '"')
+        # language dependent configuration:
+        # double quotes are "active" in some languages (e.g. German).
+        self.literal_double_quote = '"'  # TODO: use \textquotedbl ?
+
+    def __call__(self):
+        setup = [r'\usepackage{polyglossia}',
+                 r'\setdefaultlanguage{%s}' % self.language]
+        if self.otherlanguages:
+            setup.append(r'\setotherlanguages{%s}' %
+                         ','.join(sorted(self.otherlanguages.keys())))
+        return '\n'.join(setup)
+
+
+class XeLaTeXTranslator(latex2e.LaTeXTranslator):
+    """
+    Generate code for LaTeX using Unicode fonts (XeLaTex or LuaLaTeX).
+
+    See the docstring of docutils.writers._html_base.HTMLTranslator for
+    notes on and examples of safe subclassing.
+    """
+
+    def __init__(self, document) -> None:
+        self.is_xetex = True  # typeset with XeTeX or LuaTeX engine
+        latex2e.LaTeXTranslator.__init__(self, document, Babel)
+        if self.latex_encoding == 'utf8':
+            self.requirements.pop('_inputenc', None)
+        else:
+            self.requirements['_inputenc'] = (r'\XeTeXinputencoding %s '
+                                              % self.latex_encoding)
+
+    def to_latex_length(self, length_str: str, node=None) -> str:
+        """Convert "measure" `length_str` to LaTeX length specification.
+
+        XeTeX does not know the length unit px.
+        Use ``\\pdfpxdimen``, the macro holding the value of 1 px in pdfTeX.
+        This way, configuring works the same for pdftex and xetex.
+        """
+        length_str = super().to_latex_length(length_str, node)
+        if length_str.endswith('px'):
+            if not self.fallback_stylesheet:
+                self.fallbacks['_providelength'] = PreambleCmds.providelength
+            self.fallbacks['px'] = '\n\\DUprovidelength{\\pdfpxdimen}{1bp}'
+            return length_str.replace('px', '\\pdfpxdimen')
+        return length_str

venv/Lib/site-packages/id/__init__.py

@@ -0,0 +1,91 @@
+# Copyright 2022 The Sigstore Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+API for retrieving OIDC tokens.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Callable
+
+__version__ = "1.5.0"
+
+
+class IdentityError(Exception):
+    """
+    Raised on any OIDC token format or claim error.
+    """
+
+    pass
+
+
+class AmbientCredentialError(IdentityError):
+    """
+    Raised when an ambient credential should be present, but
+    can't be retrieved (e.g. network failure).
+    """
+
+    pass
+
+
+class GitHubOidcPermissionCredentialError(AmbientCredentialError):
+    """
+    Raised when the current GitHub Actions environment doesn't have permission
+    to retrieve an OIDC token.
+    """
+
+    pass
+
+
+def detect_credential(audience: str) -> str | None:
+    """
+    Try each ambient credential detector, returning the first one to succeed
+    or `None` if all fail.
+
+    Raises `AmbientCredentialError` if any detector fails internally (i.e.
+    detects a credential, but cannot retrieve it).
+    """
+    from ._internal.oidc.ambient import (
+        detect_buildkite,
+        detect_circleci,
+        detect_gcp,
+        detect_github,
+        detect_gitlab,
+    )
+
+    detectors: list[Callable[..., str | None]] = [
+        detect_github,
+        detect_gcp,
+        detect_buildkite,
+        detect_gitlab,
+        detect_circleci,
+    ]
+    for detector in detectors:
+        credential = detector(audience)
+        if credential is not None:
+            return credential
+    return None
+
+
+def decode_oidc_token(token: str) -> tuple[str, str, str]:
+    # Split the token into its three parts: header, payload, and signature
+    header, payload, signature = token.split(".")
+
+    # Decode base64-encoded header and payload
+    decoded_header = base64.urlsafe_b64decode(header + "==").decode("utf-8")
+    decoded_payload = base64.urlsafe_b64decode(payload + "==").decode("utf-8")
+
+    return decoded_header, decoded_payload, signature

venv/Lib/site-packages/id/__main__.py

@@ -0,0 +1,88 @@
+# Copyright 2022 The Sigstore Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+The `python -m id` entrypoint.
+"""
+
+import argparse
+import logging
+import os
+
+from . import __version__
+
+logging.basicConfig()
+logger = logging.getLogger(__name__)
+
+# NOTE: We configure the top package logger, rather than the root logger,
+# to avoid overly verbose logging in third-party code by default.
+package_logger = logging.getLogger("id")
+package_logger.setLevel(os.environ.get("ID_LOGLEVEL", "INFO").upper())
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="id",
+        description="a tool for generating OIDC identities",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="run with additional debug logging; supply multiple times to increase verbosity",
+    )
+    parser.add_argument(
+        "-d",
+        "--decode",
+        action="store_true",
+        help="decode the OIDC token into JSON",
+    )
+    parser.add_argument(
+        "audience",
+        type=str,
+        default=os.getenv("ID_OIDC_AUDIENCE"),
+        help="the OIDC audience to use",
+    )
+
+    return parser
+
+
+def main() -> None:
+    parser = _parser()
+    args = parser.parse_args()
+
+    # Configure logging upfront, so that we don't miss anything.
+    if args.verbose >= 1:
+        package_logger.setLevel("DEBUG")
+    if args.verbose >= 2:
+        logging.getLogger().setLevel("DEBUG")
+
+    logger.debug(f"parsed arguments {args}")
+
+    from . import decode_oidc_token, detect_credential
+
+    token = detect_credential(args.audience)
+    if token and args.decode:
+        header, payload, signature = decode_oidc_token(token)
+        print(header)
+        print(payload)
+    else:
+        print(token)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

venv/Lib/site-packages/id/_internal/oidc/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2022 The Sigstore Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

venv/Lib/site-packages/id/_internal/oidc/ambient.py

@@ -0,0 +1,328 @@
+# Copyright 2022 The Sigstore Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Ambient OIDC credential detection.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import shutil
+import subprocess  # nosec B404
+
+import requests
+
+from ... import AmbientCredentialError, GitHubOidcPermissionCredentialError
+
+logger = logging.getLogger(__name__)
+
+_GCP_PRODUCT_NAME_FILE = "/sys/class/dmi/id/product_name"
+_GCP_TOKEN_REQUEST_URL = (
+    "http://metadata/computeMetadata/v1/instance/service-accounts/default/token"  # noqa # nosec B105
+)
+_GCP_IDENTITY_REQUEST_URL = (
+    "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity"  # noqa
+)
+_GCP_GENERATEIDTOKEN_REQUEST_URL = (
+    "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/{}:generateIdToken"  # noqa
+)
+
+_env_var_regex = re.compile(r"[^A-Z0-9_]|^[^A-Z_]")
+
+
+def detect_github(audience: str) -> str | None:
+    """
+    Detect and return a GitHub Actions ambient OIDC credential.
+
+    Returns `None` if the context is not a GitHub Actions environment.
+
+    Raises if the environment is GitHub Actions, but is incorrect or
+    insufficiently permissioned for an OIDC credential.
+    """
+
+    logger.debug("GitHub: looking for OIDC credentials")
+    if not os.getenv("GITHUB_ACTIONS"):
+        logger.debug("GitHub: environment doesn't look like a GH action; giving up")
+        return None
+
+    # If we're running on a GitHub Action, we need to issue a GET request
+    # to a special URL with a special bearer token. Both are stored in
+    # the environment and are only present if the workflow has sufficient permissions.
+    req_token = os.getenv("ACTIONS_ID_TOKEN_REQUEST_TOKEN")
+    if not req_token:
+        raise GitHubOidcPermissionCredentialError(
+            "GitHub: missing or insufficient OIDC token permissions, the "
+            "ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variable was unset"
+        )
+    req_url = os.getenv("ACTIONS_ID_TOKEN_REQUEST_URL")
+    if not req_url:
+        raise GitHubOidcPermissionCredentialError(
+            "GitHub: missing or insufficient OIDC token permissions, the "
+            "ACTIONS_ID_TOKEN_REQUEST_URL environment variable was unset"
+        )
+
+    logger.debug("GitHub: requesting OIDC token")
+    resp = requests.get(
+        req_url,
+        params={"audience": audience},
+        headers={"Authorization": f"bearer {req_token}"},
+        timeout=30,
+    )
+    try:
+        resp.raise_for_status()
+    except requests.HTTPError as http_error:
+        raise AmbientCredentialError(
+            f"GitHub: OIDC token request failed (code={resp.status_code}, "
+            f"body={resp.content.decode()!r})"
+        ) from http_error
+    except requests.Timeout:
+        raise AmbientCredentialError("GitHub: OIDC token request timed out")
+
+    try:
+        body = resp.json()
+        value = body["value"]
+
+        if not isinstance(value, str):
+            raise ValueError("OIDC token is not a string")
+    except Exception as e:
+        raise AmbientCredentialError("GitHub: malformed or incomplete JSON") from e
+
+    logger.debug("GitHub: successfully requested OIDC token")
+    return value
+
+
+def detect_gcp(audience: str) -> str | None:
+    """
+    Detect an return a Google Cloud Platform ambient OIDC credential.
+
+    Returns `None` if the context is not a GCP environment.
+
+    Raises if the environment is GCP, but is incorrect or
+    insufficiently permissioned for an OIDC credential.
+    """
+    logger.debug("GCP: looking for OIDC credentials")
+
+    service_account_name = os.getenv("GOOGLE_SERVICE_ACCOUNT_NAME")
+    if service_account_name:
+        logger.debug("GCP: GOOGLE_SERVICE_ACCOUNT_NAME set; attempting impersonation")
+
+        logger.debug("GCP: requesting access token")
+        resp = requests.get(
+            _GCP_TOKEN_REQUEST_URL,
+            params={"scopes": "https://www.googleapis.com/auth/cloud-platform"},
+            headers={"Metadata-Flavor": "Google"},
+            timeout=30,
+        )
+        try:
+            resp.raise_for_status()
+        except requests.HTTPError as http_error:
+            raise AmbientCredentialError(
+                f"GCP: access token request failed (code={resp.status_code}, "
+                f"body={resp.content.decode()!r})"
+            ) from http_error
+        except requests.Timeout:
+            raise AmbientCredentialError("GCP: access token request timed out")
+
+        access_token = resp.json().get("access_token")
+
+        if not access_token:
+            raise AmbientCredentialError("GCP: access token missing from response")
+
+        resp = requests.post(
+            _GCP_GENERATEIDTOKEN_REQUEST_URL.format(service_account_name),
+            json={"audience": audience, "includeEmail": True},
+            headers={
+                "Authorization": f"Bearer {access_token}",
+            },
+            timeout=30,
+        )
+
+        logger.debug("GCP: requesting OIDC token")
+        try:
+            resp.raise_for_status()
+        except requests.HTTPError as http_error:
+            raise AmbientCredentialError(
+                f"GCP: OIDC token request failed (code={resp.status_code}, "
+                f"body={resp.content.decode()!r})"
+            ) from http_error
+        except requests.Timeout:
+            raise AmbientCredentialError("GCP: OIDC token request timed out")
+
+        oidc_token: str = resp.json().get("token")
+
+        if not oidc_token:
+            raise AmbientCredentialError("GCP: OIDC token missing from response")
+
+        logger.debug("GCP: successfully requested OIDC token")
+        return oidc_token
+
+    else:
+        logger.debug("GCP: GOOGLE_SERVICE_ACCOUNT_NAME not set; skipping impersonation")
+
+        try:
+            with open(_GCP_PRODUCT_NAME_FILE) as f:
+                name = f.read().strip()
+        except OSError:
+            logger.debug("GCP: environment doesn't have GCP product name file; giving up")
+            return None
+
+        if name not in {"Google", "Google Compute Engine"}:
+            logger.debug(f"GCP: product name file exists, but product name is {name!r}; giving up")
+            return None
+
+        logger.debug("GCP: requesting OIDC token")
+        resp = requests.get(
+            _GCP_IDENTITY_REQUEST_URL,
+            params={"audience": audience, "format": "full"},
+            headers={"Metadata-Flavor": "Google"},
+            timeout=30,
+        )
+
+        try:
+            resp.raise_for_status()
+        except requests.HTTPError as http_error:
+            raise AmbientCredentialError(
+                f"GCP: OIDC token request failed (code={resp.status_code}, "
+                f"body={resp.content.decode()!r})"
+            ) from http_error
+        except requests.Timeout:
+            raise AmbientCredentialError("GCP: OIDC token request timed out")
+
+        logger.debug("GCP: successfully requested OIDC token")
+        return resp.text
+
+
+def detect_buildkite(audience: str) -> str | None:
+    """
+    Detect and return a Buildkite ambient OIDC credential.
+
+    Returns `None` if the context is not a Buildkite environment.
+
+    Raises if the environment is Buildkite, but no Buildkite agent is found or
+    the agent encounters an error when generating an OIDC token.
+    """
+    logger.debug("Buildkite: looking for OIDC credentials")
+
+    if not os.getenv("BUILDKITE"):
+        logger.debug("Buildkite: environment doesn't look like BuildKite; giving up")
+        return None
+
+    # Check that the Buildkite agent executable exists in the `PATH`.
+    if shutil.which("buildkite-agent") is None:
+        raise AmbientCredentialError(
+            "Buildkite: could not find Buildkite agent in Buildkite environment"
+        )
+
+    # Now query the agent for a token.
+    #
+    # NOTE(alex): We're silencing `bandit` here. The reasoning for ignoring each
+    # test are as follows.
+    #
+    # B603: This is complaining about invoking an external executable. However,
+    # there doesn't seem to be any way to do this that satisfies `bandit` so I
+    # think we need to ignore this.
+    # More context at:
+    #   https://github.com/PyCQA/bandit/issues/333
+    #
+    # B607: This is complaining about invoking an external executable without
+    # providing an absolute path (we just refer to whatever `buildkite-agent`)
+    # is in the `PATH`. For a Buildkite agent, there's no guarantee where the
+    # `buildkite-agent` is installed so again, I don't think there's anything
+    # we can do about this.
+    process = subprocess.run(  # nosec B603, B607
+        ["buildkite-agent", "oidc", "request-token", "--audience", audience],
+        capture_output=True,
+        text=True,
+    )
+
+    if process.returncode != 0:
+        raise AmbientCredentialError(
+            f"Buildkite: the Buildkite agent encountered an error: {process.stdout}"
+        )
+
+    return process.stdout.strip()
+
+
+def detect_gitlab(audience: str) -> str | None:
+    """
+    Detect and return a GitLab CI/CD ambient OIDC credential.
+
+    This detection is based on an environment variable. The variable name must be
+    `<AUD>_ID_TOKEN`  where `<AUD>` is the uppercased audience argument where all
+    characters outside of ASCII letters and digits are replaced with "_". A
+    leading digit must also replaced with a "_".
+
+    As an example, audience "sigstore" would require variable SIGSTORE_ID_TOKEN,
+    and audience "http://test.audience" would require variable
+    HTTP___TEST_AUDIENCE_ID_TOKEN.
+
+    Returns `None` if the context is not GitLab CI/CD environment.
+
+    Raises if the environment is GitLab, but the `<AUD>_ID_TOKEN` environment
+    variable is not set.
+    """
+    logger.debug("GitLab: looking for OIDC credentials")
+
+    if not os.getenv("GITLAB_CI"):
+        logger.debug("GitLab: environment doesn't look like GitLab CI/CD; giving up")
+        return None
+
+    # construct a reasonable env var name from the audience
+    sanitized_audience = _env_var_regex.sub("_", audience.upper())
+    var_name = f"{sanitized_audience}_ID_TOKEN"
+    token = os.getenv(var_name)
+    if not token:
+        raise AmbientCredentialError(f"GitLab: Environment variable {var_name} not found")
+
+    logger.debug(f"GitLab: Found token in environment variable {var_name}")
+    return token
+
+
+def detect_circleci(audience: str) -> str | None:
+    """
+    Detect and return a CircleCI ambient OIDC credential.
+
+    Returns `None` if the context is not a CircleCI environment.
+
+    Raises if the environment is GitHub Actions, but is incorrect or
+    insufficiently permissioned for an OIDC credential.
+    """
+    logger.debug("CircleCI: looking for OIDC credentials")
+
+    if not os.getenv("CIRCLECI"):
+        logger.debug("CircleCI: environment doesn't look like CircleCI; giving up")
+        return None
+
+    # Check that the circleci executable exists in the `PATH`.
+    if shutil.which("circleci") is None:
+        raise AmbientCredentialError("CircleCI: could not find `circleci` in the environment")
+
+    # See NOTE on `detect_buildkite` for why we silence these warnings.
+    payload = json.dumps({"aud": audience})
+    process = subprocess.run(  # nosec B603, B607
+        ["circleci", "run", "oidc", "get", "--claims", payload],
+        capture_output=True,
+        text=True,
+    )
+
+    if process.returncode != 0:
+        raise AmbientCredentialError(
+            f"CircleCI: the `circleci` tool encountered an error: {process.stdout}"
+        )
+
+    return process.stdout.strip()