Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOC: Correct threads reference, plus minor changes #2521

Merged
merged 3 commits into from
Mar 15, 2024
Merged

DOC: Correct threads reference, plus minor changes #2521

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aeaf065
DOC: Correct threads reference, plus minor changes
j-t-1 Mar 15, 2024
13878af
DOC: Correct threads reference, plus minor changes
j-t-1 Mar 15, 2024
5e35cc8
fix broken link
stefan6419846 Mar 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
24 changes: 12 additions & 12 deletions pypdf/_reader.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -276,7 +276,7 @@ class PdfReader:
Defaults to ``False``.
password: Decrypt PDF file at initialization. If the
password is None, the file will not be decrypted.
Defaults to ``None``
Defaults to ``None``.
"""

@property
Expand Down Expand Up @@ -419,9 +419,9 @@ def metadata(self) -> Optional[DocumentInformation]:
"""
Retrieve the PDF file's document information dictionary, if it exists.

Note that some PDF files use metadata streams instead of docinfo
dictionaries, and these metadata streams will not be accessed by this
function.
Note that some PDF files use metadata streams instead of document
information dictionaries, and these metadata streams will not be
accessed by this function.
"""
if TK.INFO not in self.trailer:
return None
Expand All @@ -447,7 +447,7 @@ def _get_num_pages(self) -> int:
Calculate the number of pages in this PDF file.

Returns:
The number of pages of the parsed PDF file
The number of pages of the parsed PDF file.

Raises:
PdfReadError: if file is encrypted and restrictions prevent
Expand Down Expand Up @@ -505,7 +505,7 @@ def get_fields(
tree:
retval:
fileobj: A file object (usually a text file) to write
a report to on all interactive form fields found.
a report of all interactive form fields found.

Returns:
A dictionary where each key is a field name, and each
Expand Down Expand Up @@ -658,7 +658,7 @@ def get_form_text_fields(self, full_qualified_name: bool = False) -> Dict[str, A
Retrieve form fields from the document with textual data.

Args:
full_qualified_name: to get full name
full_qualified_name: to get full name.

Returns:
A dictionary. The key is the name of the form field,
Expand Down Expand Up @@ -698,7 +698,7 @@ def get_pages_showing_field(
Provides list of pages where the field is called.

Args:
field: Field Object, PdfObject or IndirectObject referencing a Field
field: Field Object, PdfObject or IndirectObject referencing a Field.

Returns:
List of pages:
Expand Down Expand Up @@ -887,9 +887,9 @@ def threads(self) -> Optional[ArrayObject]:
"""
Read-only property for the list of threads.

See §8.3.2 from PDF 1.7 spec.
See §12.4.3 of the PDF 1.7 or PDF 2.0 specification.
stefan6419846 marked this conversation as resolved.
Show resolved Hide resolved

It's an array of dictionaries with "/F" and "/I" properties or
An array of dictionaries with "/F" and "/I" properties or
None if there are no articles.
"""
catalog = self.root_object
Expand Down Expand Up @@ -934,7 +934,7 @@ def get_page_number(self, page: PageObject) -> Optional[int]:
an instance of :class:`PageObject<pypdf._page.PageObject>`

Returns:
The page number or None if page is not found
The page number or None if page is not found.
"""
return self._get_page_number_by_indirect(page.indirect_reference)

Expand All @@ -946,7 +946,7 @@ def get_destination_page_number(self, destination: Destination) -> Optional[int]
destination: The destination to get page number.

Returns:
The page number or None if page is not found
The page number or None if page is not found.
"""
return self._get_page_number_by_indirect(destination.page)

Expand Down
47 changes: 24 additions & 23 deletions pypdf/_writer.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,8 @@ def _rolling_checksum(stream: BytesIO, blocksize: int = 65536) -> str:

class PdfWriter:
"""
Write a PDF file out, given pages produced by another class.
Write a PDF file out, given pages produced by another class or through
cloning a PDF file during initialization.

Typically data is added from a :class:`PdfReader<pypdf.PdfReader>`.
"""
Expand Down Expand Up @@ -214,10 +215,10 @@ def __init__(
@property
def root_object(self) -> DictionaryObject:
"""
Provide direct access to Pdf Structure
Provide direct access to Pdf Structure.

Note:
Recommended be used only for read access
Recommended be used only for read access.
"""
return self._root_object

Expand Down Expand Up @@ -463,11 +464,11 @@ def pages(self) -> List[PageObject]:
Property that emulates a list of :class:`PageObject<pypdf._page.PageObject>`.
this property allows to get a page or a range of pages.

It provides also capability to remove a page/range of page from the list
(through del operator)
Note: only the page entry is removed. As the objects beneath can be used
somewhere else.
a solution to completely remove them - if they are not used somewhere -
It also provides capability to remove a page or range of pages from
the list (through del operator).
Note: only the page entry is removed, as the objects beneath can be used
elsewhere.
A solution to completely remove them - if they are not used somewhere -
is to write to a buffer/temporary and to then load it into a new PdfWriter
object.
"""
Expand All @@ -477,7 +478,7 @@ def add_blank_page(
self, width: Optional[float] = None, height: Optional[float] = None
) -> PageObject:
"""
Append a blank page to this PDF file and returns it.
Append a blank page to this PDF file and return it.

If no page size is specified, use the size of the last page.

Expand All @@ -504,7 +505,7 @@ def insert_blank_page(
index: int = 0,
) -> PageObject:
"""
Insert a blank page to this PDF file and returns it.
Insert a blank page to this PDF file and return it.

If no page size is specified, use the size of the last page.

Expand All @@ -516,7 +517,7 @@ def insert_blank_page(
index: Position to add the page.

Returns:
The newly appended page
The newly appended page.

Raises:
PageSizeNotDefinedError: if width and height are not defined
Expand Down Expand Up @@ -580,7 +581,7 @@ def open_destination(self, dest: Union[None, str, Destination, PageObject]) -> N

def add_js(self, javascript: str) -> None:
"""
Add Javascript which will launch upon opening this PDF.
Add JavaScript which will launch upon opening this PDF.

Args:
javascript: Your Javascript.
Expand Down Expand Up @@ -715,7 +716,7 @@ def append_pages_from_reader(
Args:
reader: a PdfReader object from which to copy page
annotations to this writer object. The writer's annots
will then be updated
will then be updated.
after_page_append:
Callback function that is invoked after each page is appended to
the writer. Signature includes a reference to the appended page
Expand Down Expand Up @@ -891,12 +892,12 @@ def update_page_form_field_values(
page: Page reference from PDF writer where the
annotations and field data will be updated.
fields: a Python dictionary of field names (/T) and text
values (/V)
values (/V).
flags: An integer (0 to 7). The first bit sets ReadOnly, the
second bit sets Required, the third bit sets NoExport. See
PDF Reference Table 8.70 for details.
auto_regenerate: set/unset the need_appearances flag ;
the flag is unchanged if auto_regenerate is None
the flag is unchanged if auto_regenerate is None.
"""
if CatalogDictionary.ACRO_FORM not in self._root_object:
raise PyPdfError("No /AcroForm dictionary in PdfWriter Object")
Expand Down Expand Up @@ -970,13 +971,13 @@ def reattach_fields(
) -> List[DictionaryObject]:
"""
Parse annotations within the page looking for orphan fields and
reattach then into the Fields Structure
reattach then into the Fields Structure.

Args:
page: page to analyze.
If none is provided, all pages will be analyzed
If none is provided, all pages will be analyzed.
Returns:
list of reattached fields
list of reattached fields.
"""
lst = []
if page is None:
Expand Down Expand Up @@ -1197,7 +1198,7 @@ def generate_file_identifiers(self) -> None:
Generate an identifier for the PDF that will be written.

The only point of this is ensuring uniqueness. Reproducibility is not
required;
required.
When a file is first written, both identifiers shall be set to the same value.
If both identifiers match when a file reference is resolved, it is very
likely that the correct and unchanged file has been found. If only the first
Expand Down Expand Up @@ -1240,8 +1241,8 @@ def encrypt(
Bit position 3 is for printing, 4 is for modifying content,
5 and 6 control annotations, 9 for form fields,
10 for extraction of text and graphics.
algorithm: encrypt algorithm. Values maybe one of "RC4-40", "RC4-128",
"AES-128", "AES-256-R5", "AES-256". If it's valid,
algorithm: encrypt algorithm. Values may be one of "RC4-40", "RC4-128",
"AES-128", "AES-256-R5", "AES-256". If it is valid,
`use_128bit` will be ignored.
"""
if owner_password is None:
Expand Down Expand Up @@ -1292,7 +1293,7 @@ def write(self, stream: Union[Path, StrByteType]) -> Tuple[bool, IO[Any]]:
Write the collection of pages added to this object out as a PDF file.

Args:
stream: An object to write the file to. The object can support
stream: An object to write the file to. The object can support
the write method and the tell method, similar to a file object, or
be a file path, just like the fileobj, just named it stream to keep
existing workflow.
Expand Down Expand Up @@ -1564,7 +1565,7 @@ def get_threads_root(self) -> ArrayObject:
"""
The list of threads.

See §8.3.2 from PDF 1.7 spec.
See §12.4.3 of the PDF 1.7 or PDF 2.0 specification.
stefan6419846 marked this conversation as resolved.
Show resolved Hide resolved

Returns:
An array (possibly empty) of Dictionaries with ``/F`` and
Expand Down