python-docx-oss 0.0.8rc1__tar.gz → 0.0.9rc1__tar.gz

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/HISTORY.md

@@ -1,9 +1,14 @@
 ## Release History
 
+**0.0.9 (2024-11-26)**
+
+-   svg file support in add_picture. #27
+-   update docs.
+
 **0.0.8 (2024-11-22)**
 
--   EastAsia font support fixes #25
--   Update README.md #26
+-   EastAsia font support fixes. #25
+-   Update README.md. #26
 
 **0.0.7 (2022-10-29)**
 

{python_docx_oss-0.0.8rc1/python_docx_oss.egg-info → python_docx_oss-0.0.9rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-docx-oss
-Version: 0.0.8rc1
+Version: 0.0.9rc1
 Summary: CRUD Microsoft Word .docx files.
 Home-page: https://github.com/lsaint/python-docx-oss
 Author: Ethan St. Lee
@@ -75,10 +75,15 @@ This project is based on the original work by [Steve Canny](https://github.com/s
 
 ## Release History
 
+**0.0.9 (2024-11-26)**
+
+-   svg file support in add_picture. #27
+-   update docs.
+
 **0.0.8 (2024-11-22)**
 
--   EastAsia font support fixes #25
--   Update README.md #26
+-   EastAsia font support fixes. #25
+-   Update README.md. #26
 
 **0.0.7 (2022-10-29)**
 

python_docx_oss-0.0.9rc1/docs/index.rst

@@ -0,0 +1,116 @@
+.. python-docx-oss documentation master file, created by
+   sphinx-quickstart on Wed Jul  6 15:38:29 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to python-docx-oss's documentation!
+===========================================
+
+Release v\ |release| (:ref:`Installation <install>`)
+
+*python-docx-oss* is a Python library for CRUD Microsoft Word (.docx) files.
+
+
+What it can do
+--------------
+
+.. |img| image:: /_static/img/example-docx-01.png 
+
+Here's an example of what |docx| can do:
+
+::
+
+    from docx import Document
+    from docx.shared import Inches
+
+    document = Document()
+
+    document.add_heading('Document Title', 0)
+
+    p = document.add_paragraph('A plain paragraph having some ')
+    p.add_run('bold').bold = True
+    p.add_run(' and some ')
+    p.add_run('italic.').italic = True
+
+    document.add_heading('Heading, level 1', level=1)
+    document.add_paragraph('Intense quote', style='Intense Quote')
+
+    document.add_paragraph(
+        'first item in unordered list', style='List Bullet'
+    )
+    document.add_paragraph(
+        'first item in ordered list', style='List Number'
+    )
+
+    document.add_picture('monty-truth.png', width=Inches(1.25))
+
+    records = (
+        (3, '101', 'Spam'),
+        (7, '422', 'Eggs'),
+        (4, '631', 'Spam, spam, eggs, and spam')
+    )
+
+    table = document.add_table(rows=1, cols=3)
+    hdr_cells = table.rows[0].cells
+    hdr_cells[0].text = 'Qty'
+    hdr_cells[1].text = 'Id'
+    hdr_cells[2].text = 'Desc'
+    for qty, id, desc in records:
+        row_cells = table.add_row().cells
+        row_cells[0].text = str(qty)
+        row_cells[1].text = id
+        row_cells[2].text = desc
+
+    document.add_page_break()
+
+    document.save('demo.docx')
+
+
+|img|
+
+
+User Guide
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   user/install
+   user/quickstart
+   user/documents
+   user/text
+   user/sections
+   user/hdrftr
+   user/api-concepts
+   user/styles-understanding
+   user/styles-using
+   user/shapes
+   user/custom-properties
+   user/custom-xml
+
+
+API Documentation
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   api/document
+   api/settings
+   api/style
+   api/text
+   api/table
+   api/section
+   api/shape
+   api/dml
+   api/shared
+   api/enum/index
+
+
+Contributor Guide
+-----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   dev/analysis/index

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/docs/user/install.rst

@@ -26,5 +26,5 @@ but if you use this last method you will need to install those yourself.
 Dependencies
 ------------
 
-* Python 3.8, 3.9 or 3.10
+* Python >= 3.10
 * lxml >= 4.6.5

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/docs/user/shapes.rst

@@ -19,9 +19,10 @@ will cause it to move to the right. Often, a picture is placed in a paragraph
 by itself, but this is not required. It can have text before and after it in
 the paragraph in which it's placed.
 
-At the time of writing, |docx| only supports inline pictures. Floating pictures
-can be added. If you have an active use case, submit a feature request on the
-issue tracker. The ``Document.add_picture()`` method adds a specified picture
+The ``Document.add_picture()`` method adds a specified picture
 to the end of the document in a paragraph of its own. However, by digging
 a little deeper into the API you can place text on either side of the picture
 in its paragraph, or both.
+
+If width and height are not specified in svg, the default size is *72px*.
+The ratio of width and height is kept the same as viewbox attribute.

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/docx/__init__.py

@@ -12,7 +12,7 @@ from docx.parts.numbering import NumberingPart
 from docx.parts.settings import SettingsPart
 from docx.parts.styles import StylesPart  # noqa
 
-__version__ = "0.0.8rc1"
+__version__ = "0.0.9rc1"
 
 
 # register custom Part classes with opc package reader

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/docx/image/__init__.py

@@ -8,11 +8,12 @@ size, as a required step in including them in a document.
 from __future__ import absolute_import, division, print_function, unicode_literals
 
 from docx.image.bmp import Bmp
+from docx.image.emf import Emf
 from docx.image.gif import Gif
 from docx.image.jpeg import Exif, Jfif
 from docx.image.png import Png
+from docx.image.svg import Svg
 from docx.image.tiff import Tiff
-from docx.image.emf import Emf
 
 
 SIGNATURES = (
@@ -26,4 +27,6 @@ SIGNATURES = (
     (Tiff, 0, b"II*\x00"),  # little-endian (Intel) TIFF
     (Bmp, 0, b"BM"),
     (Emf, 0, b"\x01\x00\x00\x00"),
+    (Svg, 0, b"<svg "),
+    (Svg, 0, b"<?xml version="),
 )

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/docx/image/constants.py

@@ -114,6 +114,7 @@ class MIME_TYPE(object):
     PNG = "image/png"
     TIFF = "image/tiff"
     EMF = "image/emf"
+    SVG = "image/svg+xml"
 
 
 class PNG_CHUNK_TYPE(object):

python_docx_oss-0.0.9rc1/docx/image/svg.py

@@ -0,0 +1,65 @@
+import xml.etree.ElementTree as ET
+
+from .constants import MIME_TYPE
+from .image import BaseImageHeader
+
+BASE_PX = 72
+
+
+class Svg(BaseImageHeader):
+    """
+    Image header parser for SVG images.
+    """
+
+    @classmethod
+    def from_stream(cls, stream):
+        """
+        Return |Svg| instance having header properties parsed from SVG image
+        in *stream*.
+        """
+        px_width, px_height = cls._dimensions_from_stream(stream)
+        return cls(px_width, px_height, 72, 72)
+
+    @property
+    def content_type(self):
+        """
+        MIME content type for this image, unconditionally `image/svg+xml` for
+        SVG images.
+        """
+        return MIME_TYPE.SVG
+
+    @property
+    def default_ext(self):
+        """
+        Default filename extension, always 'svg' for SVG images.
+        """
+        return "svg"
+
+    @classmethod
+    def _dimensions_from_stream(cls, stream):
+        stream.seek(0)
+        data = stream.read()
+        root = ET.fromstring(data)
+        if root.attrib.get("width") is None:
+            return cls._calculate_scaled_dimensions(root.attrib["viewBox"])
+
+        width = int(root.attrib["width"])
+        height = int(root.attrib["height"])
+        return width, height
+
+    @classmethod
+    def _calculate_scaled_dimensions(
+        cls, viewbox: str, base_px: int = BASE_PX
+    ) -> tuple[int, int]:
+        _, _, logical_width, logical_height = map(int, viewbox.split())
+
+        aspect_ratio = logical_width / logical_height
+
+        if aspect_ratio >= 1:
+            final_width = base_px
+            final_height = base_px / aspect_ratio
+        else:
+            final_height = base_px
+            final_width = base_px * aspect_ratio
+
+        return int(final_width), int(final_height)

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/docx/oxml/__init__.py

@@ -133,6 +133,8 @@ from .shape import (
 
 register_element_cls("a:blip", CT_Blip)
 register_element_cls("a:ext", CT_PositiveSize2D)
+register_element_cls("a:extLst", CT_Transform2D)
+register_element_cls("asvg:svgBlip", CT_Transform2D)
 register_element_cls("a:graphic", CT_GraphicalObject)
 register_element_cls("a:graphicData", CT_GraphicalObjectData)
 register_element_cls("a:off", CT_Point2D)

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/docx/oxml/ns.py

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 """
 Namespace-related objects.
 """
@@ -25,9 +23,10 @@ nsmap = {
     "wp": "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
     "xml": "http://www.w3.org/XML/1998/namespace",
     "xsi": "http://www.w3.org/2001/XMLSchema-instance",
+    "asvg": "http://schemas.microsoft.com/office/drawing/2016/SVG/main",
 }
 
-pfxmap = dict((value, key) for key, value in nsmap.items())
+pfxmap = {value: key for key, value in nsmap.items()}
 
 
 class NamespacePrefixedTag(str):
@@ -50,7 +49,7 @@ class NamespacePrefixedTag(str):
     @classmethod
     def from_clark_name(cls, clark_name):
         nsuri, local_name = clark_name[1:].split("}")
-        nstag = "%s:%s" % (pfxmap[nsuri], local_name)
+        nstag = f"{pfxmap[nsuri]}:{local_name}"
         return cls(nstag)
 
     @property
@@ -93,7 +92,7 @@ def nsdecls(*prefixes):
     Return a string containing a namespace declaration for each of the
     namespace prefix strings, e.g. 'p', 'ct', passed as *prefixes*.
     """
-    return " ".join(['xmlns:%s="%s"' % (pfx, nsmap[pfx]) for pfx in prefixes])
+    return " ".join([f'xmlns:{pfx}="{nsmap[pfx]}"' for pfx in prefixes])
 
 
 def nspfxmap(*nspfxs):
@@ -102,7 +101,7 @@ def nspfxmap(*nspfxs):
     *nspfxs*. Any number of namespace prefixes can be supplied, e.g.
     namespaces('a', 'r', 'p').
     """
-    return dict((pfx, nsmap[pfx]) for pfx in nspfxs)
+    return {pfx: nsmap[pfx] for pfx in nspfxs}
 
 
 def qn(tag):

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/docx/oxml/shape.py

@@ -1,6 +1,7 @@
 """
 Custom element classes for shape-related elements like ``<w:inline>``
 """
+
 from docx.oxml import parse_xml
 from docx.oxml.ns import nsdecls
 from docx.oxml.xmlchemy import BaseOxmlElement, OneAndOnlyOne
@@ -31,6 +32,7 @@ class CT_Blip(BaseOxmlElement):
 
     embed = OptionalAttribute("r:embed", ST_RelationshipId)
     link = OptionalAttribute("r:link", ST_RelationshipId)
+    extLst = ZeroOrOne("a:extLst")
 
 
 class CT_BlipFillProperties(BaseOxmlElement):
@@ -108,7 +110,7 @@ class CT_Inline(BaseOxmlElement):
             "  <a:graphic>\n"
             '    <a:graphicData uri="URI not set"/>\n'
             "  </a:graphic>\n"
-            "</wp:inline>" % nsdecls("wp", "a", "pic", "r")
+            "</wp:inline>" % nsdecls("wp", "a", "pic", "r", "asvg")
         )
 
 
@@ -145,14 +147,48 @@ class CT_Picture(BaseOxmlElement):
         contents required to define a viable picture element, based on the
         values passed as parameters.
         """
-        pic = parse_xml(cls._pic_xml())
+        if filename.endswith(".svg"):
+            pic = parse_xml(cls._pic_xml_svg())
+            pic.blipFill.blip.extLst.ext.svgBlip.embed = rId
+        else:
+            pic = parse_xml(cls._pic_xml())
+            pic.blipFill.blip.embed = rId
         pic.nvPicPr.cNvPr.id = pic_id
         pic.nvPicPr.cNvPr.name = filename
-        pic.blipFill.blip.embed = rId
         pic.spPr.cx = cx
         pic.spPr.cy = cy
         return pic
 
+    @classmethod
+    def _pic_xml_svg(cls):
+        return (
+            "<pic:pic %s>\n"
+            "  <pic:nvPicPr>\n"
+            '    <pic:cNvPr id="666" name="unnamed"/>\n'
+            "    <pic:cNvPicPr/>\n"
+            "  </pic:nvPicPr>\n"
+            "  <pic:blipFill>\n"
+            "    <a:blip>\n"
+            "      <a:extLst>\n"
+            '        <a:ext uri="{96DAC541-7B7A-43D3-8B79-37D633B846F1}">\n'
+            "          <asvg:svgBlip/>\n"
+            "        </a:ext>\n"
+            "      </a:extLst>\n"
+            "    </a:blip>\n"
+            "    <a:stretch>\n"
+            "      <a:fillRect/>\n"
+            "    </a:stretch>\n"
+            "  </pic:blipFill>\n"
+            "  <pic:spPr>\n"
+            "    <a:xfrm>\n"
+            '      <a:off x="0" y="0"/>\n'
+            '      <a:ext cx="914400" cy="914400"/>\n'
+            "    </a:xfrm>\n"
+            '    <a:prstGeom prst="rect"/>\n'
+            "  </pic:spPr>\n"
+            "</pic:pic>" % nsdecls("pic", "a", "r", "asvg")
+        )
+
     @classmethod
     def _pic_xml(cls):
         return (
@@ -174,7 +210,7 @@ class CT_Picture(BaseOxmlElement):
             "    </a:xfrm>\n"
             '    <a:prstGeom prst="rect"/>\n'
             "  </pic:spPr>\n"
-            "</pic:pic>" % nsdecls("pic", "a", "r")
+            "</pic:pic>" % nsdecls("pic", "a", "r", "asvg")
         )
 
 
@@ -204,6 +240,7 @@ class CT_PositiveSize2D(BaseOxmlElement):
 
     cx = RequiredAttribute("cx", ST_PositiveCoordinate)
     cy = RequiredAttribute("cy", ST_PositiveCoordinate)
+    svgBlip = ZeroOrOne("asvg:svgBlip")
 
 
 class CT_PresetGeometry2D(BaseOxmlElement):
@@ -260,9 +297,7 @@ class CT_ShapeProperties(BaseOxmlElement):
         Shape height as an instance of Emu, or None if not present.
         """
         xfrm = self.xfrm
-        if xfrm is None:
-            return None
-        return xfrm.cy
+        return None if xfrm is None else xfrm.cy
 
     @cy.setter
     def cy(self, value):
@@ -284,13 +319,12 @@ class CT_Transform2D(BaseOxmlElement):
 
     off = ZeroOrOne("a:off", successors=("a:ext",))
     ext = ZeroOrOne("a:ext", successors=())
+    embed = OptionalAttribute("r:embed", ST_RelationshipId)
 
     @property
     def cx(self):
         ext = self.ext
-        if ext is None:
-            return None
-        return ext.cx
+        return None if ext is None else ext.cx
 
     @cx.setter
     def cx(self, value):
@@ -300,9 +334,7 @@ class CT_Transform2D(BaseOxmlElement):
     @property
     def cy(self):
         ext = self.ext
-        if ext is None:
-            return None
-        return ext.cy
+        return None if ext is None else ext.cy
 
     @cy.setter
     def cy(self, value):

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1/python_docx_oss.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-docx-oss
-Version: 0.0.8rc1
+Version: 0.0.9rc1
 Summary: CRUD Microsoft Word .docx files.
 Home-page: https://github.com/lsaint/python-docx-oss
 Author: Ethan St. Lee
@@ -75,10 +75,15 @@ This project is based on the original work by [Steve Canny](https://github.com/s
 
 ## Release History
 
+**0.0.9 (2024-11-26)**
+
+-   svg file support in add_picture. #27
+-   update docs.
+
 **0.0.8 (2024-11-22)**
 
--   EastAsia font support fixes #25
--   Update README.md #26
+-   EastAsia font support fixes. #25
+-   Update README.md. #26
 
 **0.0.7 (2022-10-29)**
 

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/python_docx_oss.egg-info/SOURCES.txt

@@ -124,6 +124,7 @@ docx/image/helpers.py
 docx/image/image.py
 docx/image/jpeg.py
 docx/image/png.py
+docx/image/svg.py
 docx/image/tiff.py
 docx/opc/__init__.py
 docx/opc/compat.py
@@ -365,6 +366,7 @@ tests/image/test_helpers.py
 tests/image/test_image.py
 tests/image/test_jpeg.py
 tests/image/test_png.py
+tests/image/test_svg.py
 tests/image/test_tiff.py
 tests/opc/__init__.py
 tests/opc/test_coreprops.py

python_docx_oss-0.0.9rc1/tests/image/test_svg.py

@@ -0,0 +1,57 @@
+import io
+from xml.etree.ElementTree import Element, tostring
+
+import pytest
+
+from docx.image.svg import BASE_PX, Svg
+
+
+@pytest.fixture
+def svg_with_dimensions():
+    """Fixture for SVG stream with width and height."""
+    root = Element("svg", width="200", height="100")
+    return io.BytesIO(tostring(root))
+
+
+@pytest.fixture
+def svg_with_viewbox():
+    """Fixture for SVG stream with viewBox but no width and height."""
+    root = Element("svg", viewBox="0 0 400 200")
+    return io.BytesIO(tostring(root))
+
+
+@pytest.fixture(
+    params=[
+        ("0 0 400 200", 72, 36, 72),  # Landscape
+        ("0 0 200 400", 100, 200, 200),  # Portrait
+        ("0 0 100 100", 50, 50, 50),  # Square
+    ]
+)
+def viewbox_data(request):
+    """Fixture for different viewBox test cases as tuples."""
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        (b'<svg width="200" height="100"/>', 200, 100),
+        (b'<svg viewBox="0 0 400 200"/>', BASE_PX, BASE_PX // 2),
+    ]
+)
+def svg_stream_data(request):
+    return request.param
+
+
+def test_dimensions_from_stream(svg_stream_data):
+    stream_data, expected_width, expected_height = svg_stream_data
+    stream = io.BytesIO(stream_data)
+    width, height = Svg._dimensions_from_stream(stream)
+    assert width == expected_width
+    assert height == expected_height
+
+
+def test_calculate_scaled_dimensions(viewbox_data):
+    viewbox, expected_width, expected_height, base_px = viewbox_data
+    width, height = Svg._calculate_scaled_dimensions(viewbox, base_px)
+    assert width == expected_width
+    assert height == expected_height

{python_docx_oss-0.0.8rc1 → python_docx_oss-0.0.9rc1}/tests/test_files/snippets/inline.txt

@@ -1,4 +1,4 @@
-<wp:inline xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+<wp:inline xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:asvg="http://schemas.microsoft.com/office/drawing/2016/SVG/main">
   <wp:extent cx="444" cy="888"/>
   <wp:docPr id="24" name="Picture 24"/>
   <wp:cNvGraphicFramePr>