Changelog

2.16.1 (September 29, 2026)

  • Kafka producer: a token the broker rejects (wrong audience or scope) during the construction-time topic check now raises KafkaAuthenticationError instead of KafkaConnectionError

  • Retry HTTP 503 by default (in addition to 502, 504, 408 and 409) when the response carries Retry-After: GraceDB sends that when it could not obtain a database connection before running any SQL, so the request is safe to repeat. A maintenance-mode 503, which has no Retry-After, is returned to the caller immediately. The pause taken from Retry-After is capped at 30 s

  • Kafka message schema: ping messages from GraceDbKafkaProducer.ping() now have their own schema (ligo/gracedb/kafka/schemas/ping_message.json, exported as PING_MESSAGE_SCHEMA), and validate_message picks the schema from the message’s type. Previously a consumer that validated every message, as the documentation suggested, rejected the package’s own pings because they lack the upload fields. The upload schema’s type is now "upload" only, and ping() validates its message before producing it

  • Kafka producer: a non-strict flush() that stalls no longer asks the broker about every queued topic before returning; it logs the count and the last librdkafka error and returns. The per-topic metadata diagnosis (up to 5 s per topic) now runs only for flush(strict=True), where it is needed to raise KafkaTopicError. close() no longer repeats the diagnosis either: it logs how many messages were dropped and returns promptly

  • jsonschema is no longer a core dependency: it is only used to validate messages the client itself builds for Kafka, so it moved to the kafka extra (pip install ligo-gracedb[kafka]) next to confluent-kafka. The Debian and RPM packages now suggest it instead of requiring it. The schema files still load without it; validate_message and the GraceDbKafkaProducer constructor raise ImportError with the install hint if it is missing

  • create_event(), replace_event(), upload_reserved_event(), write_log(), create_notice() and gwtc_create() close the file they open after reading it (the handle was previously left open until garbage collection). Callers that pass filecontents themselves are unaffected

  • Require Python 3.11 or later (requires-python and the classifiers now agree with the versions the test suite runs on). Drop the EL8 RPM build, test and rpmlint jobs from CI; ligo-gracedb.spec stays in the repository in case RPM builds are needed again

  • Remove the unused v1_only pytest marker and its collection hook, which probed the server at collection time

  • Kafka integration tests rewritten so they run against a real broker: topics are instance-namespaced from TEST_SERVICE, the default broker is kafkagracedbtest1.igwn.org:9092, the token is discovered the same way the producer does it (scope gracedb.read), and the error-handling tests assert the exceptions the producer now raises. The CI integration job installs the kafka extra so they run with the robot token

2.16.0 (September 25, 2026)

Compatibility notes for Kafka users

The REST API is unchanged, but code that used GraceDbKafkaProducer with 2.15 may need attention (see Upgrading from 2.15):

  • create_event(..., kafka=producer) raises KafkaError subclasses instead of RuntimeError when delivery fails; except RuntimeError no longer catches them

  • The constructor now contacts the broker (check_for_topics=True) and looks up the SciToken (validate_token=True), so it raises KafkaConnectionError, KafkaTopicError or KafkaTokenError where 2.15 constructed silently and failed later. Pass check_for_topics=False and/or validate_token=False for the old behaviour

  • The default token_scope is gracedb.read instead of kafka.produce; callers that passed token_scope explicitly are unaffected

  • Outgoing messages no longer carry content_id; consumers that read it should use the graceid reservation instead

  • jsonschema became a dependency (moved to the kafka extra in 2.16.1)

Kafka producer

  • Fail fast on token problems: the SciToken is looked up once at construction (validate_token=True), so a missing or expired token raises KafkaTokenError immediately, listing the locations searched (or the expiry time of the expired token found) and the htgettoken command, instead of a generic connection error after a 10 s timeout

  • Check the broker at construction (check_for_topics=True): the default topic must exist and be authorized, or without one the instance must have at least one topic on the broker (the error lists the instances that do); an unreachable broker raises KafkaConnectionError. Pass check_for_topics=False for a producer that must start before its broker is up

  • Add KafkaTopicError (subclass of KafkaMessageDeliveryError) for topics that do not exist on the broker or that the token is not authorized for. ping() checks its topic before sending, and a stalled strict flush asks the broker about the queued topics, so a missing topic is reported by name instead of as a silent timeout

  • Remember the last librdkafka error (DNS, connection refused, TLS) and include it, with a hint about what to check, when messages are not delivered

  • Add strict keyword to GraceDbKafkaProducer.flush(): raises KafkaConnectionError, KafkaTopicError or KafkaMessageDeliveryError when messages remain queued or a delivery report carried an error

  • create_event now raises KafkaError subclasses (not RuntimeError) when Kafka delivery fails, and the HTTP-fallback warning names the cause

  • Treat broker-side SASL_AUTHENTICATION_FAILED the same as local authentication failures

  • Default token_scope for GraceDbKafkaProducer and the auth helpers is now gracedb.read (the scope GraceDB requires for publishing) instead of the non-existent kafka.produce; create_kafka_producer already used gracedb.read

  • Remove content_id from outgoing Kafka messages (it is still sent with the graceid reservation and HTTP uploads)

  • Add JSON Schema validation for Kafka messages: the schema (ligo.gracedb.kafka.schema) ships with the package as the single source of truth for the message format, the producer validates every message before publishing, and additionalProperties: true keeps older consumers compatible

  • Add jsonschema>=3.0.0 as a core dependency

  • Document which broker serves which GraceDB instance, the startup checks, and every KafkaError subclass; point the troubleshooting page at them

REST API

  • Add notices, the JSON successor to VOEvents for superevents: GraceDb.notices() and GraceDb.create_notice(), plus gracedb create notice, gracedb get notice and gracedb list notices CLI commands

  • Add replay_id keyword argument to create_event() and a --replay-id option to gracedb create event; forward it to the graceid reservation on the Kafka path so reserved events carry it. Requires a GraceDB server that supports replay_id (events from different replay analyses are sorted into separate superevents)

  • Methods that require API v2 now also accept a client constructed without an explicit api_version when the server reports api-default == 'v2' in its service info

  • event_or_superevent-decorated methods recognise a content_id UUID as an event identifier

Testing and packaging

  • Register the integration, cli and v1_only pytest markers in pyproject.toml

  • Integration tests: superevent VOEvent creation tests are skipped by default (the server now returns 410 Gone; JSON notices replace VOEvents) and can be re-enabled with TEST_VOEVENT_CREATE=1; the 410 contract is pinned in test_deprecated.py. New replay_id integration tests are gated behind TEST_REPLAY_ID=1 until server support is deployed

  • flake8 clean-up of the library code

  • Removed Debian Bullseye from CI/CD build pipeline

2.15.7 (April 02, 2026)

  • Wrap BufferError retry in produce() with proper error handling

2.15.6 (April 01, 2026)

  • Remove redundant pre-poll auth check in consumer

  • Add header decode fallback for invalid UTF-8 in consumer

  • Fix pending_messages tracking with custom delivery callbacks

  • Fix pending_messages tracking on BufferError retry

  • Namespace topics correctly in producer ping()

  • Consolidate exception handling in _create_event_via_kafka

  • Fix double file upload in create_event and upload_reserved_event — files were being sent twice in the multipart body

2.15.5 (April 01, 2026)

  • Fix RPM packaging: include ligo.gracedb.kafka in spec file package list for RHEL builds

2.15.4 (March 25, 2026)

  • Auto-flush producer in create_event after Kafka publish — users no longer need to call flush() manually

  • Add configurable flush_timeout parameter to GraceDbKafkaProducer (default: 10s)

  • Include content_id in outgoing Kafka messages

  • Update documentation

2.15.3 (March 25, 2026)

  • Add content_id field to event uploads — a SHA-256-based UUID derived from the event file contents

  • Include content_id in HTTP POST, graceid reservation, and Kafka messages

  • Enable zstd compression on Kafka producer

  • Bump producer message.max.bytes to 10 MB

2.15.2 (March 23, 2026)

  • Kafka topic is now determined automatically from group/pipeline in create_event

  • Test group events route to {instance}.test; other groups route to {instance}.{pipeline}

  • Producer topic argument is now optional when using create_event

  • Embed _producer_timestamp in Kafka messages for latency telemetry

  • Update documentation

2.15.1 (March 04, 2026)

  • Add instance-namespaced Kafka topics (instance.pipeline format)

  • Add derive_instance_name, make_topic_name, parse_topic_name utilities

  • Producer and consumer now require instance_name or service_url

  • create_kafka_producer passes service_url automatically

  • Update documentation

2.15.0 (March 02, 2026)

  • Add Kafka producer and consumer classes with SciToken integration

  • Update create_event with Kafka workflow

  • Add _reserve_graceid() and upload_reserved_event() methods

  • Update documentation

2.14.3 (September 26, 2025)

  • Deprecate oLIB pipeline

  • Drop obsolete build/install dependencies on python-future

  • Documentation fixes

2.14.2 (April 09, 2025)

  • Logging fixes

2.14.1 (March 06, 2025)

  • Token adaptor bugfixes

  • Logging improvements

2.14.0 (March 04, 2025)

  • add scitoken reloading

2.13.2 (March 03, 2025)

  • Fix packaging

2.13.1 (February 28, 2025)

  • Fix packaging

2.13.0 (October 04, 2024)

  • add gwtc-specific API commands into base client

  • catch decoding error in command-line client

  • packaging and pipeline updates

  • docs build updates

2.12.0 (September 06, 2023)

  • add retry on POST and PATCH operations

  • Remove all use of six

  • Remove use of mock package

  • Update to igwn-auth-utils 1.0.0

  • Packaging and testing updates

2.11.0 (April 18, 2023)

  • add support retrying on errors

  • Update default scitoken scope

2.10.0 (December 12, 2022)

  • add labels at log/upload time

  • testing fixes

  • documentation fixes

2.9.0 (November 11, 2022)

  • support HasMassGap instead of MassGap for VOEvents

  • gw_id support for naming confirmed GWs

2.8.0 (May 11, 2022)

  • use igwn-auth-utils for credential finding

2.7.8 (August 04, 2022)

  • pipeline-specific preferred event features

  • camelCase to snake_case transition

  • documentation changes

2.7.7 (March 28, 2022)

  • Drop python2 support

  • Dependency and testing fixes

  • Removed legacy CLI

  • Fixed client.stop() recursion error

  • Documentation cleanup

2.7.6 (February 19, 2021)

  • fix for return vs. break for generator return calls

2.7.5 (January 08, 2021)

  • changed search order for x509 credentials

2.7.4 (December 14, 2020)

  • fix for requests/urllib3 bug

  • fix for json response for update event CLI command

  • packaging changes

2.7.3 (November 23, 2020)

  • json() method for file retrieval

2.7.2 (November 16, 2020)

  • Bugfix for certificate check failure with tuple’d credentials

2.7.1 (October 19, 2020)

  • Improved exception handling for HTTPErrors

  • Fix and deprecation warning for gracedb_legacy CLI tool

2.7.0 (August 06, 2020)

  • Backend rewrite using “requests” package

2.6.1 (June 05, 2020)

  • SSL_PROTOCOL fix for python < 2.7.13

2.6.0 (June 04, 2020)

  • Added time/space_coinc_far fields to support RAVEN

  • Testing and packaging changes.

2.5.0 (November 25, 2019)

  • Add RAVEN fields to updateSuperevent

  • Add RAVEN VOEvent support to createVOEvent

  • Remove patch to support Python 2.6 and earlier.

2.4.0 (August 21, 2019)

  • Change minimum required version of six to 1.9.0

  • Add client method for updating GRB event parameters

  • Add CLI method for updating GRB event parameters

2.3.0 (July 17, 2019)

  • Add feature for reloading an expired X.509 certificate

  • Add utility function for checking user account on the server

  • Add comprehensive documentation

  • Add functionality for getting server code version

  • Add linting functionality and lint the entire code base

  • Convert show command to info for command-line interface

  • Bugfix handling of dict response in command-line interface

  • Bugfix assumption that $HOME exists

  • Bugfix fail_if_noauth implementation in client

  • Bugfix bad uses of sys.hexversion to check Python version

  • Improve certificate handling and expiration checks

2.2.2 (March 8, 2019)

  • Bugfix for Python 3 compatibility: remove all usage of dict.keys() and dict.values()

  • Bugfix handling of bytes responses in command-line interface

  • Improve command-line interface help

2.2.1 (March 1, 2019)

  • Bugfix default service URL for command-line interface

  • Bugfix packaging

2.2.0 (February 22, 2019)

2.1.2 (February 5, 2019)

2.1.1 (December 5, 2018)

  • Add new optional parameters to ligo.gracedb.rest.GraceDb.createVOEvent():

    • BNS: probability that source is a binary neutron star merger

    • NSBH: probability that source is a neutron star - black hole binary merger

    • BBH: probability that the source is a binary black hole merger

    • Terrestrial: probability that the source is a background noise fluctuation or glitch

  • Remove one optional parameter from ligo.gracedb.rest.GraceDb.createVOEvent(): vetted, specifying whether the candidate has undergone basic human vetting

  • Minor bugfixes/changes to integration tests

2.1.0 (November 29, 2018)

  • Improve error handling for failed attempts to get service information from API

  • Consolidate all authentication types under a single client class

  • Add unit tests for handling of credentials

2.0.1 (October 3, 2018)

  • Bugfix for truthiness checks for numeric arguments

  • Remove permissions detail retrieval (no longer available on server)

2.0.0 (September 25, 2018)

  • Add comprehensive compatibility for Python 3.4+

  • Add functionality for managing superevent signoffs and permissions

  • Remove temporary deprecation measure for including VOEvent file text in response

  • Add an option for specifying a server API version

  • Update unit tests

2.0.0.dev1 (July 25, 2018)

  • Add CI configuration

  • Update and centralize package version handling

  • Remove bin/gracedb executable, now built by setup.py as an entry_point

  • Add client version to request headers

  • Implement temporary measure for backwards compatibility - “fake” VOEvent file text in response

  • Add superevent categories

2.0.0.dev0 (June 28, 2018)

  • Identical to 1.29.dev1 other than packaging changes, but it was decided after the fact that we should bump the major version number

1.29.dev1 (June 21, 2018)

  • More new features for creating and managing superevents

1.29.dev0 (May 31, 2018)

  • New features for creating and managing superevents

1.28 (April 24, 2018)

  • Various fixes for Python 3

1.27 (February 13, 2018)

  • Change DEFAULT_SERVICE_URL used by command-line client to match other instances

  • Update organization of full unit test suite

1.26 (December 1, 2017)

  • Significant restructuring of unit tests

  • Add several unit tests

  • Update ligo.gracedb.rest.GraceDb.createEvent() method to properly handle multiple labels and to work with upcoming server code changes

  • Fix whitespace issues

1.25 (August 2, 2017)

  • Fix packages provide, requirements, and build dependencies

  • Add ability to create events with labels to the command-line client

  • Add ability to set offline parameter with the command-line client

  • Update unit tests

1.24 (May 25, 2017)

  • Add a check on .netrc file permissions

  • Add capability to create events with labels attached

  • Add offline boolean parameter when creating events

1.23 (February 3, 2017)

  • Improve exception handling and display of tracebacks in REST client

  • Catch and handle exceptions in logging handler

  • Update of dependencies

1.22 (January 10, 2017)

  • Fix bug related to decoding logs

  • Improve log handler cleanup

  • Remove calls to sys.exit() from ligo.gracedb.rest

1.21 (December 13, 2016)

  • Modernize Debian packaging and port to Python 2 and 3

  • Make logging handler non-blocking

1.20 (February 11, 2016)

  • Improve error handling for expired or missing credentials

  • Improved error handling when server returns non-JSON response

  • Added --use-basic-auth option to command-line client

1.19.1 (October 22, 2015)

  • Force TLSv1 for Python versions less than 2.7.9

  • Change ligo.gracedb.rest.GraceDb.adjustResponse() to put retry-after in the JSON response for 429 respose codes

  • Changed test service URL to gracedb-test.ligo.org

  • Introduced wait time to test suite

1.19 (July 29, 2015)

  • Bugfixes: comma separated strings for EM Observations and CLI createLog call

  • Capture of additional kwargs to facilitate HardwareInjection event upload

  • Packaging improvements (ligo as namespace package)

1.18 (May 13, 2015)

  • Add comment to EM Observation record

  • Allow Python lists as arguments to writeEMObservation

  • Changed ligo to namespace package

1.18.dev0 (April 20, 2015)

  • New features for robotic basic auth

  • New features for EM observation records

1.17 (March 25, 2015)

  • Bugfix for Python version incompatibility in 1.16

  • New methods/tests for creating and retrieving VOEvents

  • Bugfix for gittag test

1.16 (February 11, 2015)

  • Fixes for glue 1.47 to the command line client

  • Use SSLContext and explicitly turn off client-side server verification

  • Fix for command that lists groups, pipelines, and searches

  • Allow multiple tags to be added to an event log at creation time

  • Updates to unit test data

1.15 (October 31, 2015)

  • Features for EMBB Event Log upload and retrieval

  • Changes for (Group,Type) -> (Group,Pipeline,Search) transition

  • Added docstrings

1.14 (December 18, 2013)

  • Fixed 10 and 1000 event limits. Corresponds to issues 986 and 787 (on redmine page)

1.13 (June 28, 2013)

  • Fixed renegotiation regression. Corresponds to issue 951 (on redmine page)

1.12 (June 27, 2013)

  • Changed client to use REST API exclusively

  • Extended REST API to include all API functionality

1.11 (January 24, 2013)

  • Re-add --with python2 to match other ligo-* Python modules

  • Fix bug where stdin is specified, it is not actually read

  • Add python-ligo-common to dependencies

1.10 (January 18, 2013)

  • CLI replace feature had subtle openssl bug; now using REST client

  • Typo in help text

  • Typo in test.py wrt CWB test data

  • Remove --with-python2 from debian/rules

1.9 (January 16, 2013)

  • Add slot feature to command line interface

  • Add unit tests for CLI slot feature

  • Add rudimentary test code documentation

1.8 (January 4, 2013)

  • Incorporate Leo’s patch for fixing import problem

1.7 (December 21, 2012)

1.6 (December 19, 2012)

  • Fix some typos

  • Add more unit tests for GraceDb class

  • Add test script for command line client

  • Improve unit tests’ usability

1.5 (December 12, 2012)

  • Source 3.0 format

  • Add support for REST API

  • Add unit tests and test data

1.4 (July 19, 2012)

  • Fixed SSL renegotiation bug on large file upload.

1.3 (June 14, 2012)

  • Replace simplejson with cjson because simplejson is not available everywhere in the LSC

1.2 (June 11, 2012)

  • Add file download command

1.1 (January 22, 2012)

  • Bug Fix.

1.0 (November 1, 2011)

  • Initial release