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
KafkaAuthenticationErrorinstead ofKafkaConnectionErrorRetry 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 noRetry-After, is returned to the caller immediately. The pause taken fromRetry-Afteris capped at 30 sKafka message schema: ping messages from
GraceDbKafkaProducer.ping()now have their own schema (ligo/gracedb/kafka/schemas/ping_message.json, exported asPING_MESSAGE_SCHEMA), andvalidate_messagepicks the schema from the message’stype. 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’stypeis now"upload"only, andping()validates its message before producing itKafka 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 forflush(strict=True), where it is needed to raiseKafkaTopicError.close()no longer repeats the diagnosis either: it logs how many messages were dropped and returns promptlyjsonschemais no longer a core dependency: it is only used to validate messages the client itself builds for Kafka, so it moved to thekafkaextra (pip install ligo-gracedb[kafka]) next toconfluent-kafka. The Debian and RPM packages now suggest it instead of requiring it. The schema files still load without it;validate_messageand theGraceDbKafkaProducerconstructor raiseImportErrorwith the install hint if it is missingcreate_event(),replace_event(),upload_reserved_event(),write_log(),create_notice()andgwtc_create()close the file they open after reading it (the handle was previously left open until garbage collection). Callers that passfilecontentsthemselves are unaffectedRequire Python 3.11 or later (
requires-pythonand 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.specstays in the repository in case RPM builds are needed againRemove the unused
v1_onlypytest marker and its collection hook, which probed the server at collection timeKafka integration tests rewritten so they run against a real broker: topics are instance-namespaced from
TEST_SERVICE, the default broker iskafkagracedbtest1.igwn.org:9092, the token is discovered the same way the producer does it (scopegracedb.read), and the error-handling tests assert the exceptions the producer now raises. The CI integration job installs thekafkaextra 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)raisesKafkaErrorsubclasses instead ofRuntimeErrorwhen delivery fails;except RuntimeErrorno longer catches themThe constructor now contacts the broker (
check_for_topics=True) and looks up the SciToken (validate_token=True), so it raisesKafkaConnectionError,KafkaTopicErrororKafkaTokenErrorwhere 2.15 constructed silently and failed later. Passcheck_for_topics=Falseand/orvalidate_token=Falsefor the old behaviourThe default
token_scopeisgracedb.readinstead ofkafka.produce; callers that passedtoken_scopeexplicitly are unaffectedOutgoing messages no longer carry
content_id; consumers that read it should use the graceid reservation insteadjsonschemabecame a dependency (moved to thekafkaextra 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 raisesKafkaTokenErrorimmediately, listing the locations searched (or the expiry time of the expired token found) and thehtgettokencommand, instead of a generic connection error after a 10 s timeoutCheck 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 raisesKafkaConnectionError. Passcheck_for_topics=Falsefor a producer that must start before its broker is upAdd
KafkaTopicError(subclass ofKafkaMessageDeliveryError) 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 timeoutRemember the last librdkafka error (DNS, connection refused, TLS) and include it, with a hint about what to check, when messages are not delivered
Add
strictkeyword toGraceDbKafkaProducer.flush(): raisesKafkaConnectionError,KafkaTopicErrororKafkaMessageDeliveryErrorwhen messages remain queued or a delivery report carried an errorcreate_eventnow raisesKafkaErrorsubclasses (notRuntimeError) when Kafka delivery fails, and the HTTP-fallback warning names the causeTreat broker-side
SASL_AUTHENTICATION_FAILEDthe same as local authentication failuresDefault
token_scopeforGraceDbKafkaProducerand the auth helpers is nowgracedb.read(the scope GraceDB requires for publishing) instead of the non-existentkafka.produce;create_kafka_produceralready usedgracedb.readRemove
content_idfrom 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, andadditionalProperties: truekeeps older consumers compatibleAdd
jsonschema>=3.0.0as a core dependencyDocument which broker serves which GraceDB instance, the startup checks, and every
KafkaErrorsubclass; point the troubleshooting page at them
REST API
Add notices, the JSON successor to VOEvents for superevents:
GraceDb.notices()andGraceDb.create_notice(), plusgracedb create notice,gracedb get noticeandgracedb list noticesCLI commandsAdd
replay_idkeyword argument tocreate_event()and a--replay-idoption togracedb create event; forward it to the graceid reservation on the Kafka path so reserved events carry it. Requires a GraceDB server that supportsreplay_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_versionwhen the server reportsapi-default == 'v2'in its service infoevent_or_superevent-decorated methods recognise acontent_idUUID as an event identifier
Testing and packaging
Register the
integration,cliandv1_onlypytest markers inpyproject.tomlIntegration 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 intest_deprecated.py. Newreplay_idintegration tests are gated behindTEST_REPLAY_ID=1until server support is deployedflake8 clean-up of the library code
Removed Debian Bullseye from CI/CD build pipeline
2.15.7 (April 02, 2026)
Wrap
BufferErrorretry inproduce()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_messagestracking with custom delivery callbacksFix
pending_messagestracking onBufferErrorretryNamespace topics correctly in producer
ping()Consolidate exception handling in
_create_event_via_kafkaFix double file upload in
create_eventandupload_reserved_event— files were being sent twice in the multipart body
2.15.5 (April 01, 2026)
Fix RPM packaging: include
ligo.gracedb.kafkain spec file package list for RHEL builds
2.15.4 (March 25, 2026)
Auto-flush producer in
create_eventafter Kafka publish — users no longer need to callflush()manuallyAdd configurable
flush_timeoutparameter toGraceDbKafkaProducer(default: 10s)Include
content_idin outgoing Kafka messagesUpdate documentation
2.15.3 (March 25, 2026)
Add
content_idfield to event uploads — a SHA-256-based UUID derived from the event file contentsInclude
content_idin HTTP POST, graceid reservation, and Kafka messagesEnable zstd compression on Kafka producer
Bump producer
message.max.bytesto 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
topicargument is now optional when usingcreate_eventEmbed
_producer_timestampin Kafka messages for latency telemetryUpdate 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
sixto 1.9.0Add 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
showcommand toinfofor command-line interfaceBugfix handling of
dictresponse in command-line interfaceBugfix assumption that
$HOMEexistsBugfix
fail_if_noauthimplementation in clientBugfix bad uses of
sys.hexversionto check Python versionImprove certificate handling and expiration checks
2.2.2 (March 8, 2019)
Bugfix for Python 3 compatibility: remove all usage of
dict.keys()anddict.values()Bugfix handling of
bytesresponses in command-line interfaceImprove 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)
Full rework of command-line tool
Add option for handling legacy
tagnamekwarg (instead oftag_name) toligo.gracedb.rest.GraceDb.writeLog()Add optional
MassGapparameter toligo.gracedb.rest.GraceDb.createVOEvent()
2.1.2 (February 5, 2019)
Remove
skymap_image_filenamefromligo.gracedb.rest.GraceDb.createVOEvent()Add optional kwarg
max_resultstoligo.gracedb.rest.GraceDb.events()andligo.gracedb.rest.GraceDb.superevents()Improve testing configuration by adding pytest and tox
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 mergerNSBH: probability that source is a neutron star - black hole binary mergerBBH: probability that the source is a binary black hole mergerTerrestrial: 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 vettingMinor 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/gracedbexecutable, now built by setup.py as anentry_pointAdd 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_URLused by command-line client to match other instancesUpdate 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 changesFix whitespace issues
1.25 (August 2, 2017)
Fix packages
provide,requirements, and build dependenciesAdd 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()fromligo.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-authoption 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 codesChanged 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
createLogcallCapture 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 python2to match other ligo-* Python modulesFix 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-python2from 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)
Add workaround for Python bug http://bugs.python.org/issue11898
Add Leo Singer’s convenience classes for logging
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