From be974dd51cceb4eb422440a884c1df2c30154db7 Mon Sep 17 00:00:00 2001 From: Jerome Dumonteil Date: Sun, 17 Dec 2023 18:12:39 +0100 Subject: [PATCH] update doc --- doc/container.html | 21 ++++- doc/content.html | 10 ++- doc/document.html | 132 +++++++++++++++++------------ doc/element.html | 18 ++-- doc/index.html | 206 ++++++++++++++++++++++++++++----------------- doc/link.html | 18 +++- doc/manifest.html | 4 +- doc/meta.html | 4 +- doc/styles.html | 4 +- doc/table.html | 106 +++++++++++++++++------ doc/xmlpart.html | 18 ++-- pyproject.toml | 2 +- 12 files changed, 365 insertions(+), 178 deletions(-) diff --git a/doc/container.html b/doc/container.html index c0a21c1..74291b5 100644 --- a/doc/container.html +++ b/doc/container.html @@ -92,6 +92,9 @@

Module odfdo.container

if path: self.open(path) + def __repr__(self) -> str: + return f"<{self.__class__.__name__} type={self.mimetype} path={self.path}>" + def open(self, path_or_file): """Load the content of an ODF file.""" self.__path_like = path_or_file @@ -331,7 +334,10 @@

Module odfdo.container

@property def mimetype(self): """Return unicode value of mimetype of the document.""" - return self.get_part("mimetype").decode("utf8", "ignore") + try: + return self.get_part("mimetype").decode("utf8", "ignore") + except Exception: + return "" @mimetype.setter def mimetype(self, m): @@ -493,6 +499,9 @@

Classes

if path: self.open(path) + def __repr__(self) -> str: + return f"<{self.__class__.__name__} type={self.mimetype} path={self.path}>" + def open(self, path_or_file): """Load the content of an ODF file.""" self.__path_like = path_or_file @@ -732,7 +741,10 @@

Classes

@property def mimetype(self): """Return unicode value of mimetype of the document.""" - return self.get_part("mimetype").decode("utf8", "ignore") + try: + return self.get_part("mimetype").decode("utf8", "ignore") + except Exception: + return "" @mimetype.setter def mimetype(self, m): @@ -905,7 +917,10 @@

Instance variables

@property
 def mimetype(self):
     """Return unicode value of mimetype of the document."""
-    return self.get_part("mimetype").decode("utf8", "ignore")
+ try: + return self.get_part("mimetype").decode("utf8", "ignore") + except Exception: + return "" diff --git a/doc/content.html b/doc/content.html index 1b301e7..810e273 100644 --- a/doc/content.html +++ b/doc/content.html @@ -69,6 +69,9 @@

Module odfdo.content

self.get_element("//office:automatic-styles"), ) + def __str__(self) -> str: + return str(self.body) + # Public API def get_styles(self, family=None): @@ -133,8 +136,8 @@

Classes

(part_name, container)
-

Representation of an XML part. -Abstraction of the XML library behind.

+

Representation of an XML part.

+

Abstraction of the XML library behind.

Expand source code @@ -154,6 +157,9 @@

Classes

self.get_element("//office:automatic-styles"), ) + def __str__(self) -> str: + return str(self.body) + # Public API def get_styles(self, family=None): diff --git a/doc/document.html b/doc/document.html index a78acd3..87ee4d3 100644 --- a/doc/document.html +++ b/doc/document.html @@ -90,7 +90,7 @@

Module odfdo.document

"""Underline string of the name.""" if level >= len(UNDERLINE_LVL): return "\n" - return underline_lvl[level] * len(name) + return UNDERLINE_LVL[level] * len(name) def _show_styles(element, level=0): @@ -149,7 +149,18 @@

Module odfdo.document

class Document: - """Abstraction of the ODF document.""" + """Abstraction of the ODF document. + + To create a new Document, several possibilities: + + - Document() or Document("text") -> an empty document of type text + - Document("spreadsheet") -> an empty document of type spreadsheet + - Document("presentation") -> an empty document of type presentation + - Document("drawing") -> 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. + """ def __init__(self, target: Union[str, bytes, Path, Container, None] = "text"): # Cache of XML parts @@ -175,6 +186,15 @@

Module odfdo.document

# let's assume we open a container on existing file self.container = Container(target) + def __repr__(self) -> str: + return f"<{self.__class__.__name__} type={self.get_type()} path={self.path}>" + + def __str__(self) -> str: + try: + return self.get_formatted_text() + except NotImplementedError: + return self.body.text_recursive + @classmethod def new(cls, target="text"): doc = Document() @@ -264,8 +284,7 @@

Module odfdo.document

self.container.mimetype = m def get_type(self): - """ - Get the ODF type (also called class) of this document. + """Get the ODF type (also called class) of this document. Return: 'chart', 'database', 'formula', 'graphics', 'graphics-template', 'image', 'presentation', @@ -345,15 +364,21 @@

Module odfdo.document

"""Return content as text, with some formatting.""" # For the moment, only "type='text'" doc_type = self.get_type() - if doc_type not in { + if doc_type == "spreadsheet": + return self._tables_csv() + if doc_type in { "text", "text-template", "presentation", "presentation-template", }: - raise NotImplementedError( - 'Type of document "%s" not ' "supported yet" % doc_type - ) + return self._formatted_text(rst_mode) + raise NotImplementedError(f'Type of document "{doc_type}" not ' "supported yet") + + def _tables_csv(self): + return "\n\n".join(str(table) for table in self.body.get_tables()) + + def _formatted_text(self, rst_mode): # Initialize an empty context context = { "document": self, @@ -875,13 +900,32 @@

Classes

(target: Union[str, bytes, pathlib.Path, Container, ForwardRef(None)] = 'text')
-

Abstraction of the ODF document.

+

Abstraction of the ODF document.

+

To create a new Document, several possibilities:

+
- Document() or Document("text") -> an empty document of type text
+- Document("spreadsheet") -> an empty document of type spreadsheet
+- Document("presentation") -> an empty document of type presentation
+- Document("drawing") -> 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.

Expand source code 
class Document:
-    """Abstraction of the ODF document."""
+    """Abstraction of the ODF document.
+
+    To create a new Document, several possibilities:
+
+        - Document() or Document("text") -> an empty document of type text
+        - Document("spreadsheet") -> an empty document of type spreadsheet
+        - Document("presentation") -> an empty document of type presentation
+        - Document("drawing") -> 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.
+    """
 
     def __init__(self, target: Union[str, bytes, Path, Container, None] = "text"):
         # Cache of XML parts
@@ -907,6 +951,15 @@ 
Classes

         # let's assume we open a container on existing file
         self.container = Container(target)
 
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} type={self.get_type()} path={self.path}>"
+
+    def __str__(self) -> str:
+        try:
+            return self.get_formatted_text()
+        except NotImplementedError:
+            return self.body.text_recursive
+
     @classmethod
     def new(cls, target="text"):
         doc = Document()
@@ -996,8 +1049,7 @@ 
Classes

         self.container.mimetype = m
 
     def get_type(self):
-        """
-        Get the ODF type (also called class) of this document.
+        """Get the ODF type (also called class) of this document.
 
         Return: 'chart', 'database', 'formula', 'graphics',
             'graphics-template', 'image', 'presentation',
@@ -1077,15 +1129,21 @@ 
Classes

         """Return content as text, with some formatting."""
         # For the moment, only "type='text'"
         doc_type = self.get_type()
-        if doc_type not in {
+        if doc_type == "spreadsheet":
+            return self._tables_csv()
+        if doc_type in {
             "text",
             "text-template",
             "presentation",
             "presentation-template",
         }:
-            raise NotImplementedError(
-                'Type of document "%s" not ' "supported yet" % doc_type
-            )
+            return self._formatted_text(rst_mode)
+        raise NotImplementedError(f'Type of document "{doc_type}" not ' "supported yet")
+
+    def _tables_csv(self):
+        return "\n\n".join(str(table) for table in self.body.get_tables())
+
+    def _formatted_text(self, rst_mode):
         # Initialize an empty context
         context = {
             "document": self,
@@ -1870,45 +1928,16 @@ 
Arguments

     """Return content as text, with some formatting."""
     # For the moment, only "type='text'"
     doc_type = self.get_type()
-    if doc_type not in {
+    if doc_type == "spreadsheet":
+        return self._tables_csv()
+    if doc_type in {
         "text",
         "text-template",
         "presentation",
         "presentation-template",
     }:
-        raise NotImplementedError(
-            'Type of document "%s" not ' "supported yet" % doc_type
-        )
-    # Initialize an empty context
-    context = {
-        "document": self,
-        "footnotes": [],
-        "endnotes": [],
-        "annotations": [],
-        "rst_mode": rst_mode,
-        "img_counter": 0,
-        "images": [],
-        "no_img_level": 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 == "table:table":
-            result.append(element.get_formatted_text(context))
-            return
-        result.append(element.get_formatted_text(context))
-        if context["footnotes"]:
-            self._get_formatted_text_footnotes(result, context, rst_mode)
-        if context["annotations"]:
-            self._get_formatted_text_annotations(result, context, rst_mode)
-        # Insert the images ref, only in rst mode
-        if context["images"]:
-            self._get_formatted_text_images(result, context, rst_mode)
-    if context["endnotes"]:
-        self._get_formatted_text_endnotes(result, context, rst_mode)
-    return "".join(result)
+ return self._formatted_text(rst_mode) + raise NotImplementedError(f'Type of document "{doc_type}" not ' "supported yet")
@@ -2086,8 +2115,7 @@

Arguments

Expand source code 
def get_type(self):
-    """
-    Get the ODF type (also called class) of this document.
+    """Get the ODF type (also called class) of this document.
 
     Return: 'chart', 'database', 'formula', 'graphics',
         'graphics-template', 'image', 'presentation',
diff --git a/doc/element.html b/doc/element.html
index ca4e1fc..602b527 100644
--- a/doc/element.html
+++ b/doc/element.html
@@ -323,6 +323,12 @@ 
Module odfdo.element

             self._do_init = False
             self.__element = tag_or_elem
 
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} tag={self.tag}>"
+
+    def __str__(self):
+        return self.text_recursive
+
     @classmethod
     def from_tag(cls, tag_or_elem):
         """Element class and subclass factory. Turn an lxml Element or ODF
@@ -369,9 +375,6 @@ 
Module odfdo.element

         root = fromstring(NAMESPACES_XML % tag)  # noqa:S320
         return root[0]
 
-    def __str__(self):
-        return f'{self!r} "{self.tag}"'
-
     @staticmethod
     def _generic_attrib_getter(attr_name, family=None):
         name = _get_lxml_tag(attr_name)
@@ -3091,6 +3094,12 @@ 
Classes

             self._do_init = False
             self.__element = tag_or_elem
 
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} tag={self.tag}>"
+
+    def __str__(self):
+        return self.text_recursive
+
     @classmethod
     def from_tag(cls, tag_or_elem):
         """Element class and subclass factory. Turn an lxml Element or ODF
@@ -3137,9 +3146,6 @@ 
Classes

         root = fromstring(NAMESPACES_XML % tag)  # noqa:S320
         return root[0]
 
-    def __str__(self):
-        return f'{self!r} "{self.tag}"'
-
     @staticmethod
     def _generic_attrib_getter(attr_name, family=None):
         name = _get_lxml_tag(attr_name)
diff --git a/doc/index.html b/doc/index.html
index 216492c..8ca722b 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -384,7 +384,7 @@ 
Sub-modules
odfdo.xmlpart
-

XmlPart base class for XML parts

+

XmlPart base class for XML parts.

@@ -4922,6 +4922,9 @@

Inherited members

if path: self.open(path) + def __repr__(self) -> str: + return f"<{self.__class__.__name__} type={self.mimetype} path={self.path}>" + def open(self, path_or_file): """Load the content of an ODF file.""" self.__path_like = path_or_file @@ -5161,7 +5164,10 @@

Inherited members

@property def mimetype(self): """Return unicode value of mimetype of the document.""" - return self.get_part("mimetype").decode("utf8", "ignore") + try: + return self.get_part("mimetype").decode("utf8", "ignore") + except Exception: + return "" @mimetype.setter def mimetype(self, m): @@ -5334,7 +5340,10 @@

Instance variables

@property
 def mimetype(self):
     """Return unicode value of mimetype of the document."""
-    return self.get_part("mimetype").decode("utf8", "ignore")
+ try: + return self.get_part("mimetype").decode("utf8", "ignore") + except Exception: + return "" @@ -5514,8 +5523,8 @@

Arguments

(part_name, container)
-

Representation of an XML part. -Abstraction of the XML library behind.

+

Representation of an XML part.

+

Abstraction of the XML library behind.

Expand source code @@ -5535,6 +5544,9 @@

Arguments

self.get_element("//office:automatic-styles"), ) + def __str__(self) -> str: + return str(self.body) + # Public API def get_styles(self, family=None): @@ -5701,13 +5713,32 @@

Inherited members

(target: Union[str, bytes, pathlib.Path, Container, ForwardRef(None)] = 'text')
-

Abstraction of the ODF document.

+

Abstraction of the ODF document.

+

To create a new Document, several possibilities:

+
- Document() or Document("text") -> an empty document of type text
+- Document("spreadsheet") -> an empty document of type spreadsheet
+- Document("presentation") -> an empty document of type presentation
+- Document("drawing") -> 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.

Expand source code 
class Document:
-    """Abstraction of the ODF document."""
+    """Abstraction of the ODF document.
+
+    To create a new Document, several possibilities:
+
+        - Document() or Document("text") -> an empty document of type text
+        - Document("spreadsheet") -> an empty document of type spreadsheet
+        - Document("presentation") -> an empty document of type presentation
+        - Document("drawing") -> 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.
+    """
 
     def __init__(self, target: Union[str, bytes, Path, Container, None] = "text"):
         # Cache of XML parts
@@ -5733,6 +5764,15 @@ 
Inherited members

         # let's assume we open a container on existing file
         self.container = Container(target)
 
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} type={self.get_type()} path={self.path}>"
+
+    def __str__(self) -> str:
+        try:
+            return self.get_formatted_text()
+        except NotImplementedError:
+            return self.body.text_recursive
+
     @classmethod
     def new(cls, target="text"):
         doc = Document()
@@ -5822,8 +5862,7 @@ 
Inherited members

         self.container.mimetype = m
 
     def get_type(self):
-        """
-        Get the ODF type (also called class) of this document.
+        """Get the ODF type (also called class) of this document.
 
         Return: 'chart', 'database', 'formula', 'graphics',
             'graphics-template', 'image', 'presentation',
@@ -5903,15 +5942,21 @@ 
Inherited members

         """Return content as text, with some formatting."""
         # For the moment, only "type='text'"
         doc_type = self.get_type()
-        if doc_type not in {
+        if doc_type == "spreadsheet":
+            return self._tables_csv()
+        if doc_type in {
             "text",
             "text-template",
             "presentation",
             "presentation-template",
         }:
-            raise NotImplementedError(
-                'Type of document "%s" not ' "supported yet" % doc_type
-            )
+            return self._formatted_text(rst_mode)
+        raise NotImplementedError(f'Type of document "{doc_type}" not ' "supported yet")
+
+    def _tables_csv(self):
+        return "\n\n".join(str(table) for table in self.body.get_tables())
+
+    def _formatted_text(self, rst_mode):
         # Initialize an empty context
         context = {
             "document": self,
@@ -6696,45 +6741,16 @@ 
Arguments

     """Return content as text, with some formatting."""
     # For the moment, only "type='text'"
     doc_type = self.get_type()
-    if doc_type not in {
+    if doc_type == "spreadsheet":
+        return self._tables_csv()
+    if doc_type in {
         "text",
         "text-template",
         "presentation",
         "presentation-template",
     }:
-        raise NotImplementedError(
-            'Type of document "%s" not ' "supported yet" % doc_type
-        )
-    # Initialize an empty context
-    context = {
-        "document": self,
-        "footnotes": [],
-        "endnotes": [],
-        "annotations": [],
-        "rst_mode": rst_mode,
-        "img_counter": 0,
-        "images": [],
-        "no_img_level": 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 == "table:table":
-            result.append(element.get_formatted_text(context))
-            return
-        result.append(element.get_formatted_text(context))
-        if context["footnotes"]:
-            self._get_formatted_text_footnotes(result, context, rst_mode)
-        if context["annotations"]:
-            self._get_formatted_text_annotations(result, context, rst_mode)
-        # Insert the images ref, only in rst mode
-        if context["images"]:
-            self._get_formatted_text_images(result, context, rst_mode)
-    if context["endnotes"]:
-        self._get_formatted_text_endnotes(result, context, rst_mode)
-    return "".join(result)
+ return self._formatted_text(rst_mode) + raise NotImplementedError(f'Type of document "{doc_type}" not ' "supported yet")
@@ -6912,8 +6928,7 @@

Arguments

Expand source code 
def get_type(self):
-    """
-    Get the ODF type (also called class) of this document.
+    """Get the ODF type (also called class) of this document.
 
     Return: 'chart', 'database', 'formula', 'graphics',
         'graphics-template', 'image', 'presentation',
@@ -8703,6 +8718,12 @@ 
Inherited members

             self._do_init = False
             self.__element = tag_or_elem
 
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} tag={self.tag}>"
+
+    def __str__(self):
+        return self.text_recursive
+
     @classmethod
     def from_tag(cls, tag_or_elem):
         """Element class and subclass factory. Turn an lxml Element or ODF
@@ -8749,9 +8770,6 @@ 
Inherited members

         root = fromstring(NAMESPACES_XML % tag)  # noqa:S320
         return root[0]
 
-    def __str__(self):
-        return f'{self!r} "{self.tag}"'
-
     @staticmethod
     def _generic_attrib_getter(attr_name, family=None):
         name = _get_lxml_tag(attr_name)
@@ -17609,7 +17627,15 @@ 
Arguments

             if style is not None:
                 self.style = style
             if visited_style is not None:
-                self.visited_style = visited_style
+ self.visited_style = visited_style + + def __repr__(self) -> str: + return f"<{self.__class__.__name__} tag={self.tag} link={self.url}>" + + def __str__(self) -> str: + if self.name: + return f"[{self.name}]({self.url})" + return f"({self.url})"

Ancestors