Skip to content

MAINT: Use PEP 8 names in the encryption module - #4436

Open
zeyadrabie wants to merge 2 commits into
py-pdf:mainfrom
zeyadrabie:pep8-encryption-names
Open

zeyadrabie wants to merge 2 commits into
py-pdf:mainfrom
zeyadrabie:pep8-encryption-names

Conversation

@zeyadrabie

@zeyadrabie zeyadrabie commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Part of #3231.

Renames the internal functions, arguments, locals, and attributes in pypdf/_encryption.py to full PEP 8 names (keeping the PDF keys in comments/docstrings), converts EncryptionValues to a dataclass, and fixes four AlgV4 docstrings that said key_size was in bytes instead of bits. Nothing public exposes these classes or attributes, so no deprecation is needed.

Also renames PdfReader._ID and PdfWriter._ID to _file_identifiers and removes the "pypdf/*" = ["N802", "N803"] ignore from pyproject.toml. ViewerPreferences.PRINT_SCALING keeps a # noqa: N802 for now since it's public and needs a separate deprecation PR.

AI assistance: Used Claude Code (Claude Opus 5.5) to script the renames, apply the edits, and run the checks; I reviewed the diff myself.

@codecov

codecov Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.21%. Comparing base (d7f50bf) to head (2db52d2).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #4436   +/-   ##
=======================================
  Coverage   99.21%   99.21%           
=======================================
  Files          59       59           
  Lines       12425    12427    +2     
  Branches     2368     2368           
=======================================
+ Hits        12328    12330    +2     
  Misses         42       42           
  Partials       55       55           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.


@property
def PRINT_SCALING(self) -> NameObject:
def PRINT_SCALING(self) -> NameObject: # noqa: N802

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have the feeling that we will forget to migrate this properly. We should probably deprecate this without a replacement for now, until we use named constants everywhere.

Do you think you can do this in this PR, or do we need another PR for this?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll handle this in a separate deprecation PR once this merges and keep the noqa for now.

Comment thread pypdf/_encryption.py Outdated

@staticmethod
def compute_O_value_key(owner_password: bytes, rev: int, key_size: int) -> bytes:
def compute_o_value_key(owner_password: bytes, revision: int, key_size: int) -> bytes:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the short o? As far as I understand, this is the "owner password", thus we could name it compute_owner_password_value_key?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, renamed to compute_owner_password_value_key and updated the other short o/u names in the file to match.

Comment thread pypdf/_encryption.py Outdated

@staticmethod
def compute_O_value(rc4_key: bytes, user_password: bytes, rev: int) -> bytes:
def compute_o_value(rc4_key: bytes, user_password: bytes, revision: int) -> bytes:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See above.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed to compute_owner_password_value.

Comment thread pypdf/_encryption.py Outdated

@staticmethod
def compute_U_value(key: bytes, rev: int, id1_entry: bytes) -> bytes:
def compute_u_value(key: bytes, revision: int, id1_entry: bytes) -> bytes:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See above.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed to compute_user_password_value.

Comment thread pypdf/_encryption.py Outdated

@staticmethod
def compute_Perms_value(key: bytes, p: int, metadata_encrypted: bool) -> bytes:
def compute_perms_value(key: bytes, permissions: int, metadata_encrypted: bool) -> bytes:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we already use permissions for the P value everywhere, shouldn't we align this name here as well?

Suggested change
def compute_perms_value(key: bytes, permissions: int, metadata_encrypted: bool) -> bytes:
def compute_permissions_value(key: bytes, permissions: int, metadata_encrypted: bool) -> bytes:

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Comment thread pypdf/_encryption.py
@@ -864,11 +864,11 @@ class EncryptAlgorithm(tuple, Enum): # type: ignore[type-arg] # noqa: SLOT001


class EncryptionValues:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest two changes here:

  • Make this a dataclass.
  • Use full names instead of abbreviations again.

According to section 7.6.4.4.1 of ISO 32000-2:2020, the following verbose names can be used:

The computation of the values for the O (owner password) and the U (user password) entries for encryption revision 4 and earlier, and the O, U, OE (owner encryption), UE (user encryption) and Perms (permissions) values for encryption revision 6 require more explanation.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Switched it to a dataclass and kept the _value suffix so the fields don't clash with the actual passwords and permissions in the same methods.

Comment thread pypdf/_encryption.py Outdated
when the document is opened with user access
entry: The encryption dictionary object.
EncryptMetadata: Whether to encrypt metadata in the document.
metadata_encrypted: Whether to encrypt metadata in the document.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To better indicate that this is a condition, I would keep encrypt_metadata as name.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Switched back to encrypt_metadata everywhere.

Comment thread pypdf/_reader.py Outdated

@property
def _ID(self) -> ArrayObject | None:
def _ID(self) -> ArrayObject | None: # noqa: N802

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why aren't we renaming this, but ignore it? We will forget about this, unless we open a dedicated issue for it. (Similar to PRINT_SCALING, which is public, but used less often in our code.)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed to _file_identifiers on both PdfReader and PdfWriter.

Rename the uppercase functions, arguments and attributes in pypdf/_encryption.py and stop ignoring Ruff N802 and N803 for pypdf/.

Part of py-pdf#3231.
Rename the remaining short names, make EncryptionValues a dataclass, keep encrypt_metadata and rename _ID to _file_identifiers.
@zeyadrabie
zeyadrabie force-pushed the pep8-encryption-names branch from 68d0139 to 2db52d2 Compare November 20, 2026 03:04

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants