projectaria-commons 0.1.0__py3-none-any.whl

projectaria_commons/__init__.py

@@ -0,0 +1,28 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# 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.
+
+# pyre-strict
+
+from projectaria_commons.commons.config import Config
+from projectaria_commons.commons.http_helper import HttpHelper, retry
+from projectaria_commons.commons.request_helper import RequestHelper
+from projectaria_commons.commons.types import GraphQLError
+
+__all__ = [
+    "Config",
+    "HttpHelper",
+    "retry",
+    "RequestHelper",
+    "GraphQLError",
+]

projectaria_commons/commons/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# 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.
+
+# pyre-strict

projectaria_commons/commons/config.py

@@ -0,0 +1,231 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# 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.
+
+# pyre-strict
+
+from __future__ import annotations
+
+import logging
+from configparser import ConfigParser
+from datetime import datetime
+from pathlib import Path
+from typing import Union
+
+from projectaria_commons.commons.constants import (
+    CONFIG_FILE as _DEFAULT_CONFIG_FILE,
+    ConfigBoundKey,
+    ConfigKey,
+    ConfigSection,
+)
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class Config(ConfigParser):
+    """
+    Simple class to access the config object.
+
+    Uses a singleton pattern so one instance is shared across all modules.
+    Leverages ConfigParser to parse the config file.
+    If the config file does not exist, it is created with default values.
+    Users can overwrite values by editing the config file directly.
+
+    Subclasses can override ``config_file``, ``DEFAULT_CONFIG``, and
+    ``CONFIG_BOUNDS`` to customise the configuration for their application.
+    Each subclass maintains its own singleton via ``_config``.
+    """
+
+    _config: ConfigParser | None = None
+
+    _is_verbose: bool = False
+
+    # Process-wide logging state, stored on the base Config (not per subclass) so
+    # every Config flavor shares a single log file per application session: PAL
+    # uses this base Config directly, while the MPS CLI has its own subclass. The
+    # first class to configure logging wins; later calls reuse this handler and
+    # path.
+    _log_path: Path | None = None
+    _file_handler: logging.FileHandler | None = None
+
+    config_file: Path = _DEFAULT_CONFIG_FILE
+
+    DEFAULT_CONFIG: dict[str, dict[str, str]] = {
+        ConfigSection.DEFAULT: {
+            ConfigKey.LOG_DIR: "/tmp/logs/projectaria/ # Path to log directory",
+        },
+        ConfigSection.GRAPHQL: {
+            ConfigKey.BACKOFF: "1.5 # Backoff factor for retries",
+            ConfigKey.INTERVAL_SEC: "4 # Interval between retries in seconds",
+            ConfigKey.RETRIES: "3 # Number of times to retry a failed request",
+        },
+    }
+
+    CONFIG_BOUNDS: dict[str, dict[str, dict[str, Union[str, int, float]]]] = {
+        ConfigSection.GRAPHQL: {
+            ConfigKey.BACKOFF: {
+                ConfigBoundKey.TYPE: ConfigBoundKey.TYPE_FLOAT,
+                ConfigBoundKey.MIN_VALUE: 1.0,
+                ConfigBoundKey.MAX_VALUE: 10.0,
+            },
+            ConfigKey.INTERVAL_SEC: {
+                ConfigBoundKey.TYPE: ConfigBoundKey.TYPE_INT,
+                ConfigBoundKey.MIN_VALUE: 1,
+                ConfigBoundKey.MAX_VALUE: 10,
+            },
+            ConfigKey.RETRIES: {
+                ConfigBoundKey.TYPE: ConfigBoundKey.TYPE_INT,
+                ConfigBoundKey.MIN_VALUE: 0,
+                ConfigBoundKey.MAX_VALUE: 10,
+            },
+        },
+    }
+
+    @classmethod
+    def _apply_config_limits(cls) -> None:
+        """
+        Apply min/max value constraints from CONFIG_BOUNDS to the loaded configuration.
+        Called after all config values are loaded/merged.
+        """
+        if cls._config is None:
+            raise ValueError("Config was not loaded yet")
+
+        for section, keys in cls.CONFIG_BOUNDS.items():
+            for key, bounds in keys.items():
+                if cls._config.has_option(section, key):
+                    value_type = bounds.get(
+                        ConfigBoundKey.TYPE, ConfigBoundKey.TYPE_INT
+                    )
+                    min_value = bounds.get(ConfigBoundKey.MIN_VALUE)
+                    max_value = bounds.get(ConfigBoundKey.MAX_VALUE)
+
+                    if value_type == ConfigBoundKey.TYPE_FLOAT:
+                        current_value = cls._config.getfloat(section, key)
+                    else:
+                        current_value = cls._config.getint(section, key)
+
+                    clamped_value = current_value
+                    if min_value is not None and current_value < min_value:
+                        logger.warning(
+                            f"Config {section}.{key}={current_value} is below minimum of {min_value}. "
+                            f"Using {min_value}."
+                        )
+                        clamped_value = min_value
+                    elif max_value is not None and current_value > max_value:
+                        logger.warning(
+                            f"Config {section}.{key}={current_value} exceeds maximum of {max_value}. "
+                            f"Using {max_value}."
+                        )
+                        clamped_value = max_value
+
+                    if clamped_value != current_value:
+                        cls._config.set(section, key, str(clamped_value))
+
+    @classmethod
+    def _configure_logging(cls) -> None:
+        """
+        Set up file logging once per process (idempotent).
+
+        The first Config (sub)class to configure logging wins: it creates a
+        single timestamped log file and installs it on the root logger. Any later
+        call — a re-entry, or a sibling flavor (e.g. the MPS CLI's Config subclass
+        alongside PAL's use of this base Config) — reuses that same file instead
+        of creating another one and stealing the root handler via
+        ``basicConfig(force=True)``. This is what keeps one application session to
+        one log file.
+        """
+
+        if Config._file_handler is not None:
+            return
+
+        config = cls.get()
+        default_log_dir = cls.DEFAULT_CONFIG.get(ConfigSection.DEFAULT, {}).get(
+            ConfigKey.LOG_DIR, "/tmp/logs/projectaria/"
+        )
+        default_log_dir = default_log_dir.split("#")[0].strip()
+        log_dir = Path(
+            config.get(
+                ConfigSection.DEFAULT, ConfigKey.LOG_DIR, fallback=default_log_dir
+            )
+        )
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_file: Path = log_dir / f"{datetime.now().strftime('%Y-%m-%d-%H-%M-%S')}.log"
+        file_handler = logging.FileHandler(log_file)
+        handlers: list[logging.Handler] = [file_handler]
+        if cls._is_verbose:
+            handlers.append(logging.StreamHandler())
+        logging.basicConfig(
+            handlers=handlers,
+            level=logging.DEBUG,
+            format="%(asctime)s [%(process)d] [%(levelname)s] [%(filename)s:%(lineno)d] - %(message)s",
+            force=True,
+        )
+
+        Config._file_handler = file_handler
+        Config._log_path = log_file
+        logger.info(f"log file : {log_file}")
+
+    @classmethod
+    def get(cls) -> ConfigParser:
+        """
+        Get the config object.
+
+        Loads the config from the path specified by ``cls.config_file``.
+        If it doesn't exist, creates it with default values.
+        If the config exists but is missing keys, adds the missing keys
+        from DEFAULT_CONFIG.
+        """
+        if cls._config is None:
+            cls._config = ConfigParser(inline_comment_prefixes="#")
+
+            if not cls.config_file.is_file():
+                c = ConfigParser()
+                c.read_dict(cls.DEFAULT_CONFIG)
+                cls.config_file.parent.mkdir(parents=True, exist_ok=True)
+                with cls.config_file.open("w") as fd:
+                    c.write(fd)
+
+            cls._config.read(cls.config_file)
+            cls._configure_logging()
+
+            for section, keys in cls.DEFAULT_CONFIG.items():
+                if section != ConfigSection.DEFAULT and not cls._config.has_section(
+                    section
+                ):
+                    cls._config.add_section(section)
+                    logger.debug(
+                        f"Loaded missing config section from defaults: {section}"
+                    )
+
+                for key, value in keys.items():
+                    if not cls._config.has_option(section, key):
+                        actual_value = value.split("#")[0].strip()
+                        cls._config.set(section, key, actual_value)
+                        logger.debug(
+                            f"Loaded missing config key from defaults: {section}.{key} = {actual_value}"
+                        )
+
+            cls._apply_config_limits()
+
+            logger.info(f"Loaded config file {cls.config_file}")
+        return cls._config
+
+    @classmethod
+    def set_is_verbose(cls, is_verbose: bool) -> None:
+        cls._is_verbose = is_verbose
+
+    @classmethod
+    def get_log_path(cls) -> Path:
+        if Config._log_path is None:
+            raise ValueError("Config was not loaded yet")
+        return Config._log_path

projectaria_commons/commons/constants.py

@@ -0,0 +1,63 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# 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.
+
+# pyre-strict
+
+from pathlib import Path
+from typing import Final
+
+if Path.home() == Path("/"):
+    from tempfile import TemporaryDirectory
+
+    local_temp_dir: TemporaryDirectory = TemporaryDirectory()  # pyre-ignore [24]
+    HOME_DIR: Final[Path] = Path(local_temp_dir.name)
+else:
+    HOME_DIR: Final[Path] = Path.home()
+
+CONFIG_DIR: Final[Path] = HOME_DIR.joinpath(".projectaria")
+CONFIG_FILE: Final[Path] = CONFIG_DIR.joinpath("projectaria.ini")
+
+
+class ConfigSection:
+    DEFAULT: str = "DEFAULT"
+    GRAPHQL: str = "GRAPHQL"
+
+
+class ConfigKey:
+    LOG_DIR: str = "LOG_DIR"
+    BACKOFF: str = "BACKOFF"
+    INTERVAL_SEC: str = "INTERVAL_SEC"
+    RETRIES: str = "RETRIES"
+
+
+class ConfigBoundKey:
+    TYPE: Final[str] = "TYPE"
+    TYPE_FLOAT: Final[str] = "FLOAT"
+    TYPE_INT: Final[str] = "INT"
+    MIN_VALUE: Final[str] = "MIN"
+    MAX_VALUE: Final[str] = "MAX"
+
+
+# GraphQL keys
+KEY_ALIAS: Final[str] = "alias"
+KEY_AUTH_TOKEN: Final[str] = "auth_token"
+KEY_DATA: Final[str] = "data"
+KEY_DOC_ID: Final[str] = "doc_id"
+KEY_FRLM_ACCOUNT_ID: Final[str] = "frlm_account_id"
+KEY_HORIZON_PROFILES: Final[str] = "horizon_profiles"
+KEY_ID: Final[str] = "id"
+KEY_ME: Final[str] = "me"
+KEY_NAME: Final[str] = "name"
+KEY_USER: Final[str] = "user"
+KEY_VARIABLES: Final[str] = "variables"

projectaria_commons/commons/http_helper.py

@@ -0,0 +1,254 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# 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.
+
+# pyre-strict
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from functools import wraps
+from typing import Any, Callable
+
+import aiohttp
+from aiohttp import ClientSession, ClientTimeout
+from aiohttp.client_exceptions import ContentTypeError
+from projectaria_commons.commons.constants import KEY_AUTH_TOKEN
+
+logger = logging.getLogger(__name__)
+
+_AUTHORIZATION: str = "Authorization"
+
+_REDACTED: str = "***REDACTED***"
+_SENSITIVE_KEY_SUBSTRINGS: tuple[str, ...] = (
+    "password",
+    "passphrase",
+    "secret",
+    "token",
+    "auth_code",
+    "device_code",
+    "contact_point",
+    "email",
+    "credential",
+)
+
+
+def _redact_sensitive(value: Any) -> Any:
+    """
+    Recursively redact credentials/PII from request data before logging.
+
+    Any dict key whose (case-insensitive) name contains a sensitive substring
+    has its value replaced with a placeholder; nested dicts/lists (e.g. GraphQL
+    ``variables``) are walked so secrets can't hide one level down. Returns a new
+    structure; the original request payload is left unmodified.
+
+    Args:
+        value: The request data to redact.
+
+    Returns:
+        The redacted request data.
+    """
+    if isinstance(value, dict):
+        return {
+            k: (
+                _REDACTED
+                if isinstance(k, str)
+                and any(s in k.lower() for s in _SENSITIVE_KEY_SUBSTRINGS)
+                else _redact_sensitive(v)
+            )
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [_redact_sensitive(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(_redact_sensitive(item) for item in value)
+    return value
+
+
+def retry(
+    exceptions: list[type[Exception]] | None = None,
+    error_codes: list[int] | None = None,
+    retries: int | Callable[[], int] = 3,
+    interval: float | Callable[[], float] = 1,
+    backoff: float | Callable[[], float] = 1.5,
+):
+    """
+    Decorator for retrying async functions with exponential backoff.
+
+    ClientResponseError from aiohttp is treated specially and will only be retried
+    if the status code is in `error_codes`.
+    At least one of `exceptions` or `error_codes` must be provided.
+
+    Args:
+        exceptions: List of exceptions to catch
+        error_codes: List of HTTP status codes to catch
+        retries: Number of times to retry
+        interval: Interval between retries in seconds
+        backoff: Backoff multiplier
+
+    Returns:
+        Decorated function
+
+    Raises:
+        ValueError: If no exceptions or error codes are provided
+    """
+    if not exceptions and not error_codes:
+        raise ValueError(
+            "At least one of `exceptions` or `error_codes` must be provided."
+        )
+    exceptions = list(exceptions or [])
+    if error_codes and aiohttp.ClientResponseError not in exceptions:
+        exceptions.append(aiohttp.ClientResponseError)
+
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            _retries = retries() if callable(retries) else retries
+            _interval = interval() if callable(interval) else interval
+            _backoff = backoff() if callable(backoff) else backoff
+            attempts = 0
+            while True:
+                try:
+                    return await func(*args, **kwargs)
+                except tuple(exceptions) as e:
+                    if (
+                        isinstance(e, aiohttp.ClientResponseError)
+                        and error_codes
+                        and e.status not in error_codes
+                    ):
+                        logger.exception(e)
+                        raise e from e
+                    if attempts >= _retries:
+                        logger.error(f"Maximum number of retries reached ({_retries}).")
+                        raise e from e
+                    logger.warning(f"Exception encountered: {e}")
+                    sleep_time = _interval * (_backoff ** (attempts))
+                    attempts += 1
+                    logger.warning(
+                        f"Retrying attempt {attempts}/{_retries} in {sleep_time} seconds..."
+                    )
+                    await asyncio.sleep(sleep_time)
+
+        return wrapper
+
+    return decorator
+
+
+class HttpHelper:
+    """
+    Helper class for making async HTTP requests.
+    Provides session management and auth token injection.
+    """
+
+    def __init__(self):
+        logger.debug("Creating http session")
+        timeout: ClientTimeout = ClientTimeout(total=None)
+        self._http_session: ClientSession = ClientSession(
+            raise_for_status=True,
+            timeout=timeout,
+            headers={"Accept-Encoding": "gzip, deflate"},
+        )
+
+    @property
+    def session(self) -> ClientSession:
+        return self._http_session
+
+    async def __aenter__(self) -> "HttpHelper":
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+        """
+        Close the HTTP session on context exit.
+
+        Args:
+            exc_type: Exception type
+            exc_value: Exception value
+            traceback: Traceback object
+        """
+        await self.close()
+
+    async def close(self):
+        """Close the HTTP session."""
+        logger.debug("Closing http session")
+        await self._http_session.close()
+
+    def set_auth_token(self, auth_token: str) -> None:
+        """
+        Set the authentication token header for the HTTP session.
+
+        Args:
+            auth_token: The authentication token to set.
+        """
+        logger.debug("Setting http session auth header")
+        self._http_session.headers[_AUTHORIZATION] = f"OAuth {auth_token}"
+
+    async def post(self, **kwargs) -> dict[str, Any]:
+        """
+        Make a POST request. Inserts the authorization header if an auth_token is provided.
+
+        Args:
+            **kwargs: Keyword arguments to pass to the aiohttp request method.
+
+        Returns:
+            The response from the request.
+
+        Raises:
+            ClientResponseError: If the request fails.
+        """
+        return await self._run_method("post", **kwargs)
+
+    async def get(self, **kwargs) -> dict[str, Any]:
+        """
+        Make a GET request. Inserts the authorization header if an auth_token is provided.
+
+        Args:
+            **kwargs: Keyword arguments to pass to the aiohttp request method.
+
+        Returns:
+            The response from the request.
+
+        Raises:
+            ClientResponseError: If the request fails.
+        """
+        return await self._run_method("get", **kwargs)
+
+    async def _run_method(self, method: str, **kwargs) -> dict[str, Any]:
+        """
+        Helper to get/post to an endpoint and return the JSON response.
+        Inserts the authorization header if an auth_token is provided.
+
+        Args:
+            method: The HTTP method to use.
+            **kwargs: Keyword arguments to pass to the aiohttp request method.
+
+        Returns:
+            The response from the request.
+
+        Raises:
+            ClientResponseError: If the request fails.
+        """
+        headers = kwargs.pop("headers", {})
+        if auth_token := kwargs.pop(KEY_AUTH_TOKEN, None):
+            headers[_AUTHORIZATION] = f"OAuth {auth_token}"
+        logger.debug(f"_run_method args: {_redact_sensitive(kwargs)}")
+        m = getattr(self._http_session, method)
+        async with m(headers=headers, **kwargs) as r:
+            try:
+                return await r.json()
+            except ContentTypeError:
+                return json.loads(await r.text())
+            except Exception as e:
+                logger.exception(e)
+                raise e

projectaria_commons/commons/request_helper.py

@@ -0,0 +1,141 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# 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.
+
+# pyre-strict
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from http import HTTPStatus
+from typing import Any, Final
+
+from projectaria_commons.commons.config import Config
+from projectaria_commons.commons.constants import (
+    ConfigKey,
+    ConfigSection,
+    KEY_ALIAS,
+    KEY_DATA,
+    KEY_DOC_ID,
+    KEY_FRLM_ACCOUNT_ID,
+    KEY_HORIZON_PROFILES,
+    KEY_ID,
+    KEY_ME,
+    KEY_NAME,
+    KEY_USER,
+    KEY_VARIABLES,
+)
+from projectaria_commons.commons.http_helper import HttpHelper, retry
+from projectaria_commons.commons.types import GraphQLError
+
+logger = logging.getLogger(__name__)
+
+_DOC_ID_QUERY_ME: Final[int] = 26147971811524376
+_DOC_ID_QUERY_USER_NAME: Final[int] = 25777025568628651
+
+_GQL_URL: Final[str] = os.environ.get("GQL_URL", "https://graph.oculus.com/graphql")
+
+_HTTP_RETRY_CODES: Final[list[int]] = [
+    HTTPStatus.BAD_GATEWAY,
+    HTTPStatus.INTERNAL_SERVER_ERROR,
+    HTTPStatus.REQUEST_TIMEOUT,
+    HTTPStatus.SERVICE_UNAVAILABLE,
+    HTTPStatus.TOO_MANY_REQUESTS,
+]
+
+
+class RequestHelper:
+    """Generic GraphQL query helper built on HttpHelper."""
+
+    def __init__(self, http_helper: HttpHelper):
+        self._http_helper: HttpHelper = http_helper
+
+    @property
+    def http_helper(self) -> HttpHelper:
+        return self._http_helper
+
+    async def query_me(self, auth_token: str | None = None) -> str:
+        """
+        Validate the auth token and return the user's display name.
+
+        Queries the user's alias and FRLM account ID, then resolves the
+        display name from the Horizon profile.
+
+        Args:
+            auth_token: The auth token to use for the query. If None, the
+            http session's auth token will be used.
+
+        Returns:
+            The user's display name.
+
+        Raises:
+            GraphQLError: If the query fails.
+        """
+        logger.debug("Querying me")
+        response = await self.query_graph(
+            doc_id=_DOC_ID_QUERY_ME, variables={}, auth_token=auth_token
+        )
+
+        user_name: str = response[KEY_DATA][KEY_ME][KEY_ALIAS]
+        frlm_account: str = response[KEY_DATA][KEY_ME][KEY_FRLM_ACCOUNT_ID]
+
+        response = await self.query_graph(
+            doc_id=_DOC_ID_QUERY_USER_NAME,
+            variables={KEY_ID: frlm_account},
+            auth_token=auth_token,
+        )
+
+        if response[KEY_DATA][KEY_USER]:
+            user_name = response[KEY_DATA][KEY_USER][KEY_HORIZON_PROFILES][0][KEY_NAME]
+        return user_name
+
+    @retry(
+        error_codes=_HTTP_RETRY_CODES,
+        exceptions=[GraphQLError],
+        retries=lambda: Config.get().getint(ConfigSection.GRAPHQL, ConfigKey.RETRIES),
+        interval=lambda: Config.get().getint(
+            ConfigSection.GRAPHQL, ConfigKey.INTERVAL_SEC
+        ),
+        backoff=lambda: Config.get().getfloat(ConfigSection.GRAPHQL, ConfigKey.BACKOFF),
+    )
+    async def query_graph(
+        self, doc_id: int, variables: dict[str, Any] | None = None, **kwargs
+    ) -> dict[str, Any]:
+        """
+        Execute a GraphQL query.
+
+        Args:
+            doc_id: GraphQL document ID.
+            variables: Variables to be passed to the query.
+
+        Returns:
+            The response from the GraphQL server.
+
+        Raises:
+            GraphQLError: If the query fails.
+        """
+        response = await self._http_helper.post(
+            url=_GQL_URL,
+            json={
+                KEY_DOC_ID: doc_id,
+                KEY_VARIABLES: variables,
+            },
+            **kwargs,
+        )
+        logger.debug(f"GraphQL response {json.dumps(response, indent=2)}")
+        if "errors" in response:
+            logger.error(f"GraphQL errors: {response['errors']}")
+            raise GraphQLError(response["errors"])
+        return dict(response)

projectaria_commons/commons/types.py

@@ -0,0 +1,21 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# 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.
+
+# pyre-strict
+
+
+class GraphQLError(Exception):
+    """Raised when a GraphQL query returns errors."""
+
+    pass

projectaria_commons-0.1.0.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: projectaria-commons
+Version: 0.1.0
+Summary: Project Aria Common Utilities Library
+Home-page: https://www.projectaria.com
+Author: Meta Reality Labs Research
+License: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Shared common utilities for Project Aria tools.
+
+Provides a small, dependency-light foundation for configuration management and
+async HTTP / GraphQL access, shared by the Project Aria login library, the MPS
+CLI, and Aria Studio.
+
+For more information, visit [Project Aria](https://www.projectaria.com).

projectaria_commons-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+projectaria_commons/__init__.py,sha256=GYuj1ttWkLVqa0Qyiug9wj6NclmNZ3RQvF7LckK2Vhk,968
+projectaria_commons/commons/__init__.py,sha256=6xZPTzPtzy-lDojjgRGorJj9GQd2pzDdlt3gzc8rgAU,614
+projectaria_commons/commons/config.py,sha256=bdWz5acdFcmRJ9ZNdnAZn2okYbVL6SnObJao4YTV8_Y,8996
+projectaria_commons/commons/constants.py,sha256=E5NCPOrH6zQDV4uvjewR8sCZaw3xWM2DCtlXqHNr0IE,1880
+projectaria_commons/commons/http_helper.py,sha256=JuFIk8-yeGv3I55KDBpFo6X00LUHPY0Upf8CWrWP1wo,8292
+projectaria_commons/commons/request_helper.py,sha256=_yDo74DLWllcy1QYZoWLUNWuZbdp33UHnPljgDv1A7c,4367
+projectaria_commons/commons/types.py,sha256=1EjHBHXapPjvJVBVEkP7FWhTuzcEtMILjJpECZtt9-Y,711
+projectaria_commons-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+projectaria_commons-0.1.0.dist-info/METADATA,sha256=XANGGVvtngutlhrCOCPVF7-T-eB7g0Bk9lU2krlEEMU,817
+projectaria_commons-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+projectaria_commons-0.1.0.dist-info/top_level.txt,sha256=xr0uto86Qrk03aSEEWNLWWCWJ8qhyaIf8zYKb6XAEas,20
+projectaria_commons-0.1.0.dist-info/RECORD,,

projectaria_commons-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

projectaria_commons-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

projectaria_commons-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+projectaria_commons