Story¶

v1.21.0 에서 새로 추가됨

메서드 / 속성	간단한 설명
`Story.reset()`	스토리 출력을 시작 부분으로 “되감기”
`Story.place()`	제공된 사각형에 맞도록 스토리 콘텐츠 계산
`Story.draw()`	계산된 콘텐츠를 현재 페이지에 쓰기
`Story.element_positions()`	현재 처리 중인 스토리 콘텐츠를 로깅하는 콜백 함수
`Story.body`	스토리의 기본 body
`Story.write()`	Story를 DocumentWriter에 배치하고 그리기
`Story.write_stabilized()`	HTML 콘텐츠를 DocumentWriter에 반복 레이아웃
`Story.write_with_links()`	`write()` 와 유사하지만 PDF 링크도 생성
`Story.write_stabilized_with_links()`	`write_stabilized()` 와 유사하지만 PDF 링크도 생성
`Story.fit()`	스토리 `self` 를 포함하는 최적의 rect를 찾습니다.
`Story.fit_scale()`
`Story.fit_height()`
`Story.fit_width()`

클래스 API

class Story¶

__init__(self, html=None, user_css=None, em=12, archive=None)¶

스토리 를 생성하며, 선택적으로 HTML 및 CSS 소스를 제공합니다. HTML은 파싱되어 Story 내에서 DOM(Document Object Model)로 유지됩니다.

이 구조는 수정할 수 있습니다: Xml 클래스의 메서드를 사용하여 콘텐츠(텍스트, 이미지)를 추가, 복사, 수정 또는 제거할 수 있습니다.

완료되면 스토리 는 모든 장치에 쓸 수 있습니다. 일반적인 사용에서 장치는 DocumentWriter 에 의해 제공되어 새 페이지를 만듭니다.

다음은 일반적인 설명입니다:

Story 생성자는 제공된 HTML을 파싱하고 검증하여 DOM을 생성합니다.
PyMuPDF 는 기본 DOM의 노드 에 대한 액세스를 제공하여 HTML 소스를 조작하는 여러 방법을 제공합니다. 문서는 프로그래밍 방식으로 처음부터 완전히 구축할 수 있거나, 기존 DOM을 거의 임의로 수정할 수 있습니다. 이 인터페이스의 세부 사항은 Xml 클래스를 참조하세요.
DOM에 대한 변경이 더 이상 필요하지 않으면 스토리는 레이아웃되고 일련의 장치(일반적으로 새 페이지를 생성하기 위해 DocumentWriter 에 의해 제공되는 장치)에 공급할 준비가 됩니다.
다음 단계는 스토리를 배치하고 쓰는 것입니다. 이것은 place() 및 draw() 호출을 반복하는 루프로 직접 수행하거나, 대신 write() 또는 write_stabilised() 메서드를 사용하여 루프를 처리할 수 있습니다. 어떤 방법을 선택할지는 주로 취향의 문제입니다.
- 이러한 스타일 중 첫 번째로 작업하려면 다음 루프를 사용해야 합니다:
  1. 쓰기에 적합한 장치를 얻습니다. 일반적으로 DocumentWriter 에서 새 빈 페이지를 요청합니다.
  2. 페이지에서 스토리 데이터를 받을 하나 이상의 사각형을 결정합니다. 모든 페이지가 동일한 사각형 세트를 가질 필요는 없습니다.
  3. 각 사각형을 스토리 에 전달하여 배치하고, 해당 사각형의 어느 부분이 채워졌는지, 맞지 않는 더 많은 스토리 데이터가 있는지 확인합니다. 이 단계는 호출자가 결과에 만족할 때까지 조정된 사각형으로 여러 번 반복할 수 있습니다.
  4. 선택적으로 이 시점에서 element_positions() 메서드를 호출하여 흥미로운 항목이 배치된 위치에 대한 세부 정보를 요청할 수 있습니다. 항목은 정수 heading 속성이 0이 아닌 경우(HTML 태그 h1 - h6 에 해당), id 속성이 None 이 아닌 경우(HTML 태그 id 에 해당), 또는 href 속성이 None 이 아닌 경우(HTML 태그 href 에 해당) 흥미로운 것으로 간주됩니다. 이것은 목차, 이미지 인덱스 등의 자동 생성에 편리하게 사용할 수 있습니다.
  5. 다음으로 draw() 메서드를 사용하여 해당 사각형을 장치에 그립니다.
  6. place() 에 대한 가장 최근 호출이 모든 스토리 데이터가 맞았다고 표시하면 지금 중지합니다.
  7. 그렇지 않으면 루프로 돌아갈 수 있습니다. 현재 장치(페이지)에 배치할 더 많은 사각형이 있으면 3단계로 돌아가고, 그렇지 않으면 새 장치를 얻기 위해 1단계로 돌아갑니다.
- 대안으로 DocumentWriter 를 사용하는 경우 write() 또는 write_stabilized() 메서드를 사용할 수 있습니다. 이것들은 동작을 제어하는 콜백(특히 사용할 사각형/페이지를 열거하는 콜백)을 제공하는 대가로 모든 루프를 처리합니다.
스토리 의 어느 부분이 어떤 사각형/어떤 페이지에 배치될지는 Story 객체의 완전한 제어 하에 있으며 예측할 수 없습니다.
이미지는 스토리 의 일부일 수 있습니다. 주변 텍스트와 함께 배치됩니다.
여러 스토리는 서로 독립적으로 같은 페이지에 쓸 수 있습니다. 예를 들어 페이지 헤더, 페이지 푸터, 일반 텍스트, 주석 상자 등에 대해 별도의 스토리를 가질 수 있습니다.

매개변수:

html (str) – HTML 소스 코드. 생략하면 기본 최소값이 생성됩니다(아래 참조). 제공된 경우 완전한 HTML 문서가 필요하지 않습니다. 내장 소스 파서는 (많은/대부분의) HTML 구문 오류를 용서하며 "<b>Hello, <i>World!</i></b>" 와 같은 HTML 조각도 허용합니다.
user_css (str) – CSS 소스 코드. 제공된 경우 유효한 CSS 사양을 포함해야 합니다.
em (float) – 기본 텍스트 글꼴 크기.
archive –
렌더링을 위한 리소스를 로드할 Archive (아카이브). 현재 지원되는 리소스 타입은 이미지와 텍스트 글꼴입니다. 생략하면 스토리는 이러한 데이터를 찾으려고 시도하지 않으므로 불완전한 출력을 생성할 수 있습니다.

참고

실제 아카이브 대신 Archive (아카이브) 를 생성 하기 위한 유효한 인수도 제공할 수 있습니다. 이 경우 아카이브가 임시로 구성됩니다. 따라서 story = pymupdf.Story(archive=pymupdf.Archive("myfolder")) 대신 story = pymupdf.Story(archive="myfolder") 로 더 짧게 쓸 수도 있습니다.

place(where)¶

제공된 사각형에 맞는 스토리 콘텐츠의 일부를 계산합니다. 이 메서드는 스토리 콘텐츠의 어느 부분이 이미 쓰여졌는지에 대한 포인터를 유지하며, 다음 호출 시 해당 포인터 위치에서 재개합니다.

매개변수:: where (rect_like) – 콘텐츠의 현재 부분을 이 사각형에 맞도록 레이아웃합니다. 이것은 페이지의 MediaBox 의 하위 사각형이어야 합니다.
반환 형식:: tuple[bool, rect_like]
반환:: bool(int) more 와 사각형 filled. more == 0 이면 스토리의 모든 콘텐츠가 쓰여진 것이고, 그렇지 않으면 더 많은 콘텐츠가 후속 사각형/페이지에 쓰이기를 기다리고 있습니다. 사각형 filled 는 실제로 채워진 where 의 부분입니다.

draw(dev, matrix=None)¶

Story.place() 로 준비된 콘텐츠 부분을 페이지에 씁니다.

매개변수:

dev – dev = writer.begin_page(mediabox) 로 생성된 Device (디바이스). 장치는 콘텐츠를 쓰는 데 필요한 모든 MuPDF 함수를 호출하는 방법을 알고 있습니다.
matrix (matrix_like) – 페이지에 쓸 때 콘텐츠를 변환하는 행렬. 예를 들어 회전된 텍스트를 쓰는 것입니다. 기본값은 변환 없음(즉, Identity 행렬)을 의미합니다.

element_positions(function, args=None)¶

Story가 현재 페이지에서의 위치가 계산된 후 특정 HTML 요소에 대한 위치 정보를 제공하도록 합니다. 즉, Story.place() 직후에 이 메서드를 호출합니다.

Story 는 위치 정보를 function 에 전달합니다. 이 정보는 예를 들어 목차를 생성하는 데 사용할 수 있습니다.

매개변수:

function (callable) – ElementPosition 객체를 받는 Python 함수. Story 객체에 의해 호출되어 위치 정보를 처리합니다. 함수는 반드시 정확히 하나의 인수를 받는 호출 가능한 객체여야 합니다.
args (dict) – function 에 전달되는 ElementPosition 인스턴스에 추가되어야 하는 추가 정보가 있는 선택적 딕셔너리. 예를 들어 현재 출력 페이지 번호입니다. 이 딕셔너리의 모든 키는 유효한 Python 식별자 규칙을 준수하는 문자열이어야 합니다. 전체 정보 세트는 아래에 설명되어 있습니다.

reset()¶: 출력을 다시 시작하기 위해 스토리 문서를 시작 부분으로 되감습니다.

body¶: 스토리 DOM의 body 부분. 이 속성은 body 의 Xml 노드를 포함합니다. PDF 생성을 위한 모든 관련 콘텐츠는 “<body>” 와 “</body>” 사이에 포함됩니다.

write(writer, rectfn, positionfn=None, pagefn=None)¶

Story를 DocumentWriter 에 배치하고 그립니다. Story.place() 및 Story.draw() 등을 호출하는 루프를 구현하는 호출 코드의 필요성을 피하지만, 최소한 rectfn() 콜백을 제공해야 합니다.

매개변수:

writer – DocumentWriter 또는 None.
rectfn –
(rect_num: int, filled: Rect) 를 받아 (mediabox, rect, ctm) 를 반환하는 호출 가능한 객체:
- mediabox: 새 페이지의 None 또는 rect.
- rect: 콘텐츠가 배치될 다음 rect.
- ctm: None 또는 Matrix.
positionfn –
None 또는 (position: ElementPosition) 를 받는 호출 가능한 객체:
- position:
  추가 .page_num 멤버를 가진 ElementPosition.
일반적으로 제목이거나 id를 가진 요소를 생성할 때 여러 번 호출됩니다.
pagefn – None 또는 (page_num, mediabox, dev, after) 를 받는 호출 가능한 객체. 각 페이지의 시작(after=0)과 끝(after=1)에서 호출됩니다.

static write_stabilized(writer, contentfn, rectfn, user_css=None, em=12, positionfn=None, pagefn=None, archive=None, add_header_ids=True)¶

HTML 콘텐츠를 DocumentWriter 에 반복 레이아웃하는 정적 메서드.

예를 들어 이것은 페이지 번호가 안정될 때까지 패치되도록 하면서 목차 섹션을 추가할 수 있게 합니다.

(contentfn(), user_css, em, archive) 로부터 새 Story 를 반복적으로 생성하고 Story.write() 내부 호출로 레이아웃합니다. None writer를 사용하고 ElementPosition 목록을 추출하여 contentfn() 의 다음 호출에 전달합니다.

contentfn() 의 HTML이 변경되지 않으면 writer 를 사용하여 최종 반복을 수행합니다.

매개변수:

writer – DocumentWriter.
contentfn – ElementPositions 목록을 받아 HTML을 포함하는 문자열을 반환하는 함수. 반환된 HTML은 위치 목록에 따라 달라질 수 있습니다. 예를 들어 시작 부분 근처에 목차가 있습니다.
rectfn –
(rect_num: int, filled: Rect) 를 받아 (mediabox, rect, ctm) 를 반환하는 호출 가능한 객체:
- mediabox: 새 페이지의 None 또는 rect.
- rect: 콘텐츠가 배치될 다음 rect.
- ctm: Matrix.
pagefn – None 또는 (page_num, medibox, dev, after) 를 받는 호출 가능한 객체. 각 페이지의 시작(after=0)과 끝(after=1)에서 호출됩니다.
archive
add_header_ids – true이면 id가 아직 없는 모든 헤더 태그에 고유 id를 추가합니다. 이것은 목차의 자동 생성에 도움이 될 수 있습니다.

반환값:: None.

write_with_links(rectfn, positionfn=None, pagefn=None)¶: write() 와 유사하지만 writer 인수가 없고 각 내부 HTML 링크에 대해 링크가 생성된 PDF Document 를 반환합니다.

static write_stabilized_with_links(contentfn, rectfn, user_css=None, em=12, positionfn=None, pagefn=None, archive=None, add_header_ids=True)¶: write_stabilized() 와 유사하지만 writer 인수가 없고 대신 각 내부 HTML 링크에 대해 링크가 생성된 PDF Document 를 반환합니다.

class FitResult¶

Story.fit*() 메서드의 결과.

멤버:

big_enough:: 적합이 성공하면 True.
filled:: Story.place() 에 대한 마지막 호출에서.
more:: 적합이 성공하면 False.
numcalls:: self.place() 에 대한 호출 횟수.
parameter:: 성공한 매개변수 값 또는 가장 큰 실패 값.
Rect:: parameter 로부터 생성된 rect.

fit(self, fn, pmin=None, pmax=None, delta=0.001, verbose=False)¶

스토리 self 를 포함하는 최적의 rect를 찾습니다.

Story.FitResult 인스턴스를 반환합니다.

성공 시 self.place() 에 대한 마지막 호출은 반환된 사각형으로 수행되므로 self.draw() 를 직접 사용할 수 있습니다.

매개변수:

fn –
부동 소수점 parameter 를 받아 pymupdf.Rect() 를 반환하는 호출 가능한 객체. rect가 비어 있으면 스토리가 맞지 않는다고 가정하고 self.place() 를 호출하지 않습니다.

parameter 가 증가할 때 rect fn(parameter)가 주어지면 self.place() 가 단조롭게 동작하도록 보장해야 합니다. 이것은 일반적으로 parameter 가 증가할 때 너비와 높이가 모두 증가하거나 변경되지 않음을 의미합니다.
pmin – 고려할 최소 매개변수. None 이면 -무한대.
pmax – 고려할 최대 매개변수. None 이면 +무한대.
delta – 반환된 parameter 의 최대 오류.
verbose – true이면 진단 정보를 출력합니다.

fit_scale(self, rect, scale_min=0, scale_max=None, delta=0.001, verbose=False)¶

scale * rect 가 스토리 self 를 포함할 수 있을 만큼 큰 scale_min..scale_max 범위에서 가장 작은 값 scale 을 찾습니다.

Story.FitResult 인스턴스를 반환합니다.

매개변수:

width – rect의 너비.
height – rect의 높이.
scale_min – 고려할 최소 스케일. >= 0 이어야 합니다.
scale_max – 고려할 최대 스케일. >= scale_min 이어야 하거나 무한대의 경우 None.
delta – 반환된 스케일의 최대 오류.
verbose – true이면 진단 정보를 출력합니다.

fit_height(self, width, height_min=0, height_max=None, origin=(0, 0), delta=0.001, verbose=False)¶

크기 (width, height) 의 rect가 스토리 self 를 포함할 수 있을 만큼 큰 height_min..height_max 범위에서 가장 작은 높이를 찾습니다.

Story.FitResult 인스턴스를 반환합니다.

매개변수:

width – rect의 너비.
height_min – 고려할 최소 높이. >= 0 이어야 합니다.
height_max – 고려할 최대 높이. >= height_min 이어야 하거나 무한대의 경우 None.
origin – rect의 (x0, y0).
delta – 반환된 높이의 최대 오류.
verbose – true이면 진단 정보를 출력합니다.

fit_width(self, height, width_min=0, width_max=None, origin=(0, 0), delta=0.001, verbose=False)¶

크기 (width, height) 의 rect가 스토리 self 를 포함할 수 있을 만큼 큰 width_min..width_max 범위에서 가장 작은 너비를 찾습니다.

Story.FitResult 인스턴스를 반환합니다.

매개변수:

height – rect의 높이.
width_min – 고려할 최소 너비. >= 0 이어야 합니다.
width_max – 고려할 최대 너비. >= width_min 이어야 하거나 무한대의 경우 None.
origin – rect의 (x0, y0).
delta – 반환된 너비의 최대 오류.
verbose – true이면 진단 정보를 출력합니다.

요소 위치 지정 콜백 함수¶

콜백 함수는 스토리 출력에 대한 정보를 로깅하는 데 사용할 수 있습니다. 함수의 정보 액세스는 읽기 전용입니다. 스토리 출력에 영향을 줄 수 있는 방법이 없습니다.

이 메서드를 사용하여 스토리를 실행하는 일반적인 루프는 다음과 같습니다:

HTML = """
<html>
    <head></head>
    <body>
        <h1>Header level 1</h1>
        <h2>Header level 2</h2>
        <p>Hello MuPDF!</p>
    </body>
</html>
"""
MEDIABOX = pymupdf.paper_rect("letter")  # size of a page
WHERE = MEDIABOX + (36, 36, -36, -36)  # leave borders of 0.5 inches
story =  pymupdf.Story(html=HTML)  # make the story
writer = pymupdf.DocumentWriter("test.pdf")  # make the writer
pno = 0 # current page number
more = 1  # will be set to 0 when done
while more:  # loop until all story content is processed
    dev = writer.begin_page(MEDIABOX)  # make a device to write on the page
    more, filled = story.place(WHERE)  # compute content positions on page
    story.element_positions(recorder, {"page": pno})  # provide page number in addition
    story.draw(dev)
    writer.end_page()
    pno += 1  # increase page number
writer.close()  # close output file

def recorder(elpos):
    pass

ElementPosition 클래스의 속성¶

Story.element_positions() 에 의해 제공되는 함수에는 정확히 하나의 매개변수가 전달되어야 합니다. 다음 속성을 가진 객체입니다:

recorder 함수에 전달되는 매개변수는 다음 속성을 가진 객체입니다:

elpos.depth (int) – 박스 구조에서 이 요소의 깊이.
elpos.heading (int) – 헤더 레벨, 헤더가 없으면 0, h1 - h6 의 경우 1-6.
elpos.href (str) – href 속성의 값, 정의되지 않았으면 None.
elpos.id (str) – id 속성의 값, 정의되지 않았으면 None.
elpos.rect (tuple) – 페이지에서의 요소 위치.
elpos.text (str) – 요소의 직접 텍스트.
elpos.open_close (int 비트 필드) – 비트 0 설정: 요소 열기, 비트 1 설정: 요소 닫기. 다른 요소를 포함할 수 있어 생성/열린 후 즉시 닫히지 않을 수 있는 요소와 관련됩니다.
elpos.rect_num (int) – 지금까지 스토리로 채워진 사각형의 개수.
elpos.page_num (int) – 페이지 번호. pymupdf.Story.write*() 함수를 사용할 때만 존재합니다.

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.