airbyte.constants

  1# Copyright (c) 2024 Airbyte, Inc., all rights reserved.
  2"""Constants shared across the PyAirbyte codebase."""
  3
  4from __future__ import annotations
  5
  6import os
  7from pathlib import Path
  8
  9
 10DEBUG_MODE = False  # Set to True to enable additional debug logging.
 11
 12
 13AB_EXTRACTED_AT_COLUMN = "_airbyte_extracted_at"
 14"""A column that stores the timestamp when the record was extracted."""
 15
 16AB_META_COLUMN = "_airbyte_meta"
 17"""A column that stores metadata about the record."""
 18
 19AB_RAW_ID_COLUMN = "_airbyte_raw_id"
 20"""A column that stores a unique identifier for each row in the source data.
 21
 22Note: The interpretation of this column is slightly different from in Airbyte Dv2 destinations.
 23In Airbyte Dv2 destinations, this column points to a row in a separate 'raw' table. In PyAirbyte,
 24this column is simply used as a unique identifier for each record as it is received.
 25
 26PyAirbyte uses ULIDs for this column, which are identifiers that can be sorted by time
 27received. This allows us to determine the debug the order of records as they are received, even if
 28the source provides records that are tied or received out of order from the perspective of their
 29`emitted_at` (`_airbyte_extracted_at`) timestamps.
 30"""
 31
 32AB_INTERNAL_COLUMNS = {
 33    AB_RAW_ID_COLUMN,
 34    AB_EXTRACTED_AT_COLUMN,
 35    AB_META_COLUMN,
 36}
 37"""A set of internal columns that are reserved for PyAirbyte's internal use."""
 38
 39DEFAULT_PROJECT_DIR: Path = (
 40    Path(os.getenv("AIRBYTE_PROJECT_DIR", "") or Path.cwd()).expanduser().absolute()
 41)
 42"""Default project directory.
 43
 44Can be overridden by setting the `AIRBYTE_PROJECT_DIR` environment variable.
 45
 46If not set, defaults to the current working directory.
 47
 48This serves as the parent directory for both cache and install directories when not explicitly
 49configured.
 50"""
 51
 52DEFAULT_CACHE_ROOT: Path = (
 53    (Path(os.getenv("AIRBYTE_CACHE_ROOT", "") or (DEFAULT_PROJECT_DIR / ".cache")))
 54    .expanduser()
 55    .absolute()
 56)
 57"""Default cache root is `.cache` in the current working directory.
 58
 59The default location can be overridden by setting the `AIRBYTE_CACHE_ROOT` environment variable.
 60
 61Overriding this can be useful if you always want to store cache files in a specific location.
 62For example, in ephemeral environments like Google Colab, you might want to store cache files in
 63your mounted Google Drive by setting this to a path like `/content/drive/MyDrive/Airbyte/cache`.
 64"""
 65
 66DEFAULT_CACHE_SCHEMA_NAME = "airbyte_raw"
 67"""The default schema name to use for caches.
 68
 69Specific caches may override this value with a different schema name.
 70"""
 71
 72DEFAULT_INSTALL_DIR: Path = (
 73    Path(os.getenv("AIRBYTE_INSTALL_DIR", "") or DEFAULT_PROJECT_DIR).expanduser().absolute()
 74)
 75"""Default install directory for connectors.
 76
 77If not set, defaults to `DEFAULT_PROJECT_DIR` (`AIRBYTE_PROJECT_DIR` env var) or the current
 78working directory if neither is set.
 79"""
 80
 81
 82DEFAULT_GOOGLE_DRIVE_MOUNT_PATH = "/content/drive"
 83"""Default path to mount Google Drive in Google Colab environments."""
 84
 85DEFAULT_ARROW_MAX_CHUNK_SIZE = 100_000
 86"""The default number of records to include in each batch of an Arrow dataset."""
 87
 88
 89def _str_to_bool(value: str) -> bool:
 90    """Convert a string value of an environment values to a boolean value."""
 91    return bool(value) and value.lower() not in {"", "0", "false", "f", "no", "n", "off"}
 92
 93
 94TEMP_DIR_OVERRIDE: Path | None = (
 95    Path(os.environ["AIRBYTE_TEMP_DIR"]) if os.getenv("AIRBYTE_TEMP_DIR") else None
 96)
 97"""The directory to use for temporary files.
 98
 99This value is read from the `AIRBYTE_TEMP_DIR` environment variable. If the variable is not set,
100Tempfile will use the system's default temporary directory.
101
102This can be useful if you want to store temporary files in a specific location (or) when you
103need your temporary files to exist in user level directories, and not in system level
104directories for permissions reasons.
105"""
106
107TEMP_FILE_CLEANUP = _str_to_bool(
108    os.getenv(
109        key="AIRBYTE_TEMP_FILE_CLEANUP",
110        default="true",
111    )
112)
113"""Whether to clean up temporary files after use.
114
115This value is read from the `AIRBYTE_TEMP_FILE_CLEANUP` environment variable. If the variable is
116not set, the default value is `True`.
117"""
118
119AIRBYTE_OFFLINE_MODE = _str_to_bool(
120    os.getenv(
121        key="AIRBYTE_OFFLINE_MODE",
122        default="false",
123    )
124)
125"""Enable or disable offline mode.
126
127When offline mode is enabled, PyAirbyte will attempt to fetch metadata for connectors from the
128Airbyte registry but will not raise an error if the registry is unavailable. This can be useful in
129environments without internet access or with air-gapped networks.
130
131Offline mode also disables telemetry, similar to a `DO_NOT_TRACK` setting, ensuring no usage data
132is sent from your environment. You may also specify a custom registry URL via the`_REGISTRY_ENV_VAR`
133environment variable if you prefer to use a different registry source for metadata.
134
135This setting helps you make informed choices about data privacy and operation in restricted and
136air-gapped environments.
137"""
138
139AIRBYTE_PRINT_FULL_ERROR_LOGS: bool = _str_to_bool(
140    os.getenv(
141        key="AIRBYTE_PRINT_FULL_ERROR_LOGS",
142        default=os.getenv("CI", "false"),
143    )
144)
145"""Whether to print full error logs when an error occurs.
146This setting helps in debugging by providing detailed logs when errors occur. This is especially
147helpful in ephemeral environments like CI/CD pipelines where log files may not be persisted after
148the pipeline run.
149
150If not set, the default value is `False` for non-CI environments.
151If running in a CI environment ("CI" env var is set), then the default value is `True`.
152"""
153
154NO_UV: bool = os.getenv("AIRBYTE_NO_UV", "").lower() not in {"1", "true", "yes"}
155"""Whether to use uv for Python package management.
156
157This value is determined by the `AIRBYTE_NO_UV` environment variable. When `AIRBYTE_NO_UV`
158is set to "1", "true", or "yes", uv will be disabled and pip will be used instead.
159
160If the variable is not set or set to any other value, uv will be used by default.
161This provides a safe fallback mechanism for environments where uv is not available
162or causes issues.
163"""
164
165SECRETS_HYDRATION_PREFIX = "secret_reference::"
166"""Use this prefix to indicate a secret reference in configuration.
167
168For example, this snippet will populate the `personal_access_token` field with the value of the
169secret named `GITHUB_PERSONAL_ACCESS_TOKEN`, for instance from an environment variable.
170
171```json
172{
173  "credentials": {
174    "personal_access_token": "secret_reference::GITHUB_PERSONAL_ACCESS_TOKEN"
175  }
176}
177```
178
179For more information, see the `airbyte.secrets` module documentation.
180"""
181
182# Cloud Constants
183
184CLOUD_CLIENT_ID_ENV_VAR: str = "AIRBYTE_CLOUD_CLIENT_ID"
185"""The environment variable name for the Airbyte Cloud client ID."""
186
187CLOUD_CLIENT_SECRET_ENV_VAR: str = "AIRBYTE_CLOUD_CLIENT_SECRET"
188"""The environment variable name for the Airbyte Cloud client secret."""
189
190CLOUD_API_ROOT_ENV_VAR: str = "AIRBYTE_CLOUD_API_URL"
191"""The environment variable name for the Airbyte Cloud API URL."""
192
193CLOUD_WORKSPACE_ID_ENV_VAR: str = "AIRBYTE_CLOUD_WORKSPACE_ID"
194"""The environment variable name for the Airbyte Cloud workspace ID."""
195
196CLOUD_API_ROOT: str = "https://api.airbyte.com/v1"
197"""The Airbyte Cloud API root URL.
198
199This is the root URL for the Airbyte Cloud API. It is used to interact with the Airbyte Cloud API
200and is the default API root for the `CloudWorkspace` class.
201- https://reference.airbyte.com/reference/getting-started
202"""
203
204CLOUD_CONFIG_API_ROOT: str = "https://cloud.airbyte.com/api/v1"
205"""Internal-Use API Root, aka Airbyte "Config API".
206
207Documentation:
208- https://docs.airbyte.com/api-documentation#configuration-api-deprecated
209- https://github.com/airbytehq/airbyte-platform-internal/blob/master/oss/airbyte-api/server-api/src/main/openapi/config.yaml
210"""