python-docx-oss 0.1.0rc1__tar.gz → 0.1.1__tar.gz

python_docx_oss-0.1.1/HISTORY.md

@@ -0,0 +1,80 @@
+## Release History
+
+**0.1.1 (2026-08-21)**
+
+- Added Python 3.14 support and CI coverage for Python 3.12 through 3.14.
+- Added real Microsoft Word document round-trip coverage for floating pictures,
+  SVG images, East Asian fonts, and multiple Custom XML parts.
+- Fixed automatic Custom XML part naming to select an available `itemN.xml`
+  name and reject explicit name collisions.
+- Expanded the project overview, installation guide, in-memory document examples,
+  and Custom XML lifecycle documentation.
+
+**0.1.0 (2026-02-02)**
+
+- **UPSTREAM MERGE** with python-docx 1.2.0.
+- Backward Compatibility: Fixed a regression where `Font.name` returned a dictionary. It now correctly returns a string (ASCII name) while supporting multi-script assignment via setter. Added `Font.eastAsia` and `Font.hAnsi` properties for fine-grained font control.
+
+**0.0.12 (2025-12-03)**
+
+- default dpi for jpeg #33
+
+**0.0.11 (2025-11-17)**
+
+- round-float viewbox and enhance svg unit parsing #31
+
+**0.0.10 (2025-11-13)**
+
+- Fix modern bool representations in .docx files. #29
+- Fix \_dimensions_from_stream doesn't handle units properly from svg. #30
+
+**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
+
+**0.0.7 (2022-10-29)**
+
+- add emf image file support. #24
+
+**0.0.6 (2022-10-21)**
+
+- change default custom xml file name to item1. #23
+
+**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.
+- add delete_item in CustomXmlPart. #17
+
+**0.0.3 (2022-7-01)**
+
+- Change method text to texts in CT_R. #14
+- Add external target_ref setter. #15
+- Blacken all Python files.
+
+**0.0.2 (2022-06-24)**
+
+- Add custom xml support. #10
+- Add Part **eq**.
+- Add Part element setter.
+- Add Relationships parts_with_reltype.
+
+**0.0.1 (2022-06-16)**
+
+- Only support Python3.8, 3.9 and 3.10.
+- Add custom properties support. #2
+- Add drop_rels in Package. #5
+- Add drop_rels in Part. #5
+- Add default NumberingPart. #4
+- Fix Python3.8+ **dict** TypeError. #6
+- Add some typehint.

{python_docx_oss-0.1.0rc1 → python_docx_oss-0.1.1}/MANIFEST.in

@@ -1,4 +1,4 @@
-include HISTORY.rst LICENSE README.rst tox.ini
+include HISTORY.md LICENSE README.md tox.ini
 include requirements*.txt
 graft src/docx/templates
 graft features

python_docx_oss-0.1.1/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: python-docx-oss
+Version: 0.1.1
+Summary: Create, read, and update Microsoft Word .docx files.
+Author: Ethan St Lee
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/lsaint/python-docx-oss/blob/master/HISTORY.md
+Project-URL: Documentation, https://python-docx-oss.readthedocs.io/en/latest/
+Project-URL: Issues, https://github.com/lsaint/python-docx-oss/issues
+Project-URL: Repository, https://github.com/lsaint/python-docx-oss
+Keywords: docx,office,openxml,word
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml>=3.1.0
+Requires-Dist: typing_extensions>=4.9.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lsaint/python-docx-oss/master/docs/_static/img/oss.png" width="400" alt="python-docx-oss"/>
+</p>
+
+<p align="center">
+  <strong>A Python SDK for advanced creation and manipulation of Microsoft Word <code>.docx</code> files.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/python-docx-oss/"><img alt="PyPI" src="https://img.shields.io/pypi/v/python-docx-oss"></a>
+  <a href="https://pypi.org/project/python-docx-oss/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/python-docx-oss.svg"></a>
+  <a href="https://github.com/astral-sh/ruff"><img alt="Code style: Ruff" src="https://img.shields.io/badge/code%20style-ruff-FF6B6B.svg?logo=ruff&logoColor=white"></a>
+  <a href="https://github.com/lsaint/python-docx-oss/blob/master/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+</p>
+
+## Overview
+
+`python-docx-oss` is an independently evolving DOCX SDK built on the proven API
+foundation of [`python-docx`](https://github.com/python-openxml/python-docx). It keeps
+the familiar `docx` programming model while extending it for advanced OOXML and Open
+Packaging Convention (OPC) workflows.
+
+Use it when an application needs more than basic paragraphs and tables: custom document
+metadata, application-owned XML, vector images, floating pictures, East Asian fonts,
+or low-level package and relationship access.
+
+## Features
+
+| Capability | Support |
+| --- | --- |
+| Documents, paragraphs, runs, tables, styles, sections, headers, and footers | ✓ |
+| Custom document properties | ✓ |
+| Custom XML parts | ✓ |
+| SVG and EMF images | ✓ |
+| Inline and floating pictures | ✓ |
+| Independent ASCII, High ANSI, and East Asian font controls | ✓ |
+| Low-level OPC parts and relationships | ✓ |
+| File-path and in-memory stream processing | ✓ |
+
+## Installation
+
+```bash
+python -m pip install python-docx-oss
+```
+
+The distribution name is `python-docx-oss`, but the Python import namespace remains
+`docx`:
+
+```python
+from docx import Document
+```
+
+> [!WARNING]
+> `python-docx` and `python-docx-oss` provide the same `docx` import namespace. Do not
+> install both distributions in the same Python environment.
+
+`python-docx-oss` currently supports Python 3.12, 3.13, and 3.14.
+
+## Quick Start
+
+Create a document entirely in memory:
+
+```python
+from io import BytesIO
+
+from docx import Document
+
+document = Document()
+document.add_heading("Quarterly Report", level=1)
+document.add_paragraph("Generated entirely in memory.")
+
+output = BytesIO()
+document.save(output)
+
+docx_bytes = output.getvalue()
+```
+
+The same APIs also accept filesystem paths:
+
+```python
+document = Document("input.docx")
+document.add_paragraph("Appended by python-docx-oss.")
+document.save("output.docx")
+```
+
+## Advanced Capabilities
+
+### Custom properties
+
+```python
+document = Document()
+document.custom_properties["workflow_status"] = "approved"
+document.custom_properties["revision"] = 3
+```
+
+Custom properties are visible in Microsoft Word and stored in
+`/docProps/custom.xml`. See [Working with custom
+properties](docs/user/custom-properties.rst).
+
+### Custom XML
+
+```python
+custom_xml = document.part.add_custom_xml_part(
+    '<order xmlns="urn:example:orders" id="A-001"/>',
+)
+custom_xml.add_item("status", "ready")
+```
+
+See [Working with Custom XML](docs/user/custom-xml.rst) for lifecycle and compatibility
+considerations.
+
+### East Asian fonts
+
+```python
+run = document.add_paragraph().add_run("English 与中文")
+run.font.name = "Open Sans"
+run.font.eastAsia = "Microsoft YaHei"
+```
+
+SVG and EMF streams can be passed to the standard picture APIs. Floating pictures are
+available through `Document.add_float_picture()` and `Run.add_float_picture()`.
+
+## Compatibility and Scope
+
+- The project maintains broad compatibility with the public `python-docx` API while
+  following its own versioning and product roadmap.
+- Compatibility does not extend to every private or internal `python-docx` API. Test
+  those integrations before migrating production systems.
+- The SDK focuses exclusively on DOCX. It is not a general XLSX/PPTX Office suite.
+- It edits document structure but does not implement Word's page-layout rendering
+  engine.
+- CLI, MCP, web, desktop, and Agent runtimes belong in separate packages that consume
+  this SDK.
+
+## Documentation
+
+- [Documentation site](https://python-docx-oss.readthedocs.io/en/latest/)
+- [Installation guide](docs/user/install.rst)
+- [Quickstart](docs/user/quickstart.rst)
+- [User guide](docs/index.rst)
+- [API reference](docs/index.rst#api-documentation)
+- [Custom properties](docs/user/custom-properties.rst)
+- [Custom XML](docs/user/custom-xml.rst)
+- [Release history](HISTORY.md)
+
+## Quality and Testing
+
+The test suite combines unit and acceptance coverage with in-memory round-trip tests
+using documents created by Microsoft Word. The integration fixtures cover floating
+pictures, SVG fallback relationships, East Asian fonts, Custom XML parts, and core OPC
+package preservation.
+
+For local development:
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run pyright
+```
+
+## Project Status
+
+The current focus is stabilizing the independent SDK baseline, its in-memory workflows,
+and its advanced OOXML capabilities before expanding document inspection, comparison,
+sanitization, composition, and validation APIs.
+
+## Credits
+
+This project builds on the original work of
+[`python-docx`](https://github.com/python-openxml/python-docx) creator Steve Canny and
+its contributors. `python-docx-oss` is maintained by Ethan St Lee and its contributors.
+
+## Why “OSS”?
+
+In Brazilian jiu-jitsu, “oss” is a greeting and an expression of respect. It reflects
+the same spirit of discipline and collaboration behind this project.
+
+## License
+
+`python-docx-oss` is released under the [MIT License](LICENSE).
+
+## Support
+
+If this project is useful to you, you can support its continued development through
+the [donation page](https://lsaint.github.io/donation/?utm_source=github&utm_medium=readme&utm_campaign=python-docx-oss).

python_docx_oss-0.1.1/README.md

@@ -0,0 +1,186 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lsaint/python-docx-oss/master/docs/_static/img/oss.png" width="400" alt="python-docx-oss"/>
+</p>
+
+<p align="center">
+  <strong>A Python SDK for advanced creation and manipulation of Microsoft Word <code>.docx</code> files.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/python-docx-oss/"><img alt="PyPI" src="https://img.shields.io/pypi/v/python-docx-oss"></a>
+  <a href="https://pypi.org/project/python-docx-oss/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/python-docx-oss.svg"></a>
+  <a href="https://github.com/astral-sh/ruff"><img alt="Code style: Ruff" src="https://img.shields.io/badge/code%20style-ruff-FF6B6B.svg?logo=ruff&logoColor=white"></a>
+  <a href="https://github.com/lsaint/python-docx-oss/blob/master/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+</p>
+
+## Overview
+
+`python-docx-oss` is an independently evolving DOCX SDK built on the proven API
+foundation of [`python-docx`](https://github.com/python-openxml/python-docx). It keeps
+the familiar `docx` programming model while extending it for advanced OOXML and Open
+Packaging Convention (OPC) workflows.
+
+Use it when an application needs more than basic paragraphs and tables: custom document
+metadata, application-owned XML, vector images, floating pictures, East Asian fonts,
+or low-level package and relationship access.
+
+## Features
+
+| Capability | Support |
+| --- | --- |
+| Documents, paragraphs, runs, tables, styles, sections, headers, and footers | ✓ |
+| Custom document properties | ✓ |
+| Custom XML parts | ✓ |
+| SVG and EMF images | ✓ |
+| Inline and floating pictures | ✓ |
+| Independent ASCII, High ANSI, and East Asian font controls | ✓ |
+| Low-level OPC parts and relationships | ✓ |
+| File-path and in-memory stream processing | ✓ |
+
+## Installation
+
+```bash
+python -m pip install python-docx-oss
+```
+
+The distribution name is `python-docx-oss`, but the Python import namespace remains
+`docx`:
+
+```python
+from docx import Document
+```
+
+> [!WARNING]
+> `python-docx` and `python-docx-oss` provide the same `docx` import namespace. Do not
+> install both distributions in the same Python environment.
+
+`python-docx-oss` currently supports Python 3.12, 3.13, and 3.14.
+
+## Quick Start
+
+Create a document entirely in memory:
+
+```python
+from io import BytesIO
+
+from docx import Document
+
+document = Document()
+document.add_heading("Quarterly Report", level=1)
+document.add_paragraph("Generated entirely in memory.")
+
+output = BytesIO()
+document.save(output)
+
+docx_bytes = output.getvalue()
+```
+
+The same APIs also accept filesystem paths:
+
+```python
+document = Document("input.docx")
+document.add_paragraph("Appended by python-docx-oss.")
+document.save("output.docx")
+```
+
+## Advanced Capabilities
+
+### Custom properties
+
+```python
+document = Document()
+document.custom_properties["workflow_status"] = "approved"
+document.custom_properties["revision"] = 3
+```
+
+Custom properties are visible in Microsoft Word and stored in
+`/docProps/custom.xml`. See [Working with custom
+properties](docs/user/custom-properties.rst).
+
+### Custom XML
+
+```python
+custom_xml = document.part.add_custom_xml_part(
+    '<order xmlns="urn:example:orders" id="A-001"/>',
+)
+custom_xml.add_item("status", "ready")
+```
+
+See [Working with Custom XML](docs/user/custom-xml.rst) for lifecycle and compatibility
+considerations.
+
+### East Asian fonts
+
+```python
+run = document.add_paragraph().add_run("English 与中文")
+run.font.name = "Open Sans"
+run.font.eastAsia = "Microsoft YaHei"
+```
+
+SVG and EMF streams can be passed to the standard picture APIs. Floating pictures are
+available through `Document.add_float_picture()` and `Run.add_float_picture()`.
+
+## Compatibility and Scope
+
+- The project maintains broad compatibility with the public `python-docx` API while
+  following its own versioning and product roadmap.
+- Compatibility does not extend to every private or internal `python-docx` API. Test
+  those integrations before migrating production systems.
+- The SDK focuses exclusively on DOCX. It is not a general XLSX/PPTX Office suite.
+- It edits document structure but does not implement Word's page-layout rendering
+  engine.
+- CLI, MCP, web, desktop, and Agent runtimes belong in separate packages that consume
+  this SDK.
+
+## Documentation
+
+- [Documentation site](https://python-docx-oss.readthedocs.io/en/latest/)
+- [Installation guide](docs/user/install.rst)
+- [Quickstart](docs/user/quickstart.rst)
+- [User guide](docs/index.rst)
+- [API reference](docs/index.rst#api-documentation)
+- [Custom properties](docs/user/custom-properties.rst)
+- [Custom XML](docs/user/custom-xml.rst)
+- [Release history](HISTORY.md)
+
+## Quality and Testing
+
+The test suite combines unit and acceptance coverage with in-memory round-trip tests
+using documents created by Microsoft Word. The integration fixtures cover floating
+pictures, SVG fallback relationships, East Asian fonts, Custom XML parts, and core OPC
+package preservation.
+
+For local development:
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run pyright
+```
+
+## Project Status
+
+The current focus is stabilizing the independent SDK baseline, its in-memory workflows,
+and its advanced OOXML capabilities before expanding document inspection, comparison,
+sanitization, composition, and validation APIs.
+
+## Credits
+
+This project builds on the original work of
+[`python-docx`](https://github.com/python-openxml/python-docx) creator Steve Canny and
+its contributors. `python-docx-oss` is maintained by Ethan St Lee and its contributors.
+
+## Why “OSS”?
+
+In Brazilian jiu-jitsu, “oss” is a greeting and an expression of respect. It reflects
+the same spirit of discipline and collaboration behind this project.
+
+## License
+
+`python-docx-oss` is released under the [MIT License](LICENSE).
+
+## Support
+
+If this project is useful to you, you can support its continued development through
+the [donation page](https://lsaint.github.io/donation/?utm_source=github&utm_medium=readme&utm_campaign=python-docx-oss).

{python_docx_oss-0.1.0rc1 → python_docx_oss-0.1.1}/docs/conf.py

@@ -20,8 +20,8 @@ from docx import __version__  # noqa
 # -- Project information -----------------------------------------------------
 
 project = "python-docx-oss"
-copyright = "2022, Ethan St. Lee"
-author = "Ethan St. Lee"
+copyright = "2022-2026, Ethan St Lee"
+author = "Ethan St Lee"
 
 # The full version, including alpha/beta/rc tags
 release = __version__

{python_docx_oss-0.1.0rc1 → python_docx_oss-0.1.1}/docs/index.rst

@@ -1,14 +1,12 @@
-.. 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!
-===========================================
+python-docx-oss documentation
+=============================
 
 Release v\ |release| (:ref:`Installation <install>`)
 
-*python-docx-oss* is a Python library for CRUD Microsoft Word (.docx) files.
+*python-docx-oss* is an independently developed Python SDK for creating,
+reading, and updating Microsoft Word (``.docx``) files. It combines familiar
+document APIs with advanced WordprocessingML capabilities such as floating and
+vector images, East Asian font control, custom properties, and Custom XML.
 
 
 What it can do
@@ -16,7 +14,17 @@ What it can do
 
 .. |img| image:: /_static/img/example-docx-01.png 
 
-Here's an example of what |docx| can do:
+The library supports common document operations, including paragraphs, text
+formatting, tables, sections, headers, footers, comments, and images. It also
+supports capabilities needed by more demanding document workflows:
+
+* floating images with position and text wrapping;
+* SVG and EMF vector images;
+* separate Latin and East Asian font settings;
+* document custom properties; and
+* multiple Custom XML parts that survive a load/save round trip.
+
+Here is a small example:
 
 ::
 

python_docx_oss-0.1.1/docs/user/custom-xml.rst

@@ -0,0 +1,95 @@
+.. _custom_xml:
+
+Working with Custom XML
+=======================
+
+A ``.docx`` file is an Open Packaging Conventions package. Custom XML parts
+store application-specific XML inside its ``customXml`` directory without
+placing that data in the visible document body.
+
+.. warning::
+
+   Some applications that edit ``.docx`` files may remove Custom XML parts.
+   Test the complete editing workflow used by your application. For simple
+   scalar metadata, :ref:`Custom Properties <custom_properties>` may be a more
+   interoperable choice.
+
+
+Creating a part
+---------------
+
+Create a Custom XML part from a well-formed XML string::
+
+    from docx import Document
+
+    document = Document()
+    customers = document.part.add_custom_xml_part(
+        '<customers xmlns="urn:example:customers"><customer id="1">Ada</customer></customers>'
+    )
+    document.save("customers.docx")
+
+When no ``file_name`` is supplied, |docx| selects the next available package
+name matching ``/customXml/itemN.xml``. For example, if ``item1.xml`` and
+``item3.xml`` already exist, the new part is named ``item2.xml``.
+
+An explicit name can be supplied without the ``.xml`` suffix::
+
+    audit = document.part.add_custom_xml_part(
+        "<audit><event>created</event></audit>",
+        file_name="audit",
+    )
+
+The resulting part name is ``/customXml/audit.xml``. A ``ValueError`` is raised
+if that part name already exists.
+
+
+Finding parts
+-------------
+
+``document.part.custom_xml_parts`` returns all Custom XML parts related to the
+main document. Select a part by its package name or root element rather than by
+list position::
+
+    parts_by_name = {
+        str(part.partname): part
+        for part in document.part.custom_xml_parts
+    }
+    customers = parts_by_name["/customXml/item1.xml"]
+
+    print(customers.tag)
+    print(customers.attrib)
+    print(customers.items)
+
+
+Updating child elements
+-----------------------
+
+``items`` contains the child elements of the part's root element. These are
+``lxml`` elements, so their text and attributes can be updated directly::
+
+    customer = customers.items[0]
+    customer.text = "Grace"
+    customer.attrib["status"] = "active"
+
+Use Clark notation when adding an element in a namespace::
+
+    customers.add_item(
+        "{urn:example:customers}customer",
+        "Linus",
+        id="2",
+    )
+
+
+Deleting child elements
+-----------------------
+
+Delete a child by passing the element itself::
+
+    customer = customers.items[0]
+    customers.delete_item(customer)
+
+The indexes in ``items`` can change after deletion. Removing an entire Custom
+XML part is not currently provided by this API.
+
+Existing relationships to Custom XML property parts, such as
+``itemPropsN.xml``, are preserved during load/save round trips.

{python_docx_oss-0.1.0rc1 → python_docx_oss-0.1.1}/docs/user/documents.rst

@@ -61,34 +61,36 @@ Things to note:
   what you intend.
 
 
-Opening a 'file-like' document
-------------------------------
+Opening a file-like document
+----------------------------
 
 |docx| can open a document from a so-called *file-like* object. It can also
 save to a file-like object. This can be handy when you want to get the source
 or target document over a network connection or from a database and don't want
-to (or aren't allowed to) interact with the file system. In practice this means
-you can pass an open file or StringIO/BytesIO stream object to open or save
-a document like so::
+to (or aren't allowed to) interact with the file system. A ``.docx`` package is
+binary, so an in-memory stream must be an :class:`io.BytesIO` object::
 
-    f = open('foobar.docx', 'rb')
-    document = Document(f)
-    f.close()
+    from io import BytesIO
 
-    # or
+    from docx import Document
 
-    with open('foobar.docx', 'rb') as f:
-        source_stream = StringIO(f.read())
+    with open("foobar.docx", "rb") as file:
+        source_stream = BytesIO(file.read())
     document = Document(source_stream)
-    source_stream.close()
-    ...
-    target_stream = StringIO()
+
+    document.add_paragraph("Added in memory")
+
+    target_stream = BytesIO()
     document.save(target_stream)
 
-The ``'rb'`` file open mode parameter isn't required on all operating
-systems. It defaults to ``'r'`` which is enough sometimes, but the 'b'
-(selecting binary mode) is required on Windows and at least some versions of
-Linux to allow Zipfile to open the file.
+The caller owns streams passed to |docx| and is responsible for closing them.
+After saving, rewind the output stream before reading it or opening it again::
+
+    target_stream.seek(0)
+    reopened = Document(target_stream)
+
+Always open ``.docx`` files in binary mode (``"rb"`` for reading and ``"wb"``
+for writing).
 
 Okay, so you've got a document open and are pretty sure you can save it
 somewhere later. Next step is to get some content in there ...