pyproject.toml

[build-system]
requires = ["flit_core >=3.9,<4"]
build-backend = "flit_core.buildapi"

[project]
name = "pypdf"
authors = [{ name = "Mathieu Fenniak", email = "biziqe@mathieu.fenniak.net" }]
maintainers = [{ name = "stefan6419846" }, { name = "Martin Thoma", email = "info@martin-thoma.de" }]
description = "A pure-python PDF library capable of splitting, merging, cropping, and transforming PDF files"
readme = "README.md"
dynamic = ["version"]
license = { file = "LICENSE" }
requires-python = ">=3.8"
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: BSD License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Operating System :: OS Independent",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Typing :: Typed",
]

dependencies = [
    "typing_extensions >= 4.0; python_version < '3.11'",
]

[project.urls]
Changelog = "https://pypdf.readthedocs.io/en/latest/meta/CHANGELOG.html"
Documentation = "https://pypdf.readthedocs.io/en/latest/"
Source = "https://github.com/py-pdf/pypdf"
"Bug Reports" = "https://github.com/py-pdf/pypdf/issues"

[project.optional-dependencies]
full = [
    "cryptography",
    "Pillow>=8.0.0",
]
crypto = [
    "cryptography",
]
cryptodome = [
    "PyCryptodome",
]
image = ["Pillow>=8.0.0"]
dev = ["black", "flit", "pip-tools", "pre-commit<2.18.0", "pytest-cov", "pytest-socket", "pytest-timeout", "pytest-xdist", "wheel"]
docs = ["myst_parser", "sphinx", "sphinx_rtd_theme"]

[tool.check-wheel-contents]
package = "./pypdf"

[tool.flit.sdist]
exclude = [
    ".gitblame-ignore-revs",
    ".github/*",
    ".gitignore",
    ".gitmodules",
    ".pre-commit-config.yaml",
    "docs/*",
    "make_release.py",
    "Makefile",
    "requirements/*",
    "sample-files/.github/*",
    "sample-files/.gitignore",
    "sample-files/.pre-commit-config.yaml",
    "tests/pdf_cache/*",
]
include = ["resources/", "tests/"]

[tool.pytest.ini_options]
addopts = "--disable-socket"
filterwarnings = ["error"]
markers = [
    "slow: Test which require more than a second",
    "samples: Tests which use files from https://github.com/py-pdf/sample-files",
    "enable_socket: Tests which need to download files"
]
testpaths = ["tests"]
norecursedirs = ["tests/pdf_cache"]

[tool.isort]
line_length = 79
indent = '    '
multi_line_output = 3
include_trailing_comma = true
known_third_party = ["pytest", "setuptools"]

[tool.coverage.run]
source = ["pypdf"]
branch = true

[tool.coverage.report]
# Regexes for lines to exclude from consideration
exclude_lines = [
    # Have to re-enable the standard pragma
    "pragma: no cover",
    "@overload",
    "deprecated",

    # Don't complain about type-checking code not being hit by unit tests
    "if TYPE_CHECKING",

    # Don't complain about missing debug-only code:
    "def __repr__",
    "def __str__",
    "if self\\.debug",

    # 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__.:",
]

[tool.ruff]
line-length = 120

[tool.ruff.lint]
select = ["ALL"]
ignore = [
    "A001",    # Variable is shadowing a Python builtin
    "A002",    # Function argument is shadowing a Python builtin
    "A005",    # Module shadows a Python standard-library module
    "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed
    "ARG001",  # Unused function argument
    "ARG002",  # Unused method argument
    "ARG003",  # Unused class method argument
    "ARG004",  # Unused static method argument
    "ARG005",  # Unused lambda argument
    "B028",    # No explicit `stacklevel` keyword argument found
    "B904",    # Within an `except` clause, raise exceptions with
    "B905",    # `zip()` without an explicit `strict=` parameter
    "BLE001",  # Do not catch blind exception: `Exception`
    "COM812",  # Yes, they make the diff smaller
    "D101",    # Missing docstring in public class
    "D102",    # Missing docstring in public method
    "D105",    # Missing docstring in magic method
    "D106",    # Missing docstring in public nested class
    "D107",    # Missing docstring in `__init__`
    "D205",    # One blank line required between summary line and description
    "D212",    # I want multiline-docstrings to start at the second line
    "D400",    # First line should end with a period
    "D401",    # First line of docstring should be in imperative mood - false positives
    "D404",    # First word of the docstring should not be "This"
    "D406",    # Section name should end with a newline ("Returns")
    "D415",    # First line should end with a period
    "D417",    # Missing argument descriptions in the docstring
    "DTZ001",  # The use of `datetime.datetime()` without `tzinfo` is necessary
    "EM101",   # Exception must not use a string literal, assign to variable first
    "EM102",   # Exception must not use an f-string literal, assign to variable first
    "ERA001",  # Found commented-out code
    "FA100",   # Missing `from __future__ import annotations`, but uses `typing.Dict`
    "FA102",   # Missing `from __future__ import annotations`, but uses PEP 604 union
    "FBT001",  # Boolean positional arg in function definition
    "FBT002",  # Boolean default value in function definition
    "FBT003",  # Boolean positional value in function call
    "FIX002",  # TODOs should typically not be in the code, but sometimes are ok
    "G004",    # f-string in logging statement
    "N806",    # non-lowercase-variable-in-function
    "N814",    # Camelcase `PageAttributes` imported as constant `PG`
    "N817",    # CamelCase `PagesAttributes` imported as acronym `PA`
    "PERF203", # `try`-`except` within a loop incurs performance overhead
    "PGH003",  # Use specific rule codes when ignoring type issues
    "PLC0206", # Extracting value from dictionary without calling `.items()`
    "PLW0603", # Using the global statement to update `CUSTOM_RTL_SPECIAL_CHARS` is discouraged
    "PLW1510", # `subprocess.run` without explicit `check` argument
    "PLW2901", # `with` statement variable `img` overwritten by assignment target
    "PT011",   # `pytest.raises(ValueError)` is too broad, set the `match`
    "PT012",   # `pytest.raises()` block should contain a single simple statement
    "PT014",   # Ruff bug: Duplicate of test case at index 1 in `@pytest_mark.parametrize`
    "PTH123",  # `open()` should be replaced by `Path.open()`
    "PYI042",  # Type alias `mode_str_type` should be CamelCase
    "RET501",  # Do not explicitly `return None` in function if it is the only possible return value
    "RET502",  # Do not implicitly `return None` in function able to return non-`None` value
    "RET503",  # Missing explicit `return` at the end of function able to return non-`None` value
    "RET504",  # Unnecessary assignment to `changelog` before `return`
    "RET505",  # Unnecessary `else` after `return` statement
    "RET506",  # Unnecessary `else` after `raise` statement
    "RET507",  # Unnecessary `else` after `continue` statement
    "RET508",  # Unnecessary `else` after `break` statement
    "RUF001",  # Detect confusable Unicode-to-Unicode units. Introduces bugs
    "RUF002",  # Detect confusable Unicode-to-Unicode units. Introduces bugs
    "RUF005",  # Detect confusable Unicode-to-Unicode units. Introduces bugs
    "S101",    # Use of `assert` detected
    "S110",    # `try`-`except`-`pass` detected, consider logging the exception
    "SIM105",  # contextlib.suppress
    "SIM108",  # Don't enforce ternary operators
    "SLF001",  # Private member accessed
    "TD002",   # Authors of TODOs can be found via git
    "TD003",   # For the moment, fix it later: Missing issue link on the line following this TODO
    "TD005",   # Missing issue description after `TODO`
    "TID252",  # We want relative imports
    "TRY002",  # Create your own exception
    "TRY003",  # Avoid specifying long messages outside the exception class
    "TRY004",  # Prefer `TypeError` exception for invalid type
    "TRY201",  # Use `raise` without specifying exception name
    "TRY300",  # Consider moving this statement to an `else` block
    "TRY301",  # Abstract `raise` to an inner function
    "UP006",   # Non-PEP 585 annotation. As long as we are not on Python 3.11+
    "UP007",   # Non-PEP 604 annotation. As long as we are not on Python 3.11+
    "UP031",   # Use format specifiers instead of percent format
    "UP035",   # PEP 585. As long as we are not on Python 3.9+
    "UP038",   # Use `X | Y` in `isinstance` call instead of `(X, Y)` - PEP 604. While not on Python 3.10+
]

[tool.ruff.lint.mccabe]
max-complexity = 54  # Recommended: 10

[tool.ruff.lint.per-file-ignores]
"_cryptography.py" = ["S304", "S305"]  # Use of insecure cipher / modes, aka RC4 and AES-ECB
"_encryption.py" = ["S324"]
"_writer.py" = ["S324"]
"docs/conf.py" = ["INP001", "PTH100"]
"json_consistency.py" = ["T201"]
"make_release.py" = ["S603", "S607", "T201"]
"pypdf/*" = ["N802", "N803"]  # We first need to deprecate old stuff
"sample-files/*" = ["D100", "INP001"]
"tests/*" = ["ANN001", "ANN201", "B017", "B018", "D103", "D104", "S105", "S106"]
"tests/test_workflows.py" =  ["T201"]

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

[tool.ruff.lint.pylint]
allow-magic-value-types = ["bytes", "float", "int", "str"]
max-args = 12  # Recommended: 5
max-branches = 36  # Recommended: 12
max-returns = 11  # Recommended: 6
max-statements = 176  # Recommended: 50

[tool.docformatter]
pre-summary-newline = true
wrap-summaries = 0
wrap-descriptions = 0

[tool.mypy]
show_error_codes = true
ignore_missing_imports = true
check_untyped_defs = true
disallow_any_generics = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_unused_configs = true
exclude = ['venv', '.venv', 'tests', 'make_release.py']