python-docx-oss 0.0.3rc0__tar.gz → 0.0.4__tar.gz

python-docx-oss-0.0.4/HISTORY.md

@@ -0,0 +1,33 @@
+Release History
+---------------
+
+**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.0.3rc0 → python-docx-oss-0.0.4}/LICENSE

@@ -1,5 +1,6 @@
 The MIT License (MIT)
 Copyright (c) 2013 Steve Canny, https://github.com/scanny
+Copyright (c) 2022 Ethan St. Lee, https://github.com/lsaint
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{python-docx-oss-0.0.3rc0 → python-docx-oss-0.0.4}/MANIFEST.in

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

{python-docx-oss-0.0.3rc0/python_docx_oss.egg-info → python-docx-oss-0.0.4}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.1
 Name: python-docx-oss
-Version: 0.0.3rc0
+Version: 0.0.4
 Summary: Create and update Microsoft Word .docx files.
 Home-page: https://github.com/lsaint/python-docx-oss
 Author: Ethan St. Lee
 Author-email: ethan@ginolegaltech.cn
 License: The MIT License (MIT)
         Copyright (c) 2013 Steve Canny, https://github.com/scanny
+        Copyright (c) 2022 Ethan St. Lee, https://github.com/lsaint
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
@@ -38,49 +39,64 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Topic :: Office/Business :: Office Suites
 Classifier: Topic :: Software Development :: Libraries
+Description-Content-Type: text/markdown
 License-File: LICENSE
 
-.. image:: https://travis-ci.org/python-openxml/python-docx.svg?branch=master
-   :target: https://travis-ci.org/python-openxml/python-docx
+**_python-docx-oss_** is a Python library for CRUD Microsoft Word (.docx) files.
 
-*python-docx* is a Python library for creating and updating Microsoft Word
-(.docx) files.
 
-More information is available in the `python-docx documentation`_.
+<p>
+    <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 src="https://img.shields.io/pypi/pyversions/python-docx-oss.svg"/></a>
+    <a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></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>
 
-.. _`python-docx documentation`:
-   https://python-docx.readthedocs.org/en/latest/
+---
 
+### FAQ
+
+**Q: What's New?**
+
+**A:** [HISTORY](https://github.com/lsaint/python-docx-oss/blob/master/HISTORY.md)
+
+---
+
+More information is available in the [python-docx documentation](https://python-docx.readthedocs.org/en/latest/)
 
-.. :changelog:
 
 Release History
 ---------------
 
-0.0.2 (2022-06-24)
-+++++++++++++++++++
+**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. PR-14
+- 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)
-+++++++++++++++++++
+**0.0.2 (2022-06-24)**
 
-- Add custom xml support. PR-10
+- Add custom xml support. #10
 - Add Part __eq__.
 - Add Part element setter. 
 - Add Relationships parts_with_reltype.
 
 
-0.0.1 (2022-06-16)
-+++++++++++++++++++
+**0.0.1 (2022-06-16)**
 
 - Only support Python3.8, 3.9 and 3.10.
-- Add custom properties support. PR-2
-- Add drop_rels in Package. PR-5
-- Add drop_rels in Part. PR-5
-- Add default NumberingPart. PR-4
-- Fix Python3.8+ __dict__ TypeError. PR-6
+- 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.0.4/README.md

@@ -0,0 +1,21 @@
+**_python-docx-oss_** is a Python library for CRUD Microsoft Word (.docx) files.
+
+
+<p>
+    <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 src="https://img.shields.io/pypi/pyversions/python-docx-oss.svg"/></a>
+    <a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></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>
+
+---
+
+### FAQ
+
+**Q: What's New?**
+
+**A:** [HISTORY](https://github.com/lsaint/python-docx-oss/blob/master/HISTORY.md)
+
+---
+
+More information is available in the [python-docx documentation](https://python-docx.readthedocs.org/en/latest/)

python-docx-oss-0.0.4/docs/_templates/layout.html

@@ -0,0 +1,8 @@
+{% extends "!layout.html" %}
+  {% block footer %} {{ super() }}
+
+  <style>
+         .wy-nav-content { max-width: none; }
+  </style>
+
+{% endblock %}

python-docx-oss-0.0.4/docs/_templates/sidebarlinks.html

@@ -0,0 +1,6 @@
+<h3>Useful Links</h3>
+<ul>
+  <li><a href="http://github.com/lsaint/python-docx-oss">python-docx-oss @ GitHub</a></li>
+  <li><a href="http://pypi.python.org/pypi/python-docx-oss">python-docx-oss @ PyPI</a></li>
+  <li><a href="https://python-docx.readthedocs.io/en/latest/">python-docx documentation</a></li>
+</ul>

python-docx-oss-0.0.4/docs/conf.py

@@ -0,0 +1,198 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+import os
+import sys
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+sys.path.insert(0, os.path.abspath(".."))
+
+from docx import __version__  # noqa
+
+# -- Project information -----------------------------------------------------
+
+project = "python-docx-oss"
+copyright = "2022, Ethan St. Lee"
+author = "Ethan St. Lee"
+
+# The full version, including alpha/beta/rc tags
+release = __version__
+
+# A string of reStructuredText that will be included at the end of every source
+# file that is read. This is the right place to add substitutions that should
+# be available in every file.
+rst_epilog = """
+.. |api-Document| replace:: :class:`docx.api.Document`
+
+.. |AttributeError| replace:: :exc:`.AttributeError`
+
+.. |BaseStyle| replace:: :class:`.BaseStyle`
+
+.. |BlockItemContainer| replace:: :class:`.BlockItemContainer`
+
+.. |_Body| replace:: :class:`._Body`
+
+.. |_Cell| replace:: :class:`._Cell`
+
+.. |_CharacterStyle| replace:: :class:`._CharacterStyle`
+
+.. |Cm| replace:: :class:`.Cm`
+
+.. |ColorFormat| replace:: :class:`.ColorFormat`
+
+.. |_Column| replace:: :class:`._Column`
+
+.. |_Columns| replace:: :class:`._Columns`
+
+.. |CoreProperties| replace:: :class:`.CoreProperties`
+
+.. |CustomProperties| replace:: :class:`.CustomProperties`
+
+.. |datetime| replace:: :class:`.datetime.datetime`
+
+.. |Document| replace:: :class:`.Document`
+
+.. |DocumentPart| replace:: :class:`.DocumentPart`
+
+.. |docx| replace:: ``python-docx-oss``
+
+.. |Emu| replace:: :class:`.Emu`
+
+.. |False| replace:: :class:`False`
+
+.. |float| replace:: :class:`.float`
+
+.. |Font| replace:: :class:`.Font`
+
+.. |_Footer| replace:: :class:`._Footer`
+
+.. |FooterPart| replace:: :class:`.FooterPart`
+
+.. |_Header| replace:: :class:`._Header`
+
+.. |HeaderPart| replace:: :class:`.HeaderPart`
+
+.. |ImageParts| replace:: :class:`.ImageParts`
+
+.. |Inches| replace:: :class:`.Inches`
+
+.. |InlineShape| replace:: :class:`.InlineShape`
+
+.. |InlineShapes| replace:: :class:`.InlineShapes`
+
+.. |InvalidSpanError| replace:: :class:`.InvalidSpanError`
+
+.. |int| replace:: :class:`.int`
+
+.. |_LatentStyle| replace:: :class:`._LatentStyle`
+
+.. |LatentStyles| replace:: :class:`.LatentStyles`
+
+.. |Length| replace:: :class:`.Length`
+
+.. |None| replace:: :class:`.None`
+
+.. |NumberingPart| replace:: :class:`.NumberingPart`
+
+.. |_NumberingStyle| replace:: :class:`._NumberingStyle`
+
+.. |OpcPackage| replace:: :class:`.OpcPackage`
+
+.. |Paragraph| replace:: :class:`.Paragraph`
+
+.. |ParagraphFormat| replace:: :class:`.ParagraphFormat`
+
+.. |_ParagraphStyle| replace:: :class:`._ParagraphStyle`
+
+.. |Part| replace:: :class:`.Part`
+
+.. |Pt| replace:: :class:`.Pt`
+
+.. |_Relationship| replace:: :class:`._Relationship`
+
+.. |Relationships| replace:: :class:`._Relationships`
+
+.. |RGBColor| replace:: :class:`.RGBColor`
+
+.. |_Row| replace:: :class:`._Row`
+
+.. |_Rows| replace:: :class:`._Rows`
+
+.. |Run| replace:: :class:`.Run`
+
+.. |Section| replace:: :class:`.Section`
+
+.. |Sections| replace:: :class:`.Sections`
+
+.. |Settings| replace:: :class:`.Settings`
+
+.. |str| replace:: :class:`.str`
+
+.. |Styles| replace:: :class:`.Styles`
+
+.. |StylesPart| replace:: :class:`.StylesPart`
+
+.. |Table| replace:: :class:`.Table`
+
+.. |_TableStyle| replace:: :class:`._TableStyle`
+
+.. |TabStop| replace:: :class:`.TabStop`
+
+.. |TabStops| replace:: :class:`.TabStops`
+
+.. |_Text| replace:: :class:`._Text`
+
+.. |True| replace:: :class:`True`
+
+.. |ValueError| replace:: :class:`ValueError`
+"""
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.viewcode",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The root document.
+root_doc = "index"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".build"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_book_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# Custom sidebar templates, maps document names to template names.
+html_sidebars = {
+    "**": ["searchbox.html", "globaltoc.html", "sidebarlinks.html"],
+}

python-docx-oss-0.0.3rc0/docs/conf.py → python-docx-oss-0.0.4/docs/conf.py.bak

@@ -20,9 +20,9 @@ import sys
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath(".."))
 
+import sphinx_rtd_theme
 from docx import __version__  # noqa
 
-
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -51,8 +51,8 @@ source_suffix = ".rst"
 master_doc = "index"
 
 # General information about the project.
-project = "python-docx"
-copyright = "2013, Steve Canny"
+project = "python-docx-docx"
+copyright = "2013, Steve Canny, 2022, Ethan St.Lee"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -91,6 +91,8 @@ rst_epilog = """
 
 .. |CoreProperties| replace:: :class:`.CoreProperties`
 
+.. |CustomProperties| replace:: :class:`.CustomProperties`
+
 .. |datetime| replace:: :class:`.datetime.datetime`
 
 .. |Document| replace:: :class:`.Document`
@@ -221,7 +223,7 @@ pygments_style = "sphinx"
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "armstrong"
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -229,7 +231,7 @@ html_theme = "armstrong"
 # html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ["_themes"]
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -262,9 +264,7 @@ html_static_path = ["_static"]
 
 # Custom sidebar templates, maps document names to template names.
 # html_sidebars = {}
-html_sidebars = {
-    "**": ["localtoc.html", "relations.html", "sidebarlinks.html", "searchbox.html"]
-}
+html_sidebars = {"**": ["localtoc.html", "relations.html", "sidebarlinks.html", "searchbox.html"]}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -297,7 +297,7 @@ html_sidebars = {
 # html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "python-docxdoc"
+htmlhelp_basename = "python-docx-oss_doc"
 
 
 # -- Options for LaTeX output -----------------------------------------------

{python-docx-oss-0.0.3rc0 → python-docx-oss-0.0.4}/docs/dev/analysis/features/coreprops.rst

@@ -25,10 +25,10 @@ Candidate Protocol
     >>> document = Document()
     >>> core_properties = document.core_properties
     >>> core_properties.author
-    'python-docx'
-    >>> core_properties.author = 'Brian'
+    'python-docx-oss'
+    >>> core_properties.author = 'lsaint'
     >>> core_properties.author
-    'Brian'
+    'lsaint'
 
 
 Properties

{python-docx-oss-0.0.3rc0 → python-docx-oss-0.0.4}/docs/index.rst

@@ -1,11 +1,14 @@
+.. 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.
 
-python-docx
-===========
+Welcome to python-docx-oss's documentation!
+===========================================
 
-Release v\ |version| (:ref:`Installation <install>`)
+Release v\ |release| (:ref:`Installation <install>`)
 
-*python-docx* is a Python library for creating and updating Microsoft Word
-(.docx) files.
+*python-docx-oss* is a Python library for CRUD Microsoft Word (.docx) files.
 
 
 What it can do
@@ -81,6 +84,7 @@ User Guide
    user/styles-understanding
    user/styles-using
    user/shapes
+   user/custom-xml
 
 
 API Documentation

python-docx-oss-0.0.4/docs/requirements.txt

@@ -0,0 +1,2 @@
+lxml>=4.6.5
+sphinx-book-theme

python-docx-oss-0.0.4/docs/user/custom-xml.rst

@@ -0,0 +1,60 @@
+.. _custom-xml:
+
+Working with customXml
+=======================
+
+As we know, Word documents are .zip files under the hook. 
+Can we add any file in a docx file? Literally yes. 
+After we unzip a docx file, We can add a ``customXml`` folder at the root of it, 
+which contains any XML files. Files in other formats and paths are invalid. 
+But it's enough for us to store custom data. 
+It can not be seen or modified in Word like ``CustomProperties``. 
+
+python-docx-oss will create a default XML file in the folder if there are not.
+Then developer can add/delete/modify items in it.
+
+eg::
+
+    from docx import Document
+
+    document = Document()
+    cx = document.part.custom_xml_parts[0]
+
+    cx.add_item("my_tag", "some_texts", foo="foo_attrib_value")
+    cx.add_item("your_tag", "a_word", bar="bar_attrib_value")
+
+2 new xml elements::
+
+    <my_tag foo="foo_attrib_value">some_texts</my_tag>
+    <your_tag bar1="value1" bar2="value2">a_word</your_tag>
+
+will be add to ``customXml/item1.xml``
+
+you can retrieve it::
+
+    >>> cx.items[0].tag
+    my_tag
+
+    >>> cx.items[0].text)
+    some_texts
+
+    >>> cx.items[0].attrib["foo"]
+    foo_attrib_value
+
+    >>> cx.items[1].tag
+    your_tag
+
+    >>> cx.items[1].text)
+    a_word
+
+    >>> cx.items[1].attrib["bar2"]
+    value2
+
+or delete it::
+
+    >>> cx.delete_item(cx.items[0])
+
+Be careful. Items are stored as a list, the index may change after deletion::
+
+    >>> cx.items[0].tag
+    your_tag

{python-docx-oss-0.0.3rc0 → python-docx-oss-0.0.4}/docs/user/hdrftr.rst

@@ -80,7 +80,7 @@ A header with multiple "zones" is often accomplished using carefully placed tab
 
 The required tab-stops for a center and right-aligned "zone" are part of the ``Header``
 and ``Footer`` styles in Word. If you're using a custom template rather than the
-`python-docx` default, it probably makes sense to define that style in your template.
+`python-docx-oss` default, it probably makes sense to define that style in your template.
 
 Inserted tab characters (``"\t"``) are used to separate left, center, and right-aligned
 header content::

python-docx-oss-0.0.4/docs/user/install.rst

@@ -0,0 +1,30 @@
+.. _install:
+
+Installing
+==========
+
+|docx| is hosted on `PyPI <https://pypi.org/project/python-docx-oss/>`_,
+so installation is relatively simple, and just
+depends on what installation utilities you have installed.
+
+|docx| may be installed with ``pip`` if you have it available::
+
+    pip install python-docx-oss
+
+It can be installed manually by downloading the distribution from PyPI, unpacking the tarball,
+and running ``setup.py``::
+
+    tar xvzf python-docx-{version}.tar.gz
+    cd python-docx-oss-{version}
+    python setup.py install
+
+|docx| depends on the ``lxml`` package. 
+``pip`` will take care of satisfying those dependencies for you, 
+but if you use this last method you will need to install those yourself.
+
+
+Dependencies
+------------
+
+* Python 3.8, 3.9 or 3.10
+* lxml >= 4.6.5

{python-docx-oss-0.0.3rc0 → python-docx-oss-0.0.4}/docx/__init__.py

@@ -1,6 +1,6 @@
 from docx.api import Document  # noqa
 
-__version__ = "0.0.3rc0"
+__version__ = "0.0.4"
 
 
 # register custom Part classes with opc package reader

{python-docx-oss-0.0.3rc0 → python-docx-oss-0.0.4}/docx/opc/rel.py

@@ -173,3 +173,9 @@ class _Relationship(object):
             return self._target
         else:
             return self._target.partname.relative_ref(self._baseURI)
+
+    @target_ref.setter
+    def target_ref(self, ref: str):
+        if not self._is_external:
+            raise ValueError("can not set internal target_ref")
+        self._target = ref

{python-docx-oss-0.0.3rc0 → python-docx-oss-0.0.4}/docx/parts/customxml.py

@@ -59,3 +59,9 @@ class CustomXmlPart(XmlPart):
         Add a child element to root.
         """
         etree.SubElement(self.element, tag, **attrib).text = text
+
+    def delete_item(self, item_element: etree._Element):
+        """
+        Delete a item element. other nodes index may change after deletion.
+        """
+        self.element.remove(item_element)