py2docfx 0.1.21.dev2253172__py3-none-any.whl → 0.1.22__py3-none-any.whl

py2docfx/venv/venv1/Lib/site-packages/google/api_core/client_options.py

@@ -49,6 +49,9 @@ You can also pass a mapping object.
 """
 
 from typing import Callable, Mapping, Optional, Sequence, Tuple
+import warnings
+
+from google.api_core import general_helpers
 
 
 class ClientOptions(object):
@@ -67,8 +70,9 @@ class ClientOptions(object):
             and ``client_encrypted_cert_source`` are mutually exclusive.
         quota_project_id (Optional[str]): A project name that a client's
             quota belongs to.
-        credentials_file (Optional[str]): A path to a file storing credentials.
-            ``credentials_file` and ``api_key`` are mutually exclusive.
+        credentials_file (Optional[str]): Deprecated. A path to a file storing credentials.
+            ``credentials_file` and ``api_key`` are mutually exclusive. This argument will be
+            removed in the next major version of `google-api-core`.
 
             .. warning::
                 Important: If you accept a credential configuration (credential JSON/File/Stream)
@@ -114,6 +118,9 @@ class ClientOptions(object):
         api_audience: Optional[str] = None,
         universe_domain: Optional[str] = None,
     ):
+        if credentials_file is not None:
+            warnings.warn(general_helpers._CREDENTIALS_FILE_WARNING, DeprecationWarning)
+
         if client_cert_source and client_encrypted_cert_source:
             raise ValueError(
                 "client_cert_source and client_encrypted_cert_source are mutually exclusive"

py2docfx/venv/venv1/Lib/site-packages/google/api_core/general_helpers.py

@@ -14,3 +14,39 @@
 
 # This import for backward compatibility only.
 from functools import wraps  # noqa: F401 pragma: NO COVER
+
+_CREDENTIALS_FILE_WARNING = """\
+The `credentials_file` argument is deprecated because of a potential security risk.
+
+The `google.auth.load_credentials_from_file` method does not validate the credential
+configuration. The security risk occurs when a credential configuration is accepted
+from a source that is not under your control and used without validation on your side.
+
+If you know that you will be loading credential configurations of a
+specific type, it is recommended to use a credential-type-specific
+load method.
+
+This will ensure that an unexpected credential type with potential for
+malicious intent is not loaded unintentionally. You might still have to do
+validation for certain credential types. Please follow the recommendations
+for that method. For example, if you want to load only service accounts,
+you can create the service account credentials explicitly:
+
+```
+from google.cloud.vision_v1 import ImageAnnotatorClient
+from google.oauth2 import service_account
+
+credentials = service_account.Credentials.from_service_account_file(filename)
+client = ImageAnnotatorClient(credentials=credentials)
+```
+
+If you are loading your credential configuration from an untrusted source and have
+not mitigated the risks (e.g. by validating the configuration yourself), make
+these changes as soon as possible to prevent security risks to your environment.
+
+Regardless of the method used, it is always your responsibility to validate
+configurations received from external sources.
+
+Refer to https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
+for more details.
+"""

py2docfx/venv/venv1/Lib/site-packages/google/api_core/grpc_helpers.py

@@ -13,20 +13,19 @@
 # limitations under the License.
 
 """Helpers for :mod:`grpc`."""
-from typing import Generic, Iterator, Optional, TypeVar
-
 import collections
 import functools
+from typing import Generic, Iterator, Optional, TypeVar
 import warnings
 
-import grpc
-
-from google.api_core import exceptions
 import google.auth
 import google.auth.credentials
 import google.auth.transport.grpc
 import google.auth.transport.requests
 import google.protobuf
+import grpc
+
+from google.api_core import exceptions, general_helpers
 
 PROTOBUF_VERSION = google.protobuf.__version__
 
@@ -213,9 +212,10 @@ def _create_composite_credentials(
         credentials (google.auth.credentials.Credentials): The credentials. If
             not specified, then this function will attempt to ascertain the
             credentials from the environment using :func:`google.auth.default`.
-        credentials_file (str): A file with credentials that can be loaded with
+        credentials_file (str): Deprecated. A file with credentials that can be loaded with
             :func:`google.auth.load_credentials_from_file`. This argument is
-            mutually exclusive with credentials.
+            mutually exclusive with credentials. This argument will be
+            removed in the next major version of `google-api-core`.
 
             .. warning::
                 Important: If you accept a credential configuration (credential JSON/File/Stream)
@@ -245,6 +245,9 @@ def _create_composite_credentials(
     Raises:
         google.api_core.DuplicateCredentialArgs: If both a credentials object and credentials_file are passed.
     """
+    if credentials_file is not None:
+        warnings.warn(general_helpers._CREDENTIALS_FILE_WARNING, DeprecationWarning)
+
     if credentials and credentials_file:
         raise exceptions.DuplicateCredentialArgs(
             "'credentials' and 'credentials_file' are mutually exclusive."

py2docfx/venv/venv1/Lib/site-packages/google/api_core/grpc_helpers_async.py

@@ -20,13 +20,14 @@ functions. This module is implementing the same surface with AsyncIO semantics.
 
 import asyncio
 import functools
+import warnings
 
 from typing import AsyncGenerator, Generic, Iterator, Optional, TypeVar
 
 import grpc
 from grpc import aio
 
-from google.api_core import exceptions, grpc_helpers
+from google.api_core import exceptions, general_helpers, grpc_helpers
 
 # denotes the proto response type for grpc calls
 P = TypeVar("P")
@@ -233,9 +234,10 @@ def create_channel(
             are passed to :func:`google.auth.default`.
         ssl_credentials (grpc.ChannelCredentials): Optional SSL channel
             credentials. This can be used to specify different certificates.
-        credentials_file (str): A file with credentials that can be loaded with
+        credentials_file (str): Deprecated. A file with credentials that can be loaded with
             :func:`google.auth.load_credentials_from_file`. This argument is
-            mutually exclusive with credentials.
+            mutually exclusive with credentials. This argument will be
+            removed in the next major version of `google-api-core`.
 
             .. warning::
                 Important: If you accept a credential configuration (credential JSON/File/Stream)
@@ -280,6 +282,9 @@ def create_channel(
         ValueError: If `ssl_credentials` is set and `attempt_direct_path` is set to `True`.
     """
 
+    if credentials_file is not None:
+        warnings.warn(general_helpers._CREDENTIALS_FILE_WARNING, DeprecationWarning)
+
     # If `ssl_credentials` is set and `attempt_direct_path` is set to `True`,
     # raise ValueError as this is not yet supported.
     # See https://github.com/googleapis/python-api-core/issues/590

py2docfx/venv/venv1/Lib/site-packages/google/api_core/operations_v1/transports/base.py

@@ -16,12 +16,8 @@
 import abc
 import re
 from typing import Awaitable, Callable, Optional, Sequence, Union
+import warnings
 
-import google.api_core  # type: ignore
-from google.api_core import exceptions as core_exceptions  # type: ignore
-from google.api_core import gapic_v1  # type: ignore
-from google.api_core import retry as retries  # type: ignore
-from google.api_core import version
 import google.auth  # type: ignore
 from google.auth import credentials as ga_credentials  # type: ignore
 from google.longrunning import operations_pb2
@@ -30,6 +26,12 @@ import google.protobuf
 from google.protobuf import empty_pb2, json_format  # type: ignore
 from grpc import Compression
 
+import google.api_core  # type: ignore
+from google.api_core import exceptions as core_exceptions  # type: ignore
+from google.api_core import gapic_v1  # type: ignore
+from google.api_core import general_helpers
+from google.api_core import retry as retries  # type: ignore
+from google.api_core import version
 
 PROTOBUF_VERSION = google.protobuf.__version__
 
@@ -69,9 +71,10 @@ class OperationsTransport(abc.ABC):
                 credentials identify the application to the service; if none
                 are specified, the client will attempt to ascertain the
                 credentials from the environment.
-            credentials_file (Optional[str]): A file with credentials that can
+            credentials_file (Optional[str]): Deprecated. A file with credentials that can
                 be loaded with :func:`google.auth.load_credentials_from_file`.
-                This argument is mutually exclusive with credentials.
+                This argument is mutually exclusive with credentials. This argument will be
+                removed in the next major version of `google-api-core`.
 
                 .. warning::
                     Important: If you accept a credential configuration (credential JSON/File/Stream)
@@ -98,6 +101,9 @@ class OperationsTransport(abc.ABC):
                 "https", but for testing or local servers,
                 "http" can be specified.
         """
+        if credentials_file is not None:
+            warnings.warn(general_helpers._CREDENTIALS_FILE_WARNING, DeprecationWarning)
+
         maybe_url_match = re.match("^(?P<scheme>http(?:s)?://)?(?P<host>.*)$", host)
         if maybe_url_match is None:
             raise ValueError(

py2docfx/venv/venv1/Lib/site-packages/google/api_core/operations_v1/transports/rest.py

@@ -15,23 +15,26 @@
 #
 
 from typing import Callable, Dict, Optional, Sequence, Tuple, Union
+import warnings
 
+from google.auth import credentials as ga_credentials  # type: ignore
+from google.auth.transport.requests import AuthorizedSession  # type: ignore
+from google.longrunning import operations_pb2  # type: ignore
+import google.protobuf
+from google.protobuf import empty_pb2  # type: ignore
+from google.protobuf import json_format  # type: ignore
+import grpc
 from requests import __version__ as requests_version
 
 from google.api_core import exceptions as core_exceptions  # type: ignore
 from google.api_core import gapic_v1  # type: ignore
+from google.api_core import general_helpers
 from google.api_core import path_template  # type: ignore
 from google.api_core import rest_helpers  # type: ignore
 from google.api_core import retry as retries  # type: ignore
-from google.auth import credentials as ga_credentials  # type: ignore
-from google.auth.transport.requests import AuthorizedSession  # type: ignore
-from google.longrunning import operations_pb2  # type: ignore
-from google.protobuf import empty_pb2  # type: ignore
-from google.protobuf import json_format  # type: ignore
-import google.protobuf
 
-import grpc
-from .base import DEFAULT_CLIENT_INFO as BASE_DEFAULT_CLIENT_INFO, OperationsTransport
+from .base import DEFAULT_CLIENT_INFO as BASE_DEFAULT_CLIENT_INFO
+from .base import OperationsTransport
 
 PROTOBUF_VERSION = google.protobuf.__version__
 
@@ -91,9 +94,10 @@ class OperationsRestTransport(OperationsTransport):
                 are specified, the client will attempt to ascertain the
                 credentials from the environment.
 
-            credentials_file (Optional[str]): A file with credentials that can
+            credentials_file (Optional[str]): Deprecated. A file with credentials that can
                 be loaded with :func:`google.auth.load_credentials_from_file`.
-                This argument is ignored if ``channel`` is provided.
+                This argument is ignored if ``channel`` is provided. This argument will be
+                removed in the next major version of `google-api-core`.
 
                 .. warning::
                     Important: If you accept a credential configuration (credential JSON/File/Stream)
@@ -101,9 +105,9 @@ class OperationsRestTransport(OperationsTransport):
                     validate it before providing it to any Google API or client library. Providing an
                     unvalidated credential configuration to Google APIs or libraries can compromise
                     the security of your systems and data. For more information, refer to
-                    `Validate credential configurations from external sources`_.
+                    `Validate credential configuration from external sources`_.
 
-                .. _Validate credential configurations from external sources:
+                .. _Validate credential configuration from external sources:
 
                 https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
             scopes (Optional(Sequence[str])): A list of scopes. This argument is
@@ -130,6 +134,9 @@ class OperationsRestTransport(OperationsTransport):
                 "v1" by default.
 
         """
+        if credentials_file is not None:
+            warnings.warn(general_helpers._CREDENTIALS_FILE_WARNING, DeprecationWarning)
+
         # Run the base constructor
         # TODO(yon-mg): resolve other ctor params i.e. scopes, quota, etc.
         # TODO: When custom host (api_endpoint) is set, `scopes` must *also* be set on the

py2docfx/venv/venv1/Lib/site-packages/google/api_core/operations_v1/transports/rest_asyncio.py

@@ -16,6 +16,7 @@
 
 import json
 from typing import Any, Callable, Coroutine, Dict, Optional, Sequence, Tuple
+import warnings
 
 from google.auth import __version__ as auth_version
 
@@ -29,6 +30,7 @@ except ImportError as e:  # pragma: NO COVER
 
 from google.api_core import exceptions as core_exceptions  # type: ignore
 from google.api_core import gapic_v1  # type: ignore
+from google.api_core import general_helpers
 from google.api_core import path_template  # type: ignore
 from google.api_core import rest_helpers  # type: ignore
 from google.api_core import retry_async as retries_async  # type: ignore
@@ -96,6 +98,22 @@ class AsyncOperationsRestTransport(OperationsTransport):
                 credentials identify the application to the service; if none
                 are specified, the client will attempt to ascertain the
                 credentials from the environment.
+            credentials_file (Optional[str]): Deprecated. A file with credentials that can
+                be loaded with :func:`google.auth.load_credentials_from_file`.
+                This argument is ignored if ``channel`` is provided. This argument will be
+                removed in the next major version of `google-api-core`.
+
+                .. warning::
+                    Important: If you accept a credential configuration (credential JSON/File/Stream)
+                    from an external source for authentication to Google Cloud Platform, you must
+                    validate it before providing it to any Google API or client library. Providing an
+                    unvalidated credential configuration to Google APIs or libraries can compromise
+                    the security of your systems and data. For more information, refer to
+                    `Validate credential configurations from external sources`_.
+
+                .. _Validate credential configurations from external sources:
+
+                https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
             client_info (google.api_core.gapic_v1.client_info.ClientInfo):
                 The client info used to send a user-agent string along with
                 API requests. If ``None``, then default info will be used.
@@ -113,6 +131,9 @@ class AsyncOperationsRestTransport(OperationsTransport):
                 "v1" by default.
 
         """
+        if credentials_file is not None:
+            warnings.warn(general_helpers._CREDENTIALS_FILE_WARNING, DeprecationWarning)
+
         unsupported_params = {
             # TODO(https://github.com/googleapis/python-api-core/issues/715): Add support for `credentials_file` to async REST transport.
             "google.api_core.client_options.ClientOptions.credentials_file": credentials_file,

py2docfx/venv/venv1/Lib/site-packages/google/api_core/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2.25.1"
+__version__ = "2.26.0"

py2docfx/venv/venv1/Lib/site-packages/google/auth/_default.py

@@ -59,6 +59,38 @@ or "API not enabled" error. See the following page for troubleshooting: \
 https://cloud.google.com/docs/authentication/adc-troubleshooting/user-creds. \
 """
 
+_GENERIC_LOAD_METHOD_WARNING = """\
+The {} method is deprecated because of a potential security risk.
+
+This method does not validate the credential configuration. The security
+risk occurs when a credential configuration is accepted from a source that
+is not under your control and used without validation on your side.
+
+If you know that you will be loading credential configurations of a
+specific type, it is recommended to use a credential-type-specific
+load method.
+This will ensure that an unexpected credential type with potential for
+malicious intent is not loaded unintentionally. You might still have to do
+validation for certain credential types. Please follow the recommendations
+for that method. For example, if you want to load only service accounts,
+you can create the service account credentials explicitly:
+
+```
+from google.oauth2 import service_account
+creds = service_account.Credentials.from_service_account_file(filename)
+```
+
+If you are loading your credential configuration from an untrusted source and have
+not mitigated the risks (e.g. by validating the configuration yourself), make
+these changes as soon as possible to prevent security risks to your environment.
+
+Regardless of the method used, it is always your responsibility to validate
+configurations received from external sources.
+
+Refer to https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
+for more details.
+"""
+
 # The subject token type used for AWS external_account credentials.
 _AWS_SUBJECT_TOKEN_TYPE = "urn:ietf:params:aws:token-type:aws4_request"
 
@@ -76,6 +108,20 @@ def _warn_about_problematic_credentials(credentials):
         warnings.warn(_CLOUD_SDK_CREDENTIALS_WARNING)
 
 
+def _warn_about_generic_load_method(method_name):  # pragma: NO COVER
+    """Warns that a generic load method is being used.
+
+    This is to discourage use of the generic load methods in favor of
+    more specific methods. The generic methods are more likely to lead to
+    security issues if the input is not validated.
+
+    Args:
+        method_name (str): The name of the method being used.
+    """
+
+    warnings.warn(_GENERIC_LOAD_METHOD_WARNING.format(method_name), DeprecationWarning)
+
+
 def load_credentials_from_file(
     filename, scopes=None, default_scopes=None, quota_project_id=None, request=None
 ):
@@ -121,6 +167,8 @@ def load_credentials_from_file(
         google.auth.exceptions.DefaultCredentialsError: if the file is in the
             wrong format or is missing.
     """
+    _warn_about_generic_load_method("load_credentials_from_file")
+
     if not os.path.exists(filename):
         raise exceptions.DefaultCredentialsError(
             "File {} was not found.".format(filename)
@@ -184,6 +232,7 @@ def load_credentials_from_dict(
         google.auth.exceptions.DefaultCredentialsError: if the file is in the
             wrong format or is missing.
     """
+    _warn_about_generic_load_method("load_credentials_from_dict")
     if not isinstance(info, dict):
         raise exceptions.DefaultCredentialsError(
             "info object was of type {} but dict type was expected.".format(type(info))
@@ -256,15 +305,17 @@ def _get_gcloud_sdk_credentials(quota_project_id=None):
         _LOGGER.debug("Cloud SDK credentials not found on disk; not using them")
         return None, None
 
-    credentials, project_id = load_credentials_from_file(
-        credentials_filename, quota_project_id=quota_project_id
-    )
-    credentials._cred_file_path = credentials_filename
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        credentials, project_id = load_credentials_from_file(
+            credentials_filename, quota_project_id=quota_project_id
+        )
+        credentials._cred_file_path = credentials_filename
 
-    if not project_id:
-        project_id = _cloud_sdk.get_project_id()
+        if not project_id:
+            project_id = _cloud_sdk.get_project_id()
 
-    return credentials, project_id
+        return credentials, project_id
 
 
 def _get_explicit_environ_credentials(quota_project_id=None):
@@ -290,12 +341,15 @@ def _get_explicit_environ_credentials(quota_project_id=None):
         return _get_gcloud_sdk_credentials(quota_project_id=quota_project_id)
 
     if explicit_file is not None:
-        credentials, project_id = load_credentials_from_file(
-            os.environ[environment_vars.CREDENTIALS], quota_project_id=quota_project_id
-        )
-        credentials._cred_file_path = f"{explicit_file} file via the GOOGLE_APPLICATION_CREDENTIALS environment variable"
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            credentials, project_id = load_credentials_from_file(
+                os.environ[environment_vars.CREDENTIALS],
+                quota_project_id=quota_project_id,
+            )
+            credentials._cred_file_path = f"{explicit_file} file via the GOOGLE_APPLICATION_CREDENTIALS environment variable"
 
-        return credentials, project_id
+            return credentials, project_id
 
     else:
         return None, None

py2docfx/venv/venv1/Lib/site-packages/google/auth/_default_async.py

@@ -20,6 +20,7 @@ Implements application default credentials and project ID detection.
 import io
 import json
 import os
+import warnings
 
 from google.auth import _default
 from google.auth import environment_vars
@@ -116,14 +117,16 @@ def _get_gcloud_sdk_credentials(quota_project_id=None):
     if not os.path.isfile(credentials_filename):
         return None, None
 
-    credentials, project_id = load_credentials_from_file(
-        credentials_filename, quota_project_id=quota_project_id
-    )
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        credentials, project_id = load_credentials_from_file(
+            credentials_filename, quota_project_id=quota_project_id
+        )
 
-    if not project_id:
-        project_id = _cloud_sdk.get_project_id()
+        if not project_id:
+            project_id = _cloud_sdk.get_project_id()
 
-    return credentials, project_id
+        return credentials, project_id
 
 
 def _get_explicit_environ_credentials(quota_project_id=None):
@@ -141,11 +144,14 @@ def _get_explicit_environ_credentials(quota_project_id=None):
         return _get_gcloud_sdk_credentials(quota_project_id=quota_project_id)
 
     if explicit_file is not None:
-        credentials, project_id = load_credentials_from_file(
-            os.environ[environment_vars.CREDENTIALS], quota_project_id=quota_project_id
-        )
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            credentials, project_id = load_credentials_from_file(
+                os.environ[environment_vars.CREDENTIALS],
+                quota_project_id=quota_project_id,
+            )
 
-        return credentials, project_id
+            return credentials, project_id
 
     else:
         return None, None

py2docfx/venv/venv1/Lib/site-packages/google/auth/_helpers.py

@@ -21,6 +21,7 @@ from email.message import Message
 import hashlib
 import json
 import logging
+import os
 import sys
 from typing import Any, Dict, Mapping, Optional, Union
 import urllib
@@ -287,6 +288,46 @@ def unpadded_urlsafe_b64encode(value):
     return base64.urlsafe_b64encode(value).rstrip(b"=")
 
 
+def get_bool_from_env(variable_name, default=False):
+    """Gets a boolean value from an environment variable.
+
+    The environment variable is interpreted as a boolean with the following
+    (case-insensitive) rules:
+    - "true", "1" are considered true.
+    - "false", "0" are considered false.
+    Any other values will raise an exception.
+
+    Args:
+        variable_name (str): The name of the environment variable.
+        default (bool): The default value if the environment variable is not
+            set.
+
+    Returns:
+        bool: The boolean value of the environment variable.
+
+    Raises:
+        google.auth.exceptions.InvalidValue: If the environment variable is
+            set to a value that can not be interpreted as a boolean.
+    """
+    value = os.environ.get(variable_name)
+
+    if value is None:
+        return default
+
+    value = value.lower()
+
+    if value in ("true", "1"):
+        return True
+    elif value in ("false", "0"):
+        return False
+    else:
+        raise exceptions.InvalidValue(
+            'Environment variable "{}" must be one of "true", "false", "1", or "0".'.format(
+                variable_name
+            )
+        )
+
+
 def is_python_3():
     """Check if the Python interpreter is Python 2 or 3.