From 9f2c59381303ad50079ac0b38a66fd828c86e8fa Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Tue, 21 Dec 2021 13:34:05 +0100 Subject: [PATCH 1/2] Metadata API: Remove Signed.bump_expiration() Remove `bump_expiration()` method, which is unlikely to be used as is, i.e. bump to "current expiration date plus delta". A more realistic use case is to bump to "now plus delta" (see #1727 for details). Moreover, bump_expiration can either way easily be replaced by a one-liner expression using the 'datetime' module. A corresponding code snippet is added to the `expires` property's docstring. Note: `expires` became a property with a millisec-removing setter (for spec conformance) in #1712, which further reduces the need for a convenience bump_expiration method. This patch also removes a related unit test and updates another one. Signed-off-by: Lukas Puehringer --- tests/test_api.py | 6 +----- tuf/api/metadata.py | 12 ++++++------ 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/tests/test_api.py b/tests/test_api.py index 6accd680bd..531d8f868c 100755 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -264,10 +264,6 @@ def test_metadata_base(self) -> None: md.signed.bump_version() self.assertEqual(md.signed.version, 2) self.assertEqual(md.signed.expires, datetime(2030, 1, 1, 0, 0)) - md.signed.bump_expiration() - self.assertEqual(md.signed.expires, datetime(2030, 1, 2, 0, 0)) - md.signed.bump_expiration(timedelta(days=365)) - self.assertEqual(md.signed.expires, datetime(2031, 1, 2, 0, 0)) # Test is_expired with reference_time provided is_expired = md.signed.is_expired(md.signed.expires) @@ -329,7 +325,7 @@ def test_metadata_verify_delegate(self) -> None: # verify fails when delegate content is modified expires = snapshot.signed.expires - snapshot.signed.bump_expiration() + snapshot.signed.expires = expires + timedelta(days=1) with self.assertRaises(exceptions.UnsignedMetadataError): root.verify_delegate(Snapshot.type, snapshot) snapshot.signed.expires = expires diff --git a/tuf/api/metadata.py b/tuf/api/metadata.py index f4bff9537b..68b6d4bebf 100644 --- a/tuf/api/metadata.py +++ b/tuf/api/metadata.py @@ -30,7 +30,7 @@ import logging import tempfile from collections import OrderedDict -from datetime import datetime, timedelta +from datetime import datetime from typing import ( IO, Any, @@ -409,6 +409,11 @@ def _type(self) -> str: @property def expires(self) -> datetime: + """The metadata expiry date:: + + # Use 'datetime' module to e.g. expire in seven days from now + obj.expires = utcnow() + timedelta(days=7) + """ return self._expires @expires.setter @@ -508,11 +513,6 @@ def is_expired(self, reference_time: Optional[datetime] = None) -> bool: return reference_time >= self.expires - # Modification. - def bump_expiration(self, delta: timedelta = timedelta(days=1)) -> None: - """Increments the expires attribute by the passed timedelta.""" - self.expires += delta - def bump_version(self) -> None: """Increments the metadata version number by 1.""" self.version += 1 From b754c37533409b12337bb57828ca838bef60b446 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Wed, 22 Dec 2021 11:33:02 +0100 Subject: [PATCH 2/2] doc: display inherited members on RTD Update sphinx/rtd conf to display inherited members. This is enabled specifically for the newly added `expires` property, which has a useful code snippet in the docstring. We don't display - them on the tuf.api automodule overview page (avoid duplicates) - members inherited from the built-in Exception class Signed-off-by: Lukas Puehringer --- docs/api/tuf.api.rst | 3 ++- docs/conf.py | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/api/tuf.api.rst b/docs/api/tuf.api.rst index d4309b843e..7d3126d23d 100644 --- a/docs/api/tuf.api.rst +++ b/docs/api/tuf.api.rst @@ -16,4 +16,5 @@ Metadata API tuf.api.serialization .. automodule:: tuf.api.metadata - :no-members: \ No newline at end of file + :no-members: + :no-inherited-members: diff --git a/docs/conf.py b/docs/conf.py index cb146ed917..a5314127e8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,5 +66,6 @@ autodoc_default_options = { 'members': True, + 'inherited-members': 'Exception', # excl. members inherited from 'Exception' 'exclude-members': 'to_dict, from_dict' -} \ No newline at end of file +}