- PDFSyntax는 PDF Specification의 7장 “Syntax”에 초점을 맞춘 Python 라이브러리로, PDF 파일의 내부 문서 구조를 바이트 단위까지 검사하고 변환하는 데 사용됨
- 순수 Python으로 처음부터 작성됐고 의존성이 없는 경량 라이브러리이며, 단순성과 불변성을 중시함
- 기본 편집 방식은 PDF 사양이 허용하는 비파괴적 증분 업데이트로, 원본 파일 끝에 변경 섹션을 추가하며 되감기나 단일 리비전으로 합치기가 가능함
- CLI는
overview, disasm, text, fonts, browse 등을 제공하며, browse는 PDF 소스를 보기 좋게 출력하고 하이퍼링크가 포함된 정적 HTML로 내부 구조를 탐색하게 함
- 현재는 베타 품질의 작업 중인 프로젝트로 API가 언제든 바뀔 수 있고, MIT 라이선스이지만 아직 외부 기여는 받지 않음
PDF 내부 구조 검사와 변환
- PDFSyntax는 PDF 파일의 내부 구조를 검사하고 변환하기 위한 Python 라이브러리임
- Portable Document Format(PDF) Specification의 7장인 “Syntax”에 초점을 맞춤
- 문서 구조 관리를 바이트 수준까지 구현해 다음과 같은 용도에 사용됨
- 메타데이터 접근
- 페이지 회전
- PDF 읽기/쓰기 작업
- 내부 객체 접근과 조작
설계 방향
- 내부 함수들은 PDF 읽기/쓰기 작업을 위한 API 툴킷으로 노출됨
- 일부 기능은 터미널이나 브라우저에서 사용할 수 있도록 CLI로도 제공됨
- 라이브러리는 순수 Python으로 작성됐고 외부 의존성이 없음
- 단순성과 불변성을 중시함
- 기본 편집 방식은 원본을 직접 덮어쓰지 않고 원본 파일 끝에 변경 내용을 추가하는 증분 업데이트임
- 필요하면 리비전을 되감을 수 있음
- 모든 리비전을 하나로 합칠 수도 있음
설치와 CLI 사용
pip install pdfsyntax
pdfsyntax COMMAND FILE
- 소스에서 설치한 경우 더 긴 형식으로 실행할 수 있음
python3 -m pdfsyntax COMMAND FILE
- 빠른 PDF 분석을 위한 주요 명령은 다음과 같음
overview: 구조와 메타데이터에 대한 텍스트 정보 출력disasm: 파일 구조 덤프를 터미널에 출력text: 스캔처럼 공간 배치를 유지한 추출 텍스트 출력fonts: 사용된 폰트 목록 출력browse: PDF 소스를 보기 좋게 출력하고 하이퍼링크를 추가한 정적 HTML을 생성해 내부 구조 탐색을 지원
API 사용 방식
- PDFSyntax는 대부분 단순한 함수들로 구성됨
readfile로 PDF를 읽고 metadata로 메타데이터를 Python dict 형태로 얻을 수 있음
>>> from pdfsyntax import readfile, metadata
>>> doc = readfile("samples/simple_text_string.pdf")
>>> metadata(doc)
Doc 객체는 문서의 내부 상태를 저장하는 거의 유일한 전용 클래스임
- 원본 파일에서 캐시되거나 메모이즈된 콘텐츠
- 콘텐츠 추가·수정·삭제 변경 사항
- 증분 업데이트로 추적되는 수정 내역
- 같은
metadata 함수는 Doc 객체의 메서드로도 사용할 수 있음
>>> doc.metadata()
get_object, update_object 같은 저수준 함수로 문서 내부 객체에 직접 접근하고 조작할 수 있음rotate 같은 고수준 함수도 제공됨
>>> from pdfsyntax import rotate, writefile
>>> doc180 = rotate(doc, 180)
- 회전 예시에서는 원본 객체가 변경되지 않고, 진행 중인 방향 변경을 담은 새 객체가 만들어짐
- 수정된 PDF는
writefile로 디스크에 쓸 수 있음
>>> writefile(doc180, "rotated_doc.pdf")
- 결과 파일은 원본 콘텐츠 뒤에 새 섹션이 추가된 형태이며, 이 섹션을 잘라내면 변경을 되돌릴 수 있음
현재 상태와 기여 정책
- 프로젝트는 작업 중이며 베타 품질 소프트웨어임
- API는 언제든 변경될 수 있음
- 다음 작업 목록에는 아래 항목이 포함됨
- 페이지 자르기와 붙이기
- 무손실 압축
- 더 많은 필터
- 텍스트 추출 개선
- 레이아웃 감지를 통한 텍스트 추출 보강
- PDFSyntax는 MIT 라이선스임
- 현재는 외부 기여를 받지 않음
- 개인 프로젝트이며 시간이 제한적임
- 새 기능과 리팩터링 로드맵에 먼저 집중한 뒤 안정화되면 기여를 받을 예정임