From bd3c2b7742e380de5c4efa2e4632af73332e9a20 Mon Sep 17 00:00:00 2001 From: Troy Raen Date: Tue, 2 Jul 2024 14:24:12 -0700 Subject: [PATCH] doc updates. prep release v0.3.9 --- CHANGELOG.md | 6 ++++++ docs/source/for-developers/add-new-schema.rst | 11 +++++++--- .../for-developers/get-alerts-for-testing.rst | 2 +- .../manage-dependencies-poetry.md | 21 ++++++++++++++++++- pittgoogle/auth.py | 2 ++ pittgoogle/pubsub.py | 6 ++++++ pittgoogle/registry.py | 12 +++++------ 7 files changed, 49 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 18cfddf..c90054c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) (none) +## \[v0.3.9\] - 2024-07-02 + +### Changed + +- Minor documentation updates. + ## \[v0.3.8\] - 2024-07-02 ### Changed diff --git a/docs/source/for-developers/add-new-schema.rst b/docs/source/for-developers/add-new-schema.rst index 8adaa48..e9cdcd2 100644 --- a/docs/source/for-developers/add-new-schema.rst +++ b/docs/source/for-developers/add-new-schema.rst @@ -1,6 +1,9 @@ Add a new schema to the registry ================================ +[FIXME] This information is old. It needs to be updated to describe to the SchemaHelpers and Schema +child classes. + This page contains instructions for adding a new schema to the registry so that it can be loaded using :meth:`pittgoogle.Schemas.get` and used to serialize and deserialize the alert bytes. @@ -24,12 +27,14 @@ Add a new section to the manifest following the template provided there. The fie those of a :class:`pittgoogle.schema.Schema`. The ``helper`` field must point to code that can find and load the new schema definition; more information below. +[FIXME] + Case 1: The schema definition is not needed in order to deserialize the alert bytes. This is true for -all Json, and the Avro streams which attach the schema in the data header. Set -``schemaless_alert_bytes='false'``. Leave ``helper`` and ``path`` as defaults. +all Json, and the Avro streams which attach the schema in the data header. You should be able to use the +default helper (see below). The rest of the cases assume the schema definition is required. This is true for "schemaless" Avro streams -which do not attach the schema to the data packet. Set ``schemaless_alert_bytes='true'`` +which do not attach the schema to the data packet. Case 2: You can write some code that will get the schema definition from an external repository. You will probably need to write your own ``helper`` method (more below). Follow ``lsst`` as an example. This is diff --git a/docs/source/for-developers/get-alerts-for-testing.rst b/docs/source/for-developers/get-alerts-for-testing.rst index 79ea885..666f97f 100644 --- a/docs/source/for-developers/get-alerts-for-testing.rst +++ b/docs/source/for-developers/get-alerts-for-testing.rst @@ -11,7 +11,7 @@ Setup Get alerts from a Pub/Sub subscription -------------------------------------- -If you need to create the subscription, follow the example in :class:`pittgoogle.Subscription`. +If you need to create the subscription, follow the example in :class:`pittgoogle.pubsub.Subscription`. Here are examples that get an alert from each of our "loop" streams: diff --git a/docs/source/for-developers/manage-dependencies-poetry.md b/docs/source/for-developers/manage-dependencies-poetry.md index caec3e4..3cfc2ed 100644 --- a/docs/source/for-developers/manage-dependencies-poetry.md +++ b/docs/source/for-developers/manage-dependencies-poetry.md @@ -1,6 +1,6 @@ # Manage dependencies with Poetry -This page contains instructions for managing the `pittgoogle` package dependencies using [Poetry](https://python-poetry.org/). +This page contains instructions for managing the `pittgoogle-client` package dependencies using [Poetry](https://python-poetry.org/). Poetry was implemented in this repo in [pull #7](https://github.com/mwvgroup/pittgoogle-client/pull/7). ## Setup your environment @@ -17,6 +17,19 @@ conda activate poetry-py311 pip install poetry ``` +If you come back to this later you may need to reactivate your environment. + +```bash +conda activate poetry-py311 +``` + +If you want to start over with a fresh environment, deactivate the environment and remove it. + +```bash +conda deactivate +conda remove --name poetry-py311 --all +``` + ## Install existing dependencies This repo already contains a poetry.lock file, so running `poetry install` will give you @@ -28,6 +41,12 @@ If you would rather start over completely, skip ahead to the next section. poetry install ``` +If you want to install the docs dependencies as well, use: + +```bash +poetry install --extras=docs +``` + ## Update Dependency Versions To upgrade to the latest versions compatible with the pyproject.toml file, you have two options below diff --git a/pittgoogle/auth.py b/pittgoogle/auth.py index 9d00b15..fd46799 100644 --- a/pittgoogle/auth.py +++ b/pittgoogle/auth.py @@ -67,6 +67,8 @@ class Auth: myauth.credentials It will first look for a service account key file, then fallback to OAuth2. + + ---- """ # Strings _below_ the field will make these also show up as individual properties in rendered docs. diff --git a/pittgoogle/pubsub.py b/pittgoogle/pubsub.py index 8c8e2fc..300815d 100644 --- a/pittgoogle/pubsub.py +++ b/pittgoogle/pubsub.py @@ -295,6 +295,8 @@ class Subscription: .. code-block:: python alerts = subscription.pull_batch(subscription, max_messages=4) # list of pittgoogle.Alert objects + + ---- """ name: str = attrs.field() @@ -485,6 +487,8 @@ def my_batch_callback(results): # open the stream in the background and process messages through the callbacks # this blocks indefinitely. use `Ctrl-C` to close the stream and unblock consumer.stream() + + ---- """ _subscription: Union[str, Subscription] = attrs.field( @@ -658,6 +662,8 @@ class Response: Anything the user wishes to return. If not `None`, the Consumer will collect the results in a list and pass the list to the user's batch callback for further processing. If there is no batch callback the results will be lost. + + ---- """ ack: bool = attrs.field(default=True, converter=bool) diff --git a/pittgoogle/registry.py b/pittgoogle/registry.py index 54f10d2..1514338 100644 --- a/pittgoogle/registry.py +++ b/pittgoogle/registry.py @@ -40,13 +40,13 @@ class Schemas: .. code-block:: python # View list of registered schema names. - pittgoogle.Schemas.names - - # View more information about the schemas. - pittgoogle.Schemas.manifest + pittgoogle.Schemas().names # Load a schema (choose a name from above and substitute it below). - schema = pittgoogle.Schemas.get(schema_name="ztf") + schema = pittgoogle.Schemas().get(schema_name="ztf") + + # View more information about all the schemas. + pittgoogle.Schemas().manifest **For Developers**: :doc:`/for-developers/add-new-schema` @@ -90,7 +90,7 @@ def get(schema_name: str | None) -> schema.Schema: # That's all we know how to check so far. raise exceptions.SchemaError( - f"{schema_name} not found. For valid names, see `pittgoogle.Schemas.names`." + f"{schema_name} not found. For valid names, see `pittgoogle.Schemas().names`." ) @property