.. image:: https://img.shields.io/pypi/v/paradocx.svg
:target: https://pypi.org/project/paradocx
.. image:: https://img.shields.io/pypi/pyversions/paradocx.svg
.. image:: https://github.com/jaraco/paradocx/workflows/tests/badge.svg
:target: https://github.com/jaraco/paradocx/actions?query=workflow%3A%22tests%22
:alt: tests
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json
:target: https://github.com/astral-sh/ruff
:alt: Ruff
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Code style: Black
.. .. image:: https://readthedocs.org/projects/PROJECT_RTD/badge/?version=latest
.. :target: https://PROJECT_RTD.readthedocs.io/en/latest/?badge=latest
.. image:: https://img.shields.io/badge/skeleton-2023-informational
:target: https://blog.jaraco.com/skeleton
``paradocx`` builds on the Open Office XML Spec provided by openpack to
provide interfaces for working with Microsoft Word documents in the
Office 2007 'docx' format.
Introduction
============
Constructing simple documents using Paradocx is fairly straightforward::
>>> import paradocx
>>> doc = paradocx.Document()
>>> doc.paragraph('Things to do', style='Heading 1')
<Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p at 0x22a1240>
>>> doc.paragraph('First, spend some time learning paradocx usage.')
<Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p at 0x22a12d0>
>>> doc.paragraph('Then, put together some examples')
<Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p at 0x22a1240>
>>> doc.paragraph('Finally, put those examples in the paradocx documentation')
<Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p at 0x22a12d0>
>>> doc.save('mydoc.docx')
Using `part-edit` from `Openpack <https://pypi.org/project/openpack>`_,
one can see the document that was constructed::
> EDITOR=cat part-edit mydoc.docx/word/document.xml
<w:document xmlns:dcterms="http://purl.org/dc/terms/" xmlns:ve="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<w:body>
<w:p>
<w:pPr>
<w:pStyle w:val="Heading 1"/>
</w:pPr>
<w:r>
<w:t>Things to do</w:t>
</w:r>
</w:p>
<w:p>
<w:r>
<w:t>First, spend some time learning paradocx usage.</w:t>
</w:r>
</w:p>
<w:p>
<w:r>
<w:t>Then, put together some examples</w:t>
</w:r>
</w:p>
<w:p>
<w:r>
<w:t>Finally, put those examples in the paradocx documentation</w:t>
</w:r>
</w:p>
</w:body>
</w:document>
One may also append tables to a document::
>>> import paradocx
>>> doc = paradocx.Document()
>>> doc.table([['a', 'b', 'c'], ['1', '2', '3']])
<Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}tbl at 0x2231240>
>>> doc.save('data.docx')
Object Model and Advanced Usage
===============================
The core object for a Word document is the `paradocx.package.WordPackage`. All
operations involving constructing a Word document use some form of this class
(the `paradocx.Document` subclasses `WordPackage`).
See `the source
<https://github.com/jaraco/paradocx/blob/master/paradocx/package.py>`_
for a trivial example of usage.
Each `WordPackage` is a container of a number of related parts. The parts
represent the various aspects of a document. The following example, adapted
from real-world usage, shows how
one might construct a more complex structure from a series of XML templates
on the file system::
import string
def load_template(name, **params):
with open(name) as f:
template = string.Template(f.read())
return template.substitute(params)
doc = WordPackage()
doc.start_part.data = load_template('document.xml', text="Hello world")
# styles
styles = StylesPart(doc)
doc.add(styles)
styles.data = load_template('styles.xml')
doc.start_part.relate(styles)
title = "My initial document"
# Header for cover page
cover_header = HeaderPart(doc, '/word/cover-header.xml')
doc.add(cover_header)
cover_header.data = load_template('cover-header.xml', title=title)
doc.start_part.relate(cover_header, 'PmxHdr0')
# body header
header = HeaderPart(doc)
doc.add(header)
header.data = load_template('header.xml', title=title)
doc.start_part.relate(header, 'PmxHdr1')
# body footer
footer = FooterPart(doc)
doc.add(footer)
footer.data = load_template('footer.xml',
date=unicode(datetime.datetime.now()))
doc.start_part.relate(footer, 'PmxFtr1')
# image1
image1 = ImagePart(doc, '/word/media/logo.png')
doc.add(image1, override=False)
with open('my_logo.png', 'rb') as logo_data:
image1.data = logo_data.read()
doc.start_part.relate(image1, 'Logo1')
header.relate(image1, 'Logo1')
# cover page uses the logo, so relate it
cover_header.relate(image1, 'Logo1')
# settings
settings = SettingsPart(doc)
doc.add(settings)
settings.data = load_template('settings.xml')
doc.start_part.relate(settings)
doc.save(...)
For more details on constructing the XML data for the underlying parts,
consider using a reference document and the OpenPack tools for inspecting
the document for the necessary elements, or consider reading some of the
resources at the `Microsoft Dev Center
<http://msdn.microsoft.com/en-us/library/office/aa338205%28v=office.12%29.aspx>`_
or read up on the `standards developed around Office Open XML
<http://en.wikipedia.org/wiki/Office_Open_XML>`_.
Testing
=======
Paradocx uses `tox <https://pypi.org/project/tox>`_ for
running the tests. To test, simply invoke ``tox`` on the repo.
Raw data
{
"_id": null,
"home_page": "https://github.com/jaraco/paradocx",
"name": "paradocx",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Jason R. Coombs",
"author_email": "jaraco@jaraco.com",
"download_url": "https://files.pythonhosted.org/packages/23/27/3adc47260bb531c7204ecf8d2db283c75af3bff1d25c2bb17fa86bd241d4/paradocx-1.5.0.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/pypi/v/paradocx.svg\n :target: https://pypi.org/project/paradocx\n\n.. image:: https://img.shields.io/pypi/pyversions/paradocx.svg\n\n.. image:: https://github.com/jaraco/paradocx/workflows/tests/badge.svg\n :target: https://github.com/jaraco/paradocx/actions?query=workflow%3A%22tests%22\n :alt: tests\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\n :target: https://github.com/astral-sh/ruff\n :alt: Ruff\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Code style: Black\n\n.. .. image:: https://readthedocs.org/projects/PROJECT_RTD/badge/?version=latest\n.. :target: https://PROJECT_RTD.readthedocs.io/en/latest/?badge=latest\n\n.. image:: https://img.shields.io/badge/skeleton-2023-informational\n :target: https://blog.jaraco.com/skeleton\n\n``paradocx`` builds on the Open Office XML Spec provided by openpack to\nprovide interfaces for working with Microsoft Word documents in the\nOffice 2007 'docx' format.\n\nIntroduction\n============\n\nConstructing simple documents using Paradocx is fairly straightforward::\n\n >>> import paradocx\n >>> doc = paradocx.Document()\n >>> doc.paragraph('Things to do', style='Heading 1')\n <Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p at 0x22a1240>\n >>> doc.paragraph('First, spend some time learning paradocx usage.')\n <Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p at 0x22a12d0>\n >>> doc.paragraph('Then, put together some examples')\n <Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p at 0x22a1240>\n >>> doc.paragraph('Finally, put those examples in the paradocx documentation')\n <Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p at 0x22a12d0>\n >>> doc.save('mydoc.docx')\n\nUsing `part-edit` from `Openpack <https://pypi.org/project/openpack>`_,\none can see the document that was constructed::\n\n > EDITOR=cat part-edit mydoc.docx/word/document.xml\n <w:document xmlns:dcterms=\"http://purl.org/dc/terms/\" xmlns:ve=\"http://schemas.openxmlformats.org/markup-compatibility/2006\" xmlns:dcmitype=\"http://purl.org/dc/dcmitype/\" xmlns:v=\"urn:schemas-microsoft-com:vml\" xmlns:dc=\"http://purl.org/dc/elements/1.1/\" xmlns:r=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships\" xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\" xmlns:wp=\"http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing\" xmlns:cp=\"http://schemas.openxmlformats.org/package/2006/metadata/core-properties\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">\n <w:body>\n <w:p>\n <w:pPr>\n <w:pStyle w:val=\"Heading 1\"/>\n </w:pPr>\n <w:r>\n <w:t>Things to do</w:t>\n </w:r>\n </w:p>\n <w:p>\n <w:r>\n <w:t>First, spend some time learning paradocx usage.</w:t>\n </w:r>\n </w:p>\n <w:p>\n <w:r>\n <w:t>Then, put together some examples</w:t>\n </w:r>\n </w:p>\n <w:p>\n <w:r>\n <w:t>Finally, put those examples in the paradocx documentation</w:t>\n </w:r>\n </w:p>\n </w:body>\n </w:document>\n\n\nOne may also append tables to a document::\n\n >>> import paradocx\n >>> doc = paradocx.Document()\n >>> doc.table([['a', 'b', 'c'], ['1', '2', '3']])\n <Element {http://schemas.openxmlformats.org/wordprocessingml/2006/main}tbl at 0x2231240>\n >>> doc.save('data.docx')\n\n\nObject Model and Advanced Usage\n===============================\n\nThe core object for a Word document is the `paradocx.package.WordPackage`. All\noperations involving constructing a Word document use some form of this class\n(the `paradocx.Document` subclasses `WordPackage`).\n\nSee `the source\n<https://github.com/jaraco/paradocx/blob/master/paradocx/package.py>`_\nfor a trivial example of usage.\n\nEach `WordPackage` is a container of a number of related parts. The parts\nrepresent the various aspects of a document. The following example, adapted\nfrom real-world usage, shows how\none might construct a more complex structure from a series of XML templates\non the file system::\n\n import string\n\n def load_template(name, **params):\n with open(name) as f:\n template = string.Template(f.read())\n return template.substitute(params)\n\n doc = WordPackage()\n doc.start_part.data = load_template('document.xml', text=\"Hello world\")\n\n # styles\n styles = StylesPart(doc)\n doc.add(styles)\n styles.data = load_template('styles.xml')\n doc.start_part.relate(styles)\n\n title = \"My initial document\"\n\n # Header for cover page\n cover_header = HeaderPart(doc, '/word/cover-header.xml')\n doc.add(cover_header)\n cover_header.data = load_template('cover-header.xml', title=title)\n doc.start_part.relate(cover_header, 'PmxHdr0')\n\n # body header\n header = HeaderPart(doc)\n doc.add(header)\n header.data = load_template('header.xml', title=title)\n doc.start_part.relate(header, 'PmxHdr1')\n\n # body footer\n footer = FooterPart(doc)\n doc.add(footer)\n footer.data = load_template('footer.xml',\n date=unicode(datetime.datetime.now()))\n doc.start_part.relate(footer, 'PmxFtr1')\n\n # image1\n image1 = ImagePart(doc, '/word/media/logo.png')\n doc.add(image1, override=False)\n with open('my_logo.png', 'rb') as logo_data:\n image1.data = logo_data.read()\n doc.start_part.relate(image1, 'Logo1')\n header.relate(image1, 'Logo1')\n # cover page uses the logo, so relate it\n cover_header.relate(image1, 'Logo1')\n\n # settings\n settings = SettingsPart(doc)\n doc.add(settings)\n settings.data = load_template('settings.xml')\n doc.start_part.relate(settings)\n\n doc.save(...)\n\nFor more details on constructing the XML data for the underlying parts,\nconsider using a reference document and the OpenPack tools for inspecting\nthe document for the necessary elements, or consider reading some of the\nresources at the `Microsoft Dev Center\n<http://msdn.microsoft.com/en-us/library/office/aa338205%28v=office.12%29.aspx>`_\nor read up on the `standards developed around Office Open XML\n<http://en.wikipedia.org/wiki/Office_Open_XML>`_.\n\nTesting\n=======\n\nParadocx uses `tox <https://pypi.org/project/tox>`_ for\nrunning the tests. To test, simply invoke ``tox`` on the repo.\n",
"bugtrack_url": null,
"license": "",
"summary": "paradocx",
"version": "1.5.0",
"project_urls": {
"Homepage": "https://github.com/jaraco/paradocx"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7bfbf4728212a3a4da0f363ef3e1a1dbc3303b190975730df289c2968160180f",
"md5": "31f4b8bf4647d9368a7373c6119f3bca",
"sha256": "25f151b4a8c41f62ba6fcd0eda6ad2e7b75dad0d11132b8e3fe5f5a4af9e5153"
},
"downloads": -1,
"filename": "paradocx-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "31f4b8bf4647d9368a7373c6119f3bca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10600,
"upload_time": "2023-11-07T14:34:10",
"upload_time_iso_8601": "2023-11-07T14:34:10.087773Z",
"url": "https://files.pythonhosted.org/packages/7b/fb/f4728212a3a4da0f363ef3e1a1dbc3303b190975730df289c2968160180f/paradocx-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "23273adc47260bb531c7204ecf8d2db283c75af3bff1d25c2bb17fa86bd241d4",
"md5": "da6e9feb9f78d6d7bfb9b5251f5db96b",
"sha256": "6dcce8867fdc088fe6d05592fe1e9ee2fe0131822bda000460449ccf593a084e"
},
"downloads": -1,
"filename": "paradocx-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "da6e9feb9f78d6d7bfb9b5251f5db96b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 28911,
"upload_time": "2023-11-07T14:34:11",
"upload_time_iso_8601": "2023-11-07T14:34:11.197762Z",
"url": "https://files.pythonhosted.org/packages/23/27/3adc47260bb531c7204ecf8d2db283c75af3bff1d25c2bb17fa86bd241d4/paradocx-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-07 14:34:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jaraco",
"github_project": "paradocx",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "paradocx"
}
JSON
