XMind SDK for Python

https://github.com/xmindltd/xmind-sdk-python
Admin
XMind SDK for Python helps Python developers easily work with XMind files and build XMind...
Tokens:56,832
Snippets:446
Trust Score:8.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install XMind SDK with setup.py

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/README.md

Installs the XMind SDK for Python from the cloned repository. It is recommended to run this inside an isolated virtualenv.

```bash
python setup.py install
```

--------------------------------

### Example: using WorkbookMixinElement methods

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/mixin.md

Loads a workbook, gets the primary sheet, and demonstrates getID, updateModifiedTime, and getModifiedTime. The print statements use Python 2 syntax.

```python
from xmind import load
from xmind.core.mixin import WorkbookMixinElement

workbook = load("plan.xmind")
sheet = workbook.getPrimarySheet()          # a WorkbookMixinElement subclass

assert isinstance(sheet, WorkbookMixinElement)
print sheet.getID()                         # e.g. '193c0a7...'
sheet.updateModifiedTime()
print sheet.getModifiedTime()               # 'MM/DD/YYYY HH:MM:SS' UTC
```

--------------------------------

### Usage example: create_document and create_element

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Shows how to create a DOM document and append a topic element with a namespace URI.

```python
from xmind.core import create_document, create_element

doc = create_document()
el = create_element("topic", "urn:xmind:xmap:xmlns:content:2.0")
doc.appendChild(el)
```

--------------------------------

### Typical usage of setPlainNotes and getNotes

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/notes.md

Shows how to set and retrieve plain text notes on a topic using the XMind SDK. The example loads a workbook, gets the root topic, sets notes, and prints the content. It also demonstrates that setting notes again replaces the previous content.

```python
import xmind

workbook = xmind.load("plan.xmind")
root = workbook.getPrimarySheet().getRootTopic()

root.setPlainNotes("notes for this topic (F4 in XMind)")
notes = root.getNotes()                 # NotesElement
print notes.getContent()                # 'notes for this topic (F4 in XMind)'

root.setPlainNotes("updated note")      # replaces the previous <plain> child
print notes.getContent()                # 'updated note'
```

--------------------------------

### Basic usage of xmind.load

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/xmind.md

Example of opening an existing XMind file (creates a new one if absent) and printing the primary sheet's title.

```python
import xmind

workbook = xmind.load("/tmp/plan.xmind")
sheet = workbook.getPrimarySheet()
print sheet.getTitle()
```

--------------------------------

### Element usage example

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Shows how to create a custom Element subclass, set an attribute, set text content, and retrieve it. The output is 'Hello'.

```python
from xmind.core import Element

class Topic(Element):
    TAG_NAME = "topic"

t = Topic()                     # builds a <topic/> DOM element
t.setAttribute("id", "abc-123")
t.setTextContent("Hello")
print t.getTextContent()        # Hello
```

--------------------------------

### Decorator usage examples

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/utils.md

Usage examples for the prevent and check decorators. Shows that prevent swallows exceptions and check returns None when the attribute is missing.

```python
from xmind.utils import prevent, check

@prevent
def maybe_fail():
    raise Exception("boom")
print maybe_fail()                                  # None — exception swallowed

class Holder(object):
    def __init__(self):
        self.value = 1

    @check("value")
    def read_value(self):
        return self.value

print Holder().read_value()                         # 1
print Holder.__new__(Holder).read_value()           # None — no 'value' attr
```

--------------------------------

### Basic usage of WorkbookLoader

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/loader.md

Basic usage example: loads a .xmind file and prints the title of the primary sheet.

```python
from xmind.core.loader import WorkbookLoader

loader = WorkbookLoader("plan.xmind")
workbook = loader.get_workbook()
print workbook.getPrimarySheet().getTitle()
```

--------------------------------

### Error handling and save with xmind.load

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/xmind.md

Example showing error handling for a wrong extension and saving the workbook to its own path.

```python
import xmind

try:
    workbook = xmind.load("/tmp/map.txt")   # wrong extension
except Exception as e:
    print "load failed:", e

workbook = xmind.load("/tmp/map.xmind")
xmind.save(workbook)                        # saves to the workbook's own path
```

--------------------------------

### Error handling for unsupported note formats

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/notes.md

Demonstrates that calling getContent with an unsupported format raises an exception, and that even the string 'plain' fails because it is not the exact constant object. The example shows the error messages printed.

```python
try:
    notes.getContent("html")            # format != const.PLAIN_FORMAT_NOTE
except Exception as e:
    print e                             # 'Only support plain text notes right now'

# even the same *value* fails if it is not the exact constant object
try:
    notes.getContent("plain")           # str literal is not the const object
except Exception as e:
    print "raises:", e
```

--------------------------------

### xmind.load(path) internal implementation

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/xmind.md

Internal code showing how `load` uses `WorkbookLoader` to get the workbook.

```python
loader = WorkbookLoader(path)
return loader.get_workbook()
```

--------------------------------

### Constructing and setting a TitleElement

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/title.md

Example of manually creating a detached TitleElement, setting its content, and appending it to a sheet.

```python
from xmind import load
from xmind.core.title import TitleElement

workbook = load("plan.xmind")
sheet = workbook.getPrimarySheet()
title = TitleElement(None, workbook)   # a detached <title/>
title.setTextContent("Hello XMind")
sheet.appendChild(title)

print sheet.getTitle()                  # 'Hello XMind'
```

--------------------------------

### Build a topic tree with xmind SDK

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/topic.md

Build a topic tree: load a workbook, get the primary sheet and root topic, then add a sub-topic with title, position, plain notes, URL and file hyperlinks, and a marker. Shows how to read back sub-topics, position, and marker ID.

```python
import xmind

workbook = xmind.load("plan.xmind")
sheet = workbook.getPrimarySheet()
root = sheet.getRootTopic()
root.setTitle("Roadmap")

sub = root.addSubTopic()            # created automatically
sub.setTitle("Phase 1")
sub.setPosition(120, 40)
sub.setPlainNotes("kickoff in January")
sub.setURLHyperlink("https://xmind.net")
sub.setFileHyperlink("logo.jpeg")
sub.addMarker("priority-1")

print root.getSubTopics()           # [<TopicElement ...>]
print sub.getPosition()             # (120, 40)
print sub.getMarkers()[0].getMarkerId()   # <MarkerId: priority-1>
```

--------------------------------

### Error handling with WorkbookLoader

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/loader.md

Error handling example: only the extension check raises an exception; missing files or other failures produce an empty workbook silently.

```python
from xmind.core.loader import WorkbookLoader

try:
    loader = WorkbookLoader("plan.txt")
except Exception as e:
    print "extension error:", e

loader = WorkbookLoader("does-not-exist.xmind")   # no exception
wb = loader.get_workbook()                        # empty workbook document
```

--------------------------------

### Create Document and set version

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Creates an empty Document and attempts to set its version. Because the document has no documentElement yet, setVersion is a no-op.

```python
from xmind.core import Document

doc = Document()                 # empty document
doc.setVersion("2.0")            # no documentElement yet, so no-op
```

--------------------------------

### MarkerRefElement

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/markerref.md

Documentation for the MarkerRefElement class, including its constructor and methods for getting and setting marker identifiers.

```APIDOC
## Class `MarkerRefElement`

### Description
Represents a single marker reference within a topic. Provides methods to get and set the marker identifier.

### Constructor
`def __init__(self, node=None, ownerWorkbook=None):`

### Methods

#### `getMarkerId()`

Returns a `MarkerId` object built from the `marker-id` attribute.

#### `setMarkerId(val)`

Sets the `marker-id` attribute to the string representation of `val`.

### Example

```python
import xmind
from xmind.core.markerref import MarkerId

workbook = xmind.load("plan.xmind")
root = workbook.getPrimarySheet().getRootTopic()

t = root.addSubTopic(); t.setTitle("Do it")
t.addMarker(MarkerId.priority1)          # MarkerId instance
t.addMarker("flag-red")                  # plain string is wrapped

for ref in t.getMarkers():               # list of MarkerRefElement
    mid = ref.getMarkerId()
    print str(mid), mid.getFamilly()     # 'priority-1' 'priority', etc.
```
```

--------------------------------

### Node.__init__(node)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Initializes a Node instance with the given underlying DOM node.

```APIDOC
## Node.__init__(node)

### Description
Initializes a Node instance with the given underlying DOM node.

### Method
Constructor

### Parameters
- **node** (xml.dom.Node) - Required - Underlying DOM node to wrap

### Request Example
```python
node = Node(dom_node)
```

### Response
No return value.
```

--------------------------------

### WorkbookMixinElement.__init__(node=None, ownerWorkbook=None)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/mixin.md

Constructor for WorkbookMixinElement. Initializes the element with an optional existing DOM node and owner workbook, and registers the owner workbook.

```APIDOC
## WorkbookMixinElement.__init__(node=None, ownerWorkbook=None)

### Description
Constructor for WorkbookMixinElement. Initializes the element with an optional existing DOM node and owner workbook, and registers the owner workbook.

### Method
Constructor

### Signature
```python
def __init__(self, node=None, ownerWorkbook=None):
    super(WorkbookMixinElement, self).__init__(node)
    self._owner_workbook = ownerWorkbook
    self.registOwnerWorkbook()
```

### Parameters
- **node** (xml.dom.Element) - Optional - Existing DOM element to wrap; when omitted, a new element is created from `TAG_NAME`.
- **ownerWorkbook** (WorkbookDocument) - Optional - The workbook document this element belongs to.

### Notes
- The constructor always calls `registOwnerWorkbook()`, which forwards the workbook's DOM document to `Element.setOwnerDocument`.
- Passing an orphan node with an `ownerWorkbook` still rewires the DOM owner.

```

--------------------------------

### WorkbookLoader.__init__ constructor

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/loader.md

Constructor for WorkbookLoader. Resolves the path, checks the .xmind extension, and attempts to parse content.xml from the ZIP archive. All exceptions inside the try block are swallowed, leaving _content_stream as None.

```python
def __init__(self, path):
    """ Load XMind workbook from given path

    :param path:    path to XMind file. If not an existing file,
                    will not raise an exception.

    """
    super(WorkbookLoader, self).__init__()
    self._input_source = utils.get_abs_path(path)

    file_name, ext = utils.split_ext(self._input_source)

    if ext != const.XMIND_EXT:
        raise Exception("The XMind filename is missing the '%s' extension!" % const.XMIND_EXT)

    # Input Stream
    self._content_stream = None

    try:
        with utils.extract(self._input_source) as input_stream:
            for stream in input_stream.namelist():
                if stream == const.CONTENT_XML:
                    self._content_stream = utils.parse_dom_string(
                        input_stream.read(stream))
    except:
        pass
```

--------------------------------

### Workbook Basic Workflow

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/workbook.md

Demonstrates loading a workbook, modifying topics, managing sheets, and saving the workbook to a specific path.

```python
import xmind
from xmind.core.topic import TopicElement

workbook = xmind.load("plan.xmind")

sheet = workbook.getPrimarySheet()
root = sheet.getRootTopic()
root.setTitle("Plan")

sub = TopicElement(ownerWorkbook=workbook)   # or workbook.createTopic()
root.addSubTopic(sub)
sub.setTitle("Phase 1")

s2 = workbook.createSheet()
s2.setTitle("Second sheet")
workbook.addSheet(s2)                         # insert at end
workbook.moveSheet(1, 0)                      # move sheet 1 to front

workbook.set_path("/tmp/plan.xmind")
xmind.save(workbook)                          # uses the stored path
```

--------------------------------

### Save to workbook's own path with error handling

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/xmind.md

Example of saving to the path stored on the workbook, with error handling for when no path is set.

```python
import xmind

workbook = xmind.load("/tmp/plan.xmind")

try:
    xmind.save(workbook)                 # uses workbook.get_path()
except Exception as e:
    print "save failed:", e              # e.g. workbook has no path set
```

--------------------------------

### Basic usage of xmind.save with explicit path

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/xmind.md

Example of saving a workbook to an explicit path after modifying the primary sheet's title.

```python
import xmind

workbook = xmind.load("/tmp/plan.xmind")
workbook.getPrimarySheet().setTitle("Updated plan")
xmind.save(workbook, "/tmp/plan-v2.xmind")
```

--------------------------------

### NotesElement.__init__

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/notes.md

Creates a NotesElement instance wrapping an existing <notes> DOM element or creating a new one, with an optional owner topic.

```APIDOC
## NotesElement.__init__

### Description
Initializes a NotesElement instance. If a node is provided, it wraps that existing <notes> DOM element; otherwise, a new <notes> element is created. The ownerTopic is used for delegation to the owner sheet/workbook.

### Method
Constructor

### Signature
```python
NotesElement(node=None, ownerTopic=None)
```

### Parameters
- **node** (xml.dom.Element) - Optional - Existing <notes> DOM element to wrap; when omitted a new <notes> element is created.
- **ownerTopic** (TopicElement) - Optional - Topic owning these notes (required for getOwnerSheet/getOwnerWorkbook delegation).
```

--------------------------------

### Document.__init__(node=None)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Initializes a new Document instance, optionally wrapping an existing xml.dom.Document. If no node is provided, a new document is created.

```APIDOC
## Document.__init__(node=None)

### Description
Initializes a new Document instance. If `node` is provided, it wraps that existing DOM document; otherwise, a new document is created.

### Method
Constructor

### Signature
```python
def __init__(self, node=None):
    self._node = node or self._documentConstructor()
```

### Parameters
- **node** (xml.dom.Document) - Optional - Existing DOM document to wrap. Defaults to `None` (new document created).

### Example
```python
from xmind.core import Document

doc = Document()  # empty document
```
```

--------------------------------

### Element attribute error handling

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Error handling example: getAttribute returns None for missing keys, and setAttribute with None removes the attribute.

```python
t = Topic()
assert t.getAttribute("missing") is None
t.setAttribute("id", None)      # removes the attribute
```

--------------------------------

### Typical usage of PositionElement

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/position.md

Demonstrates loading a workbook, creating a PositionElement, setting coordinates, printing them, and attaching the element to a root topic. Note that getX/getY return attribute strings.

```python
from xmind import load
from xmind.core.position import PositionElement

workbook = load("plan.xmind")
pos = PositionElement(None, workbook)

pos.setX(100)
pos.setY(50)
print pos.getX(), pos.getY()          # '100' '50'  (attribute strings)

# attach to a topic directly
topic = workbook.getPrimarySheet().getRootTopic()
topic.appendChild(pos)
```

--------------------------------

### Load or create an XMind workbook

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/README.md

Loads an existing XMind file or creates a new one at the given path. The path must end with the .xmind extension.

```python
import xmind
workbook = xmind.load(/path/to/file/)  # Requires '.xmind' extension
```

--------------------------------

### Element.__init__(node=None)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Initializes an Element instance, optionally wrapping an existing DOM element. If no node is provided, a new element is created based on the class's TAG_NAME.

```APIDOC
## Element.__init__(node=None)

### Description
Initializes an Element instance, optionally wrapping an existing DOM element. If no node is provided, a new element is created based on the class's TAG_NAME.

### Method
Constructor

### Signature
```python
def __init__(self, node=None):
```

### Parameters
- **node** (xml.dom.Element) - Optional - Existing DOM element to wrap; when omitted a new element is built from TAG_NAME.

### Example
```python
from xmind.core import Element

class Topic(Element):
    TAG_NAME = "topic"

t = Topic()  # builds a <topic/> DOM element
```
```

--------------------------------

### Round-trip through TopicElement

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/position.md

Demonstrates the supported workflow of setting and getting a position on a root topic, and removing it. getPosition returns a tuple of ints, or None after removal.

```python
root = workbook.getPrimarySheet().getRootTopic()
root.setPosition(120, 40)
print root.getPosition()                # (120, 40)  — tuple of ints
root.removePosition()
print root.getPosition()                # None
```

--------------------------------

### WorkbookDocument.__init__(node=None, path=None)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/workbook.md

Constructs a new WorkbookDocument object. If a DOM node is provided, it parses it; otherwise, a new DOM document is created. The path parameter sets where the workbook will be saved.

```APIDOC
## WorkbookDocument.__init__(node=None, path=None)

### Description
Constructs a new WorkbookDocument object. If a DOM node is provided, it parses it; otherwise, a new DOM document is created. The path parameter sets where the workbook will be saved.

### Parameters
- **node** (xml.dom.Document) - Optional - Existing DOM document (parsed content.xml). When None, a fresh DOM document is created.
- **path** (str) - Optional - Path the workbook will be saved to (used when xmind.save(workbook) is called without a path).

### Behavior
Locates or creates the single WorkbookElement root and calls setVersion(const.VERSION). A fresh doc gets version="2.0", while a loaded doc keeps an existing version attribute.
```

--------------------------------

### Create and attach relationships via sheet

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/relationship.md

Shows typical usage: load a workbook, get the primary sheet and root topic, create subtopics, create a relationship with a title, and add it to the sheet. Then prints the endpoint IDs and title.

```python
import xmind

workbook = xmind.load("plan.xmind")
sheet = workbook.getPrimarySheet()
root = sheet.getRootTopic()

t1 = root.addSubTopic(); t1.setTitle("A")
t2 = root.addSubTopic(); t2.setTitle("B")

rel = sheet.createRelationship(t1.getID(), t2.getID(), "links A to B")
sheet.addRelationship(rel)

print rel.getEnd1ID(), rel.getEnd2ID()      # the two topic ids
print rel.getTitle()                        # 'links A to B'
```

--------------------------------

### WorkbookDocument Constructor

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/workbook.md

Initializes a new WorkbookDocument, creating a root WorkbookElement if one does not exist and setting the document version.

```python
def __init__(self, node=None, path=None):
    """
    Construct new `WorkbookDocument` object

    :param node:    pass DOM node object and parse as `WorkbookDocument`
                    object. if node not given then created new one.

    :param path:    set workbook will to be placed.

    """
    super(WorkbookDocument, self).__init__(node)
    self._path = path
    # Initialize WorkbookDocument to make sure that contains
    # WorkbookElement as root.
    _workbook_element = self.getFirstChildNodeByTagName(
        const.TAG_WORKBOOK)

    self._workbook_element = WorkbookElement(
        _workbook_element,
        self)

    if not _workbook_element:
        self.appendChild(self._workbook_element)

    self.setVersion(const.VERSION)
```

--------------------------------

### WorkbookElement.__init__(node=None, ownerWorkbook=None)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/workbook.md

Initializes a WorkbookElement, optionally wrapping an existing DOM element and setting the owner workbook. It declares XML namespace attributes and ensures at least one sheet exists.

```APIDOC
## WorkbookElement.__init__(node=None, ownerWorkbook=None)

### Description
Initializes a WorkbookElement, optionally wrapping an existing DOM element and setting the owner workbook. It declares XML namespace attributes and ensures at least one sheet exists.

### Method
Constructor

### Parameters
- **node** (xml.dom.Element) - Optional - Existing xmap-content DOM element to wrap. Default: None.
- **ownerWorkbook** (WorkbookDocument) - Optional - Owning workbook. Default: None.

### Behavior
- Declares namespace attributes: xmlns, xmlns:fo, xmlns:xhtml, xmlns:xlink, xmlns:svg.
- If no sheets exist, creates and adds a new sheet.

```

--------------------------------

### WorkbookElement.__init__ constructor

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/workbook.md

Initializes a WorkbookElement with default namespace attributes and ensures at least one sheet is present. If no sheets exist, a new sheet is created and added.

```python
def __init__(self, node=None, ownerWorkbook=None):
    super(WorkbookElement, self).__init__(node, ownerWorkbook)

    # Initialize WorkbookElement with default attribute
    namespace = (const.NAMESPACE, const.XMAP)
    attrs = [const.NS_FO, const.NS_XHTML, const.NS_XLINK, const.NS_SVG]

    for attr in attrs:
        self.setAttributeNS(namespace, attr)

    # Initialize WorkbookElement need contains at least one SheetElement
    if not self.getSheets():
        sheet = self.createSheet()
        self.addSheet(sheet)
```

--------------------------------

### Add and Retrieve Markers

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/markerref.md

Demonstrates adding markers to a topic using MarkerId instances or strings, and iterating through the resulting MarkerRefElement objects.

```python
import xmind
from xmind.core.markerref import MarkerId

workbook = xmind.load("plan.xmind")
root = workbook.getPrimarySheet().getRootTopic()

t = root.addSubTopic(); t.setTitle("Do it")
t.addMarker(MarkerId.priority1)          # MarkerId instance
t.addMarker("flag-red")                  # plain string is wrapped

for ref in t.getMarkers():               # list of MarkerRefElement
    mid = ref.getMarkerId()
    print str(mid), mid.getFamilly()     # 'priority-1' 'priority', etc.
```

--------------------------------

### Manage sheet lifecycle

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/sheet.md

Demonstrates loading a workbook, modifying the primary sheet, and creating/adding a new sheet to the workbook.

```python
import xmind

workbook = xmind.load("plan.xmind")

s1 = workbook.getPrimarySheet()
s1.setTitle("first sheet")
print s1.getTitle()

s2 = workbook.createSheet()      # not yet attached
s2.setTitle("second sheet")
workbook.addSheet(s2)
root = s2.getRootTopic()
root.setTitle("root node")
```

--------------------------------

### Node.getPrefix(qualifiedName)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Returns everything through the first ':' (inclusive) of qualifiedName, or None when there is no ':'.

```APIDOC
## Node.getPrefix(qualifiedName)

### Description
Returns everything through the first ':' (inclusive) of qualifiedName, or None when there is no ':'.

### Method
getPrefix

### Parameters
- **qualifiedName** (str) - Required - Name that may contain a prefix:localName separator

### Response
- **str or None** - The prefix including ':', or None if no ':'
```

--------------------------------

### WorkbookLoader(path)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/loader.md

Constructor that initializes a WorkbookLoader instance with a path to an XMind file. It validates the file extension and attempts to parse the content.xml from the ZIP archive.

```APIDOC
## WorkbookLoader(path)

### Description
Initializes a WorkbookLoader instance with the given path to an XMind file. The constructor resolves the absolute path, checks the file extension, and attempts to parse the content.xml from the ZIP archive.

### Method
Constructor

### Signature
```python
def __init__(self, path):
```

### Parameters
- **path** (str) - Required - Path to a `.xmind` file. Resolved with `utils.get_abs_path` (tilde `~` expansion and absolute-path resolution). Missing files do not raise an exception.

### Behavior
1. Resolves the absolute path and checks the extension against `const.XMIND_EXT` (`".xmind"`).
2. Opens the path as a read-only ZIP archive (`utils.extract` → `zipfile.ZipFile(path, "r")`).
3. Scans the archive's `namelist()` for `content.xml` (`const.CONTENT_XML`) and parses that entry with `utils.parse_dom_string` (→ `xml.dom.minidom.parseString`), storing the resulting DOM in `_content_stream`.
4. **All** exceptions inside the `try` block (missing file, corrupt ZIP, missing `content.xml`, DOM parse errors) are swallowed by `except: pass`; `_content_stream` stays `None`.

### Throws
- **Exception** - `"The XMind filename is missing the '.xmind' extension!"` — path extension is not `.xmind`.

### Example
```python
from xmind.core.loader import WorkbookLoader

loader = WorkbookLoader("plan.xmind")
```
```

--------------------------------

### Document.__init__ constructor

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Constructor for the Document class. If no node is provided, a new DOM document is created via _documentConstructor().

```python
def __init__(self, node=None):
    self._node = node or self._documentConstructor()
```

--------------------------------

### xmind.main()

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/xmind.md

No-op function defined for the `if __name__ == '__main__':` guard; it performs no work.

```APIDOC
## xmind.main()

### Description
No-op function defined for the `if __name__ == '__main__':` guard; it performs no work.

### Method
Function

### Signature
```python
def main():
    pass
```

### Parameters
None

### Return
None
```

--------------------------------

### Node.insertBefore(new_node, ref_node)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Inserts new_node's implementation before ref_node's implementation. ref_node must already be a child of this node.

```APIDOC
## Node.insertBefore(new_node, ref_node)

### Description
Inserts new_node's implementation before ref_node's implementation. ref_node must already be a child of this node (DOM contract). Returns the result of the DOM insertBefore.

### Method
insertBefore

### Parameters
- **new_node** (Node) - Required - Node to insert
- **ref_node** (Node) - Required - Existing child that new_node is inserted before

### Response
- **object** - Result of the DOM insertBefore
```

--------------------------------

### getContent method

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/notes.md

Retrieves the notes content in the specified format. Only plain text format is supported; any other format raises an Exception. Returns None if no content is found for the given format.

```python
def getContent(self, format=const.PLAIN_FORMAT_NOTE):
    """ Get notes content

    :parma format:  specified returned content format, plain text
                    by default.
    """

    content = self.getFirstChildNodeByTagName(format)

    if not content:
        return

    if format is const.PLAIN_FORMAT_NOTE:
        content = PlainNotes(node=content, ownerTopic=self.getOwnerTopic())
    else:
        raise Exception("Only support plain text notes right now")

    return content.getTextContent()
```

--------------------------------

### Basic utils usage

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/utils.md

Basic usage of xmind.utils functions: get_abs_path, generate_id, readable_time, get_current_time, and extract. Shows expected outputs in comments.

```python
from xmind import utils

print utils.get_abs_path("plan.xmind")              # /abs/path/to/plan.xmind
print utils.generate_id()                           # 26-hex-char id string
print utils.readable_time(utils.get_current_time()) # 'MM/DD/YYYY HH:MM:SS' UTC

with utils.extract("plan.xmind") as archive:        # zipfile.ZipFile
    print archive.namelist()
```

--------------------------------

### save(path=None) method implementation

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/saver.md

Saves the workbook to a .xmind file, resolving the destination path, validating the extension, compressing content into a ZIP archive, and raising exceptions for missing path or wrong extension.

```python
def save(self, path=None):
    """
    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 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("XMind filenames require a '.xmind' extension")

    content = self._get_content()

    f=utils.compress(path)
    f.write(content, const.CONTENT_XML)

```

--------------------------------

### TopicsElement

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/topic.md

Documentation for the TopicsElement class, including its constructor and methods for accessing sub-topics.

```APIDOC
## Class `TopicsElement`

### Description
Represents a `<topics>` element in an XMind workbook. Provides access to sub-topics and their type.

### Constructor
`def __init__(self, node=None, ownerWorkbook=None)`

### Methods

#### `getType()`

- **Signature**: `def getType(self)`
- **Description**: Returns the `type` attribute of the topics element ("root" or "attached").
- **Returns**: `str` - The type attribute.

#### `getSubTopics()`

- **Signature**: `def getSubTopics(self)`
- **Description**: Returns a list of `TopicElement` objects for each `<topic>` child.
- **Returns**: `list` of `TopicElement`.

#### `getSubTopicByIndex(index)`

- **Signature**: `def getSubTopicByIndex(self, index)`
- **Description**: Returns the sub-topic at the given index. If the index is out of range, returns the entire list of sub-topics.
- **Parameters**:
  - `index` (int) - Required - The index of the sub-topic to retrieve.
- **Returns**: `TopicElement` or `list` of `TopicElement`.
```

--------------------------------

### TitleElement.__init__

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/title.md

Constructor for TitleElement. Creates a new TitleElement instance, optionally wrapping an existing <title> DOM element and specifying the owning workbook.

```APIDOC
## TitleElement.__init__

### Description
Initializes a new TitleElement instance. If a node is provided, it wraps the existing <title> DOM element; otherwise, a new <title> element is created.

### Method
Constructor

### Signature
```python
TitleElement(node=None, ownerWorkbook=None)
```

### Parameters
- **node** (xml.dom.Element) - Optional - Existing <title> DOM element to wrap; when omitted a new <title> element is created.
- **ownerWorkbook** (WorkbookDocument) - Optional - Owning workbook.

### Usage Example
```python
from xmind.core.title import TitleElement

workbook = load("plan.xmind")
title = TitleElement(None, workbook)   # a detached <title/>
```
```

--------------------------------

### Catching load and save errors

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/errors.md

Demonstrates catching exceptions during workbook loading and saving, specifically highlighting extension validation errors.

```python
import xmind

# Extension validation on load
try:
    workbook = xmind.load("map.txt")
except Exception as e:
    print "load error:", e          # 'The XMind filename is missing ...'

try:
    workbook = xmind.load("map.xmind")
    xmind.save(workbook, "map.txt") # extension check on save
except Exception as e:
    print "save error:", e          # "XMind filenames require a '.xmind' extension"
```

--------------------------------

### xmind.main() signature

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/xmind.md

No-op function defined for the `if __name__ == '__main__':` guard; it performs no work.

```python
def main():
    pass
```

--------------------------------

### Basic usage with WorkbookSaver

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/saver.md

Loads a workbook from 'plan.xmind' and saves a copy as 'copy.xmind' using WorkbookSaver. This shows the typical workflow of creating a saver and writing the workbook to a new file.

```python
from xmind.core.saver import WorkbookSaver
from xmind.core.loader import WorkbookLoader

wb = WorkbookLoader("plan.xmind").get_workbook()
Saver = WorkbookSaver(wb)
Saver.save("copy.xmind")

```

--------------------------------

### xmind.load(path) signature

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/xmind.md

Function signature for loading an XMind workbook from a given path. If the file does not exist, a new workbook is created.

```python
def load(path):
    """ Load XMind workbook from given path. If file no
    exist on given path then created new one.

    """
```

--------------------------------

### get_workbook()

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/loader.md

Parses the XMind file into a WorkbookDocument object and returns it. Uses the content stream and input source set by the constructor.

```APIDOC
## get_workbook()

### Description
Parses the XMind file into a `WorkbookDocument` object and returns it. Uses the `_content_stream` and `_input_source` set by the constructor.

### Method
Instance Method

### Signature
```python
def get_workbook(self):
```

### Parameters
(none)

### Return Value
- **WorkbookDocument** - Wraps the parsed DOM (or a fresh empty document when `_content_stream` is `None`). The `path` is passed through so `WorkbookDocument.get_path()` returns it.

### Example
```python
from xmind.core.loader import WorkbookLoader

loader = WorkbookLoader("plan.xmind")
workbook = loader.get_workbook()
print workbook.getPrimarySheet().getTitle()
```
```

--------------------------------

### TopicMixinElement constructor

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/mixin.md

Constructor for TopicMixinElement, a base class for NotesElement and its content children. It wraps an existing DOM element and stores the owning topic.

```python
class TopicMixinElement(Element):
    def __init__(self, node, ownerTopic):
        super(TopicMixinElement, self).__init__(node)
        self._owner_topic = ownerTopic
```

--------------------------------

### MarkerId.__init__(name)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/markerref.md

Constructs a MarkerId instance representing a marker identifier with a name string, such as "priority-1".

```APIDOC
## MarkerId.__init__(name)

### Description
Creates a new MarkerId instance with the given marker name string.

### Parameters
- **name** (str) - Required - The marker id string, e.g. `"priority-1"`.

### Returns
None.

### Example
```python
marker = MarkerId("priority-1")
```
```

--------------------------------

### Create and remove relationships

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/sheet.md

Shows how to create a relationship between two topics using their IDs and how to remove that relationship from the sheet.

```python
import xmind

workbook = xmind.load("plan.xmind")
sheet = workbook.getPrimarySheet()
root = sheet.getRootTopic()

t1 = root.addSubTopic()
t2 = root.addSubTopic()
t1.setTitle("A")
t2.setTitle("B")

rel = sheet.createRelationship(t1.getID(), t2.getID(), "linked")
sheet.addRelationship(rel)

# later, remove it again
sheet.removeRelationship(rel)
```

--------------------------------

### SheetElement.__init__(node=None, ownerWorkbook=None)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/sheet.md

Initializes a SheetElement wrapping an existing <sheet> DOM element or creating a new one. Adds an id attribute if missing and ensures a root topic exists.

```APIDOC
## SheetElement.__init__(node=None, ownerWorkbook=None)

### Description
Initializes a SheetElement. If a node is provided, it wraps the existing <sheet> DOM element; otherwise, a new element is created. The constructor adds an id attribute if missing and guarantees a root topic exists.

### Method
Constructor

### Signature
```python
def __init__(self, node=None, ownerWorkbook=None):
```

### Parameters
- **node** (xml.dom.Element) - Optional - Existing <sheet> DOM element to wrap.
- **ownerWorkbook** (WorkbookDocument) - Optional - Owning workbook.

### Behavior
- Adds an `id` attribute if missing.
- Ensures a root topic exists via `_get_root_topic()`.
```

--------------------------------

### TopicElement __init__ method

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/topic.md

Constructor for TopicElement. Adds an id attribute when missing. A lone TopicElement has no owner workbook, so sheet/workbook lookups return None until attached.

```python
def __init__(self, node=None, ownerWorkbook=None):
    super(TopicElement, self).__init__(node, ownerWorkbook)

    self.addIdAttribute(const.ATTR_ID)
```

--------------------------------

### xmind.load(path)

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/xmind.md

Loads an XMind workbook from the given path. If the file does not exist, a new workbook is created. Returns a WorkbookDocument object.

```APIDOC
## xmind.load(path)

### Description
Loads an XMind workbook from the given path. If the file does not exist, a new workbook is created.

### Method
Function

### Signature
```python
def load(path):
```

### Parameters
- **path** (str) - Required - Path to the XMind file. Must end with `.xmind`. If the file does not exist, a new workbook is created.

### Return
`WorkbookDocument` - A parsed or freshly constructed workbook document.

### Throws
- `Exception` - If the path extension is not `.xmind`.
- (silent) - Any ZIP/DOM parsing failure is swallowed; a fresh empty workbook is returned instead.

### Example
```python
import xmind

workbook = xmind.load("/tmp/plan.xmind")
sheet = workbook.getPrimarySheet()
print sheet.getTitle()
```
```

--------------------------------

### create_document()

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/core.md

Creates a new, empty DOM document object.

```APIDOC
## create_document()

### Description
Creates a new, empty DOM document object.

### Method
Function call

### Signature
```python
def create_document():
    """:cls: ``xml.dom.Document`` object constructor
    """
    return DOM.Document()
```

### Parameters
None

### Returns
- `xml.dom.minidom.Document` — a new, empty DOM document

### Example
```python
from xmind.core import create_document

doc = create_document()
```
```

--------------------------------

### Error handling when saving without a path

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/saver.md

Shows how to handle the Exception raised when a workbook has no path and no explicit destination is given. Also demonstrates that providing a path resolves the issue.

```python
from xmind.core.saver import WorkbookSaver
from xmind.core.workbook import WorkbookDocument

orphan = WorkbookDocument(None, None)    # path is None

try:
    WorkbookSaver(orphan).save()
except Exception as e:
    print "save requires a path:", e

# providing the path solves it
WorkbookSaver(orphan).save("/tmp/orphan.xmind")

```

--------------------------------

### PlainNotes

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/notes.md

Class for plain text notes. Constructor accepts content, optional node, and optional ownerTopic. Use setContent to replace the text content.

```APIDOC
## Class `PlainNotes`

### Description
Represents a plain text note. Can be constructed with initial content or an existing DOM element. The note is serialized as `<plain>text</plain>` inside `<notes>`.

### Constructor
```python
PlainNotes(content=None, node=None, ownerTopic=None)
```

#### Parameters
- `content` (str) - Optional - Plain-text body; if provided, sets the text content at construction.
- `node` (xml.dom.Element) - Optional - Existing `<plain>` DOM element to wrap.
- `ownerTopic` (TopicElement) - Optional - Owning topic.

### Method: `setContent`

#### Description
Replaces the text content with the given content.

#### Signature
```python
def setContent(self, content):
```

#### Parameters
- `content` (str) - Required - New plain text content.

### Example Usage
```python
import xmind

workbook = xmind.load("plan.xmind")
root = workbook.getPrimarySheet().getRootTopic()

root.setPlainNotes("notes for this topic (F4 in XMind)")
notes = root.getNotes()                 # NotesElement
print notes.getContent()                # 'notes for this topic (F4 in XMind)'

root.setPlainNotes("updated note")      # replaces the previous <plain> child
print notes.getContent()                # 'updated note'
```

### Error Handling
- Unsupported formats raise an exception: `getContent("html")` raises 'Only support plain text notes right now'.
- Passing a string literal like `"plain"` that is not the exact constant object also raises.
```

--------------------------------

### WorkbookMixinElement constructor

Source: https://github.com/xmindltd/xmind-sdk-python/blob/master/_autodocs/api-reference/mixin.md

Constructor for WorkbookMixinElement. Accepts an optional DOM node and owner workbook. Always calls registOwnerWorkbook() to rewire the DOM owner document.

```python
class WorkbookMixinElement(Element):
    def __init__(self, node=None, ownerWorkbook=None):
        super(WorkbookMixinElement, self).__init__(node)
        self._owner_workbook = ownerWorkbook
        self.registOwnerWorkbook()
```
Tokens:
Raw