Added convenience method DocDetails.make_filename (#1006)

Author: jamesbraza

paperqa/types.py

@@ -531,7 +531,13 @@ class DocDetails(Doc):
     )
     doi: str | None = None
     doi_url: str | None = None
-    doc_id: str | None = None
+    doc_id: str | None = Field(
+        default=None,
+        description=(
+            "Unique ID for this document. Simple ways to acquire one include"
+            " hashing the DOI or a stringifying a UUID."
+        ),
+    )
     file_location: str | os.PathLike | None = None
     license: str | None = Field(
         default=None,
@@ -811,6 +817,29 @@ def __getitem__(self, item: str):
         except AttributeError:
             return self.other[item]
 
+    def make_filename(self, title_limit: int | None = 48) -> str:
+        """
+        Make a filesystem-safe filename that has the doc ID appended, but no extension.
+
+        Args:
+            title_limit: Character limit on the title.
+
+        Returns:
+            Filename that is filesystem safe (e.g. non-safe chars are replaced with dash).
+        """
+        if not self.title or not self.doc_id:
+            raise ValueError("Unable to create filename without both title and doc_id.")
+        # SEE: https://stackoverflow.com/a/71199182
+        encoded_title = re.sub(
+            r"[/\\?%*:|\"<>\x7F\x00-\x1F]", "-", self.title[:title_limit]
+        )
+        # NOTE: we append the doc ID for a few reasons:
+        # 1. Prevent collisions for identical titles
+        #    SEE: https://stackoverflow.com/a/71761675
+        # 2. Filenames shouldn't end in a period,
+        #    so append the doc ID to circumvent that gotcha
+        return "_".join((encoded_title, self.doc_id))
+
     @computed_field  # type: ignore[prop-decorator]
     @property
     def formatted_citation(self) -> str:

tests/test_paperqa.py

@@ -1551,6 +1551,7 @@ def test_docdetails_doc_id_roundtrip() -> None:
     # now let's do this with a doi
     doc_details_with_doi_no_doc_id = DocDetails(
         doi=test_doi,
+        title=r"A Stub | \emph{Stub Title}",
         docname="test_doc",
         citation="Test Citation",
         dockey="test_dockey",
@@ -1566,6 +1567,10 @@ def test_docdetails_doc_id_roundtrip() -> None:
     assert (
         doc_details_with_doi_no_doc_id.dockey == doc_details_with_doi_no_doc_id.doc_id
     )
+    assert (
+        doc_details_with_doi_no_doc_id.make_filename()
+        == "A Stub - -emph{Stub Title}_7f8a71c920c202c5"
+    )
 
     # round-trip serializaiton should keep the same doc_id
     new_with_doi_no_doc_id = DocDetails(
@@ -1574,6 +1579,10 @@ def test_docdetails_doc_id_roundtrip() -> None:
     assert (
         new_with_doi_no_doc_id.doc_id == doc_details_with_doi_no_doc_id.doc_id
     ), "DocDetails with doc_id should keep the same doc_id after serialization"
+    assert (
+        new_with_doi_no_doc_id.make_filename()
+        == "A Stub - -emph{Stub Title}_7f8a71c920c202c5"
+    )
 
     # since validation runs on assignment, make sure we can assign correctly
     doc_details_with_doi_no_doc_id.doc_id = test_specified_doc_id