소개
Aspose.PDF FOSS for Python은(는) 구조적이고 문서 수준의 편집을 위한 진입점으로 Document 클래스를 중심으로 하며, 이 클래스는 pages, form, outlines, tagged_content, attachments를 노출합니다. 페이지 내용을 추가하는 것 외에도, 이 라이브러리는 PDF를 완전하고 배포 가능한 아티팩트로 만드는 작업을 다룹니다: 구조화된 데이터를 수집하고 노출하는 인터랙티브 양식 필드, 문서 수준 파일 첨부, 텍스트 저작을 위한 글꼴 검색 및 임베딩, 그리고 탐색을 위한 북마크 트리. 이러한 모든 영역은 AsposePdfException을 루트로 하는 단일 예외 계층을 통해 오류를 발생시키므로, 호출자는 모듈별로 예외 유형을 추측하지 않고도 패키지 전용 실패를 잡을 수 있습니다.
이 가이드는 해당 문서 관리 인터페이스를 사용하는 방법을 보여줍니다: AsposePdfException 서브클래스를 잡고 구분하기, Form 및 Field를 사용한 AcroForm 필드 생성 및 읽기, FileSpecification을 통한 첨부 파일 삽입 및 복구, FontRepository와 FontRegistry를 이용한 글꼴 해결, 그리고 OutlineCollection와 OutlineItem을 사용한 북마크 트리 구축. 각 섹션은 현재 패키지에 존재하는 클래스와 메서드만 사용합니다.
Aspose.PDF FOSS for Python은(는) Python 패키지인 aspose-pdf-foss-for-python이며, MIT 라이선스로 배포되고 Python 3.11 이상이 필요합니다. 최상위 모듈 이름은 aspose_pdf입니다. 핵심 패키지는 cryptography와 asn1crypto에만 의존하고, 선택적 추가 기능으로 Pillow 기반 이미지 디코딩, Brotli 기반 WOFF2 글꼴 지원, 그리고 HarfBuzz 기반 복잡한 텍스트 레이아웃을 제공합니다.
핵심 기능
AsposePdfException와 함께하는 예외 처리
Aspose.PDF FOSS for Python의 모든 패키지 전용 오류는 AsposePdfException에서 파생됩니다. 대부분의 문서 처리 실패는 그 PdfException 서브클래스에 해당하며, 이는 다시 PdfParseException(잘못된 입력), PdfSecurityException(암호화 및 비밀번호 오류, InvalidPasswordException 포함), PdfValidationException(구조 또는 규격 위반)의 기반이 됩니다. 보다 구체적인 서브클래스를 먼저 잡고 마지막에 AsposePdfException을 잡음으로써, 호출자는 잘못된 비밀번호와 손상된 파일에 대해 각각 다르게 대응할 수 있으며, 그 외 모든 예외에 대해서는 단일 대체 처리 방식을 유지할 수 있습니다.
from aspose_pdf import Document
from aspose_pdf.exceptions import (
AsposePdfException,
InvalidPasswordException,
PdfParseException,
)
def open_document(path, password=None):
try:
document = Document()
document.load_from(path, password=password)
return document
except InvalidPasswordException:
print(f"{path}: a correct password is required")
except PdfParseException as error:
print(f"{path}: not a valid PDF ({error})")
except AsposePdfException as error:
# Catches every other aspose_pdf-specific error not handled above.
print(f"{path}: PDF operation failed ({error})")
return None
대화형 양식 필드
Document.form은(는) 문서의 AcroForm 필드 위에 Form 파사드를 반환합니다. Form.add_text_field(), add_checkbox(), 및 add_radio_group()는 페이지와 위젯 사각형에 연결된 새로운 최종 필드를 생성하며, 각각 Field을(를) 반환합니다. Field은(는) name, value, field_type를 공개하여 기존 필드를 이름으로 검사하고 업데이트할 수 있게 하며, Field.remove()은(는) 필드를 완전히 삭제합니다.
from aspose_pdf import Document
with Document() as document:
page = document.pages.add()
document.form.add_text_field("customer_name", page, (72, 700, 300, 720))
document.form.add_checkbox("subscribe", page, (72, 670, 90, 688), on_value="Yes")
document.form.add_radio_group(
"plan",
page,
{"Basic": (72, 630, 90, 648), "Pro": (72, 600, 90, 618)},
value="Basic",
)
for field in document.form.fields:
print(field.name, field.field_type, field.value)
for field in document.form.fields:
if field.name == "customer_name":
field.value = "Jane Doe"
document.form.generate_appearances()
document.save("form.pdf")
내장 파일 및 첨부 파일
Document.add_attachment은(는) 바이트를 문서 수준 파일 첨부로 삽입하며, 저장 시 PDF의 /Names /EmbeddedFiles 이름 트리에 기록되고, 선택적 MIME 유형, 설명 및 생성/수정 날짜와 함께 저장됩니다. Document.embedded_files는 모든 첨부 파일을 타입이 지정된 FileSpecification(name, contents, mime_type, description, size)로 읽어들이며, Document.get_embedded_file는 이름으로 하나를 찾아냅니다. FileSpecification.save()은(는) 복구된 바이트를 디스크에 기록합니다.
from aspose_pdf import Document
with Document() as document:
document.pages.add()
document.add_attachment(
"notes.txt",
b"Reviewed and approved.",
mime="text/plain",
description="Reviewer notes",
)
document.save("with-attachment.pdf")
with Document() as document:
document.load_from("with-attachment.pdf")
for spec in document.embedded_files:
print(spec.name, spec.mime_type, spec.size)
notes = document.get_embedded_file("notes.txt")
if notes is not None:
notes.save("notes-recovered.txt")
글꼴 검색 및 임베딩
FontRepository은(는) 글꼴 소스를 집계하고 문서 전체에서 이름으로 글꼴을 해결합니다. FontRepository.add_source()은(는) FontSource를 등록합니다(예: FolderFontSource(디렉터리를 스캔하고, 선택적으로 재귀적으로)); FontRepository.find_font()와 search()는 이후 글꼴을 패밀리, 전체, 또는 PostScript 이름으로 해결하며, 표준 글꼴 레지스트리로 폴백합니다. 각 일치는 FontDescriptor이며, 이를 직접 Page.add_text에 전달하여 글꼴을 임베드하고 서브셋할 수 있습니다. FontRegistry은(는) 일반적인 비표준 이름(Arial, Times New Roman 등)을 search_font_by_name()을 통해 가장 가까운 Standard-14 등가물에 매핑합니다.
from aspose_pdf import Document, FolderFontSource, FontRepository
from aspose_pdf.font_registry import FontRegistry
FontRepository.add_source(FolderFontSource("./fonts", scan_subdirectories=True))
descriptor = FontRepository.find_font("Open Sans")
if descriptor is None:
# Fall back to the closest Standard-14 match for a common font name.
descriptor = FontRegistry().search_font_by_name("Arial")
with Document() as document:
page = document.pages.add()
page.add_text(
"Rendered with a resolved font",
x=72,
y=700,
font_size=14,
font=descriptor,
)
document.save("font-sample.pdf")
문서 개요 및 북마크
Document.outlines은(는) PDF 북마크 트리의 최상위 컨테이너인 OutlineCollection을 반환합니다. OutlineCollection.add는 최상위 OutlineItem를 추가하고; OutlineItem.add()는 기존 북마크 아래에 자식 북마크를 중첩합니다. 각 OutlineItem는 title, 대상 page_index, 그리고 is_bold/is_italic 표시 플래그를 가지고 있으며, 자체 children 목록을 공개합니다.
from aspose_pdf import Document
from aspose_pdf.outlines import OutlineItem
with Document() as document:
document.pages.add()
document.pages.add()
chapter = OutlineItem("Chapter 1: Overview", page_index=0)
document.outlines.add(chapter)
chapter.add(OutlineItem("Section 1.1", page_index=0, is_italic=True))
document.outlines.add(OutlineItem("Chapter 2: Details", page_index=1, is_bold=True))
document.save("bookmarked.pdf")
빠른 시작
패키지를 설치한 후, 단일 스크립트에서 북마크, 문서 메타데이터 및 첨부 파일을 결합한 문서를 작성합니다.
asposefoss/pdf is not yet published — build from source until it ships. See the project README for build instructions.from aspose_pdf import Document
from aspose_pdf.outlines import OutlineItem
with Document() as document:
page = document.pages.add()
page.add_text("Quarterly Report", x=72, y=740, font_size=20)
document.outlines.add(OutlineItem("Quarterly Report", page_index=0))
document.info = {"Title": "Quarterly Report"}
document.add_attachment(
"source-data.csv", b"quarter,total\nQ1,1000\n", mime="text/csv"
)
document.save("report.pdf")
with Document() as reopened:
reopened.load_from("report.pdf")
print(reopened.page_count, "page(s),", reopened.info.get("Title"))
print([spec.name for spec in reopened.embedded_files])
지원되는 포맷
| 형식 | 확장자 | 읽기 | 쓰기 |
|---|---|---|---|
| 예 | 예 | ||
| TIFF | tiff | - | 예 |
Page.render, Page.save_as_image, 및 Document.save_page_as_image는 TIFF와 함께 PNG 래스터 출력도 생성합니다.
이는 문서 로드 포맷이 아니라 페이지 래스터화 출력입니다.
오픈 소스 및 라이선스
Aspose.PDF FOSS for Python은 MIT 라이선스 하에 공개됩니다: 사용 제한이 없으며, 런타임 비용이 없고, 상업적이든 개인적이든 사용을 위한 등록 요구사항이 없습니다. 소스 코드는 github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python에 호스팅되며, 패키지는 PyPI에 aspose-pdf-foss-for-python로 게시됩니다.
