Release v0.10.0: SDK modernization, structured exceptions, and expanded test coverage#58
Merged
LegendEvent merged 38 commits intomainfrom Apr 17, 2026
Merged
Release v0.10.0: SDK modernization, structured exceptions, and expanded test coverage#58LegendEvent merged 38 commits intomainfrom
LegendEvent merged 38 commits intomainfrom
Conversation
…orts, add type hints
…lent error swallowing in similardevices
Apply consistent PEP 8 style transformations to all remaining Python files, matching the pattern already applied to 11 files in a previous commit. Changes are purely mechanical with zero logic modifications: - Single to double quotes for all string literals - PEP 8 import ordering (stdlib > third-party > local) - Remove unused `import requests` from endpoint modules - Trailing commas on multi-line function signatures - Multi-line `_make_request` call formatting - Remove trailing whitespace, ensure trailing newlines - Type hint improvements (`int = None` to `Optional[int] = None`) Files changed: darktrace/__init__.py, auth.py darktrace/dt_antigena.py, dt_breaches.py, dt_components.py, dt_cves.py, dt_details.py, dt_deviceinfo.py, dt_devicesearch.py, dt_email.py, dt_endpointdetails.py, dt_enums.py, dt_intelfeed.py, dt_mbcomments.py, dt_metrics.py, dt_models.py, dt_pcaps.py, dt_status.py, dt_summarystatistics.py examples/intelfeed_example.py, threat_intelligence.py Verified: all 22 files pass py_compile, package imports OK (v0.9.0), 90 tests pass / 0 fail, scope fidelity confirmed (style-only changes). Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
- Add [tool.ruff] config: target-version py37, line-length 120 - Configure lint rules: E, F, W, I, UP (ignore E501 for docstrings) - Configure format: double quotes, space indentation - Configure isort: known-first-party darktrace - Add [project.optional-dependencies] dev group: ruff, pytest, pre-commit - Exclude examples/ from ruff checks
- Replace _UNSET = object() with _Unset singleton class in dt_utils.py
- _Unset has __repr__ ('<UNSET>'), __bool__ (False), singleton via __new__
- Add _InternalTimeoutType = Union[_Unset, None, float, Tuple[float, float]]
- Update _resolve_timeout to use _InternalTimeoutType (no type: ignore needed)
- Remove 24 _UNSET-related # type: ignore[assignment] across 19 modules
- Preserve all return-type # type: ignore[assignment] (unrelated to _UNSET)
- Fix missing Dict/Any imports in dt_subnets.py (F821 bug)
- Add # noqa: F401 to __version__ import in __init__.py
- Update test files for ruff formatting compatibility
- One-time ruff format pass on all darktrace/ and root Python files - Import sorting (isort), consistent quote style, whitespace normalization - No logic changes — formatting only - conftest.py: add # noqa: E402 for post-function imports - setup.py: quote style normalization, remove unused os import
- Add .pre-commit-config.yaml with ruff (--fix) and ruff-format hooks - Add .github/workflows/lint.yml with parallel lint + test jobs - Lint job: ruff check + ruff format --check (Python 3.12) - Test job: pip install -e .[dev] + pytest - Triggers on push/PR to main branch
3-phase architecture: - Phase 1: Refresh GitNexus index with embeddings (skippable) - Phase 2: Run 4 Cypher detection checks + allowlist filtering - Phase 3: Dynamic deep investigation for actionable issues Features: - Allowlist for false positives (30 orphaned SDK classes) - LLM-consumable output with rich context - Dynamic investigation queries per issue type - Sisyphus ulw mode trigger for complex issues
- Remove deprecated approve_action method from dt_antigena.py - Remove corresponding test from test_mock.py - Replace bare except Exception with specific exception types (requests.exceptions.RequestException, json.JSONDecodeError) in add_comment, acknowledge, unacknowledge methods Code smells detected by GitNexus code intelligence hook.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Add real activate_action() method that POSTs to /antigena with activate:true. Fix approve_action() deprecation message to no longer reference the previously missing activate_action method. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Restore approve_action and activate_action assertions in test_antigena_methods. Restore TestDeprecations class with test_approve_action_deprecated. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
refactor: codebase modernization, quality tooling, and API correctness fixes
…s, and expanded tests - Migrate all 27 endpoint modules to use idiomatic BaseEndpoint helpers (_get, _post_json, _post_form, _delete) instead of manual header/request calls - Add structured exception hierarchy (darktrace/exceptions.py) with 8 purpose-built HTTP error classes wrapping requests.HTTPError - Add _raise_for_status() to BaseEndpoint for consistent error handling - Expand CI matrix to Python 3.8-3.12 in lint workflow - Add 28 HMAC signature tests (tests/test_auth.py) - Add 47 POST/DELETE mock tests (tests/test_post_delete.py) - Remove legacy setup.py (pyproject.toml is sole build config) - Fix README: remove false async-ready claim, add exceptions docs - Full backward compatibility maintained: no public API signature changes
refactor: modernize SDK with idiomatic patterns, structured exceptions, and expanded tests - Migrate all 27 endpoint modules to use idiomatic BaseEndpoint helpers (_get, _post_json, _post_form, _delete) instead of manual header/request calls - Add structured exception hierarchy (darktrace/exceptions.py) with 8 purpose-built HTTP error classes wrapping requests.HTTPError - Add _raise_for_status() to BaseEndpoint for consistent error handling - Expand CI matrix to Python 3.8-3.12 in lint workflow - Add 28 HMAC signature tests (tests/test_auth.py) - Add 47 POST/DELETE mock tests (tests/test_post_delete.py) - Remove legacy setup.py (pyproject.toml is sole build config) - Fix README: remove false async-ready claim, add exceptions docs - Full backward compatibility maintained: no public API signature changes
… wiring, modernize annotations - Replace all -> Any return types with dict | list, bytes, dict, or None across 27 endpoint modules - Wrap connection/timeout errors in darktrace.ConnectionError with exception chaining - Replace 5 raw response.raise_for_status() calls with _raise_for_status() - Add from __future__ import annotations to all endpoint modules - Modernize type annotations (Optional[X] -> X | None, Dict -> dict, etc.) - Add 12 tests for exception wiring, HTTP status mapping, and backward compatibility - Update .gitignore for local tooling files
… wiring, modernize annotations - Replace all -> Any return types with dict | list, bytes, dict, or None across 27 endpoint modules - Wrap connection/timeout errors in darktrace.ConnectionError with exception chaining - Replace 5 raw response.raise_for_status() calls with _raise_for_status() - Add from __future__ import annotations to all endpoint modules - Modernize type annotations (Optional[X] -> X | None, Dict -> dict, etc.) - Add 12 tests for exception wiring, HTTP status mapping, and backward compatibility - Update .gitignore for local tooling files
- Remove unreachable comment after return in dt_tags.py - Delete tests/real/test_devicesearch_real.py (3 zero-value stub tests) - Remove empty test_email_decode_link stub from test_sdk_readonly.py - Note: import json in dt_breaches.py retained (still used by except blocks, Task 6 will handle)
- Remove 3 try/except blocks that catch-log-reraise (add_comment, acknowledge, unacknowledge) - Remove now-unused imports: import json, import requests - Fix test anti-pattern: replace assert True with pass in except blocks - Exceptions now propagate naturally through _post_json() → _make_request()
- Convert 4 manual GET methods in dt_analyst.py to use self._get() - Remove now-unused _raise_for_status import from dt_analyst.py - Add from __future__ import annotations to client.py - Remove unnecessary quotes from type annotations (UP037)
- Extract _dashboard_get() helper in dt_email.py - 4 dashboard GET methods now delegate to shared helper - Public API signatures and docstrings preserved exactly - dt_breaches.py with_comment methods left as-is (differ in called method) - Test boilerplate left as-is (explicitness preferred)
- Add from __future__ import annotations to __init__.py and auth.py - Replace Dict/Optional/Union/Tuple with PEP 604 syntax (dict, | None, |, tuple) - Modernize TimeoutType and _InternalTimeoutType aliases - Add [tool.mypy] config section to pyproject.toml - Zero legacy typing imports remain in darktrace/ source
- Add TYPE_CHECKING guard for DarktraceClient in dt_utils.py - Type BaseEndpoint.__init__ client as DarktraceClient - Type __exit__ with proper stdlib types (type, BaseException, TracebackType) - Remove unused typing.Any from client.py - No circular imports
- Add import-linter>=2.0 as dev dependency - Configure hub-and-spoke independence contract (dt_* modules) - Configure infrastructure isolation contract (dt_utils) - Full coupling analysis report in evidence files
- Remove 25 trivial __init__ overrides (just super().__init__(client)) - Clean 14 'future-proofing' / 'forward compatibility' phrases - Remove 7 redundant inline comments (code is self-explanatory) - Preserve all helpful documentation: docstrings, IMPORTANT, backwards compat notes
Email module tests now skip instead of failing when the Darktrace/Email sub-product is not licensed on the appliance (returns 403 Forbidden).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR merges the
devbranch intomain, delivering the v0.10.0 release. It represents a comprehensive modernization of the Darktrace SDK — introducing a structured exception hierarchy, migrating the build system topyproject.toml, enforcing ruff linting/formatting across the entire codebase, and significantly expanding test coverage.34 commits · 49 files changed · +3,517 / −2,388 lines
Changes by Category
🏗️ Architecture & Core Infrastructure
darktrace/exceptions.py— all exceptions subclassrequests.HTTPErrorfor backward compatibility. Hierarchy:DarktraceError→BadRequestError (400),AuthenticationError (401),ForbiddenError (403),NotFoundError (404),RateLimitError (429),ServerError (5xx),ConnectionError_UNSETsentinel → typed class_UNSETsentinel pattern indt_utils.pywith a properly typed_UnsetTypeclass for better IDE support and type safetysetup.pywithpyproject.toml(104 lines) — ruff config, project metadata, build system declarationBaseEndpointmodernizationdt_utils.pyexpanded with logging, idiomatic helper methods (_get(),_post_json()),__repr__(), and structured error propagation🔧 Refactoring (13 commits)
Optional[X]→X | None,Union[X, Y]→X | Y_get_headers()+_make_request()pattern toself._get()/self._post_json()indt_analyst,dt_breaches, and other modulesdt_breaches, bareexcept:handlers, dead code, unused imports__all__exports added to all 27 endpoint modules for explicit public API declaration__repr__and class docstrings added to core modules🐛 Bug Fixes (5 commits)
activate_actionrestoredactivate_actionmethod todt_antigena.pythat was accidentally removedapprove_actionwith proper deprecation warningsexcept:handlersdt_similardevices.pysilently catching and ignoring errorstimeparameter default in advanced search GET path__all__sort order__init__.pyexports to be alphabetically sorted🎨 Style & Formatting (3 commits)
pyproject.toml[tool.ruff], line-length=120)🧪 Test Coverage (4 new/expanded test files)
tests/test_auth.pytests/test_exceptions.pyrequests.HTTPErrortests/test_post_delete.pytests/test_mock.pytests/test_sdk_readonly.py📦 Tooling & CI (1 feature + 5 chore commits)
.pre-commit-config.yamlwith ruff, trailing-whitespace, end-of-file-fixer.github/).gitignoreupdates — sisyphus/state exclusions, hooks/ moved to local-only📚 Documentation
examples/README.mdconftest.pywith better pytest CLI option handlingBreaking Changes
setup.pyremovedThe build system has migrated to
pyproject.toml. Projects installing viapip install -e .will continue to work without changes (pip supportspyproject.tomlnatively since pip 21.3).Methods now raise structured exceptions from
darktrace.exceptionsinstead of rawrequests.HTTPError. Existingexcept requests.HTTPErrorhandlers remain compatible — all new exceptions subclass it.approve_actiondeprecated in AntigenaUse
activate_actioninstead.approve_actionstill works but emits aDeprecationWarning.Files Changed (49)
Click to expand full file list
New files:
darktrace/exceptions.py— Exception hierarchytests/test_auth.py— Auth unit teststests/test_exceptions.py— Exception unit teststests/test_post_delete.py— POST/DELETE integration testspyproject.toml— Build config (replaces setup.py)Removed files:
setup.py— Migrated to pyproject.tomltests/real/test_devicesearch_real.py— ConsolidatedModified (all 27 endpoint modules + core):
darktrace/__init__.py,darktrace/auth.py,darktrace/client.py,darktrace/dt_utils.pydarktrace/dt_advanced_search.py,darktrace/dt_analyst.py,darktrace/dt_antigena.py,darktrace/dt_breaches.py,darktrace/dt_components.py,darktrace/dt_cves.py,darktrace/dt_details.py,darktrace/dt_deviceinfo.py,darktrace/dt_devices.py,darktrace/dt_devicesearch.py,darktrace/dt_devicesummary.py,darktrace/dt_email.py,darktrace/dt_endpointdetails.py,darktrace/dt_enums.py,darktrace/dt_filtertypes.py,darktrace/dt_intelfeed.py,darktrace/dt_mbcomments.py,darktrace/dt_metricdata.py,darktrace/dt_metrics.py,darktrace/dt_models.py,darktrace/dt_network.py,darktrace/dt_pcaps.py,darktrace/dt_similardevices.py,darktrace/dt_status.py,darktrace/dt_subnets.py,darktrace/dt_summarystatistics.py,darktrace/dt_tags.pydarktrace/_version.py— 0.9.0 → 0.10.0conftest.py,README.md,.gitignoreexamples/README.md,examples/intelfeed_example.py,examples/threat_intelligence.py,examples/tor_exit_nodes.pytests/test_compilation.py,tests/test_mock.py,tests/test_sdk_readonly.pyCommit Breakdown
featfixrefactorstyletestdocschoreChecklist
requests.HTTPErrorpyproject.tomlreplacessetup.pyfor modern Python packaging__all__exports added for explicit public API surfaceapprove_actionwithDeprecationWarning(backwards-compat preserved)