Expanded many docstrings, sanitized pyproject.toml

Author: deeplook

CHANGELOG.rst

@@ -3,6 +3,15 @@
 ChangeLog
 =========
 
+1.6.0 (2025-09-25)
+------------------
+- Replace setup.py with pyproject.toml, rework GitHub workflows (#405).
+- Drop support for Python 3.8.
+- Modernize codebase, added type annotations, expanded docstrings, etc.
+- Add a Makefile.
+- Add publishing workflows.
+- Remove dunder constants and use importlib.metadata to get the version number.
+
 1.5.1 (2023-01-07)
 ------------------
 - Final fix to conversion from shorthand quadratic to cubic bézier (#372).

Makefile

@@ -38,7 +38,7 @@ hooks:  ## Run all pre-commit hooks.
 	uv run pre-commit run --all-files
 
 .PHONY: all
-all: install lint hooks test ## Run all checks (install, lint, test).
+all: lint typecheck hooks test ## Run all checks (lint, typecheck, hookstest).
 
 .PHONY: dist
 dist: ## Build the package for distribution.

README.rst

@@ -149,9 +149,6 @@ the system command-line. Here is the output from ``svg2pdf -h``::
     issues/pull requests:
         https://github.com/deeplook/svglib
 
-    Copyleft by Dinu Gherman, 2008-2021 (LGPL 3):
-        http://www.gnu.org/copyleft/gpl.html
-
 
 Dependencies
 ------------
@@ -235,19 +232,20 @@ in the ``tests`` directory. There, in ``tests/README.rst``, you can
 also read more about testing. You can run the testsuite e.g. like
 shown in the following lines on the command-line::
 
-    $ tar xfz svglib-<version>.tar.gz
-    $ cd svglib-<version>
-    $ PYTHONPATH=. py.test
-    ======================== test session starts =========================
-    platform darwin -- Python 3.7.3, pytest-5.0.1, py-1.8.0, pluggy-0.12.0
-    rootdir: /Users/dinu/repos/github/deeplook/svglib, inifile:
-    plugins: cov-2.4.0
-    collected 36 items
+    $ make test
+    ========================= test session starts =========================
+    platform darwin -- Python 3.9.6, pytest-8.4.2, pluggy-1.6.0
+    rootdir: /Users/dinu/dev/svglib
+    configfile: pyproject.toml
+    plugins: cov-7.0.0
+    collected 115 items
 
-    tests/test_basic.py ............................
-    tests/test_samples.py .s.s.s.s
+    tests/test_basic.py ............................................ [ 43%]
+    ..................                                               [ 53%]
+    tests/test_fonts.py ............s.....................s.....     [ 88%]
+    tests/test_samples.py .s.s.s.s.....                              [100%]
 
-    =============== 32 passed, 4 skipped in 49.18 seconds ================
+    ============== 109 passed, 6 skipped, 1 warning in 33.32s =============
 
 
 Bug reports

pyproject.toml

@@ -3,9 +3,7 @@ name = "svglib"
 version = "1.6.0"
 description = "A pure-Python library for reading and converting SVG"
 readme = "README.rst"
-authors = [
-    { name = "Dinu Gherman", email = "gherman@darwin.in-berlin.de" },
-]
+authors = [{ name = "Dinu Gherman" }]
 keywords = [
     "SVG",
     "PDF",
@@ -62,12 +60,13 @@ build-backend = "hatchling.build"
 
 [project.optional-dependencies]
 dev = [
+    "mypy>=1.18.1",
     "pre-commit>=4.3.0",
     "pytest>=8.3.5",
     "pytest-cov>=7.0.0",
     "pytest-runner>=6.0.1",
     "ruff>=0.13.0",
-    "tox>=4.0.0",
+    "tox>=4.30.2",
 ]
 
 [tool.ruff]
@@ -82,9 +81,3 @@ select = [
 
 [tool.ruff.format]
 quote-style = "double"
-
-[dependency-groups]
-dev = [
-    "mypy>=1.18.1",
-    "tox>=4.30.2",
-]

src/svglib/__init__.py

@@ -1,22 +1,76 @@
-"""A simple converter from SVG to PDF.
+"""A tool for converting SVG to PDF.
 
-For further information please check the file README.txt!
+This module provides a high-level function for converting SVG files to PDF format
+using the ReportLab graphics library. It also serves as the main entry point for
+the svglib package.
+
+The module includes:
+- svg2pdf(): Convert SVG files to PDF programmatically.
+- main(): Command-line interface for SVG to PDF conversion.
+- Automatic file path handling and output generation.
 """
 
 import argparse
 import sys
 import textwrap
 from datetime import datetime
+from importlib.metadata import PackageNotFoundError, version
 from os.path import basename, dirname, exists, splitext
 from typing import Optional
 
 from reportlab.graphics import renderPDF
 
 from svglib import svglib
 
+try:
+    __version__ = version("svglib")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
 
 def svg2pdf(path: str, outputPat: Optional[str] = None) -> None:
-    "Convert an SVG file to a PDF one."
+    """Convert an SVG file to PDF format.
+
+    High-level function that loads an SVG file, converts it to a ReportLab drawing,
+    and saves it as a PDF file. Supports both .svg and .svgz (compressed SVG) files.
+
+    Args:
+        path: Path to the input SVG file (.svg or .svgz extension).
+        outputPat: Optional output path pattern. Supports placeholders:
+            - %(dirname)s: Directory of input file
+            - %(basename)s: Full filename with extension
+            - %(base)s: Filename without extension
+            - %(ext)s: File extension
+            - %(now)s: Current datetime object
+            - %(format)s: Output format (always "pdf")
+            Also supports {name} format strings.
+
+    Returns:
+        None. The PDF file is written to disk.
+
+    Raises:
+        FileNotFoundError: If the input SVG file does not exist.
+        Exception: If SVG parsing or PDF generation fails.
+        OSError: If the output directory is not writable.
+
+    Examples:
+        Basic conversion:
+        >>> svg2pdf("input.svg")  # Creates "input.pdf"
+
+        Custom output location:
+        >>> svg2pdf("input.svg", "output.pdf")
+
+        Using placeholders:
+        >>> svg2pdf("path/file.svg", "%(dirname)s/converted/%(base)s.pdf")
+        # Creates "path/converted/file.pdf"
+
+        Timestamped output:
+        >>> svg2pdf("file.svg", "backup/%(now.year)s-%(now.month)s-%(base)s.pdf")
+
+    Note:
+        The function will overwrite existing PDF files without warning.
+        For compressed SVG files (.svgz), the file is automatically decompressed.
+    """
 
     # derive output filename from output pattern
     file_info = {
@@ -52,10 +106,7 @@ def main() -> None:
     ext_caps = ext.upper()
     format_args = dict(
         prog=basename(sys.argv[0]),
-        version=svglib.__version__,
-        author=svglib.__author__,
-        license=svglib.__license__,
-        copyleft_year=str(datetime.now().year),
+        version=__version__,
         ts_pattern="{{dirname}}/out-"
         "{{now.hour}}-{{now.minute}}-{{now.second}}-"
         "%(base)s",
@@ -87,9 +138,7 @@ def main() -> None:
 
         issues/pull requests:
             https://github.com/deeplook/svglib
-
-        Copyleft by {author}, 2008-{copyleft_year} ({license}):
-            https://www.gnu.org/licenses/lgpl-3.0.html""".format(**format_args)
+        """.format(**format_args)
     )
     p = argparse.ArgumentParser(
         description=desc,
@@ -119,7 +168,7 @@ def main() -> None:
     args = p.parse_args()
 
     if args.version:
-        print(svglib.__version__)
+        print(__version__)
         sys.exit()
 
     if not args.input: