Merge pull request #4 from fyndata/develop

Release 0.1.0

Author: glarrain

fd_gcp/__init__.py

@@ -0,0 +1,30 @@
+"""
+Fyndata's library of Google Cloud Platform (GCP) utils
+======================================================
+
+Among other things, this library makes it easier to interact with some
+GCP services or even mock the interaction with them.
+
+Each module that is dedicated to interact with an specific GCP service is named
+``gcp_{service_acronym}`` e.g. :mod:`gcp_kms`.
+
+There are other modules for the external users of the library such as
+:mod:`exceptions` and :mod:`auth`.
+
+
+Google Resource Name (GRN)
+--------------------------
+
+The terms *resource name* and *resource id* are used extensively in GCP's
+documentation and code. Because of the reasons below, for GCP we created an
+analogy of AWS' concept of *Amazon Resource Name* (ARN): *Google Resource Name*
+(GRN).
+
+- Using the word "name" of X might be misleading since it seems too casual
+  and one could easily say "the name of that key ring is ``my-keyring``" but
+  that would be wrong: the format of the name of a key ring resource is
+  ``projects/[PROJECT_ID]/locations/[LOCATION_ID]/keyRings/[KEY_RING_ID]``.
+- It is annoying to have code entities named such as
+  ``kms_crypto_key_resource_name`` (unlike ``kms_crypto_key_id``).
+
+"""

fd_gcp/_http.py

@@ -0,0 +1,27 @@
+import logging
+
+import google.auth.exceptions
+import googleapiclient.errors
+import googleapiclient.http
+import httplib2
+
+from . import exceptions
+
+
+logger = logging.getLogger(__name__)
+
+
+def execute_google_api_client_request(
+    request: googleapiclient.http.HttpRequest,
+) -> httplib2.Response:
+    try:
+        response = request.execute()
+    except google.auth.exceptions.GoogleAuthError as exc:
+        raise exceptions.AuthError from exc
+    except googleapiclient.errors.HttpError as exc:
+        new_exc = exceptions.process_googleapiclient_http_error(exc)
+        raise new_exc from exc
+    except googleapiclient.errors.Error as exc:
+        raise exceptions.UnrecognizedApiError from exc
+
+    return response

fd_gcp/auth.py

@@ -0,0 +1,86 @@
+"""
+Authentication and authorization utilities.
+
+"""
+import logging
+
+import google.auth.compute_engine
+import google.auth.credentials
+import google.auth.exceptions
+
+from . import exceptions
+from .common import GcpCredentials
+
+# Make sure package 'cryptography' is available for 'google.auth', which prefers that lib instead
+#   of falling back (silently) to package 'rsa' (pure Python).
+#   https://github.com/googleapis/google-auth-library-python/blob/v1.5.1/google/auth/crypt/rsa.py#L19
+try:
+    import google.auth.crypt._cryptography_rsa
+except ImportError as exc:  # pragma: no cover
+    msg = "Package 'cryptography' is required for optimum performance of 'google.auth'."
+    raise ImportError(msg) from exc
+
+
+logger = logging.getLogger(__name__)
+
+
+def get_env_default_credentials() -> GcpCredentials:
+    """
+    Return the default credentials for the current GCP environment.
+
+    .. warning:: if the env var ``GOOGLE_APPLICATION_CREDENTIALS`` is set, then
+        the returned value might correspond to something else.
+
+    """
+    try:
+        credentials, _ = google.auth.default()
+    except google.auth.exceptions.DefaultCredentialsError as exc:
+        raise exceptions.AuthError from exc
+    return credentials
+
+
+def get_env_project_id() -> str:
+    """
+    Return the project ID of the current GCP environment.
+
+    .. warning:: if the env var ``GOOGLE_APPLICATION_CREDENTIALS`` is set, then
+        the returned value might correspond to something else.
+
+    """
+    try:
+        _, project_id = google.auth.default()
+    except google.auth.exceptions.DefaultCredentialsError as exc:
+        raise exceptions.AuthError from exc
+    if not isinstance(project_id, str):
+        raise exceptions.Error("Unexpected Google Auth lib response.", project_id)
+
+    return project_id
+
+
+def get_gce_credentials(service_account_email: str =None) -> GcpCredentials:
+    """
+    Return credentials provided by Compute Engine service account.
+
+    .. warning:: This function does not attempt to authenticate or verify that
+        the ``service_account_email`` does indeed exist. It will return a
+        credentials object anyway.
+
+    A Compute Engine instance may have multiple service accounts.
+
+    `Google's Auth Library for Python docs`_ say:
+
+       "Applications running on Compute Engine, Container Engine, or the
+       App Engine flexible environment can obtain credentials provided by
+       Compute Engine service accounts."
+
+    .. _Google's Auth Library for Python docs:
+         https://google-auth.readthedocs.io/en/latest/user-guide.html#compute-engine-container-engine-and-the-app-engine-flexible-environment
+
+    """
+    service_account_email = service_account_email or 'default'
+    return google.auth.compute_engine.Credentials(service_account_email)
+
+
+def load_credentials_from_file(filename: str) -> GcpCredentials:
+    credentials, _ = google.auth._default._load_credentials_from_file(filename)
+    return credentials

fd_gcp/common.py

@@ -0,0 +1,7 @@
+"""
+Definitions and data useful for many services modules.
+
+"""
+# warning: do NOT remove any of these definitions, even though they are not used in this module.
+from google.auth.credentials import Credentials as GcpCredentials  # noqa: F401
+from googleapiclient.discovery import Resource as GcpResource  # noqa: F401

fd_gcp/constants.py

@@ -0,0 +1,18 @@
+"""
+GCP's or this library's-specific common constants.
+
+"""
+
+# GCP project ID
+# > A project ID must start with a lowercase letter, and can contain only ASCII letters, digits,
+# > and hyphens, and must be between 6 and 30 characters.
+# https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project
+PROJECT_ID_MAX_LENGTH = 30
+# TODO: PROJECT_ID_REGEX = re.compile(r'^...$')
+
+# GCP region ID
+#   https://cloud.google.com/about/locations/
+# note: as of 2018-10-22, we have not found anywhere official the value of this restriction.
+# note: as of 2018-10-22, the longest region ID is 'northamerica-northeast1' (23 characters).
+REGION_ID_MAX_LENGTH_ESTIMATION = 48
+# TODO: REGION_ID_MAX_LENGTH