python-docx-oss 0.0.4__tar.gz → 0.0.6__tar.gz

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/HISTORY.md

@@ -1,6 +1,17 @@
 Release History
 ---------------
 
+**0.0.6 (2022-10-21)**
+
+- change default custom xml file name to item1.
+
+
+**0.0.5 (2022-8-08)**
+
+- minor refactor custom-properties
+- add add_float_picture in Document #21
+
+
 **0.0.4 (2022-7-21)**
 
 - public python-docx-oss docs @ readthedocs.

{python-docx-oss-0.0.4/python_docx_oss.egg-info → python-docx-oss-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-docx-oss
-Version: 0.0.4
+Version: 0.0.6
 Summary: Create and update Microsoft Word .docx files.
 Home-page: https://github.com/lsaint/python-docx-oss
 Author: Ethan St. Lee
@@ -42,7 +42,13 @@ Classifier: Topic :: Software Development :: Libraries
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
-**_python-docx-oss_** is a Python library for CRUD Microsoft Word (.docx) files.
+<p align="center">
+<img src="./docs/_static/img/oss.png" width="400" alt="oss"/>
+</p>
+
+*As a Brazilian jiu-jitsu player, OSS means anything and everything. It’s a term used in BJJ that is a way of greeting and demonstrating respect to others.*
+
+**_python-docx-oss_** is a Python library for CRUD Microsoft Word (.docx) files. It fork from [python-docx](https://github.com/python-openxml/python-docx).
 
 
 <p>
@@ -62,12 +68,23 @@ License-File: LICENSE
 
 ---
 
-More information is available in the [python-docx documentation](https://python-docx.readthedocs.org/en/latest/)
+More information is available in the [python-docx-oss documentation](https://python-docx-oss.readthedocs.io/en/latest/)
 
 
 Release History
 ---------------
 
+**0.0.6 (2022-10-21)**
+
+- change default custom xml file name to item1.
+
+
+**0.0.5 (2022-8-08)**
+
+- minor refactor custom-properties
+- add add_float_picture in Document #21
+
+
 **0.0.4 (2022-7-21)**
 
 - public python-docx-oss docs @ readthedocs.

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/README.md

@@ -1,4 +1,10 @@
-**_python-docx-oss_** is a Python library for CRUD Microsoft Word (.docx) files.
+<p align="center">
+<img src="./docs/_static/img/oss.png" width="400" alt="oss"/>
+</p>
+
+*As a Brazilian jiu-jitsu player, OSS means anything and everything. It’s a term used in BJJ that is a way of greeting and demonstrating respect to others.*
+
+**_python-docx-oss_** is a Python library for CRUD Microsoft Word (.docx) files. It fork from [python-docx](https://github.com/python-openxml/python-docx).
 
 
 <p>
@@ -18,4 +24,4 @@
 
 ---
 
-More information is available in the [python-docx documentation](https://python-docx.readthedocs.org/en/latest/)
+More information is available in the [python-docx-oss documentation](https://python-docx-oss.readthedocs.io/en/latest/)

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docs/conf.py

@@ -64,6 +64,8 @@ rst_epilog = """
 
 .. |docx| replace:: ``python-docx-oss``
 
+.. |python-docx-oss| replace:: ``python-docx-oss``
+
 .. |Emu| replace:: :class:`.Emu`
 
 .. |False| replace:: :class:`False`

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docs/index.rst

@@ -84,6 +84,7 @@ User Guide
    user/styles-understanding
    user/styles-using
    user/shapes
+   user/custom-properties
    user/custom-xml
 
 

python-docx-oss-0.0.6/docs/user/custom-properties.rst

@@ -0,0 +1,30 @@
+.. _custom_properties:
+
+Working with custom properties
+==============================
+The custom properties can be accessed/modified by navigating to 
+File menu --> Properties --> Advanced properties --> Customization in Word. 
+These properties are stored in the ``/docProps/custom.xml`` file.
+
+we can CRUD them via python-docx-oss::
+
+    from docx import Document
+    document = Document()
+
+    >>> print(document.custom_properties["not-exist-key"])
+    None
+
+    >>> document.custom_properties["bjj"] = "oss"
+    >>> print(document.custom_properties["bjj"])
+    oss
+    
+    >>> document.custom_properties["bjj"] = "rnc"
+    >>> print(document.custom_properties["bjj"])
+    rnc
+
+    >>> document.custom_properties["bjj"] = None
+    >>> print(document.custom_properties["bjj"])
+    None
+
+Be careful, users also can see & modify these properties in Word.
+Use :ref:`customXml<custom_xml>` if you need them hidden.

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docs/user/custom-xml.rst

@@ -1,4 +1,4 @@
-.. _custom-xml:
+.. _custom_xml:
 
 Working with customXml
 =======================
@@ -6,9 +6,10 @@ Working with customXml
 As we know, Word documents are .zip files under the hook. 
 Can we add any file in a docx file? Literally yes. 
 After we unzip a docx file, We can add a ``customXml`` folder at the root of it, 
-which contains any XML files. Files in other formats and paths are invalid. 
+which contains any .xml files. 
+Files with other extension and paths are invalid. 
 But it's enough for us to store custom data. 
-It can not be seen or modified in Word like ``CustomProperties``. 
+It can not be seen or modified in Word like :ref:`CustomProperties<custom_properties>`. 
 
 python-docx-oss will create a default XML file in the folder if there are not.
 Then developer can add/delete/modify items in it.

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/__init__.py

@@ -1,6 +1,6 @@
 from docx.api import Document  # noqa
 
-__version__ = "0.0.4"
+__version__ = "0.0.6"
 
 
 # register custom Part classes with opc package reader

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/document.py

@@ -1,9 +1,4 @@
-# encoding: utf-8
-
 """|Document| and closely related objects"""
-
-from __future__ import absolute_import, division, print_function, unicode_literals
-
 from docx.blkcntnr import BlockItemContainer
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
@@ -71,6 +66,13 @@ class Document(ElementProxy):
         run = self.add_paragraph().add_run()
         return run.add_picture(image_path_or_stream, width, height)
 
+    def add_float_picture(self, image_path_or_stream, width=None, height=None, pos_x=0, pos_y=0):
+        """
+        Add float picture at fixed position `pos_x` and `pos_y` to the top-left point of page.
+        """
+        run = self.add_paragraph().add_run()
+        return run.add_float_picture(image_path_or_stream, width, height, pos_x, pos_y)
+
     def add_section(self, start_type=WD_SECTION.NEW_PAGE):
         """
         Return a |Section| object representing a new section added at the end

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/opc/customprops.py

@@ -21,7 +21,7 @@ class CustomProperties:
             if elm.tag == "{%s}i4" % NS_VT:
                 try:
                     return int(elm.text)
-                except Exception:
+                except ValueError:
                     return elm.text
             elif elm.tag == "{%s}bool" % NS_VT:
                 return elm.text == "1"
@@ -38,9 +38,7 @@ class CustomProperties:
                 elmType = "i4"
                 value = str(int(value))
             prop = etree.SubElement(self._element, "property")
-            elm = etree.SubElement(
-                prop, "{%s}%s" % (NS_VT, elmType), nsmap={"vt": NS_VT}
-            )
+            elm = etree.SubElement(prop, "{%s}%s" % (NS_VT, elmType), nsmap={"vt": NS_VT})
             elm.text = value
             prop.set("name", key)
             prop.set("fmtid", "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}")
@@ -58,6 +56,4 @@ class CustomProperties:
         return len(self._element)
 
     def lookup(self, item):
-        return next(
-            (child for child in self._element if child.get("name") == item), None
-        )
+        return next((child for child in self._element if child.get("name") == item), None)

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/opc/parts/customprops.py

@@ -58,5 +58,4 @@ class CustomPropertiesPart(XmlPart):
     def _new(cls, package):
         partname = PackURI("/docProps/custom.xml")
         content_type = CT.OPC_CUSTOM_PROPERTIES
-        customProperties = CT_CustomProperties.new()
-        return CustomPropertiesPart(partname, content_type, customProperties, package)
+        return CustomPropertiesPart(partname, content_type, CT_CustomProperties.new(), package)

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/oxml/__init__.py

@@ -117,6 +117,7 @@ register_element_cls("w:settings", CT_Settings)
 
 from .shape import CT_GraphicalObject  # noqa
 from .shape import (
+    CT_Anchor,
     CT_Blip,
     CT_BlipFillProperties,
     CT_GraphicalObjectData,
@@ -144,6 +145,7 @@ register_element_cls("pic:spPr", CT_ShapeProperties)
 register_element_cls("wp:docPr", CT_NonVisualDrawingProps)
 register_element_cls("wp:extent", CT_PositiveSize2D)
 register_element_cls("wp:inline", CT_Inline)
+register_element_cls("wp:anchor", CT_Anchor)
 
 from .styles import CT_LatentStyles, CT_LsdException, CT_Style, CT_Styles  # noqa
 

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/oxml/customprops.py

@@ -1,19 +1,12 @@
-# encoding: utf-8
-
 """
 lxml custom element classes for core properties-related XML elements.
 """
-
-from __future__ import absolute_import, division, print_function, unicode_literals
-
 import re
 from datetime import datetime, timedelta
 
-from lxml import etree
-
 from . import parse_xml
 from .ns import nsdecls, qn
-from .xmlchemy import BaseOxmlElement, ZeroOrOne
+from .xmlchemy import BaseOxmlElement
 
 
 class CT_CustomProperties(BaseOxmlElement):
@@ -34,8 +27,7 @@ class CT_CustomProperties(BaseOxmlElement):
         Return a new ``<property>`` element
         """
         xml = cls._customProperties_tmpl
-        customProperties = parse_xml(xml)
-        return customProperties
+        return parse_xml(xml)
 
     def _datetime_of_element(self, property_name):
         element = getattr(self, property_name)
@@ -52,10 +44,9 @@ class CT_CustomProperties(BaseOxmlElement):
         """
         Return element returned by 'get_or_add_' method for *prop_name*.
         """
-        get_or_add_method_name = "get_or_add_%s" % prop_name
+        get_or_add_method_name = f"get_or_add_{prop_name}"
         get_or_add_method = getattr(self, get_or_add_method_name)
-        element = get_or_add_method()
-        return element
+        return get_or_add_method()
 
     @classmethod
     def _offset_dt(cls, dt, offset_str):

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/oxml/shape.py

@@ -1,10 +1,10 @@
-# encoding: utf-8
-
 """
 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
 
-from . import parse_xml
 from .ns import nsdecls
 from .simpletypes import (
     ST_Coordinate,
@@ -308,3 +308,67 @@ class CT_Transform2D(BaseOxmlElement):
     def cy(self, value):
         ext = self.get_or_add_ext()
         ext.cy = value
+
+
+class CT_Anchor(BaseOxmlElement):
+    """
+    ``<w:anchor>`` element, container for a floating image.
+    """
+
+    extent = OneAndOnlyOne("wp:extent")
+    docPr = OneAndOnlyOne("wp:docPr")
+    graphic = OneAndOnlyOne("a:graphic")
+
+    @classmethod
+    def new(cls, cx, cy, shape_id, pic, pos_x, pos_y):
+        """
+        Return a new ``<wp:anchor>`` element populated with the values passed
+        as parameters.
+        """
+        anchor = parse_xml(cls._anchor_xml(pos_x, pos_y))
+        anchor.extent.cx = cx
+        anchor.extent.cy = cy
+        anchor.docPr.id = shape_id
+        anchor.docPr.name = "Picture %d" % shape_id
+        anchor.graphic.graphicData.uri = (
+            "http://schemas.openxmlformats.org/drawingml/2006/picture"
+        )
+        anchor.graphic.graphicData._insert_pic(pic)
+        return anchor
+
+    @classmethod
+    def new_pic_anchor(cls, shape_id, rId, filename, cx, cy, pos_x, pos_y):
+        """
+        Return a new `wp:anchor` element containing the `pic:pic` element
+        specified by the argument values.
+        """
+        pic_id = 0  # Word doesn't seem to use this, but does not omit it
+        pic = CT_Picture.new(pic_id, filename, rId, cx, cy)
+        anchor = cls.new(cx, cy, shape_id, pic, pos_x, pos_y)
+        anchor.graphic.graphicData._insert_pic(pic)
+        return anchor
+
+    @classmethod
+    def _anchor_xml(cls, pos_x, pos_y):
+        return (
+            '<wp:anchor distT="0" distB="0" distL="0" distR="0" simplePos="0" relativeHeight="0" \n'
+            '           behindDoc="1" locked="0" layoutInCell="1" allowOverlap="1" \n'
+            "           %s>\n"
+            '  <wp:simplePos x="0" y="0"/>\n'
+            '  <wp:positionH relativeFrom="page">\n'
+            "    <wp:posOffset>%d</wp:posOffset>\n"
+            "  </wp:positionH>\n"
+            '  <wp:positionV relativeFrom="page">\n'
+            "    <wp:posOffset>%d</wp:posOffset>\n"
+            "  </wp:positionV>\n"
+            '  <wp:extent cx="914400" cy="914400"/>\n'
+            "  <wp:wrapNone/>\n"
+            '  <wp:docPr id="666" name="unnamed"/>\n'
+            "  <wp:cNvGraphicFramePr>\n"
+            '    <a:graphicFrameLocks noChangeAspect="1"/>\n'
+            "  </wp:cNvGraphicFramePr>\n"
+            "  <a:graphic>\n"
+            '    <a:graphicData uri="URI not set"/>\n'
+            "  </a:graphic>\n"
+            "</wp:anchor>" % (nsdecls("wp", "a", "pic", "r"), int(pos_x), int(pos_y))
+        )

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/parts/document.py

@@ -63,7 +63,7 @@ class DocumentPart(BaseStoryPart):
             return []
 
     def add_custom_xml_part(
-        self, xml: str, file_name: str = "item", content_type: str = CT.XML
+        self, xml: str, file_name: str = "item1", content_type: str = CT.XML
     ) -> CustomXmlPart:
         """
         Add a file in /customXml/*file_name*.xml with default content *xml*

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/parts/story.py

@@ -1,12 +1,7 @@
-# encoding: utf-8
-
 """|BaseStoryPart| and related objects"""
-
-from __future__ import absolute_import, division, print_function, unicode_literals
-
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.opc.part import XmlPart
-from docx.oxml.shape import CT_Inline
+from docx.oxml.shape import CT_Anchor, CT_Inline
 from docx.shared import lazyproperty
 
 
@@ -58,6 +53,17 @@ class BaseStoryPart(XmlPart):
         shape_id, filename = self.next_id, image.filename
         return CT_Inline.new_pic_inline(shape_id, rId, filename, cx, cy)
 
+    def new_pic_anchor(self, image_descriptor, width, height, pos_x, pos_y):
+        """Return a newly-created `w:anchor` element.
+
+        The element contains the image specified by *image_descriptor* and is scaled
+        based on the values of *width* and *height*.
+        """
+        rId, image = self.get_or_add_image(image_descriptor)
+        cx, cy = image.scaled_dimensions(width, height)
+        shape_id, filename = self.next_id, image.filename
+        return CT_Anchor.new_pic_anchor(shape_id, rId, filename, cx, cy, pos_x, pos_y)
+
     @property
     def next_id(self):
         """Next available positive integer id value in this story XML document.

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/docx/text/run.py

@@ -59,6 +59,12 @@ class Run(Parented):
         self._r.add_drawing(inline)
         return InlineShape(inline)
 
+    def add_float_picture(self, image_path_or_stream, width=None, height=None, pos_x=0, pos_y=0):
+        """Add float picture at fixed position `pos_x` and `pos_y` to the top-left point of page."""
+        anchor = self.part.new_pic_anchor(image_path_or_stream, width, height, pos_x, pos_y)
+        self._r.add_drawing(anchor)
+        return anchor
+
     def add_tab(self):
         """
         Add a ``<w:tab/>`` element at the end of the run, which Word

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6/python_docx_oss.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-docx-oss
-Version: 0.0.4
+Version: 0.0.6
 Summary: Create and update Microsoft Word .docx files.
 Home-page: https://github.com/lsaint/python-docx-oss
 Author: Ethan St. Lee
@@ -42,7 +42,13 @@ Classifier: Topic :: Software Development :: Libraries
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
-**_python-docx-oss_** is a Python library for CRUD Microsoft Word (.docx) files.
+<p align="center">
+<img src="./docs/_static/img/oss.png" width="400" alt="oss"/>
+</p>
+
+*As a Brazilian jiu-jitsu player, OSS means anything and everything. It’s a term used in BJJ that is a way of greeting and demonstrating respect to others.*
+
+**_python-docx-oss_** is a Python library for CRUD Microsoft Word (.docx) files. It fork from [python-docx](https://github.com/python-openxml/python-docx).
 
 
 <p>
@@ -62,12 +68,23 @@ License-File: LICENSE
 
 ---
 
-More information is available in the [python-docx documentation](https://python-docx.readthedocs.org/en/latest/)
+More information is available in the [python-docx-oss documentation](https://python-docx-oss.readthedocs.io/en/latest/)
 
 
 Release History
 ---------------
 
+**0.0.6 (2022-10-21)**
+
+- change default custom xml file name to item1.
+
+
+**0.0.5 (2022-8-08)**
+
+- minor refactor custom-properties
+- add add_float_picture in Document #21
+
+
 **0.0.4 (2022-7-21)**
 
 - public python-docx-oss docs @ readthedocs.

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/python_docx_oss.egg-info/SOURCES.txt

@@ -6,13 +6,13 @@ setup.py
 tox.ini
 docs/Makefile
 docs/conf.py
-docs/conf.py.bak
 docs/index.rst
 docs/requirements.txt
 docs/_static/.gitignore
 docs/_static/img/example-docx-01.png
 docs/_static/img/hdrftr-01.png
 docs/_static/img/hdrftr-02.png
+docs/_static/img/oss.png
 docs/_templates/layout.html
 docs/_templates/sidebarlinks.html
 docs/_themes/armstrong/LICENSE
@@ -81,6 +81,7 @@ docs/dev/analysis/schema/ct_body.rst
 docs/dev/analysis/schema/ct_document.rst
 docs/dev/analysis/schema/ct_p.rst
 docs/user/api-concepts.rst
+docs/user/custom-properties.rst
 docs/user/custom-xml.rst
 docs/user/documents.rst
 docs/user/hdrftr.rst

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/tests/opc/test_customprops.py

@@ -1,19 +1,10 @@
-# encoding: utf-8
-
 """
 Unit test suite for the docx.opc.customprops module
 """
-
-from __future__ import absolute_import, division, print_function, unicode_literals
-
 import pytest
 
-from datetime import datetime
-
 from docx.opc.customprops import CustomProperties
-from docx.oxml.customprops import CT_CustomProperties
 from docx.oxml import parse_xml
-from lxml import etree
 
 
 class DescribeCustomProperties(object):
@@ -53,12 +44,12 @@ class DescribeCustomProperties(object):
     )
     def prop_set_fixture(self, request, custom_properties_blank):
         prop_name, str_type, str_value, value = request.param
-        expected_xml = self.customProperties(prop_name, str_type, str_value)
+        expected_xml = self.custom_properties(prop_name, str_type, str_value)
         return custom_properties_blank, prop_name, value, expected_xml
 
     # fixture components ---------------------------------------------
 
-    def customProperties(self, prop_name, str_type, str_value):
+    def custom_properties(self, prop_name, str_type, str_value):
         tmpl = (
             '<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/custom-properties" '
             'xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes">\n'

{python-docx-oss-0.0.4 → python-docx-oss-0.0.6}/tests/test_document.py

@@ -1,15 +1,11 @@
-# encoding: utf-8
-
 """Unit test suite for the docx.document module"""
-
-from __future__ import absolute_import, division, print_function, unicode_literals
-
 import pytest
 
-from docx.document import _Body, Document
+from docx.document import Document, _Body
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
 from docx.opc.coreprops import CoreProperties
+from docx.oxml.shape import CT_Anchor
 from docx.parts.document import DocumentPart
 from docx.section import Section, Sections
 from docx.settings import Settings
@@ -21,7 +17,8 @@ from docx.text.paragraph import Paragraph
 from docx.text.run import Run
 
 from .unitutil.cxml import element, xml
-from .unitutil.mock import class_mock, instance_mock, method_mock, property_mock
+from .unitutil.mock import (class_mock, instance_mock, method_mock,
+                            property_mock)
 
 
 class DescribeDocument(object):
@@ -66,6 +63,21 @@ class DescribeDocument(object):
         run_.add_picture.assert_called_once_with(path, width, height)
         assert picture is picture_
 
+    def it_can_add_a_float_picture(self, add_float_picture_fixture):
+        (
+            document,
+            path,
+            width,
+            height,
+            pos_x,
+            pos_y,
+            run_,
+            float_picture_,
+        ) = add_float_picture_fixture
+        anchor = document.add_float_picture(path, width, height, pos_x, pos_y)
+        run_.add_float_picture.assert_called_once_with(path, width, height, pos_x, pos_y)
+        assert  anchor is float_picture_
+
     def it_can_add_a_section(
         self, add_section_fixture, Section_, section_, document_part_
     ):
@@ -180,6 +192,14 @@ class DescribeDocument(object):
         run_.add_picture.return_value = picture_
         return document, path, width, height, run_, picture_
 
+    @pytest.fixture
+    def add_float_picture_fixture(self, add_paragraph_, run_, float_picture_):
+        document = Document(None, None)
+        path, width, height, pos_x, pos_y = "foobar.png", 100, 200, 100000, 200000
+        add_paragraph_.return_value.add_run.return_value = run_
+        run_.add_float_picture.return_value = float_picture_
+        return document, path, width, height, pos_x, pos_y, run_, float_picture_
+
     @pytest.fixture(
         params=[
             ("w:sectPr", WD_SECTION.EVEN_PAGE, "w:sectPr/w:type{w:val=evenPage}"),
@@ -317,6 +337,10 @@ class DescribeDocument(object):
     def picture_(self, request):
         return instance_mock(request, InlineShape)
 
+    @pytest.fixture
+    def float_picture_(self, request):
+        return instance_mock(request, CT_Anchor)
+
     @pytest.fixture
     def run_(self, request):
         return instance_mock(request, Run)