Merge pull request #5 from keruzu/master

Fix grammar errors and typos.

README.md

@@ -1,28 +1,28 @@
 #XMind SDK for python
 
-**XMind SDK for python** to help python developers to easily work with XMind file and build XMind extensions.
+**XMind SDK for python** to help Python developers to easily work with XMind files and build XMind extensions.
 
 ##Install XMind SDK for python
 
-Clone repository to local working directory
+Clone the repository to a local working directory
 
 	git clone https://github.com/xmindltd/xmind-sdk-python.git
 
-right now, you got directory named `xmind-sdk-python` under current directory. Change to directory `xmind-sdk-python` and install **XMind SDK for python**.
+Now there will be a directory named `xmind-sdk-python` under the current directory. Change to the directory `xmind-sdk-python` and install **XMind SDK for python**.
 
 	python setup.py install
 
-*We're highly recommend to install __XMind SDK for python__ under isolate python environment using [virtualenv](https://pypi.python.org/pypi/virtualenv)*
+*It is highly recommended to install __XMind SDK for python__ under an isolated python environment using [virtualenv](https://pypi.python.org/pypi/virtualenv)*
 
 ##Usage
 
-Open XMind file from exist path or create new XMind file and placed to given path
+Open an existing XMind file or create a new XMind file and place it into a given path
 
 	import xmind
-	workbook = xmind.load(/path/to/file/)
+	workbook = xmind.load(/path/to/file/)  # Requires '.xmind' extension
 
-Save XMind file to given path. 
-If path not given then will save to path that set to workbook
+Save XMind file to a path.
+If the path is not given then the API will save to the path set in the workbook
 
 	xmind.save(workbook)
 

xmind/core/__init__.py

@@ -40,13 +40,15 @@ def create_element(tag_name, namespaceURI=None, prefix=None, localName=None):
 
 
 class Node(object):
-    """All of components of XMind workbook are subclass of Node
+    """
+    All of components of XMind workbook subclass Node
     """
     def __init__(self, node):
         self._node = node
 
     def _equals(self, obj=None):
-        """Compare passed object and current instance
+        """
+        Compare the passed object with the current instance
         """
         if obj is None or not isinstance(obj, self.__class__):
             return False
@@ -55,20 +57,17 @@ def _equals(self, obj=None):
         return self.getImplementation() == obj.getImplementation()
 
     def getImplementation(self):
-        """Get DOM implementation of passed node. Provides a interface for
-        manipulate DOM directly
+        """
+        Get DOM implementation of passed node. Provides an interface to
+        manipulate the DOM directly
         """
         return self._node
 
     def getOwnerDocument(self):
-        raise Exception(
-            """This is method doesn't implementated
-            """)
+        raise NotImplementedError("This method requires an implementation!")
 
     def setOwnerDocument(self, doc):
-        raise Exception(
-            """This is method doesn't implementated
-            """)
+        raise NotImplementedError("This method requires an implementation!")
 
     def getLocalName(self, qualifiedName):
         index = qualifiedName.find(":")
@@ -83,7 +82,8 @@ def getPrefix(self, qualifiedName):
             return qualifiedName[:index + 1]
 
     def appendChild(self, node):
-        """Append passed node to the end of child node list of this node
+        """
+        Append passed node to the end of child node list of this node
         """
         node.setOwnerDocument(self.getOwnerDocument())
 
@@ -92,7 +92,8 @@ def appendChild(self, node):
         return self._node.appendChild(node_impel)
 
     def insertBefore(self, new_node, ref_node):
-        """Insert new node before ref_node. Please notice that ref_node
+        """
+        Insert new node before ref_node. Please notice that ref_node
         must be a child of this node.
         """
         new_node.setOwnerDocument(self.getOwnerDocument())
@@ -103,7 +104,8 @@ def insertBefore(self, new_node, ref_node):
         return self._node.insertBefore(new_node_imple, ref_node_imple)
 
     def getChildNodesByTagName(self, tag_name):
-        """Search for all children with specified tag name under passed DOM
+        """
+        Search for all children with specified tag name under passed DOM
         implementation, instead of all descendants
         """
         child_nodes = []
@@ -157,6 +159,8 @@ def output(self, output_stream):
 
 class Document(Node):
     def __init__(self, node=None):
+        # FIXME: Should really call the base class
+        #super(Document, self).__init__()
         self._node = node or self._documentConstructor()
         # self.arg = arg
 
@@ -165,7 +169,8 @@ def _documentConstructor(self):
 
     @property
     def documentElement(self):
-        """Get root element of passed DOM implementation for manipulate
+        """
+        Get root element of passed DOM implementation for manipulate
         """
         return self._node.documentElement
 
@@ -193,6 +198,8 @@ class Element(Node):
     TAG_NAME = ""
 
     def __init__(self, node=None):
+        # FIXME: Should really call the base class
+        #super(Element, self).__init__()
         self._node = node or self._elementConstructor(
             self.TAG_NAME.decode("utf8"))
 
@@ -216,8 +223,9 @@ def setOwnerDocument(self, doc_imple):
         self._node.ownerDocument = doc_imple
 
     def setAttributeNS(self, namespace, attr):
-        """Set attributes with namespace to DOM implementation.
-        Please notice that namespce must be a pairs of namespace name and
+        """
+        Set attributes with namespace to DOM implementation.
+        Please notice that namespace must be a namespace name and
         namespace value. Attr composed by namespceURI, localName and value.
         """
         namespace_name, namespace_value = namespace
@@ -230,7 +238,8 @@ def setAttributeNS(self, namespace, attr):
             self._node.setAttributeNS(namespaceURI, qualifiedName, value)
 
     def getAttribute(self, attr_name):
-        """Get attribute with specified name. And allowed get attribute with
+        """
+        Get attribute with specified name. And allowed get attribute with
         specified name in ``prefix:localName`` format.
         """
         if not self._node.hasAttribute(attr_name):
@@ -242,7 +251,8 @@ def getAttribute(self, attr_name):
         return self._node.getAttribute(attr_name)
 
     def setAttribute(self, attr_name, attr_value=None):
-        """Set attribute to element. Please notice that if ``attr_value`` is
+        """
+        Set attribute to element. Please notice that if ``attr_value`` is
         None and attribute with specified ``attr_name`` is exist,
         attribute will be removed.
         """
@@ -253,7 +263,8 @@ def setAttribute(self, attr_name, attr_value=None):
             self._node.removeAttribute(attr_name)
 
     def createElement(self, tag_name):
-        """Create new element. But created element doesn't add to the child
+        """
+        Create new element. But created element doesn't add to the child
         node list of this element, invoke :func: ``self.appendChild`` or :func:
         ``self.insertBefore`` to add created element to the child node list of
         this element.

xmind/core/loader.py

@@ -22,8 +22,8 @@ class WorkbookLoader(object):
     def __init__(self, path):
         """ Load XMind workbook from given path
 
-        :param path:    path of XMind, if path is not a exists file,
-                        will not occured error.
+        :param path:    path to XMind file. If not an existing file,
+                        will not raise an exception.
 
         """
         super(WorkbookLoader, self).__init__()
@@ -32,7 +32,7 @@ def __init__(self, path):
         file_name, ext = utils.split_ext(self._input_source)
 
         if ext != const.XMIND_EXT:
-            raise Exception("Illegal XMind file")
+            raise Exception("The XMind filename is missing the '%s' extension!" % const.XMIND_EXT)
 
         # Input Stream
         self._content_stream = None

xmind/core/position.py

@@ -23,6 +23,8 @@ class PositionElement(WorkbookMixinElement):
     def __init__(self, node=None, ownerWorkbook=None):
         super(PositionElement, self).__init__(node, ownerWorkbook)
 
+    # FIXME: These should be converted to getter/setters
+
     def getX(self):
         return self.getAttribute(const.ATTR_X)
 

xmind/core/relationship.py

@@ -42,6 +42,8 @@ def _find_end_point(self, id):
         if end_point.tagName == const.TAG_TOPIC:
             return TopicElement(end_point, owner_workbook)
 
+    # FIXME: Convert the following to getter/setter
+
     def getEnd1ID(self):
         return self.getAttribute(const.ATTR_END1)
 

xmind/core/saver.py

@@ -36,20 +36,21 @@ def _get_content(self):
         return content_path
 
     def save(self, path=None):
-        """ Save workbook to given path. If path not given, then
-        will save to path that set to workbook.
+        """
+        Save the workbook to the given path. If the path is not given, then
+        will save to the path set in workbook.
         """
         path = path or self._workbook.get_path()
 
         if not path:
-            raise Exception("Please specified path to save XMind file")
+            raise Exception("Please specify a filename for the XMind file")
 
         path = utils.get_abs_path(path)
 
         file_name, ext = utils.split_ext(path)
 
         if ext != const.XMIND_EXT:
-            raise Exception("Illegal XMind file")
+            raise Exception("XMind filenames require a '%s' extension" % const.XMIND_EXT)
 
         content = self._get_content()
 

xmind/core/sheet.py

@@ -45,9 +45,10 @@ def _get_root_topic(self):
         return root_topic
 
     def createRelationship(self, end1, end2, title=None):
-        """ Create relationship between with two different topics and return
-        created rel. Please notice that created rel will not be added to
-        sheet and invoke `addRelationship` to add rel to sheet.
+        """
+        Create a relationship between two different topics and return the
+        created rel. Please notice that the created rel will not be added to
+        sheet. Call `addRelationship()` to add rel to sheet.
 
         :param end1:    topic ID
         :param end2:    topic ID
@@ -67,7 +68,8 @@ def _getRelationships(self):
         return self.getFirstChildNodeByTagName(const.TAG_RELATIONSHIPS)
 
     def addRelationship(self, rel):
-        """ Add relationship to sheet
+        """
+        Add relationship to sheet
         """
         _rels = self._getRelationships()
         owner_workbook = self.getOwnerWorkbook()
@@ -80,7 +82,8 @@ def addRelationship(self, rel):
         rels.appendChild(rel)
 
     def removeRelationship(self, rel):
-        """ Remove relationship between two different topics
+        """
+        Remove a relationship between two different topics
         """
         rels = self._getRelationships()
 
@@ -100,6 +103,7 @@ def getRootTopic(self):
     def _get_title(self):
         return self.getFirstChildNodeByTagName(const.TAG_TITLE)
 
+    # FIXME: convert to getter/setter
     def getTitle(self):
         title = self._get_title()
         if title:

xmind/core/topic.py

@@ -108,7 +108,6 @@ def getMarkers(self):
                 marker_list.append(MarkerRefElement(i, self.getOwnerWorkbook()))
         return marker_list
 
-
     def addMarker(self, markerId):
 
         if not markerId:
@@ -231,7 +230,8 @@ def getSubTopicByIndex(self, index, topics_type=const.TOPIC_ATTACHED):
 
     def addSubTopic(self, topic=None, index=-1,
                     topics_type=const.TOPIC_ATTACHED):
-        """ Add sub topic to current topic and return added sub topic
+        """
+        Add a sub topic to the current topic and return added sub topic
 
         :param topic:   `TopicElement` object. If not `TopicElement` object
                         passed then created new one automatically.
@@ -281,7 +281,8 @@ def getHyperlink(self):
         return self.getAttribute(const.ATTR_HREF)
 
     def setFileHyperlink(self, path):
-        """ Set file as topic hyperlink
+        """
+        Set file as topic hyperlink
 
         :param path: path of specified file
 
@@ -293,7 +294,8 @@ def setFileHyperlink(self, path):
         self._set_hyperlink(path)
 
     def setTopicHyperlink(self, tid):
-        """ Set topic as topic hyperlink
+        """
+        Set topic as topic hyperlink
 
         :param id: given topic's id
 
@@ -319,7 +321,8 @@ def setURLHyperlink(self, url):
         self._set_hyperlink(url)
 
     def getNotes(self):
-        """ Return `NotesElement` object` and invoke
+        """
+        Return `NotesElement` object` and invoke
         `NotesElement.getContent()` to get notes content.
         """
 
@@ -377,7 +380,8 @@ def getType(self):
         return self.getAttribute(const.ATTR_TYPE)
 
     def getSubTopics(self):
-        """List all sub topics on current topic
+        """
+        List all sub topics on the current topic
         """
         topics = []
         ownerWorkbook = self.getOwnerWorkbook()
@@ -387,7 +391,8 @@ def getSubTopics(self):
         return topics
 
     def getSubTopicByIndex(self, index):
-        """Get specified sub topic by index
+        """
+        Get specified sub topic by index
         """
         sub_topics = self.getSubTopics()
         if index < 0 or index >= len(sub_topics):