Xj+$dZddlmZddlmZmZmZmZmZddl m Z ddl m Z ddl mZddlmZmZddlmZmZmZmZdd lmZer6dd lmZdd lmZmZdd lm Z m!Z!dd l"m#Z#ddl$m%Z%ddl&m'Z'm(Z(ddl)m*Z*ddl+m,Z,GddeZ-Gdde Z.y )z'|Document| and closely related objects.) annotations)IO TYPE_CHECKINGIteratorListSequence)BlockItemContainer) WD_SECTION)WD_BREAK)SectionSections) ElementProxyEmuInchesLength)RunN)CommentComments)CT_Body CT_Document) DocumentPart)Settings)ParagraphStyle _TableStyle)Table) ParagraphcreZdZdZdfd Z d ddZdddZdZdddZ d ddZ e jfd dZ d!d"d Z ed#d Zed Zed Zd$d Zed%dZed&dZd'dZed(dZed)dZedZed*dZed+dZed,dZxZS)-DocumentzWordprocessingML (WML) document. Not intended to be constructed directly. Use :func:`docx.Document` to open or create a document. cVtt| |||_||_d|_yN)superr__init___element_part_Document__body)selfelementpart __class__s a/mnt/ssd/data/Dropbox/adrian/vault-secondbrain/venv/lib/python3.12/site-packages/docx/document.pyr"zDocument.__init__#s' h&w/   ct|tr|gn|}|d}|d}|jj|||}|j ||j |S)aAdd a comment to the document, anchored to the specified runs. `runs` can be a single `Run` object or a non-empty sequence of `Run` objects. Only the first and last run of a sequence are used, it's just more convenient to pass a whole sequence when that's what you have handy, like `paragraph.runs` for example. When `runs` contains a single `Run` object, that run serves as both the first and last run. A comment can be anchored only on an even run boundary, meaning the text the comment "references" must be a non-zero integer number of consecutive runs. The runs need not be _contiguous_ per se, like the first can be in one paragraph and the last in the next paragraph, but all runs between the first and the last will be included in the reference. The comment reference range is delimited by placing a `w:commentRangeStart` element before the first run and a `w:commentRangeEnd` element after the last run. This is why only the first and last run are required and why a single run can serve as both first and last. Word works out which text to highlight in the UI based on these range markers. `text` allows the contents of a simple comment to be provided in the call, providing for the common case where a comment is a single phrase or sentence without special formatting such as bold or italics. More complex comments can be added using the returned `Comment` object in much the same way as a `Document` or (table) `Cell` object, using methods like `.add_paragraph()`, .add_run()`, etc. The `author` and `initials` parameters allow that metadata to be set for the comment. `author` is a required attribute on a comment and is the empty string by default. `initials` is optional on a comment and may be omitted by passing |None|, but Word adds an `initials` attribute by default and we follow that convention by using the empty string when no `initials` argument is provided. r)textauthorinitials) isinstancercomments add_commentmark_comment_range comment_id)r&runsr.r/r0 first_runlast_runcomments r*r3zDocument.add_comment)scJ$D#.vDG 8--++fx+X $$Xw/A/ABr+ctd|cxkrdksntd|z|dk(rdnd|z}|j||S)aReturn a heading paragraph newly added to the end of the document. The heading paragraph will contain `text` and have its paragraph style determined by `level`. If `level` is 0, the style is set to `Title`. If `level` is 1 (or omitted), `Heading 1` is used. Otherwise the style is set to `Heading {level}`. Raises |ValueError| if `level` is outside the range 0-9. r z"level must be in range 0-9, got %dTitlez Heading %d) ValueError add_paragraph)r&r.levelstyles r* add_headingzDocument.add_headingZsEEQAEIJ J A:<%+?!!$..r+c|j}|jjtj|S)z=Return newly |Paragraph| object containing only a page break.)r>add_run add_breakr PAGE)r& paragraphs r*add_page_breakzDocument.add_page_breakgs1&&( %%hmm4r+c:|jj||S)aReturn paragraph newly added to the end of the document. The paragraph is populated with `text` and having paragraph style `style`. `text` can contain tab (``\t``) characters, which are converted to the appropriate XML form for a tab. `text` can also include newline (``\n``) or carriage return (``\r``) characters, each of which is converted to a line break. )_bodyr>)r&r.r@s r*r>zDocument.add_paragraphmszz''e44r+cd|jj}|j|||S)aReturn new picture shape added in its own paragraph at end of the document. The picture contains the image at `image_path_or_stream`, scaled based on `width` and `height`. If neither width nor height is specified, the picture appears at its native size. If only one is specified, it is used to compute a scaling factor that is then applied to the unspecified dimension, preserving the aspect ratio of the image. The native size of the picture is calculated using the dots-per-inch (dpi) value specified in the image file, defaulting to 72 dpi if no value is specified, as is often the case. )r>rC add_picture)r&image_path_or_streamwidthheightruns r*rKzDocument.add_pictureys/   "**,3UFCCr+c|jjj}||_t ||j S)zReturn a |Section| object newly added at the end of the document. The optional `start_type` argument must be a member of the :ref:`WdSectionStart` enumeration, and defaults to ``WD_SECTION.NEW_PAGE`` if not provided. )r#bodyadd_section_break start_typer r$)r&rS new_sectPrs r* add_sectionzDocument.add_sections5 ]]''99; * z4::..r+cb|jj|||j}||_|S)zAdd a table having row and column counts of `rows` and `cols` respectively. `style` may be a table style object or a table style name. If `style` is |None|, the table inherits the default table style of the document. )rI add_table _block_widthr@)r&rowscolsr@tables r*rWzDocument.add_tables.  $$T41B1BC  r+c.|jjS)zGA |Comments| object providing access to comments added to the document.)r$r2r&s r*r2zDocument.commentszz"""r+c.|jjS)zGA |CoreProperties| object providing Dublin Core properties of document.)r$core_propertiesr]s r*r`zDocument.core_propertiesszz)))r+c.|jjS)zThe |InlineShapes| collection for this document. An inline shape is a graphical object, such as a picture, contained in a run of text and behaving like a character glyph, being flowed like other text in a paragraph. )r$ inline_shapesr]s r*rbzDocument.inline_shapesszz'''r+c6|jjS)zHGenerate each `Paragraph` or `Table` in this document in document order.)rIiter_inner_contentr]s r*rdzDocument.iter_inner_contentszz,,..r+c.|jjS)zThe |Paragraph| instances in the document, in document order. Note that paragraphs within revision marks such as ```` or ```` do not appear in this list. )rI paragraphsr]s r*rfzDocument.paragraphsszz$$$r+c|jS)z+The |DocumentPart| object of this document.)r$r]s r*r(z Document.partszzr+c:|jj|y)zSave this document to `path_or_stream`. `path_or_stream` can be either a path to a filesystem location (a string) or a file-like object. N)r$save)r&path_or_streams r*riz Document.saves 'r+cBt|j|jS)zD|Sections| object providing access to each section in this document.)r r#r$r]s r*sectionszDocument.sectionss tzz22r+c.|jjS)zDA |Settings| object providing access to the document-level settings.)r$settingsr]s r*rnzDocument.settingsr^r+c.|jjS)zBA |Styles| object providing access to the styles in this document.)r$stylesr]s r*rpzDocument.stylesszz   r+c.|jjS)aPAll |Table| instances in the document, in document order. Note that only tables appearing at the top level of the document appear in this list; a table nested inside a table cell does not appear. A table within revision marks such as ```` or ```` will also not appear in the list. )rItablesr]s r*rrzDocument.tablesszz   r+c|jd}|jxs td}|jxs td}|jxs td}t ||z |z S)zGA |Length| object specifying the space between margins in last section.r-g!@)rl page_widthr left_margin right_marginr)r&sectionrurvrws r*rXzDocument._block_widthsc--#''66#; ))6VAY ++8vay : +l:;;r+c||j%t|jj||_|jS)z>The |_Body| instance containing the content for this document.)r%_Bodyr#rQr]s r*rIzDocument._bodys0 ;;  2 2D9DK{{r+)r'rr(r)r{r{) r6zRun | Sequence[Run]r. str | Noner/strr0r|returnr)r{rt)r.r}r?int)r{N)r.r}r@zstr | ParagraphStyle | Noner~r)NN)rLstr | IO[bytes]rMint | Length | NonerNr)rSr r )rYrrZrr@zstr | _TableStyle | None)r~r)r~zIterator[Paragraph | Table])r~zList[Paragraph])r~r)rjr)r~r )r~r)r~z List[Table])r~rr~rz)__name__ __module__ __qualname____doc__r"r3rArGr>rKr NEW_PAGErUrWpropertyr2r`rbrdrfr(rirlrnrprrrXrI __classcell__r)s@r*rrs ! /!// /  /  /b / 5&*&* D-D#D$ D&4>3F3F/##**((/%%(33##!!!!<<r+rc,eZdZdZdfd ZddZxZS)rzzoProxy for `` element in this document. It's primary role is a container for document content. c<tt| ||||_yr )r!rzr"rI)r&body_elmparentr)s r*r"z_Body.__init__s eT#Hf5 r+c:|jj|S)zReturn this |_Body| instance after clearing it of all content. Section properties for the main document story, if present, are preserved. )rI clear_contentr]s r*rz_Body.clear_contents   " r+)rrrzt.ProvidesStoryPartr)rrrrr"rrrs@r*rzrzs r+rz)/r __future__rtypingrrrrr docx.blkcntnrr docx.enum.sectionr docx.enum.textr docx.sectionr r docx.sharedrrrr docx.text.runr docx.typestypest docx.commentsrrdocx.oxml.documentrrdocx.parts.documentr docx.settingsrdocx.styles.stylerr docx.tablerdocx.text.paragraphrrrzr+r*rs_.">>,(#*99/70&= -Z|Zz r+