update doc

jdum · Dec 17, 2023 · be974dd · be974dd
1 parent cd991d2
commit be974dd
Show file tree

Hide file tree

Showing 12 changed files with 365 additions and 178 deletions.
diff --git a/doc/container.html b/doc/container.html
@@ -92,6 +92,9 @@ <h1 class="title">Module <code>odfdo.container</code></h1>
         if path:
             self.open(path)
 
+    def __repr__(self) -&gt; str:
+        return f&#34;&lt;{self.__class__.__name__} type={self.mimetype} path={self.path}&gt;&#34;
+
     def open(self, path_or_file):
         &#34;&#34;&#34;Load the content of an ODF file.&#34;&#34;&#34;
         self.__path_like = path_or_file
@@ -331,7 +334,10 @@ <h1 class="title">Module <code>odfdo.container</code></h1>
     @property
     def mimetype(self):
         &#34;&#34;&#34;Return unicode value of mimetype of the document.&#34;&#34;&#34;
-        return self.get_part(&#34;mimetype&#34;).decode(&#34;utf8&#34;, &#34;ignore&#34;)
+        try:
+            return self.get_part(&#34;mimetype&#34;).decode(&#34;utf8&#34;, &#34;ignore&#34;)
+        except Exception:
+            return &#34;&#34;
 
     @mimetype.setter
     def mimetype(self, m):
@@ -493,6 +499,9 @@ <h2 class="section-title" id="header-classes">Classes</h2>
         if path:
             self.open(path)
 
+    def __repr__(self) -&gt; str:
+        return f&#34;&lt;{self.__class__.__name__} type={self.mimetype} path={self.path}&gt;&#34;
+
     def open(self, path_or_file):
         &#34;&#34;&#34;Load the content of an ODF file.&#34;&#34;&#34;
         self.__path_like = path_or_file
@@ -732,7 +741,10 @@ <h2 class="section-title" id="header-classes">Classes</h2>
     @property
     def mimetype(self):
         &#34;&#34;&#34;Return unicode value of mimetype of the document.&#34;&#34;&#34;
-        return self.get_part(&#34;mimetype&#34;).decode(&#34;utf8&#34;, &#34;ignore&#34;)
+        try:
+            return self.get_part(&#34;mimetype&#34;).decode(&#34;utf8&#34;, &#34;ignore&#34;)
+        except Exception:
+            return &#34;&#34;
 
     @mimetype.setter
     def mimetype(self, m):
@@ -905,7 +917,10 @@ <h3>Instance variables</h3>
 <pre><code class="python">@property
 def mimetype(self):
     &#34;&#34;&#34;Return unicode value of mimetype of the document.&#34;&#34;&#34;
-    return self.get_part(&#34;mimetype&#34;).decode(&#34;utf8&#34;, &#34;ignore&#34;)</code></pre>
+    try:
+        return self.get_part(&#34;mimetype&#34;).decode(&#34;utf8&#34;, &#34;ignore&#34;)
+    except Exception:
+        return &#34;&#34;</code></pre>
 </details>
 </dd>
 </dl>

diff --git a/doc/content.html b/doc/content.html
@@ -69,6 +69,9 @@ <h1 class="title">Module <code>odfdo.content</code></h1>
             self.get_element(&#34;//office:automatic-styles&#34;),
         )
 
+    def __str__(self) -&gt; str:
+        return str(self.body)
+
     # Public API
 
     def get_styles(self, family=None):
@@ -133,8 +136,8 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <span>(</span><span>part_name, container)</span>
 </code></dt>
 <dd>
-<div class="desc"><p>Representation of an XML part.
-Abstraction of the XML library behind.</p></div>
+<div class="desc"><p>Representation of an XML part.</p>
+<p>Abstraction of the XML library behind.</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
@@ -154,6 +157,9 @@ <h2 class="section-title" id="header-classes">Classes</h2>
             self.get_element(&#34;//office:automatic-styles&#34;),
         )
 
+    def __str__(self) -&gt; str:
+        return str(self.body)
+
     # Public API
 
     def get_styles(self, family=None):

diff --git a/doc/document.html b/doc/document.html
@@ -90,7 +90,7 @@ <h1 class="title">Module <code>odfdo.document</code></h1>
     &#34;&#34;&#34;Underline string of the name.&#34;&#34;&#34;
     if level &gt;= len(UNDERLINE_LVL):
         return &#34;\n&#34;
-    return underline_lvl[level] * len(name)
+    return UNDERLINE_LVL[level] * len(name)
 
 
 def _show_styles(element, level=0):
@@ -149,7 +149,18 @@ <h1 class="title">Module <code>odfdo.document</code></h1>
 
 
 class Document:
-    &#34;&#34;&#34;Abstraction of the ODF document.&#34;&#34;&#34;
+    &#34;&#34;&#34;Abstraction of the ODF document.
+
+    To create a new Document, several possibilities:
+
+        - Document() or Document(&#34;text&#34;) -&gt; an empty document of type text
+        - Document(&#34;spreadsheet&#34;) -&gt; an empty document of type spreadsheet
+        - Document(&#34;presentation&#34;) -&gt; an empty document of type presentation
+        - Document(&#34;drawing&#34;) -&gt; an empty document of type drawing
+
+    If the argument is not a known type, or is a Path, Document will load
+    the content of the file.
+    &#34;&#34;&#34;
 
     def __init__(self, target: Union[str, bytes, Path, Container, None] = &#34;text&#34;):
         # Cache of XML parts
@@ -175,6 +186,15 @@ <h1 class="title">Module <code>odfdo.document</code></h1>
         # let&#39;s assume we open a container on existing file
         self.container = Container(target)
 
+    def __repr__(self) -&gt; str:
+        return f&#34;&lt;{self.__class__.__name__} type={self.get_type()} path={self.path}&gt;&#34;
+
+    def __str__(self) -&gt; str:
+        try:
+            return self.get_formatted_text()
+        except NotImplementedError:
+            return self.body.text_recursive
+
     @classmethod
     def new(cls, target=&#34;text&#34;):
         doc = Document()
@@ -264,8 +284,7 @@ <h1 class="title">Module <code>odfdo.document</code></h1>
         self.container.mimetype = m
 
     def get_type(self):
-        &#34;&#34;&#34;
-        Get the ODF type (also called class) of this document.
+        &#34;&#34;&#34;Get the ODF type (also called class) of this document.
 
         Return: &#39;chart&#39;, &#39;database&#39;, &#39;formula&#39;, &#39;graphics&#39;,
             &#39;graphics-template&#39;, &#39;image&#39;, &#39;presentation&#39;,
@@ -345,15 +364,21 @@ <h1 class="title">Module <code>odfdo.document</code></h1>
         &#34;&#34;&#34;Return content as text, with some formatting.&#34;&#34;&#34;
         # For the moment, only &#34;type=&#39;text&#39;&#34;
         doc_type = self.get_type()
-        if doc_type not in {
+        if doc_type == &#34;spreadsheet&#34;:
+            return self._tables_csv()
+        if doc_type in {
             &#34;text&#34;,
             &#34;text-template&#34;,
             &#34;presentation&#34;,
             &#34;presentation-template&#34;,
         }:
-            raise NotImplementedError(
-                &#39;Type of document &#34;%s&#34; not &#39; &#34;supported yet&#34; % doc_type
-            )
+            return self._formatted_text(rst_mode)
+        raise NotImplementedError(f&#39;Type of document &#34;{doc_type}&#34; not &#39; &#34;supported yet&#34;)
+
+    def _tables_csv(self):
+        return &#34;\n\n&#34;.join(str(table) for table in self.body.get_tables())
+
+    def _formatted_text(self, rst_mode):
         # Initialize an empty context
         context = {
             &#34;document&#34;: self,
@@ -875,13 +900,32 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <span>(</span><span>target: Union[str, bytes, pathlib.Path, <a title="odfdo.container.Container" href="container.html#odfdo.container.Container">Container</a>, ForwardRef(None)] = 'text')</span>
 </code></dt>
 <dd>
-<div class="desc"><p>Abstraction of the ODF document.</p></div>
+<div class="desc"><p>Abstraction of the ODF document.</p>
+<p>To create a new Document, several possibilities:</p>
+<pre><code>- Document() or Document("text") -&gt; an empty document of type text
+- Document("spreadsheet") -&gt; an empty document of type spreadsheet
+- Document("presentation") -&gt; an empty document of type presentation
+- Document("drawing") -&gt; an empty document of type drawing
+</code></pre>
+<p>If the argument is not a known type, or is a Path, Document will load
+the content of the file.</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class Document:
-    &#34;&#34;&#34;Abstraction of the ODF document.&#34;&#34;&#34;
+    &#34;&#34;&#34;Abstraction of the ODF document.
+
+    To create a new Document, several possibilities:
+
+        - Document() or Document(&#34;text&#34;) -&gt; an empty document of type text
+        - Document(&#34;spreadsheet&#34;) -&gt; an empty document of type spreadsheet
+        - Document(&#34;presentation&#34;) -&gt; an empty document of type presentation
+        - Document(&#34;drawing&#34;) -&gt; an empty document of type drawing
+
+    If the argument is not a known type, or is a Path, Document will load
+    the content of the file.
+    &#34;&#34;&#34;
 
     def __init__(self, target: Union[str, bytes, Path, Container, None] = &#34;text&#34;):
         # Cache of XML parts
@@ -907,6 +951,15 @@ <h2 class="section-title" id="header-classes">Classes</h2>
         # let&#39;s assume we open a container on existing file
         self.container = Container(target)
 
+    def __repr__(self) -&gt; str:
+        return f&#34;&lt;{self.__class__.__name__} type={self.get_type()} path={self.path}&gt;&#34;
+
+    def __str__(self) -&gt; str:
+        try:
+            return self.get_formatted_text()
+        except NotImplementedError:
+            return self.body.text_recursive
+
     @classmethod
     def new(cls, target=&#34;text&#34;):
         doc = Document()
@@ -996,8 +1049,7 @@ <h2 class="section-title" id="header-classes">Classes</h2>
         self.container.mimetype = m
 
     def get_type(self):
-        &#34;&#34;&#34;
-        Get the ODF type (also called class) of this document.
+        &#34;&#34;&#34;Get the ODF type (also called class) of this document.
 
         Return: &#39;chart&#39;, &#39;database&#39;, &#39;formula&#39;, &#39;graphics&#39;,
             &#39;graphics-template&#39;, &#39;image&#39;, &#39;presentation&#39;,
@@ -1077,15 +1129,21 @@ <h2 class="section-title" id="header-classes">Classes</h2>
         &#34;&#34;&#34;Return content as text, with some formatting.&#34;&#34;&#34;
         # For the moment, only &#34;type=&#39;text&#39;&#34;
         doc_type = self.get_type()
-        if doc_type not in {
+        if doc_type == &#34;spreadsheet&#34;:
+            return self._tables_csv()
+        if doc_type in {
             &#34;text&#34;,
             &#34;text-template&#34;,
             &#34;presentation&#34;,
             &#34;presentation-template&#34;,
         }:
-            raise NotImplementedError(
-                &#39;Type of document &#34;%s&#34; not &#39; &#34;supported yet&#34; % doc_type
-            )
+            return self._formatted_text(rst_mode)
+        raise NotImplementedError(f&#39;Type of document &#34;{doc_type}&#34; not &#39; &#34;supported yet&#34;)
+
+    def _tables_csv(self):
+        return &#34;\n\n&#34;.join(str(table) for table in self.body.get_tables())
+
+    def _formatted_text(self, rst_mode):
         # Initialize an empty context
         context = {
             &#34;document&#34;: self,
@@ -1870,45 +1928,16 @@ <h2 id="arguments">Arguments</h2>
     &#34;&#34;&#34;Return content as text, with some formatting.&#34;&#34;&#34;
     # For the moment, only &#34;type=&#39;text&#39;&#34;
     doc_type = self.get_type()
-    if doc_type not in {
+    if doc_type == &#34;spreadsheet&#34;:
+        return self._tables_csv()
+    if doc_type in {
         &#34;text&#34;,
         &#34;text-template&#34;,
         &#34;presentation&#34;,
         &#34;presentation-template&#34;,
     }:
-        raise NotImplementedError(
-            &#39;Type of document &#34;%s&#34; not &#39; &#34;supported yet&#34; % doc_type
-        )
-    # Initialize an empty context
-    context = {
-        &#34;document&#34;: self,
-        &#34;footnotes&#34;: [],
-        &#34;endnotes&#34;: [],
-        &#34;annotations&#34;: [],
-        &#34;rst_mode&#34;: rst_mode,
-        &#34;img_counter&#34;: 0,
-        &#34;images&#34;: [],
-        &#34;no_img_level&#34;: 0,
-    }
-    body = self.body
-    # Get the text
-    result = []
-    for element in body.children:
-        # self._get_formatted_text_child(result, element, context, rst_mode)
-        if element.tag == &#34;table:table&#34;:
-            result.append(element.get_formatted_text(context))
-            return
-        result.append(element.get_formatted_text(context))
-        if context[&#34;footnotes&#34;]:
-            self._get_formatted_text_footnotes(result, context, rst_mode)
-        if context[&#34;annotations&#34;]:
-            self._get_formatted_text_annotations(result, context, rst_mode)
-        # Insert the images ref, only in rst mode
-        if context[&#34;images&#34;]:
-            self._get_formatted_text_images(result, context, rst_mode)
-    if context[&#34;endnotes&#34;]:
-        self._get_formatted_text_endnotes(result, context, rst_mode)
-    return &#34;&#34;.join(result)</code></pre>
+        return self._formatted_text(rst_mode)
+    raise NotImplementedError(f&#39;Type of document &#34;{doc_type}&#34; not &#39; &#34;supported yet&#34;)</code></pre>
 </details>
 </dd>
 <dt id="odfdo.document.Document.get_part"><code class="name flex">
@@ -2086,8 +2115,7 @@ <h2 id="arguments">Arguments</h2>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">def get_type(self):
-    &#34;&#34;&#34;
-    Get the ODF type (also called class) of this document.
+    &#34;&#34;&#34;Get the ODF type (also called class) of this document.
 
     Return: &#39;chart&#39;, &#39;database&#39;, &#39;formula&#39;, &#39;graphics&#39;,
         &#39;graphics-template&#39;, &#39;image&#39;, &#39;presentation&#39;,

diff --git a/doc/element.html b/doc/element.html
@@ -323,6 +323,12 @@ <h1 class="title">Module <code>odfdo.element</code></h1>
             self._do_init = False
             self.__element = tag_or_elem
 
+    def __repr__(self) -&gt; str:
+        return f&#34;&lt;{self.__class__.__name__} tag={self.tag}&gt;&#34;
+
+    def __str__(self):
+        return self.text_recursive
+
     @classmethod
     def from_tag(cls, tag_or_elem):
         &#34;&#34;&#34;Element class and subclass factory. Turn an lxml Element or ODF
@@ -369,9 +375,6 @@ <h1 class="title">Module <code>odfdo.element</code></h1>
         root = fromstring(NAMESPACES_XML % tag)  # noqa:S320
         return root[0]
 
-    def __str__(self):
-        return f&#39;{self!r} &#34;{self.tag}&#34;&#39;
-
     @staticmethod
     def _generic_attrib_getter(attr_name, family=None):
         name = _get_lxml_tag(attr_name)
@@ -3091,6 +3094,12 @@ <h2 class="section-title" id="header-classes">Classes</h2>
             self._do_init = False
             self.__element = tag_or_elem
 
+    def __repr__(self) -&gt; str:
+        return f&#34;&lt;{self.__class__.__name__} tag={self.tag}&gt;&#34;
+
+    def __str__(self):
+        return self.text_recursive
+
     @classmethod
     def from_tag(cls, tag_or_elem):
         &#34;&#34;&#34;Element class and subclass factory. Turn an lxml Element or ODF
@@ -3137,9 +3146,6 @@ <h2 class="section-title" id="header-classes">Classes</h2>
         root = fromstring(NAMESPACES_XML % tag)  # noqa:S320
         return root[0]
 
-    def __str__(self):
-        return f&#39;{self!r} &#34;{self.tag}&#34;&#39;
-
     @staticmethod
     def _generic_attrib_getter(attr_name, family=None):
         name = _get_lxml_tag(attr_name)