paradocx


Nameparadocx JSON
Version 1.5.0 PyPI version JSON
download
home_pagehttps://github.com/jaraco/paradocx
Summaryparadocx
upload_time2023-11-07 14:34:11
maintainer
docs_urlNone
authorJason R. Coombs
requires_python>=3.8
license
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            .. 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"
}
        
Elapsed time: 0.14701s