[Python-modules-commits] [python-odf] 85/118: Improved the doc strings
Wolfgang Borgert
debacle at moszumanska.debian.org
Fri Oct 3 21:27:26 UTC 2014
This is an automated email from the git hooks/post-receive script.
debacle pushed a commit to reference refs/remotes/upstream/master
in repository python-odf.
commit cfd82e0e024e0a863f95aaeea3c34c99cd2909ca
Author: Søren Roug <soren.roug at eea.europa.eu>
Date: Sun Apr 25 16:00:46 2010 +0000
Improved the doc strings
---
odf/attrconverters.py | 4 ++++
odf/element.py | 61 ++++++++++++++++++++++++++++++++++++++-------------
odf/grammar.py | 2 +-
odf/namespaces.py | 2 +-
odf/opendocument.py | 28 +++++++++++++++++++----
5 files changed, 76 insertions(+), 21 deletions(-)
diff --git a/odf/attrconverters.py b/odf/attrconverters.py
index d84a958..a85d7af 100644
--- a/odf/attrconverters.py
+++ b/odf/attrconverters.py
@@ -76,6 +76,7 @@ def cnv_duration(attribute, arg, element):
return str(arg)
def cnv_family(attribute, arg, element):
+ """ A style family """
if str(arg) not in ("text", "paragraph", "section", "ruby", "table", "table-column", "table-row", "table-cell",
"graphic", "presentation", "drawing-page", "chart"):
raise ValueError, "'%s' not allowed" % str(arg)
@@ -1465,6 +1466,9 @@ attrconverters = {
class AttrConverters:
def convert(self, attribute, value, element):
+ """ Based on the element, figures out how to check/convert the attribute value
+ All values are converted to string
+ """
conversion = attrconverters.get((attribute, element.qname), None)
if conversion is not None:
return conversion(attribute, value, element)
diff --git a/odf/element.py b/odf/element.py
index 27aec38..ee5377d 100644
--- a/odf/element.py
+++ b/odf/element.py
@@ -1,6 +1,6 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
-# Copyright (C) 2007-2008 Søren Roug, European Environment Agency
+# Copyright (C) 2007-2010 Søren Roug, European Environment Agency
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
@@ -112,6 +112,9 @@ class Node(xml.dom.Node):
return self.childNodes[-1]
def insertBefore(self, newChild, refChild):
+ """ Inserts the node newChild before the existing child node refChild.
+ If refChild is null, insert newChild at the end of the list of children.
+ """
if newChild.nodeType not in self._child_node_types:
raise IllegalChild, "%s cannot be child of %s" % (newChild.tagName, self.tagName)
if newChild.parentNode is not None:
@@ -135,21 +138,26 @@ class Node(xml.dom.Node):
newChild.parentNode = self
return newChild
- def appendChild(self, node):
- if node.nodeType == self.DOCUMENT_FRAGMENT_NODE:
- for c in tuple(node.childNodes):
+ def appendChild(self, newChild):
+ """ Adds the node newChild to the end of the list of children of this node.
+ If the newChild is already in the tree, it is first removed.
+ """
+ if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE:
+ for c in tuple(newChild.childNodes):
self.appendChild(c)
### The DOM does not clearly specify what to return in this case
- return node
- if node.nodeType not in self._child_node_types:
- raise IllegalChild, "<%s> is not allowed in %s" % ( node.tagName, self.tagName)
- if node.parentNode is not None:
- node.parentNode.removeChild(node)
- _append_child(self, node)
- node.nextSibling = None
- return node
+ return newChild
+ if newChild.nodeType not in self._child_node_types:
+ raise IllegalChild, "<%s> is not allowed in %s" % ( newChild.tagName, self.tagName)
+ if newChild.parentNode is not None:
+ newChild.parentNode.removeChild(newChild)
+ _append_child(self, newChild)
+ newChild.nextSibling = None
+ return newChild
def removeChild(self, oldChild):
+ """ Removes the child node indicated by oldChild from the list of children, and returns it.
+ """
#FIXME: update ownerDocument.element_dict or find other solution
try:
self.childNodes.remove(oldChild)
@@ -191,8 +199,8 @@ def _append_child(self, node):
node.__dict__["parentNode"] = self
class Childless:
- """Mixin that makes childless-ness easy to implement and avoids
- the complexity of the Node methods that deal with children.
+ """ Mixin that makes childless-ness easy to implement and avoids
+ the complexity of the Node methods that deal with children.
"""
attributes = None
@@ -207,6 +215,7 @@ class Childless:
return None
def appendChild(self, node):
+ """ Raises an error """
raise xml.dom.HierarchyRequestErr(
self.tagName + " nodes cannot have children")
@@ -214,14 +223,17 @@ class Childless:
return False
def insertBefore(self, newChild, refChild):
+ """ Raises an error """
raise xml.dom.HierarchyRequestErr(
self.tagName + " nodes do not have children")
def removeChild(self, oldChild):
+ """ Raises an error """
raise xml.dom.NotFoundErr(
self.tagName + " nodes do not have children")
def replaceChild(self, newChild, oldChild):
+ """ Raises an error """
raise xml.dom.HierarchyRequestErr(
self.tagName + " nodes do not have children")
@@ -247,8 +259,12 @@ class CDATASection(Childless, Text):
nodeType = Node.CDATA_SECTION_NODE
def toXml(self,level,f):
+ """ Generate XML output of the node. If the text contains "]]>", then
+ escape it by going out of CDATA mode (]]>), then write the string
+ and then go into CDATA mode again. (<![CDATA[)
+ """
if self.data:
- f.write('<![CDATA[%s]]>' % self.data)
+ f.write('<![CDATA[%s]]>' % self.data.replace(']]>',']]>]]><![CDATA['))
class Element(Node):
""" Creates a arbitrary element and is intended to be subclassed not used on its own.
@@ -311,12 +327,18 @@ class Element(Node):
raise AttributeError, "Required attribute missing: %s in <%s>" % (r[1].lower().replace('-',''), self.tagName)
def get_knownns(self, prefix):
+ """ Odfpy maintains a list of known namespaces. In some cases a prefix is used, and
+ we need to know which namespace it resolves to.
+ """
global nsdict
for ns,p in nsdict.items():
if p == prefix: return ns
return None
def get_nsprefix(self, namespace):
+ """ Odfpy maintains a list of known namespaces. In some cases we have a namespace URL,
+ and needs to look up or assign the prefix for it.
+ """
if namespace is None: namespace = ""
prefix = _nsassign(namespace)
if not self.namespaces.has_key(namespace):
@@ -345,6 +367,9 @@ class Element(Node):
self.ownerDocument.rebuild_caches(element)
def addText(self, text, check_grammar=True):
+ """ Adds text to an element
+ Setting check_grammar=False turns off grammar checking
+ """
if check_grammar and self.qname not in grammar.allows_text:
raise IllegalText, "The <%s> element does not allow text" % self.tagName
else:
@@ -352,6 +377,9 @@ class Element(Node):
self.appendChild(Text(text))
def addCDATA(self, cdata, check_grammar=True):
+ """ Adds CDATA to an element
+ Setting check_grammar=False turns off grammar checking
+ """
if check_grammar and self.qname not in grammar.allows_text:
raise IllegalText, "The <%s> element does not allow text" % self.tagName
else:
@@ -420,6 +448,8 @@ class Element(Node):
del self.attributes[prefix + ":" + localpart]
def getAttribute(self, attr):
+ """ Get an attribute value. The method knows which namespace the attribute is in
+ """
allowed_attrs = self.allowed_attributes()
if allowed_attrs is None:
if type(attr) == type(()):
@@ -470,6 +500,7 @@ class Element(Node):
return accumulator
def getElementsByType(self, element):
+ """ Gets elements based on the type, which is function from text.py, draw.py etc. """
obj = element(check_grammar=False)
return self._getElementsByObj(obj,[])
diff --git a/odf/grammar.py b/odf/grammar.py
index 09ec02c..d5d8d59 100644
--- a/odf/grammar.py
+++ b/odf/grammar.py
@@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
-# Copyright (C) 2006-2009 Søren Roug, European Environment Agency
+# Copyright (C) 2006-2010 Søren Roug, European Environment Agency
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
diff --git a/odf/namespaces.py b/odf/namespaces.py
index ef9fc75..642598d 100644
--- a/odf/namespaces.py
+++ b/odf/namespaces.py
@@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
-# Copyright (C) 2006-2009 Søren Roug, European Environment Agency
+# Copyright (C) 2006-2010 Søren Roug, European Environment Agency
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
diff --git a/odf/opendocument.py b/odf/opendocument.py
index f8e208d..4e222ca 100644
--- a/odf/opendocument.py
+++ b/odf/opendocument.py
@@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
-# Copyright (C) 2006-2009 Søren Roug, European Environment Agency
+# Copyright (C) 2006-2010 Søren Roug, European Environment Agency
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
@@ -344,7 +344,7 @@ class OpenDocument:
self.thumbnail = filecontent
def addObject(self, document, objectname=None):
- """ Add an object. The object must be an OpenDocument class
+ """ Adds an object (subdocument). The object must be an OpenDocument class
The return value will be the folder in the zipfile the object is stored in
"""
self.childobjects.append(document)
@@ -385,7 +385,9 @@ class OpenDocument:
self.meta.addElement(meta.Generator(text=TOOLSVERSION))
def save(self, outputfile, addsuffix=False):
- """ Save the document under the filename """
+ """ Save the document under the filename.
+ If the filename is '-' then save to stdout
+ """
if outputfile == '-':
outputfp = zipfile.ZipFile(sys.stdout,"w")
else:
@@ -396,11 +398,16 @@ class OpenDocument:
outputfp.close()
def write(self, outputfp):
+ """ User API to write the ODF file to an open file descriptor
+ Writes the ZIP format
+ """
zipoutputfp = zipfile.ZipFile(outputfp,"w")
self._zipwrite(zipoutputfp)
def _zipwrite(self, outputfp):
- """ Write the document to an open file pointer """
+ """ Write the document to an open file pointer
+ This is where the real work is done
+ """
self._z = outputfp
self._now = time.localtime()[:6]
self.manifest = manifest.Manifest()
@@ -497,6 +504,7 @@ class OpenDocument:
return element.Text(data)
def createCDATASection(self, data):
+ """ Method to create a CDATA section """
return element.CDATASection(cdata)
def getMediaType(self):
@@ -504,12 +512,14 @@ class OpenDocument:
return self.mimetype
def getStyleByName(self, name):
+ """ Finds a style object based on the name """
ncname = make_NCName(name)
if self._styles_dict == {}:
self.rebuild_caches()
return self._styles_dict.get(ncname, None)
def getElementsByType(self, element):
+ """ Gets elements based on the type, which is function from text.py, draw.py etc. """
obj = element(check_grammar=False)
if self.element_dict == {}:
self.rebuild_caches()
@@ -517,48 +527,58 @@ class OpenDocument:
# Convenience functions
def OpenDocumentChart():
+ """ Creates a chart document """
doc = OpenDocument('application/vnd.oasis.opendocument.chart')
doc.chart = Chart()
doc.body.addElement(doc.chart)
return doc
def OpenDocumentDrawing():
+ """ Creates a drawing document """
doc = OpenDocument('application/vnd.oasis.opendocument.graphics')
doc.drawing = Drawing()
doc.body.addElement(doc.drawing)
return doc
def OpenDocumentImage():
+ """ Creates an image document """
doc = OpenDocument('application/vnd.oasis.opendocument.image')
doc.image = Image()
doc.body.addElement(doc.image)
return doc
def OpenDocumentPresentation():
+ """ Creates a presentation document """
doc = OpenDocument('application/vnd.oasis.opendocument.presentation')
doc.presentation = Presentation()
doc.body.addElement(doc.presentation)
return doc
def OpenDocumentSpreadsheet():
+ """ Creates a spreadsheet document """
doc = OpenDocument('application/vnd.oasis.opendocument.spreadsheet')
doc.spreadsheet = Spreadsheet()
doc.body.addElement(doc.spreadsheet)
return doc
def OpenDocumentText():
+ """ Creates a text document """
doc = OpenDocument('application/vnd.oasis.opendocument.text')
doc.text = Text()
doc.body.addElement(doc.text)
return doc
def OpenDocumentTextMaster():
+ """ Creates a text master document """
doc = OpenDocument('application/vnd.oasis.opendocument.text-master')
doc.text = Text()
doc.body.addElement(doc.text)
return doc
def load(odffile):
+ """ Load an ODF file into memory
+ Returns a reference to the structure
+ """
from load import LoadParser
from xml.sax import make_parser, handler
z = zipfile.ZipFile(odffile)
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/python-odf.git
More information about the Python-modules-commits
mailing list