pyproject.toml

# SPDX-FileCopyrightText: 2022 James R. Barlow
# SPDX-License-Identifier: MPL-2.0

[build-system]
requires = ["scikit-build-core>=0.10", "nanobind>=2.0"]
build-backend = "scikit_build_core.build"

[tool.scikit-build]
wheel.packages = ["src/pikepdf"]
cmake.build-type = "Release"
wheel.py-api = "cp314"
# The wheel-building CI jobs download qpdf's source into ./qpdf to compile
# libqpdf before building. Without this exclusion scikit-build-core sweeps that
# entire tree (~2900 Apache-2.0 files) into the sdist, which bloats it and
# misrepresents the sdist as containing third-party source. libqpdf is a build
# prerequisite, not part of pikepdf's source.
sdist.exclude = ["qpdf"]

[project]
name = "pikepdf"
version = "10.17.0"
description = "Read, write, repair, and transform PDFs in Python, powered by qpdf"
readme = "README.md"
requires-python = ">=3.11"
keywords = ["PDF"]
authors = [{ name = "James R. Barlow", email = "james@purplerock.ca" }]
license = "MPL-2.0"
# PEP 639. `license` above is pikepdf's own license and is what
# License-Expression declares; these files are additionally shipped in
# .dist-info/licenses/ and enumerated in License-File metadata. third-party-
# licenses/ covers the compiled libraries that auditwheel/delocate/delvewheel
# vendor into binary wheels -- see third-party-licenses/README.md for the
# component-to-license mapping. Setting this explicitly also replaces
# scikit-build-core's default license glob, which on case-insensitive Windows
# filesystems matched files it should not have.
license-files = ["LICENSE.txt", "third-party-licenses/*"]
classifiers = [
  "Development Status :: 5 - Production/Stable",
  "Intended Audience :: Developers",
  "Intended Audience :: Information Technology",
  "Programming Language :: C++",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: Implementation :: CPython",
  "Topic :: Multimedia :: Graphics",
  "Topic :: Software Development :: Libraries",
  "Programming Language :: Python :: Free Threading :: 3 - Stable",
]
dependencies = ["Pillow>=10.0.1", "lxml>=4.8", "packaging"]

[project.optional-dependencies]
pdfa = ["jsonschema>=4.18", "referencing", "fonttools>=4.40"]

[project.urls]
documentation = "https://pikepdf.readthedocs.io/"
repository = "https://github.com/pikepdf/pikepdf"
changelog = "https://pikepdf.readthedocs.io/en/latest/releasenotes/index.html"

[tool.cibuildwheel]
test-command = "pytest -nauto {project}/tests"
test-groups = ["test"]
# Reminder:
#   build.yml sets CIBW_BUILD to select what can be built
#   this file sets skip to deselect what cannot be built
skip = [
  "*-win32", # no 32-bit builds/not supported by Pillow anymore
]
# We publish cp314t free-threaded wheels (built by default now that 3.14
# free-threading is stable) but not cp313t: cp313t requires the
# `cpython-freethreading` enable group, which we deliberately leave disabled,
# so it is never built and needs no skip selector.
# Use plain `build` (pip-backed isolation) rather than `build[uv]`: the uv
# bundled into the manylinux/musllinux images has a regression where `uv pip
# install` into build's isolated env fails with "Failed to inspect Python
# interpreter from active virtual environment", deterministically breaking the
# x86_64 wheel builds. The isolated build deps are tiny (nanobind +
# scikit-build-core), so the speed cost is negligible.
build-frontend = "build"

[tool.cibuildwheel.environment]
QPDF_MIN_VERSION = "12.4.2"
QPDF_VERSION = "12.4.2"
QPDF_PATTERN = "https://github.com/qpdf/qpdf/releases/download/vVERSION/qpdf-VERSION.tar.gz"

[tool.cibuildwheel.linux]
before-all = [
  """yum install -y \
    libjpeg-turbo-devel \
    libxml2-devel \
    libxslt-devel \
    wget \
    zlib-devel \
  """,
  "sh -c 'yum install -y libxmp || true'",
  "bash build-scripts/posix-build-wheel-deps.bash",
]
# QPDF_CACHE_DIR lets before-all reuse a qpdf build cached by build.yml; the
# build script downloads and compiles qpdf itself on a cache miss.
environment-pass = ["CI", "QPDF_CACHE_DIR"]
# For manylinux_2_28 we need this shim for auditwheel
# https://github.com/pypa/auditwheel/pull/597
repair-wheel-command = "LD_LIBRARY_PATH=\"/usr/local/lib:/usr/local/lib64\" auditwheel repair -w {dest_dir} {wheel}"
manylinux-x86_64-image = "manylinux_2_28"
musllinux-x86_64-image = "musllinux_1_2"
musllinux-aarch64-image = "musllinux_1_2"

[[tool.cibuildwheel.overrides]]
select = "*-musllinux*"
before-all = [
  """apk add \
    cmake \
    exempi-dev \
    jpeg-dev \
    make \
    mupdf-tools \
    ninja \
    py3-lxml \
    py3-pillow \
    py3-wheel \
    python3 \
    python3-dev \
    wget \
    zlib-dev \
  """,
  "bash build-scripts/posix-build-wheel-deps.bash",
]

[tool.cibuildwheel.macos]
before-all = [
  "sh -c 'brew update || true'",
  "sh -c 'brew install gnutls little-cms2 mupdf wget || true'",
  "bash build-scripts/posix-download-qpdf.bash $QPDF_VERSION",
  "bash build-scripts/posix-build-wheel-deps.bash",
] # Use 'brew whatever || true' workaround until https://github.com/actions/setup-python/issues/9966 is fixed

[[tool.cibuildwheel.overrides]]
# macOS has many complex considerations.
# See (and update) build_process.md.
select = "*-macosx*arm64"
inherit.environment = "append"
environment.MACOSX_DEPLOYMENT_TARGET = "15.0"

[tool.cibuildwheel.windows]
before-build = "pip install delvewheel"
# delvewheel discovers qpdf30.dll's runtime dependencies via --add-path and vendors
# them into pikepdf.libs/ with name mangling. It excludes vcruntime140* by default
# (CPython ships its own copy) and name-mangles msvcp140.dll so it cannot shadow or
# collide with the system copy or another wheel's copy. This is what keeps the wheel
# self-contained without bundling a conflicting un-mangled runtime in the package
# directory, which previously caused issue #718. See win-download-qpdf.ps1, which
# publishes QPDF_DIR.
repair-wheel-command = "delvewheel repair --add-path %QPDF_DIR%/bin -w {dest_dir} {wheel}"

[[tool.cibuildwheel.overrides]]
# Windows does not build qpdf; win-download-qpdf.ps1 unpacks a prebuilt release
# to a runner-dependent location and exports QPDF_DIR.
select = "*-win*"
inherit.environment = "append"
environment.QPDF_SOURCE_TREE = "$QPDF_DIR"
environment.QPDF_BUILD_LIBDIR = "$QPDF_DIR/lib"

[tool.mypy]
exclude = ["^_qpdf\\.py$"]

[[tool.mypy.overrides]]
module = ["fontTools", "fontTools.*", "jsonschema", "jsonschema.*"]
ignore_missing_imports = true

[tool.pytest.ini_options]
minversion = "6.0"
norecursedirs = [
  "*.egg",
  ".*",
  "lib",
  "_darcs",
  "dist",
  "build",
  "node_modules",
  "venv",
  "{arch}",
]
testpaths = ["tests"]
addopts = "-n auto"
markers = [
  "slow: tests that take more than a few seconds; skip with `-m 'not slow'`.",
  "abi3_smoke: a small subset of tests that exercise pikepdf's C extension surface without touching optional Pillow/lxml/numpy runtime paths. Selected with `-m abi3_smoke` for the abi3 debug-Python CI job (where building those native deps from sdist is impractical). Default pytest runs include these tests like any other.",
]

[tool.coverage.run]
concurrency = ["multiprocessing"]

[tool.coverage.report]
# Regexes for lines to exclude from consideration
exclude_lines = [
  # Have to re-enable the standard pragma
  "pragma: no cover",
  # Don't complain if tests don't hit defensive assertion code:
  "raise AssertionError",
  "raise NotImplementedError",
  # Don't complain if non-runnable code isn't run:
  "if 0:",
  "if __name__ == .__main__.:",
  "if TYPE_CHECKING:",
  "if typing.TYPE_CHECKING:",
]

[tool.coverage.html]
directory = "coverage/pycov"

[tool.ruff]
src = ["src/pikepdf"]
target-version = "py311"

[tool.ruff.lint]
select = [
  "D",    # pydocstyle
  "E",    # pycodestyle
  "W",    # pycodestyle
  "F",    # pyflakes
  "I001", # isort
  "TID",  # flake8-tidy-imports
  "UP",   # pyupgrade
  "YTT",  # flake8-2020
]
ignore = ["D105", "B028"]

[tool.ruff.lint.flake8-tidy-imports]
ban-relative-imports = "all"
banned-module-level-imports = ["numpy"]

[tool.ruff.lint.isort]
known-first-party = ["pikepdf", "pikepdf._core"]
known-third-party = [
  "PIL",
  "conftest",
  "hypothesis",
  "lxml",
  "psutil",
  "pytest",
  "setuptools",
]
required-imports = ["from __future__ import annotations"]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.per-file-ignores]
"**/*.ipynb" = ["D", "E", "F"]
"bin/bump_version.py" = ["E501"]
"docs/*.py" = ["D", "E501", "E402", "F401"]
"examples/*.py" = ["D103"]
"fuzzing/*.py" = ["D", "E501"]
"tests/*test*.py" = ["D", "E501"]
"tests/test_pdfa_*.py" = ["D", "E402", "E501"]

[tool.ruff.format]
quote-style = "preserve"

[dependency-groups]
dev = [
  "clang-format==22.1.5",
  "cyclopts",
  "mypy",
  "prek",
  "pygithub",
  "ruff>=0.12.9",
  "setuptools>=80.9.0",
  { include-group = "build" },
  { include-group = "mypy" },
  { include-group = "test" },
]
# Mirrors [build-system].requires, so that `uv run` keeps these installed for
# `make build`, which builds without isolation.
build = ["nanobind>=2.0", "scikit-build-core>=0.10"]
docs = [
  "myst-parser>=3.0.1",
  "sphinx>=3",
  "sphinx-autoapi",
  "sphinx-design",
  "sphinx-issues",
  "sphinx-rtd-theme",
]
mypy = ["lxml-stubs", "types-Pillow", "types-requests", "types-setuptools"]
test = [
  "attrs>=20.2.0",
  "coverage[toml]",
  "fonttools>=4.40",
  "jsonschema>=4.18",
  "referencing",
  "hypothesis>=6.36",
  "numpy>=1.21.0; platform_machine == 'x86_64' and platform_python_implementation == 'CPython'",
  "psutil>=5.9; os_name != 'nt'",
  "nanobind",
  "pytest>=6.2.5",
  "pytest-cov>=3.0.0",
  "pytest-timeout>=2.1.0",
  "pytest-xdist>=2.5.0",
  "python-dateutil>=2.8.1",
  "python-xmp-toolkit>=2.0.1,<2.1.0; os_name != 'nt' and platform_machine == 'x86_64'",
]