chore: Prepare 3.1.0 — fix the release pipeline and stop OtlpExporter discarding events

[m96-chan]

Summary

Release preparation for 3.1.0, and two things found while checking whether releasing was safe.

v3.0.2 is tagged, has a GitHub release, and is not on PyPI. pip install pyetwkit has been getting 3.0.1 since December.

Changes

1. The release pipeline could not recover from a failure

v3.0.2 run:  Build wheels (3.14)  failure
             Publish to PyPI      skipped     <- correct: needs build-wheels

manual re-run:
             Build wheels (3.14)  success
             Publish to PyPI      skipped     <- the trap

The re-run went green while publishing nothing, because workflow_dispatch can never satisfy if: github.event_name == 'release'. The recovery path reports success and does nothing, which is how this went unnoticed for nine months.

• workflow_dispatch gains an explicit publish input, default false, so a failed release can be finished without a dispatch ever uploading by accident.
• The publish job now counts artifacts first. PyPI does not allow a version to be re-uploaded, so shipping four wheels instead of five is not a mistake that can be corrected afterwards.

2. OtlpExporter reported success while discarding everything — closes #88

def flush(self) -> bool:
    ...
    # In production, would send to OTLP endpoint
    # For now, just clear the batch
    self._batch.clear()
    return True

flush() now raises NotImplementedError when anything is buffered. A monitoring pipeline that reports success while sending nothing is worse than one that stops. shutdown() stays quiet — callers reach it from finally, and teardown is the wrong place to learn this.

README and docstrings corrected to describe what exists. OtlpFileExporter works and the example now uses it.

3. Version 3.1.0

Minor, not patch: set_wpp_pdb_path, set_wpp_tmf_file, set_wpp_tmf_search_path, set_property_formatting, formatted_properties and raw_data are all new. 3.0.2 is skipped rather than reused — republishing a number that already means something to anyone who read its release notes would be worse than a gap.

Related Issue

Closes #88

Test Plan

Added/Modified Tests

test_exporter_flush asserted hasattr(exporter, "flush") without calling it — one of ten hasattr-only tests in that file, which is why this shipped. Replaced with five behavioural tests: flush raises, export_batch raises, an empty flush is not an error, shutdown does not raise, and a regression guard that OtlpFileExporter still writes its spans.

Test Results

pytest        332 passed, 0 skipped
ruff / black  clean
python -c "import pyetwkit; print(pyetwkit.__version__)"  ->  3.1.0

The release.yml change cannot be exercised by CI — publishing is the thing being fixed. What is verified is that the workflow parses and the job wires up as intended:

publish if: github.event_name == 'release' || inputs.publish
steps: ['Download all artifacts', 'Check the artifact set is complete', 'Publish to PyPI']

The artifact check is a plain find | wc -l against known counts, so its failure mode is a wrong count, not a wrong upload.

Checklist

• Tests have been added/updated
• All tests pass
• Ready for code review
• Documentation updated
• CHANGELOG.md updated — the README changelog, which is where this project keeps it

Additional Notes

After merging, cutting the release is: tag v3.1.0, publish a GitHub release, and check PyPI actually received it rather than trusting the green tick. If the run fails partway, re-run with publish: true — which now works.

I have not created the tag or the release; publishing to PyPI is irreversible and yours to trigger.

Still open, deliberately: the OTLP transport itself. #88 is closed by making the failure visible, not by implementing it. Whether to reopen #52 or file a fresh issue for the transport is the one decision left over from that discussion.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HhPcm483PrDmuQEUSALBFn