Merge pull request #3 from jsickcodes/file-header

File header feature

Author: jonathansick

CHANGELOG.rst

@@ -4,7 +4,10 @@ Change log
 Unreleased
 ----------
 
-- ``--prefix`` argument allows you to customize the suffix of the plain text mirror.
+New configuration options from the command line:
+
+- ``--prefix`` option allows you to customize the suffix of the plain text mirror.
+- ``--header`` option allows you to add header content to the plain text file.
 
 0.1.0 (2021-03-18)
 ------------------

README.rst

@@ -119,5 +119,31 @@ However, you can customize the suffix of the file name by setting a ``--suffix``
        hooks:
          - id: docxplain
            args:
-             - "prefix"
+             - "--prefix"
              - ".extracted.txt"
+
+Plain text file header
+----------------------
+
+You can add a header to the plain text file's content by setting the ``--header`` command-line option
+This is useful for explaining that the file is autogenerated::
+
+   repos:
+     - repo: https://github.com/jsickcodes/pre-commit-docx-plain
+       rev: 0.2.0
+       hooks:
+         - id: docxplain
+           args:
+             - "--header"
+             - "THIS FILE IS AUTOGENERATED"
+
+You can also insert the name of the source docx file using Python format string syntax and the ``docx`` template variable::
+
+   repos:
+     - repo: https://github.com/jsickcodes/pre-commit-docx-plain
+       rev: 0.2.0
+       hooks:
+         - id: docxplain
+           args:
+             - "--header"
+             - "This file is autogenerated from {docx}. Do not edit."

src/docxplain/cli.py

@@ -23,5 +23,10 @@ def create_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--suffix", default=".txt", help="File suffix for plain text file."
     )
+    parser.add_argument(
+        "--header",
+        default=None,
+        help="Content to add to the top of the plain text file.",
+    )
 
     return parser

src/docxplain/converter.py

@@ -2,13 +2,16 @@
 
 import hashlib
 from pathlib import Path
+from typing import Optional
 
 import pypandoc
 
 __all__ = ["convert_file", "get_hash"]
 
 
-def convert_file(filename: str, suffix: str = ".txt") -> bool:
+def convert_file(
+    filename: str, suffix: str = ".txt", header: Optional[str] = None
+) -> bool:
     """Convert the docx file to plaintext.
 
     Parameters
@@ -19,6 +22,8 @@ def convert_file(filename: str, suffix: str = ".txt") -> bool:
         Suffix for the output plain text file, including ``"."`` prefix.
         Default is ``".txt"``, but a suffix like ``".extracted.txt"``
         could be useful.
+    header : `str`, optional
+        Content that is added to the top of the plain text file.
 
     Returns
     -------
@@ -38,15 +43,26 @@ def convert_file(filename: str, suffix: str = ".txt") -> bool:
 
     pypandoc.convert_file(str(docx_path), "plain", outputfile=str(plain_path))
 
+    if header:
+        insert_header(plain_path, header, docx_path.name)
+
     if exists:
         final_hash = get_hash(plain_path)
         return final_hash != initial_hash
     else:
         return True
 
 
+def insert_header(path: Path, header: str, docx_name: str) -> None:
+    """Add a header to the beginning of a plain text file."""
+    content = path.read_text()
+    context = {"docx": docx_name}
+    content = "\n\n".join((header.format(**context), content))
+    path.write_text(content)
+
+
 def get_hash(path: Path) -> str:
-    """Get the SHA256 hash diget of a file."""
+    """Get the SHA256 hash digest of a file."""
     m = hashlib.sha256()
     m.update(path.read_bytes())
     return m.hexdigest()

tests/converter_test.py

@@ -42,3 +42,33 @@ def test_suffix(tmp_path: Path) -> None:
     assert convert_file(str(docxpath), suffix=".extracted.txt") is True
     plain_path = work_dir.joinpath("test_doc.extracted.txt")
     assert plain_path.is_file()
+
+
+def test_header(tmp_path: Path) -> None:
+    """Test the case of a customized plain text file header."""
+    repo_data = Path(__file__).parent.joinpath("data/new")
+    work_dir = tmp_path / "header"
+    shutil.copytree(repo_data, work_dir)
+    docxpath = work_dir.joinpath("test_doc.docx")
+    header = "This file is autogenerated."
+    assert convert_file(str(docxpath), header=header) is True
+    plain_path = docxpath.with_suffix(".txt")
+    assert plain_path.is_file()
+    content = plain_path.read_text().splitlines()
+    assert content[0] == "This file is autogenerated."
+
+
+def test_header_templating(tmp_path: Path) -> None:
+    """Test the case of a templated custom file header that includes the
+    document name.
+    """
+    repo_data = Path(__file__).parent.joinpath("data/new")
+    work_dir = tmp_path / "header"
+    shutil.copytree(repo_data, work_dir)
+    docxpath = work_dir.joinpath("test_doc.docx")
+    header = "This file is autogenerated from {docx}."
+    assert convert_file(str(docxpath), header=header) is True
+    plain_path = docxpath.with_suffix(".txt")
+    assert plain_path.is_file()
+    content = plain_path.read_text().splitlines()
+    assert content[0] == "This file is autogenerated from test_doc.docx."