diff --git a/pittgoogle/auth.py b/pittgoogle/auth.py index eab661b..5556d26 100644 --- a/pittgoogle/auth.py +++ b/pittgoogle/auth.py @@ -1,41 +1,12 @@ # -*- coding: UTF-8 -*- """Classes to manage authentication with Google Cloud. -.. contents:: - :local: - :depth: 2 - .. note:: To authenticate, you must have completed one of the setup options described in - :doc:`/main/one-time-setup/authentication`. The recommended workflow is to use a + :doc:`/main/one-time-setup/authentication`. The recommendation is to use a :ref:`service account ` and :ref:`set environment variables `. In that case, you will not need to call this module directly. - -Usage Example --------------- - -The basic call is: - -.. code-block:: python - - import pittgoogle - - myauth = pittgoogle.auth.Auth() - -This will load authentication settings from your :ref:`environment variables `. -You can override this behavior with keyword arguments. This does not automatically load the -credentials. To do that, request them explicitly: - -.. code-block:: python - - myauth.credentials - -It will first look for a service account key file, then fallback to OAuth2. - -API ----- - """ import logging import os @@ -56,28 +27,51 @@ @define class Auth: - """Credentials for authentication to a Google Cloud project. + """Credentials for authenticating with a Google Cloud project. + + This class provides methods to obtain and load credentials from either a service account + key file or an OAuth2 session. + To authenticate, you must have completed one of the setup options described in the + :doc:`/main/one-time-setup/authentication`.:doc:`/main/one-time-setup/authentication` + + Attributes + ---------- + GOOGLE_CLOUD_PROJECT : str + The project ID of the Google Cloud project to connect to. This can be set as an + environment variable. + + GOOGLE_APPLICATION_CREDENTIALS : str + The path to a keyfile containing service account credentials. Either this or the + `OAUTH_CLIENT_*` settings are required for successful authentication. + + OAUTH_CLIENT_ID : str + The client ID for an OAuth2 connection. Either this and `OAUTH_CLIENT_SECRET`, or + the `GOOGLE_APPLICATION_CREDENTIALS` setting, are required for successful + authentication. + + OAUTH_CLIENT_SECRET : str + The client secret for an OAuth2 connection. Either this and `OAUTH_CLIENT_ID`, or + the `GOOGLE_APPLICATION_CREDENTIALS` setting, are required for successful + authentication. + + Usage + ----- + + The basic call is: + + .. code-block:: python - Missing parameters will be obtained from an environment variable of the same name, - if it exists. + myauth = pittgoogle.Auth() - :param GOOGLE_CLOUD_PROJECT: - Project ID of the Google Cloud project to connect to. + This will load authentication settings from your :ref:`environment variables `. + You can override this behavior with keyword arguments. This does not automatically load the + credentials. To do that, request them explicitly: - :param GOOGLE_APPLICATION_CREDENTIALS: - Path to a keyfile containing service account credentials. - Either this or both `OAUTH_CLIENT_*` settings are required for successful - authentication using `Auth`. + .. code-block:: python - :param OAUTH_CLIENT_ID: - Client ID for an OAuth2 connection. - Either this and `OAUTH_CLIENT_SECRET`, or the `GOOGLE_APPLICATION_CREDENTIALS` - setting, are required for successful authentication using `Auth`. + myauth.credentials - :param OAUTH_CLIENT_SECRET: - Client secret for an OAuth2 connection. - Either this and `OAUTH_CLIENT_ID`, or the `GOOGLE_APPLICATION_CREDENTIALS` setting, - are required for successful authentication using `Auth`. + It will first look for a service account key file, then fallback to OAuth2. """ GOOGLE_CLOUD_PROJECT = field(factory=lambda: os.getenv("GOOGLE_CLOUD_PROJECT", None)) diff --git a/pittgoogle/bigquery.py b/pittgoogle/bigquery.py index 4172269..6d46d6d 100644 --- a/pittgoogle/bigquery.py +++ b/pittgoogle/bigquery.py @@ -1,28 +1,11 @@ # -*- coding: UTF-8 -*- """Classes to facilitate connections to BigQuery datasets and tables. -.. contents:: - :local: - :depth: 2 - .. note:: This module relies on :mod:`pittgoogle.auth` to authenticate API calls. The examples given below assume the use of a :ref:`service account ` and :ref:`environment variables `. - -Usage Examples ---------------- - -.. code-block:: python - - import pittgoogle - - [TODO] - -API ----- - """ import logging from typing import Optional, Union diff --git a/pittgoogle/pubsub.py b/pittgoogle/pubsub.py index cafc466..065b499 100644 --- a/pittgoogle/pubsub.py +++ b/pittgoogle/pubsub.py @@ -262,28 +262,26 @@ def publish(self, alert: "Alert") -> int: @define class Subscription: - """Basic attributes of a Pub/Sub subscription and methods to manage it. + """Creates a Pub/Sub subscription and provides methods to manage it. + + Args: + name (str): + Name of the Pub/Sub subscription. + auth (pittgoogle.auth.Auth, optional): + Credentials for the Google Cloud project that owns this subscription. If not provided, it will be created + from environment variables. + topic (pittgoogle.pubsub.Topic, optional): + Topic this subscription should be attached to. Required only when the subscription needs to be created. + client (google.cloud.pubsub_v1.SubscriberClient, optional): + Pub/Sub client that will be used to access the subscription. This kwarg is useful if you want to + reuse a client. If None, a new client will be created. + schema_name (str): + Schema name of the alerts in the subscription. Passed to :class:`pittgoogle.Alert` for unpacking. + If not provided, some properties of the Alert may not be available. For a list of schema names, see + :meth:`pittgoogle.Schemas.names`. + + Usage: - Parameters - ----------- - name : `str` - Name of the Pub/Sub subscription. - auth : :class:`pittgoogle.auth.Auth`, optional - Credentials for the Google Cloud project that owns this subscription. If not provided, - it will be created from environment variables. - topic : :class:`pittgoogle.pubsub.Topic`, optional - Topic this subscription should be attached to. Required only when the subscription needs - to be created. - client : `pubsub_v1.SubscriberClient`, optional - Pub/Sub client that will be used to access the subscription. This kwarg is useful if you - want to reuse a client. If None, a new client will be created. - schema_name : `str` - One of "ztf", "ztf.lite", "elasticc.v0_9_1.alert", "elasticc.v0_9_1.brokerClassification". - Schema name of the alerts in the subscription. Passed to :class:`pittgoogle.pubsub.Alert` - for unpacking. If not provided, some properties of the `Alert` may not be available. - - Usage - ----- Create a subscription to the "ztf-loop" topic: .. code-block:: python @@ -432,32 +430,28 @@ def purge(self): class Consumer: """Consumer class to pull a Pub/Sub subscription and process messages. - Parameters - ----------- - subscription : `str` or :class:`pittgoogle.pubsub.Subscription` - Pub/Sub subscription to be pulled (it must already exist in Google Cloud). - msg_callback : `callable` - Function that will process a single message. It should accept a - :class:`pittgoogle.pubsub.Alert` and return a :class:`pittgoogle.pubsub.Response`. - batch_callback : `callable`, optional - Function that will process a batch of results. It should accept a list of the results - returned by the `msg_callback`. - batch_maxn : `int`, optional - Maximum number of messages in a batch. This has no effect if `batch_callback` is None. - batch_max_wait_between_messages : `int`, optional - Max number of seconds to wait between messages before before processing a batch. - This has no effect if `batch_callback` is None. - max_backlog : `int`, optional - Maximum number of pulled but unprocessed messages before pausing the pull. - max_workers : `int`, optional - Maximum number of workers for the `executor`. This has no effect if an `executor` is provided. - executor : `concurrent.futures.ThreadPoolExecutor`, optional - Executor to be used by the Google API to pull and process messages in the background. - - Usage - ----- - - Open a streaming pull. Recommended for long-runnining listeners. This will pull and process + Args: + subscription (str or Subscription): + Pub/Sub subscription to be pulled (it must already exist in Google Cloud). + msg_callback (callable): + Function that will process a single message. It should accept a Alert and return a Response. + batch_callback (callable, optional): + Function that will process a batch of results. It should accept a list of the results + returned by the msg_callback. + batch_maxn (int, optional): + Maximum number of messages in a batch. This has no effect if batch_callback is None. + batch_max_wait_between_messages (int, optional): + Max number of seconds to wait between messages before processing a batch. This has + no effect if batch_callback is None. + max_backlog (int, optional): + Maximum number of pulled but unprocessed messages before pausing the pull. + max_workers (int, optional): + Maximum number of workers for the executor. This has no effect if an executor is provided. + executor (concurrent.futures.ThreadPoolExecutor, optional): + Executor to be used by the Google API to pull and process messages in the background. + + Usage: + Open a streaming pull. Recommended for long-running listeners. This will pull and process messages in the background, indefinitely. User must supply a callback that processes a single message. It should accept a :class:`pittgoogle.pubsub.Alert` and return a :class:`pittgoogle.pubsub.Response`. Optionally, can provide a callback that processes a batch of messages. Note that messages are diff --git a/pittgoogle/types_.py b/pittgoogle/types_.py index f972cdb..a7da725 100644 --- a/pittgoogle/types_.py +++ b/pittgoogle/types_.py @@ -1,5 +1,5 @@ # -*- coding: UTF-8 -*- -"""Functions to support working with alerts and related data.""" +"""Classes defining new types.""" import importlib.resources import logging from typing import TYPE_CHECKING, Optional @@ -21,7 +21,7 @@ class Schema: """Class for an individual schema. This class is not intended to be used directly. - Use `pittgoogle.registry.Schemas` instead. + Use :class:`pittgoogle.Schemas` instead. """ name: str = field() diff --git a/pittgoogle/utils.py b/pittgoogle/utils.py index cd18980..b4e9467 100644 --- a/pittgoogle/utils.py +++ b/pittgoogle/utils.py @@ -1,5 +1,5 @@ # -*- coding: UTF-8 -*- -"""Functions to support working with alerts and related data.""" +"""Classes and functions to support working with alerts and related data.""" import json import logging from base64 import b64decode, b64encode