Pull updates from master repo

.fdignore

@@ -0,0 +1,7 @@
+.tox
+Session.vim
+build/
+docs/.build
+features/_scratch
+__pycache__/
+src/*.egg-info

.gitignore

@@ -1,7 +1,8 @@
+/build/
 .coverage
 /dist/
 /docs/.build/
-/*.egg-info
+/src/*.egg-info
 *.pyc
 .pytest_cache/
 _scratch/

.projections.json

@@ -0,0 +1,14 @@
+{
+  "src/docx/*.py" : {
+    "alternate" : [
+      "tests/{dirname}/test_{basename}.py"
+    ],
+    "type" : "source"
+  },
+  "tests/**/test_*.py" : {
+    "alternate" : [
+      "src/docx/{dirname}/{basename}.py"
+    ],
+    "type" : "test"
+  }
+}

.readthedocs.yaml

@@ -0,0 +1,19 @@
+version: 2
+
+# -- set the OS, Python version and other tools you might need --
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
+# -- build documentation in the "docs/" directory with Sphinx --
+sphinx:
+  configuration: docs/conf.py
+  # -- fail on all warnings to avoid broken references --
+  # fail_on_warning: true
+
+# -- package versions required to build your documentation --
+# -- see https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html --
+python:
+   install:
+   - requirements: requirements-docs.txt

.rgignore

@@ -0,0 +1,9 @@
+.tox
+Session.vim
+build/
+docs/.build
+features/_scratch
+__pycache__/
+ref/
+src/*.egg-info
+tests/test_files

HISTORY.rst

@@ -3,6 +3,62 @@
 Release History
 ---------------
 
+1.2.0 (2025-06-16)
+++++++++++++++++++
+
+- Add support for comments
+- Drop support for Python 3.8, add testing for Python 3.13
+
+
+1.1.2 (2024-05-01)
+++++++++++++++++++
+
+- Fix #1383 Revert lxml<=4.9.2 pin that breaks Python 3.12 install
+- Fix #1385 Support use of Part._rels by python-docx-template
+- Add support and testing for Python 3.12
+
+
+1.1.1 (2024-04-29)
+++++++++++++++++++
+
+- Fix #531, #1146 Index error on table with misaligned borders
+- Fix #1335 Tolerate invalid float value in bottom-margin
+- Fix #1337 Do not require typing-extensions at runtime
+
+
+1.1.0 (2023-11-03)
+++++++++++++++++++
+
+- Add BlockItemContainer.iter_inner_content()
+
+
+1.0.1 (2023-10-12)
+++++++++++++++++++
+
+- Fix #1256: parse_xml() and OxmlElement moved.
+- Add Hyperlink.fragment and .url
+
+
+1.0.0 (2023-10-01)
++++++++++++++++++++
+
+- Remove Python 2 support. Supported versions are 3.7+
+- Fix #85:   Paragraph.text includes hyperlink text
+- Add #1113: Hyperlink.address
+- Add Hyperlink.contains_page_break
+- Add Hyperlink.runs
+- Add Hyperlink.text
+- Add Paragraph.contains_page_break
+- Add Paragraph.hyperlinks
+- Add Paragraph.iter_inner_content()
+- Add Paragraph.rendered_page_breaks
+- Add RenderedPageBreak.following_paragraph_fragment
+- Add RenderedPageBreak.preceding_paragraph_fragment
+- Add Run.contains_page_break
+- Add Run.iter_inner_content()
+- Add Section.iter_inner_content()
+
+
 0.8.11 (2021-05-15)
 +++++++++++++++++++
 

MANIFEST.in

@@ -1,5 +1,6 @@
 include HISTORY.rst LICENSE README.rst tox.ini
-graft docx/templates
+include requirements*.txt
+graft src/docx/templates
 graft features
 graft tests
 graft docs

Makefile

@@ -1,46 +1,64 @@
 BEHAVE = behave
 MAKE   = make
 PYTHON = python
-SETUP  = $(PYTHON) ./setup.py
+TWINE  = $(PYTHON) -m twine
 
-.PHONY: accept clean coverage docs readme register sdist test upload
+.PHONY: accept build clean cleandocs coverage docs install opendocs sdist test
+.PHONY: test-upload wheel
 
 help:
 	@echo "Please use \`make <target>' where <target> is one or more of"
-	@echo "  accept    run acceptance tests using behave"
-	@echo "  clean     delete intermediate work product and start fresh"
-	@echo "  cleandocs delete intermediate documentation files"
-	@echo "  coverage  run nosetests with coverage"
-	@echo "  docs      generate documentation"
-	@echo "  opendocs  open browser to local version of documentation"
-	@echo "  register  update metadata (README.rst) on PyPI"
-	@echo "  sdist     generate a source distribution into dist/"
-	@echo "  upload    upload distribution tarball to PyPI"
+	@echo "  accept       run acceptance tests using behave"
+	@echo "  build        generate both sdist and wheel suitable for upload to PyPI"
+	@echo "  clean        delete intermediate work product and start fresh"
+	@echo "  cleandocs    delete intermediate documentation files"
+	@echo "  coverage     run pytest with coverage"
+	@echo "  docs         generate documentation"
+	@echo "  opendocs     open browser to local version of documentation"
+	@echo "  register     update metadata (README.rst) on PyPI"
+	@echo "  sdist        generate a source distribution into dist/"
+	@echo "  test         run unit tests using pytest"
+	@echo "  test-upload  upload distribution to TestPyPI"
+	@echo "  upload       upload distribution tarball to PyPI"
+	@echo "  wheel        generate a binary distribution into dist/"
 
 accept:
-	$(BEHAVE) --stop
+	uv run $(BEHAVE) --stop
+
+build:
+	uv build
 
 clean:
-	find . -type f -name \*.pyc -exec rm {} \;
+	# find . -type f -name \*.pyc -exec rm {} \;
+	fd -e pyc -I -x rm
 	rm -rf dist *.egg-info .coverage .DS_Store
 
 cleandocs:
 	$(MAKE) -C docs clean
 
 coverage:
-	py.test --cov-report term-missing --cov=docx tests/
+	uv run pytest --cov-report term-missing --cov=docx tests/
 
 docs:
 	$(MAKE) -C docs html
 
+install:
+	pip install -Ue .
+
 opendocs:
 	open docs/.build/html/index.html
 
-register:
-	$(SETUP) register
-
 sdist:
-	$(SETUP) sdist
+	uv build --sdist
+
+test:
+	uv run pytest -x
+
+test-upload: sdist wheel
+	uv run $(TWINE) upload --repository testpypi dist/*
+
+upload: clean sdist wheel
+	uv run $(TWINE) upload dist/*
 
-upload:
-	$(SETUP) sdist upload
+wheel:
+	uv build --wheel

README.md

@@ -0,0 +1,26 @@
+# python-docx
+
+*python-docx* is a Python library for reading, creating, and updating Microsoft Word 2007+ (.docx) files.
+
+## Installation
+
+```
+pip install python-docx
+```
+
+## Example
+
+```python
+>>> from docx import Document
+
+>>> document = Document()
+>>> document.add_paragraph("It was a dark and stormy night.")
+<docx.text.paragraph.Paragraph object at 0x10f19e760>
+>>> document.save("dark-and-stormy.docx")
+
+>>> document = Document("dark-and-stormy.docx")
+>>> document.paragraphs[0].text
+'It was a dark and stormy night.'
+```
+
+More information is available in the [python-docx documentation](https://python-docx.readthedocs.org/en/latest/)

docs/api/comments.rst

@@ -0,0 +1,27 @@
+
+.. _comments_api:
+
+Comment-related objects
+=======================
+
+.. currentmodule:: docx.comments
+
+
+|Comments| objects
+------------------
+
+.. autoclass:: Comments()
+   :members:
+   :inherited-members:
+   :exclude-members:
+       part
+
+
+|Comment| objects
+------------------
+
+.. autoclass:: Comment()
+   :members:
+   :inherited-members:
+   :exclude-members:
+       part

docs/api/document.rst

@@ -50,68 +50,68 @@ if that behavior is desired.
 
    .. attribute:: author
 
-      *string* -- An entity primarily responsible for making the content of the
+      `string` -- An entity primarily responsible for making the content of the
       resource.
 
    .. attribute:: category
 
-      *string* -- A categorization of the content of this package. Example
+      `string` -- A categorization of the content of this package. Example
       values might include: Resume, Letter, Financial Forecast, Proposal,
       or Technical Presentation.
 
    .. attribute:: comments
 
-      *string* -- An account of the content of the resource.
+      `string` -- An account of the content of the resource.
 
    .. attribute:: content_status
 
-      *string* -- completion status of the document, e.g. 'draft'
+      `string` -- completion status of the document, e.g. 'draft'
 
    .. attribute:: created
 
-      *datetime* -- time of intial creation of the document
+      `datetime` -- time of intial creation of the document
 
    .. attribute:: identifier
 
-      *string* -- An unambiguous reference to the resource within a given
+      `string` -- An unambiguous reference to the resource within a given
       context, e.g. ISBN.
 
    .. attribute:: keywords
 
-      *string* -- descriptive words or short phrases likely to be used as
+      `string` -- descriptive words or short phrases likely to be used as
       search terms for this document
 
    .. attribute:: language
 
-      *string* -- language the document is written in
+      `string` -- language the document is written in
 
    .. attribute:: last_modified_by
 
-      *string* -- name or other identifier (such as email address) of person
+      `string` -- name or other identifier (such as email address) of person
       who last modified the document
 
    .. attribute:: last_printed
 
-      *datetime* -- time the document was last printed
+      `datetime` -- time the document was last printed
 
    .. attribute:: modified
 
-      *datetime* -- time the document was last modified
+      `datetime` -- time the document was last modified
 
    .. attribute:: revision
 
-      *int* -- number of this revision, incremented by Word each time the
+      `int` -- number of this revision, incremented by Word each time the
       document is saved. Note however |docx| does not automatically increment
       the revision number when it saves a document.
 
    .. attribute:: subject
 
-      *string* -- The topic of the content of the resource.
+      `string` -- The topic of the content of the resource.
 
    .. attribute:: title
 
-      *string* -- The name given to the resource.
+      `string` -- The name given to the resource.
 
    .. attribute:: version
 
-      *string* -- free-form version string
+      `string` -- free-form version string

docs/api/shared.rst

@@ -52,7 +52,7 @@ allowing values to be expressed in the units most appropriate to the context.
    :members:
    :undoc-members:
 
-   *r*, *g*, and *b* are each an integer in the range 0-255 inclusive. Using
+   `r`, `g`, and `b` are each an integer in the range 0-255 inclusive. Using
    the hexidecimal integer notation, e.g. `0x42` may enhance readability
    where hex RGB values are in use::