|
| 1 | +Python Client for Google Cloud Aiplatform V1 Schema Trainingjob Definition API |
| 2 | +================================================= |
| 3 | + |
| 4 | +Quick Start |
| 5 | +----------- |
| 6 | + |
| 7 | +In order to use this library, you first need to go through the following steps: |
| 8 | + |
| 9 | +1. `Select or create a Cloud Platform project.`_ |
| 10 | +2. `Enable billing for your project.`_ |
| 11 | +3. Enable the Google Cloud Aiplatform V1 Schema Trainingjob Definition API. |
| 12 | +4. `Setup Authentication.`_ |
| 13 | + |
| 14 | +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project |
| 15 | +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project |
| 16 | +.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html |
| 17 | + |
| 18 | +Installation |
| 19 | +~~~~~~~~~~~~ |
| 20 | + |
| 21 | +Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to |
| 22 | +create isolated Python environments. The basic problem it addresses is one of |
| 23 | +dependencies and versions, and indirectly permissions. |
| 24 | + |
| 25 | +With `virtualenv`_, it's possible to install this library without needing system |
| 26 | +install permissions, and without clashing with the installed system |
| 27 | +dependencies. |
| 28 | + |
| 29 | +.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ |
| 30 | + |
| 31 | + |
| 32 | +Mac/Linux |
| 33 | +^^^^^^^^^ |
| 34 | + |
| 35 | +.. code-block:: console |
| 36 | +
|
| 37 | + python3 -m venv <your-env> |
| 38 | + source <your-env>/bin/activate |
| 39 | + <your-env>/bin/pip install /path/to/library |
| 40 | +
|
| 41 | +
|
| 42 | +Windows |
| 43 | +^^^^^^^ |
| 44 | + |
| 45 | +.. code-block:: console |
| 46 | +
|
| 47 | + python3 -m venv <your-env> |
| 48 | + <your-env>\Scripts\activate |
| 49 | + <your-env>\Scripts\pip.exe install \path\to\library |
| 50 | +
|
| 51 | +
|
| 52 | +Logging |
| 53 | +------- |
| 54 | + |
| 55 | +This library uses the standard Python :code:`logging` functionality to log some RPC events that could be of interest for debugging and monitoring purposes. |
| 56 | +Note the following: |
| 57 | + |
| 58 | +#. Logs may contain sensitive information. Take care to **restrict access to the logs** if they are saved, whether it be on local storage or on Google Cloud Logging. |
| 59 | +#. Google may refine the occurrence, level, and content of various log messages in this library without flagging such changes as breaking. **Do not depend on immutability of the logging events**. |
| 60 | +#. By default, the logging events from this library are not handled. You must **explicitly configure log handling** using one of the mechanisms below. |
| 61 | + |
| 62 | + |
| 63 | +Simple, environment-based configuration |
| 64 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 65 | + |
| 66 | +To enable logging for this library without any changes in your code, set the :code:`GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to a valid Google |
| 67 | +logging scope. This configures handling of logging events (at level :code:`logging.DEBUG` or higher) from this library in a default manner, emitting the logged |
| 68 | +messages in a structured format. It does not currently allow customizing the logging levels captured nor the handlers, formatters, etc. used for any logging |
| 69 | +event. |
| 70 | + |
| 71 | +A logging scope is a period-separated namespace that begins with :code:`google`, identifying the Python module or package to log. |
| 72 | + |
| 73 | +- Valid logging scopes: :code:`google`, :code:`google.cloud.asset.v1`, :code:`google.api`, :code:`google.auth`, etc. |
| 74 | +- Invalid logging scopes: :code:`foo`, :code:`123`, etc. |
| 75 | + |
| 76 | +**NOTE**: If the logging scope is invalid, the library does not set up any logging handlers. |
| 77 | + |
| 78 | + |
| 79 | +Examples |
| 80 | +^^^^^^^^ |
| 81 | + |
| 82 | +- Enabling the default handler for all Google-based loggers |
| 83 | + |
| 84 | +.. code-block:: console |
| 85 | +
|
| 86 | + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google |
| 87 | +
|
| 88 | +- Enabling the default handler for a specific Google module (for a client library called :code:`library_v1`): |
| 89 | + |
| 90 | +.. code-block:: console |
| 91 | +
|
| 92 | + export GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google.cloud.library_v1 |
| 93 | +
|
| 94 | +
|
| 95 | +Advanced, code-based configuration |
| 96 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 97 | + |
| 98 | +You can also configure a valid logging scope using Python's standard `logging` mechanism. |
| 99 | + |
| 100 | + |
| 101 | +Examples |
| 102 | +^^^^^^^^ |
| 103 | + |
| 104 | +- Configuring a handler for all Google-based loggers |
| 105 | + |
| 106 | +.. code-block:: python |
| 107 | +
|
| 108 | + import logging |
| 109 | +
|
| 110 | + from google.cloud.translate_v3 import translate |
| 111 | +
|
| 112 | + base_logger = logging.getLogger("google") |
| 113 | + base_logger.addHandler(logging.StreamHandler()) |
| 114 | + base_logger.setLevel(logging.DEBUG) |
| 115 | +
|
| 116 | +- Configuring a handler for a specific Google module (for a client library called :code:`library_v1`): |
| 117 | + |
| 118 | +.. code-block:: python |
| 119 | +
|
| 120 | + import logging |
| 121 | +
|
| 122 | + from google.cloud.translate_v3 import translate |
| 123 | +
|
| 124 | + base_logger = logging.getLogger("google.cloud.library_v1") |
| 125 | + base_logger.addHandler(logging.StreamHandler()) |
| 126 | + base_logger.setLevel(logging.DEBUG) |
| 127 | +
|
| 128 | +
|
| 129 | +Logging details |
| 130 | +~~~~~~~~~~~~~~~ |
| 131 | + |
| 132 | +#. Regardless of which of the mechanisms above you use to configure logging for this library, by default logging events are not propagated up to the root |
| 133 | + logger from the `google`-level logger. If you need the events to be propagated to the root logger, you must explicitly set |
| 134 | + :code:`logging.getLogger("google").propagate = True` in your code. |
| 135 | +#. You can mix the different logging configurations above for different Google modules. For example, you may want use a code-based logging configuration for |
| 136 | + one library, but decide you need to also set up environment-based logging configuration for another library. |
| 137 | + |
| 138 | + #. If you attempt to use both code-based and environment-based configuration for the same module, the environment-based configuration will be ineffectual |
| 139 | + if the code -based configuration gets applied first. |
| 140 | + |
| 141 | +#. The Google-specific logging configurations (default handlers for environment-based configuration; not propagating logging events to the root logger) get |
| 142 | + executed the first time *any* client library is instantiated in your application, and only if the affected loggers have not been previously configured. |
| 143 | + (This is the reason for 2.i. above.) |
0 commit comments