Skip to content

usaspending-orm v0.7.1

Choose a tag to compare

View all tags
@caseydreier caseydreier released this 16 Apr 21:24
· 87 commits to main since this release
v0.7.1
0e83230
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Added

New resources and query builders

  • client.awards.find_by_generated_id(...).child_awards — iterate child
    awards (delivery/task orders) under an IDV via the new IDVChildAwardsSearch
    builder.
  • client.award_accounts — new resource plus AwardAccount model for listing
    federal accounts associated with a specific award via /awards/accounts/.
  • client.tas — new resource for the TreasuryAccountSymbols hierarchy (TAS
    agencies, federal accounts, TAS codes), backed by the
    references/filter_tree/tas/* endpoints.
  • Funding / Agency models now expose federal-account relationships without
    forcing an API call to hydrate.
  • ClientSideQueryBuilder base class for in-memory filtering/sorting of
    fixed-payload responses (used by TASCodesQuery and FederalAccountsQuery).

Configuration

  • config.cache_namespace — cache-key namespace so multiple applications or
    environments don't collide in the pickle cache directory.
  • config.default_result_limit — hard cap on unbounded queries (default
    10_000) to prevent runaway pagination; set to None to disable.
  • config.allowed_download_hosts — allow-list of hostnames the library will
    fetch binary downloads from. Defaults to {"api.usaspending.gov",
    "files.usaspending.gov"}.
  • config.validate() now also rejects malformed base_url, CR/LF in
    user_agent, and empty cache_dir; validates pagination parameters on
    QueryBuilder.

Public API

  • Export DetachedInstanceError from the top-level package so callers can
    from usaspending import DetachedInstanceError as documented in the README.
  • Upstream sync: ten new F-series assistance type codes from USASpending API
    Sprint 216 are wired into .grants(), .loans(), .direct_payments(), and
    .other_assistance() helpers.

Performance

  • Count caching on QueryBuilder so query[5], len(query), and similar
    indexing operations don't re-hit the count endpoint.
  • Stable per-client cache keys that share across USASpendingClient instances
    with the same namespace.
  • Funding model is now client-aware and skips API calls when loading agency
    objects that already have their data.

Tooling and tests

  • Raised ruff linting standards and added comprehensive tests for exception
    classes, logging configuration, file-format handling, security error paths,
    and RateLimiter time mocking.

Changed

  • ValidationError now inherits from both USASpendingError and the built-in
    ValueError. Existing except ValueError sites keep working while the library
    can consistently raise ValidationError.
  • RateLimiter raises ValidationError instead of bare ValueError for invalid
    max_calls / period.
  • RecipientsResource.find_by_recipient_id annotated non-Optional to match
    its raises-on-miss behavior; find_by_duns and find_by_uei remain Optional
    (search-delegation convention).
  • Agency.get_obligations return annotation corrected from float | None to
    Decimal | None; Agency.total_obligations now coerces stored values via
    to_decimal().
  • TransactionsSearch._award_id and FundingSearch._award_id annotated as str
    | None.
  • time_period(start, end) now rejects inverted ranges (end < start).
  • to_date() accepts datetime input and narrows to .date(); supports multiple
    ISO-ish formats (space / T separators, optional microseconds, optional Z /
    timezone offset).
  • AgenciesSearch consolidated; SubAgencyQuery refactored to use the
    QueryBuilder pattern; RecipientQuery now uses query params for year.
  • Award download type handling refactored for clarity (_download_type
    attribute on award models).
  • Model constructors now require a USASpendingClient explicitly where lazy
    fetch is possible.
  • Build system: poetry removed; project is now pure uv-based.

Bug fixes

  • to_date() returned datetime objects unchanged instead of narrowing to date
    (regression hole in the subclass check).
  • IDVChildAwardsSearch._clone() silently dropped _filter_objects,
    _max_pages, _order_by, and _order_direction on chaining.
  • SubAwardsSearch._clone() reimplemented base-clone logic instead of
    delegating (drift risk).
  • AwardAccountsQuery._clone() copied stale _cached_count across filter
    changes.
  • Agency.latest_action_date crashed with AttributeError when
    _get_award_summary() returned None.
  • round_to_millions() cleaned up a redundant disjunct (>= 10M or >= 1M).
  • Removed unused DEFAULT_KEEP_UPPERCASE set, which also contained a latent
    missing-comma bug that concatenated two entries into one bogus token.
  • Malformed Raises: block in AwardResource.find_by_generated_id docstring.
  • Agency.id was missing its return-type annotation.
  • Lazy-fetch no longer fires when a key is present as None (prevents
    spurious API calls for null fields).
  • TextFormatter acronym expansion no longer leaks state across calls.
  • Minor filter bugs fixed in Location, Recipient, and Transaction filters.

Security

  • Binary downloads (_download_binary_file) now require https and a hostname
    on config.allowed_download_hosts, mitigating SSRF if API responses are
    tampered with.
  • File-backed cache directory is created at 0700 and tightened to 0700 if it
    already exists with looser bits. Protects the pickle-backed cache on shared
    hosts.
  • ZIP extraction: initial path-traversal protection landed earlier on main;
    this release further hardens it by creating the extract directory at 0700,
    detecting absolute paths via stdlib posixpath.isabs / ntpath.isabs (covers
    Windows drive letters and UNC prefixes), and using normpath-based prefix
    comparison in place of per-member realpath.

Full commit log:
v0.7.0...v0.7.1

Assets 2
Loading