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

python_docx_oss-0.2.0/HISTORY.md

@@ -0,0 +1,91 @@
+## Release History
+
+**0.2.0 (2026-08-24)**
+
+- Added direct loading from raw DOCX bytes with ``Document(bytes)``.
+- Added ``Document.to_bytes()`` for in-memory export and ``Document.copy()``
+  for independent document snapshots.
+- Added safe removal of Custom XML parts, including their document and property
+  relationships.
+- Added real-document EMF round-trip coverage and corrected the EMF MIME type.
+- Documented the capability matrix, upstream maintenance policy, and
+  compatibility boundary with official ``python-docx``.
+
+**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.2.0}/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.2.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: python-docx-oss
+Version: 0.2.0
+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.
+
+## Capability Matrix
+
+| Capability | Status | Primary API |
+| --- | --- | --- |
+| Documents, paragraphs, tables, styles, sections, headers, and footers | Stable | `Document()` and document object APIs |
+| Custom document properties | Stable | `document.custom_properties` |
+| Custom XML lifecycle | Stable | `add_custom_xml_part()`, `delete_custom_xml_part()` |
+| SVG and EMF images | Stable | `add_picture()` |
+| Inline and floating pictures | Stable | `add_picture()`, `add_float_picture()` |
+| Latin and East Asian font controls | Stable | `run.font.name`, `run.font.hAnsi`, `run.font.eastAsia` |
+| Low-level OPC parts and relationships | Stable | `document.part.package`, `part.rels` |
+| In-memory read, export, and independent copies | Stable | `Document()`, `to_bytes()`, `copy()` |
+| Package inspection, diff, and sanitization | Planned | — |
+
+## 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)
+- [python-docx compatibility](docs/user/compatibility.rst)
+- [Upstream maintenance](docs/dev/upstream-maintenance.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.2.0/README.md

@@ -0,0 +1,189 @@
+<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.
+
+## Capability Matrix
+
+| Capability | Status | Primary API |
+| --- | --- | --- |
+| Documents, paragraphs, tables, styles, sections, headers, and footers | Stable | `Document()` and document object APIs |
+| Custom document properties | Stable | `document.custom_properties` |
+| Custom XML lifecycle | Stable | `add_custom_xml_part()`, `delete_custom_xml_part()` |
+| SVG and EMF images | Stable | `add_picture()` |
+| Inline and floating pictures | Stable | `add_picture()`, `add_float_picture()` |
+| Latin and East Asian font controls | Stable | `run.font.name`, `run.font.hAnsi`, `run.font.eastAsia` |
+| Low-level OPC parts and relationships | Stable | `document.part.package`, `part.rels` |
+| In-memory read, export, and independent copies | Stable | `Document()`, `to_bytes()`, `copy()` |
+| Package inspection, diff, and sanitization | Planned | — |
+
+## 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)
+- [python-docx compatibility](docs/user/compatibility.rst)
+- [Upstream maintenance](docs/dev/upstream-maintenance.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.2.0}/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.2.0/docs/dev/upstream-maintenance.rst

@@ -0,0 +1,95 @@
+Upstream maintenance
+====================
+
+``python-docx-oss`` evolves as an independent DOCX SDK. Its source, tests,
+versioning, and releases are authoritative in this repository. The official
+`python-docx repository <https://github.com/python-openxml/python-docx>`_ is an
+upstream source of compatible APIs, bug fixes, and OPC/WordprocessingML
+improvements; it is not the development repository for ``python-docx-oss``.
+
+Upstream baseline
+-----------------
+
+The current upstream baseline is ``python-docx v1.2.0`` at commit
+``e45454602b53e8e572b179ccf1c91093ec9f4ed7``.
+
+This baseline identifies the last official release whose changes have been
+evaluated as a whole. It does not imply compatibility with every private or
+internal upstream API.
+
+No local repository layout is required. A maintainer may obtain upstream source
+using a temporary clone, a read-only Git remote, a release archive, or another
+equivalent method. Maintenance instructions and project documentation must not
+depend on sibling directories, personal filesystem paths, or local-only
+branches.
+
+When to evaluate upstream
+-------------------------
+
+Evaluate upstream changes when:
+
+* ``python-docx`` publishes a release;
+* upstream fixes a security, data-loss, or document-compatibility issue;
+* a supported downstream workflow needs a new standard API; or
+* an upcoming ``python-docx-oss`` release needs a baseline refresh.
+
+Continuous synchronization with individual upstream commits is not required.
+
+Integration workflow
+--------------------
+
+#. Obtain the target upstream tag or commit and compare it with the recorded
+   baseline.
+#. Review release notes and classify changes to public APIs, OPC packaging,
+   XML handling, templates, schemas, tests, and documentation.
+#. Create a dedicated branch in ``python-docx-oss`` for the integration. The
+   branch name and the location used to obtain upstream source are not part of
+   the public maintenance contract.
+#. Integrate the relevant changes as a reviewable change set. Preserve upstream
+   history when practical, but prefer a clear, auditable result over a blind
+   merge.
+#. Resolve conflicts according to the compatibility rules below.
+#. Run the full verification gates and review the package artifacts.
+#. Update this baseline, compatibility notes, and ``HISTORY.md`` in the same
+   integration change.
+
+Compatibility and conflict rules
+--------------------------------
+
+Standard public ``python-docx`` behavior is preferred unless adopting it would
+break an API intentionally supported by ``python-docx-oss``. An upstream
+integration must preserve the supported capabilities documented in the
+Capability Matrix and covered by the regression test suite.
+
+Compatibility with upstream private APIs is not guaranteed. Intentional public
+API differences must be recorded in compatibility or divergence notes rather
+than hidden in conflict-resolution commits.
+
+Verification gates
+------------------
+
+An upstream integration is complete only when the repository CI passes. This
+includes:
+
+* unit, integration, and acceptance tests on all supported Python versions;
+* lint, formatting, and scoped type checks;
+* documentation and distribution builds; and
+* real-DOCX round trips required by the Capability Matrix and regression test
+  suite.
+
+The resulting wheel and source distribution must contain the expected package
+data and install without also installing the official ``python-docx``
+distribution, because both projects provide the ``docx`` import namespace.
+
+Recording the result
+--------------------
+
+For each completed baseline refresh, record:
+
+* the upstream tag and resolved commit;
+* the material APIs and fixes adopted;
+* intentionally omitted upstream changes and their rationale; and
+* any new compatibility boundary visible to users.
+
+Temporary comparison checkouts, remotes, and branches are local implementation
+details and are not part of the permanent project record.

{python_docx_oss-0.1.0rc1 → python_docx_oss-0.2.0}/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:
 
 ::
 
@@ -89,6 +97,7 @@ User Guide
    user/shapes
    user/custom-properties
    user/custom-xml
+   user/compatibility
 
 
 API Documentation
@@ -109,11 +118,11 @@ API Documentation
    api/shared
    api/enum/index
 
-
 Contributor Guide
 -----------------
 
 .. toctree::
    :maxdepth: 1
 
+   dev/upstream-maintenance
    dev/analysis/index