Merge pull request #24 from openSUSE/23-add-doctype.xpath

Fix #23: Add `.xpath` method to Doctype

Author: tomschr

changelog.d/23.feature.rst

@@ -0,0 +1 @@
+Support ``.xpath`` method in :class:`~docbuild.model.doctype.Doctype`

src/docbuild/models/doctype.py

@@ -15,10 +15,15 @@
 class Doctype(BaseModel):
     """A "doctype" that comprises of a product, docset, lifecycle, and language.
 
-    >>> Doctype.from_str("sles/15-SP6@supported/en-us,de-de")
-    Doctype(product=<Product.SLES: 'sles'>, docset=['15-SP6'], \
-    lifecycle=<LifecycleFlag.SUPPORTED: 'supported'>, \
-    langs=[LanguageCode(language='en-us'), LanguageCode(language='de-de')])
+    >>> doctype = Doctype.from_str("sles/15-SP6@supported/en-us,de-de")
+    >>> doctype.product
+    <Product.sles: 'sles'>
+    >>> doctype.docset
+    ['15-SP6']
+    >>> doctype.lifecycle.name
+    'supported'
+    >>> doctype.langs
+    [LanguageCode(language='de-de'), LanguageCode(language='en-us')]
     """
 
     # __init__.__doc__ = """Create a new Doctype instance.
@@ -222,3 +227,46 @@ def from_str(cls, doctype_str: str) -> Self:
             lifecycle=lifecycle,
             langs=langs,
         )
+
+    def xpath(self) -> str:
+        """Return an XPath expression for this Doctype to find all deliverables.
+
+        >>> result = Doctype.from_str("sles/15-SP6@supported/en-us,de-de").xpath()
+        >>> expected = (
+        ...     "product[@productid='sles']/docset[@setid='15-SP6']"
+        ...     "[@lifecycle='supported']"
+        ...     "/builddocs/language[@lang='de-de' or @lang='en-us']"
+        ... )
+        >>> result == expected
+        True
+
+        :return: A relative XPath expression that can be used to find all
+            deliverables that match this Doctype.
+        """
+        # Example: /sles/15-SP6@supported/en-us,de-de
+        product = f"product[@productid={self.product.value!r}]"
+        setids = [f'@setid={d!r}' for d in self.docset if d != '*']
+
+        setids_str = ' or '.join(setids)
+        if setids_str:
+            docset = f"docset[{setids_str}]"
+        else:
+            docset = 'docset'
+
+        lifecycle = ' or '.join(
+            [f'@lifecycle={lc.name!r}'
+             for lc in self.lifecycle
+             if lc != LifecycleFlag.UNKNOWN ]
+        )
+        if lifecycle:
+            docset += f"[{lifecycle}]"
+
+        if '*' in self.langs:
+            language = 'language'
+        else:
+            language = ' or '.join(
+                [f"@lang={lang.language!r}" for lang in self.langs]
+            )
+            language = f"language[{language}]"
+
+        return f'{product}/{docset}/builddocs/{language}'

tests/models/test_doctype.py

@@ -209,3 +209,55 @@ def test_sorted_langs_in_doctype_instantiation():
         langs=langs,
     )
     assert dt1.langs == sorted([LanguageCode(lang) for lang in langs])
+
+
+@pytest.mark.parametrize(
+    'string,xpath',
+    [
+        # 1: product + one docset + a single language
+        (
+            'sles/15-SP6/en-us',
+            (
+                "product[@productid='sles']"
+                "/docset[@setid='15-SP6']"
+                "/builddocs/language[@lang='en-us']"
+            ),
+        ),
+        # 2: product + all docsets + a single language
+        (
+            'sles//en-us',
+            ("product[@productid='sles']/docset/builddocs/language[@lang='en-us']"),
+        ),
+        # 3: product + one docset + one lifecycle + multiple languages
+        (
+            'sles/15-SP6@supported/en-us,de-de',
+            (
+                "product[@productid='sles']"
+                "/docset[@setid='15-SP6'][@lifecycle='supported']"
+                "/builddocs/language[@lang='de-de' or @lang='en-us']"
+            ),
+        ),
+        # 4: product + one docset + multiple lifecycles + one language
+        (
+            'sles/15-SP7@supported,beta/de-de',
+            (
+                "product[@productid='sles']"
+                "/docset[@setid='15-SP7'][@lifecycle='supported' or @lifecycle='beta']"
+                "/builddocs/language[@lang='de-de']"
+            ),
+        ),
+        # 5: product + one docset + multiple lifecycles + all languages
+        (
+            'sles/15-SP6@supported/*',
+            (
+                "product[@productid='sles']"
+                "/docset[@setid='15-SP6'][@lifecycle='supported']"
+                '/builddocs/language'
+            ),
+        ),
+    ],
+)
+def test_xpath_in_doctype(string, xpath):
+    """Test the XPath extraction from a Doctype."""
+    doctype = Doctype.from_str(string)
+    assert xpath == doctype.xpath()