Skip to content

README.md

Latest commit

 

History

History
198 lines (141 loc) · 5.62 KB

README.md

File metadata and controls

198 lines (141 loc) · 5.62 KB
Raw

amazon-linux-supportinfo

supportinfo is a Python library for parsing and querying Amazon Linux's package support metadata. It reads the support_info.xml documents Amazon Linux publishes and exposes the data through a typed Python API.

It is the parsing engine used by dnf-plugin-support-info to power dnf supportinfo --pkg <name> on Amazon Linux 2023.

Document formats

Two schemas are supported. The right handler is picked automatically from the root element's schema_version attribute.

Schema Detection Capabilities
Legacy (unversioned) No schema_version attribute Per-package supported / unsupported state with start/end dates
1.0 <package_support schema_version="1.0"> Adds named lifecycles, multiple support phases per lifecycle, support levels with severity scopes, milestones (named dates), package classes, and package origins (repo + signing key)

Both XSDs ship with the package under supportinfo/schemas/.

Requirements

  • Python 3.9 or newer
  • lxml and xmlschema (installed automatically)

Installation

The package is not yet on PyPI. Install from a checkout:

pip install .

Or for development:

pip install -e ".[test,dev]"

Usage

Loading a document

from supportinfo.handler import SupportinfoHandler

handler = SupportinfoHandler.create("/path/to/support_info.xml")

create validates the document against the matching XSD and returns either SupportinfoHandlerLegacy or SupportinfoHandlerV10. Both expose the same interface; the 1.0 handler adds methods for the richer metadata.

create raises FileNotFoundError if the file is missing and xmlschema.XMLSchemaValidationError if the file fails schema validation.

Looking up a single package

from datetime import date

# Returns SupportStatement, or None if the package is not in the document.
info = handler.get_package_support_info("kernel", day=date(2026, 6, 1))

if info is None:
    print("not in the support metadata")
else:
    # Legacy: 'supported', 'unsupported', or 'unknown'.
    # 1.0:    the phase name from the file (e.g. 'full_support').
    print(info.current_phase)

    # Phases the package transitions through, in chronological order.
    for name, phase in info.phases.items():
        print(name, phase.start_date)

For 1.0 documents, the same package can ship from more than one repository (for example, a curl in the core repo and a curl in an extras repo). Pass origin= to pick one, or call get_all_package_support_info to get every copy at once:

# 1.0 only. Raises ValueError if the package is in more than one origin
# and origin= is not given.
info = handler.get_package_support_info("curl", origin="al2023_core")

# 1.0 only. Returns Dict[origin_name, SupportStatement].
all_origins = handler.get_all_package_support_info("curl")

origin= is silently ignored for legacy documents.

Listing every package in a document

for entry in handler.get_package_entries():
    print(entry.name, entry.statement_id, entry.note_ref)

statement_id is the legacy statement ID or, for the 1.0 schema, the lifecycle name. note_ref is the per-package note ID for legacy and None for 1.0 (which attaches notes at the lifecycle level instead).

Bulk metadata

# Dict[id_or_lifecycle_name, SupportStatement]
metadata = handler.get_support_metadata(day=date(2027, 1, 1))
notes    = handler.get_support_notes()  # Dict[note_id, text]

1.0-only metadata

Available on SupportinfoHandlerV10. On the legacy handler, the lifecycle and milestone helpers return an empty list (or None if you asked for a specific name).

handler.get_lifecycle_info()                    # all lifecycles
handler.get_lifecycle_info("default_lc")        # one lifecycle, or None
handler.get_milestone_info()                    # all milestones
handler.get_milestone_info("AL2023_GA")
handler.get_support_level_info()                # all support levels
handler.get_support_level_info("default")

Detecting the schema version

from supportinfo.handler import SupportinfoSchemaVersions

if handler.schema_version is SupportinfoSchemaVersions.V1_0:
    print("1.0 schema")
else:
    print("legacy schema")

# Or get the raw string:
print(handler.schema_version.value)   # "1.0" or "unversioned"

For the full set of dataclasses (PackageEntry, PhaseInfo, SupportStatement, SupportLevelInfo, MilestoneInfo, LifecycleInfo, OriginInfo), see src/supportinfo/handler.py.

Development

Run the tests

pytest

Tests cover both schemas. Fixtures live under test/files/ and don't need Amazon Linux or network access.

Lint and format

flake8 src/ test/
black src/ test/
isort src/ test/
mypy src/

Configuration is in .flake8 and pyproject.toml.

Building an RPM (downstream packagers)

make sources
rpmbuild -ba \
  --define "_sourcedir $PWD" \
  --define "_srcrpmdir $PWD" \
  --define "_specdir $PWD" \
  python-supportinfo.spec

make sources writes python-supportinfo-<version>.tar.gz to the current directory; the --define flags tell rpmbuild to look for it there instead of the default ~/rpmbuild/SOURCES. The spec file targets Amazon Linux 2023 and produces python3-supportinfo as a noarch RPM.

Reporting security issues

Do not open a GitHub issue. Use AWS's vulnerability reporting page instead.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE and NOTICE.