### Complete Styling Example in ODFDO

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Style_and_Styling.md

Demonstrates creating a document, defining a custom table cell style with specific formatting, applying it to a header row, and saving the styled document. Ensure the 'odfdo' library is installed.

```python
from odfdo import Document, Paragraph, Table, Row, Cell, Style, create_table_cell_style

# Create document
doc = Document('spreadsheet')

# Get first table
table = doc.body.get_table(0)

# Create header style
header_style = create_table_cell_style(
    'HeaderCell',
    background_color='#4472C4',
    color='#FFFFFF',
    text_align='center',
    border_width='1pt',
    border_line='solid'
)
doc.styles.append(header_style)

# Apply to header row
header_row = table.get_row(0)
for cell in header_row.get_cells():
    cell.style = 'HeaderCell'

doc.save('styled.ods')

```

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

### Install odfdo using pip

Source: https://github.com/jdum/odfdo/blob/main/README.md

Install the odfdo library from PyPI using pip. This is the recommended installation method.

```bash
pip install odfdo
```

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

### Install odfdo from sources

Source: https://github.com/jdum/odfdo/blob/main/README.md

Install the odfdo library from its source code. This requires synchronizing dependencies.

```bash
uv sync
```

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

### Set Media Type Example

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Example demonstrating how to set the MIME type for a file in the manifest. This requires obtaining the manifest object first.

```python
manifest = doc.get_part('manifest')
manifest.set_media_type('/Configurations2/toolpanel.xcs', 'text/xml')
```

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

### Example: Complete Form

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Forms_and_Controls.md

An example demonstrating how to create a document and add various form controls like text input, password fields, checkboxes, and buttons.

```APIDOC
## Example: Complete Form

```python
from odfdo import Document, Form, FormText, FormPassword, FormCheckbox, FormButton

doc = Document('text')

# Create a form
form = Form(name='LoginForm', action='/login')

# Add text input
username = FormText(name='username')
form.append(username)

# Add password field
password = FormPassword(name='password')
form.append(password)

# Add checkbox
remember = FormCheckbox(
    name='remember_me',
    label='Remember me',
    checked=False
)
form.append(remember)

# Add submit button
submit = FormButton(label='Login', button_type='submit')
form.append(submit)

doc.body.append(form)
doc.save('form.odt')
```
```

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

### Install development dependencies and run tests

Source: https://github.com/jdum/odfdo/blob/main/README.md

Install development dependencies for odfdo and run the test suite using pytest. This is useful for verifying the installation or contributing to the project.

```bash
uv sync --dev
uv run pytest -n8
```

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

### Accessing and Iterating Tracked Changes

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Advanced_Features.md

Example demonstrating how to access tracked changes in a document and iterate through them. Requires the `odfdo` library to be installed.

```python
from odfdo import Document

doc = Document('text')

# Access tracked changes
changes = doc.body.get_elements('descendant::text:tracked-changes')
if changes:
    tracked = changes[0]
    all_changes = tracked.get_changes()
    for change in all_changes:
        print(f"Change: {change.tag}")

```

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

### Create and Append Column Example

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Demonstrates how to create a Column instance with a specific width and append it to a table.

```python
from odfdo import Column

col = Column(width='3cm')
table.append(col)
```

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

### Example Usage

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Advanced_Features.md

Demonstrates how to access and iterate through tracked changes in a document.

```APIDOC
### Example

```python
from odfdo import Document

doc = Document('text')

# Access tracked changes
changes = doc.body.get_elements('descendant::text:tracked-changes')
if changes:
    tracked = changes[0]
    all_changes = tracked.get_changes()
    for change in all_changes:
        print(f"Change: {change.tag}")
```
```

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

### Work with Tables in Spreadsheets

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/INDEX.md

This snippet shows how to create a new spreadsheet, access existing tables, get and set cell values, and append new rows with data. The 'odfdo' library must be installed.

```python
from odfdo import Document, Table, Row, Cell

doc = Document('spreadsheet')
table = doc.body.get_table(0)

# Access cells
value = table.get_value('B3')
table.set_value('C4', 42)

# Add rows
row = table.append_row(['Data1', 'Data2', 'Data3'])

doc.save('data.ods')
```

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

### Generate documentation from sources

Source: https://github.com/jdum/odfdo/blob/main/README.md

Install documentation generation dependencies and run the documentation generation script. This process creates the documentation in the ./docs directory.

```bash
uv sync --group doc
uv run python doc_src/generate_doc.py
```

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

### How to apply a style to a paragraph

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Minimal example demonstrating how to add a styled paragraph to an ODF document.

```python
from odfdo import Document, Paragraph, Style

# Define a simple style
my_style = Style(family="paragraph")
my_style.set_style("font-size", "16pt", "color", "navy")

doc = Document()
doc.add_style(my_style)

# Create a paragraph with the defined style
styled_paragraph = Paragraph("This paragraph has a custom style.", style=my_style)
doc.append(styled_paragraph)

doc.save("styled_paragraph.odt")
```

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

### Working with Styles

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/INDEX.md

Explains how to get, create, add, and apply styles to elements within the document.

```APIDOC
## Working with Styles

### Description
Operations for managing and applying styles.

### Examples
```python
# Get style from document
style = doc.styles.get_style('Heading 1', family='paragraph')

# Create and add style
style = Style(name='Custom', family='paragraph')
doc.styles.append(style)

# Apply to element
element.style = 'Custom'
```
```

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

### Add Table to Document

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Minimal example of how to add a table to a text document.

```python
from odfdo import Document, Table

doc = Document(doctype='text')

# Create a table with 2 rows and 2 columns
table = Table.new(rows=2, cols=2)

# Add some data to the table cells
table[0, 0].set_text('Row 1, Col 1')
table[0, 1].set_text('Row 1, Col 2')
table[1, 0].set_text('Row 2, Col 1')
table[1, 1].set_text('Row 2, Col 2')

# Add the table to the document
doc.add_element(table)

doc.save('add_table_example.odt')

```

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

### Create and Save a Complete Form

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Forms_and_Controls.md

Example demonstrating the creation of a login form with text, password, checkbox, and submit button, then saving it to an ODT file.

```python
from odfdo import Document, Form, FormText, FormPassword, FormCheckbox, FormButton

doc = Document('text')

# Create a form
form = Form(name='LoginForm', action='/login')

# Add text input
username = FormText(name='username')
form.append(username)

# Add password field
password = FormPassword(name='password')
form.append(password)

# Add checkbox
remember = FormCheckbox(
    name='remember_me',
    label='Remember me',
    checked=False
)
form.append(remember)

# Add submit button
submit = FormButton(label='Login', button_type='submit')
form.append(submit)

doc.body.append(form)
doc.save('form.odt')
```

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

### creator

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the initial creator/author.

```APIDOC
### creator (read/write)

```python
@property
def creator(self) -> str | None:

@creator.setter
def creator(self, creator: str) -> None:
```

Get or set the initial creator/author.

**Alias:** `author`

**Example:**
```python
doc.metadata.creator = "John Doe"
# or
doc.metadata.author = "John Doe"
```
```

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

### Managing Styles in ODF Documents

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/INDEX.md

Provides examples for retrieving existing styles from a document, creating new styles, and applying them to elements.

```python
# Get style from document
style = doc.styles.get_style('Heading 1', family='paragraph')
```

```python
# Create and add style
style = Style(name='Custom', family='paragraph')
doc.styles.append(style)
```

```python
# Apply to element
element.style = 'Custom'
```

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

### Define Display Name

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Style_and_Styling.md

Get or set the user-visible name for the style.

```python
@property
def display_name(self) -> str | None:

@display_name.setter
def display_name(self, display_name: str) -> None:
```

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

### initial_creator

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the initial creator (should not change).

```APIDOC
### initial_creator (read/write)

```python
@property
def initial_creator(self) -> str | None:

@initial_creator.setter
def initial_creator(self, initial_creator: str) -> None:
```

Get or set the initial creator (should not change).
```

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

### Create a Document with a Footnote

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Advanced_Features.md

Demonstrates how to create a document with a paragraph and an associated footnote using ODFDO. Ensure 'odfdo' is installed.

```python
from odfdo import Document, Paragraph, Note, NoteBody

doc = Document('text')

para = Paragraph('Text with a footnote.')

note = Note()
note_body = NoteBody()
note_body.append(Paragraph('This is the footnote text.'))
note.append(note_body)

para.append(note)
doc.body.append(para)

```

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

### Get All Forms

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Forms_and_Controls.md

Retrieves a list of all forms present in the document.

```python
def get_forms(self) -> list[Form]:
```

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

### Get and Set Cell Value

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Use the `value` property to get or set the cell's value. The type is inferred from the ODF type attribute. Example shows setting an integer and retrieving it.

```python
@property
def value(self) -> str | bool | int | float | Decimal | date | datetime | timedelta | None:

@value.setter
def value(self, value: Any) -> None:
```

```python
cell = Cell(42)
print(cell.value)  # 42
cell.value = 100
print(cell.value)  # 100
```

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

### Configure Table Margins and Position

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Example of configuration of table position in a text document, including size, column width, and styles for table, row, column, and cell.

```python
from odfdo import Document, Table

doc = Document(doctype='text')

# Create a table
table = Table.new(rows=3, cols=3)

# Set table width to 80% of the page width
table.set_width('80%')

# Set column widths
table.set_column_width(col=0, width='5cm')
table.set_column_width(col=1, width='3cm')
table.set_column_width(col=2, width='100pt')

# Add some data
table[0, 0].set_text('Data 1')
table[1, 1].set_text('Data 2')
table[2, 2].set_text('Data 3')

# Add the table to the document
doc.add_element(table)

doc.save('table_position_example.odt')

```

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

### Create DrawImage Element

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Shapes_and_Drawings.md

Example of creating a DrawImage element with a specified image file path. Ensure the image file exists at the provided path.

```python
from odfdo import DrawImage

image = DrawImage('Pictures/photo.jpg')
```

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

### MetaUserDefined Value Type Property

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the data type of the user-defined metadata property's value. Examples include 'string', 'float', 'date', 'boolean'.

```python
@property
def value_type(self) -> str:

@value_type.setter
def value_type(self, value_type: str) -> None:
```

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

### Add Title to Text Document

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Minimal example of how to add a Header of first level to a text document.

```python
from odfdo import Document

doc = Document(doctype='text')

# Add a first-level heading (title)
doc.add_heading('My Document Title', level=1)

# Add some content
doc.add_paragraph('This is the main content of the document.')

doc.save('add_title_example.odt')

```

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

### Get All Document Parts

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Document.md

Retrieve a list of all file names contained within the document's archive.

```python
from odfdo import Document

doc = Document('existing.odt')
all_parts = doc.get_parts()
print(all_parts)  # ['content.xml', 'styles.xml', 'meta.xml', ...]
```

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

### Access Content Part

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Example showing how to access the main content part of an ODF document. This is typically done using the 'get_part' method.

```python
content = doc.get_part('content')
```

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

### Get and Set Cell Formula

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Use the `formula` property to get or set the formula associated with the cell.

```python
@property
def formula(self) -> str | None:

@formula.setter
def formula(self, formula: str | None) -> None:
```

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

### Create Paragraph with Style

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Paragraph_and_Text_Elements.md

Shows how to create a paragraph and apply a specific style, such as 'Heading1', to it.

```python
from odfdo import Paragraph

para = Paragraph("Styled paragraph", style="Heading1")
```

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

### Get and Set Cell Type

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Use the `cell_type` property to get or set the ODF type attribute of the cell.

```python
@property
def cell_type(self) -> str:

@cell_type.setter
def cell_type(self, cell_type: str) -> None:
```

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

### Write Hello World in Spreadsheet Document

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Creates a minimal spreadsheet document with 'Hello World' in the first cell.

```python
from odf.opendocument import OpenDocumentSpreadsheet
from odf.table import Table, TableRow, TableCell

sheet = OpenDocumentSpreadsheet()

table = Table(name="MyTable")
sheet.spreadsheet.addElement(table)

row = TableRow()
table.addElement(row)

cell = TableCell(valuetype="string")
row.addElement(cell)
cell.addElement(P(text="Hello World"))

sheet.save("hello_world.ods")
```

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

### Get and Set Cell Currency

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Use the `currency` property to get or set the currency code for cells of currency type.

```python
@property
def currency(self) -> str | None:

@currency.setter
def currency(self, currency: str) -> None:
```

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

### Write Hello World in Text Document

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Creates a minimal text document containing 'Hello World' in a paragraph.

```python
from odf.opendocument import OpenDocumentText
from odf.text import P

textdoc = OpenDocumentText()
textdoc.text.addElement(P(text="Hello World"))
textdoc.save("hello_world.odt")
```

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

### Get and Set Cell Text

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Use the `text` property to get or set the string representation of the cell's content.

```python
@property
def text(self) -> str:

@text.setter
def text(self, text: str) -> None:
```

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

### Advanced Element Usage Example

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Element_Base_Class.md

Demonstrates creating a complex nested structure with styled spans, inserting elements, traversing children, cloning, and modifying elements within an ODF document.

```python
from odfdo import Document, Paragraph, Span, FIRST_CHILD

doc = Document('text')
body = doc.body

# Create complex nested structure
para = Paragraph()

# Add spans with different styles
para.append(Span("Hello ", style='Bold'))
para.append(Span("world", style='Italic'))

# Insert at beginning
intro = Span("» ", style='Bold')
para.insert(intro, FIRST_CHILD)

# Traverse children
for child in para.children:
    print(f"Child: {child.tag}, Text: {child.text}")

# Clone and modify
clone = para.clone
clone.text = clone.text.replace('world', 'universe')

body.append(para)
body.append(clone)

doc.save('element_demo.odt')
```

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

### Create a 'Hello world' ODT document

Source: https://github.com/jdum/odfdo/blob/main/README.md

Create a new ODF text document and add a simple 'Hello world!' paragraph. The document is then saved as 'hello.odt'.

```python
from odfdo import Document, Paragraph

doc = Document('text')
doc.body.append(Paragraph("Hello world!"))

doc.save("hello.odt")
```

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

### Get or Set Document Language

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Document.md

Get or set the document's language code. Use standard language codes like 'en-US' or 'fr-FR'.

```python
@property
def language(self) -> str:
    """Get or set the document's language code (e.g., 'en-US', 'fr-FR')."""
```

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

### Create Basic Spreadsheet

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Creates a simple spreadsheet with one table, populates it with data, and then strips the table to compute its size.

```python
from odf.opendocument import OpenDocumentSpreadsheet
from odf.table import Table, TableRow, TableCell
from odf.text import P


doc = OpenDocumentSpreadsheet()

table = Table(name="MyTable")
doc.spreadsheet.addElement(table)

row = TableRow()
table.addElement(row)

cell = TableCell(valuetype="string")
row.addElement(cell)
cell.addElement(P(text="Header 1"))

cell = TableCell(valuetype="string")
row.addElement(cell)
cell.addElement(P(text="Header 2"))

row = TableRow()
table.addElement(row)

cell = TableCell(valuetype="string")
row.addElement(cell)
cell.addElement(P(text="Data 1A"))

cell = TableCell(valuetype="string")
row.addElement(cell)
cell.addElement(P(text="Data 1B"))

row = TableRow()
table.addElement(row)

cell = TableCell(valuetype="string")
row.addElement(cell)
cell.addElement(P(text="Data 2A"))

cell = TableCell(valuetype="string")
row.addElement(cell)
cell.addElement(P(text="Data 2B"))

# Strip the table and compute its size
table.strip() # Removes empty rows and columns
print(f"Table size: {len(table.getElementsByType(TableRow))} rows, {len(table.columns)} columns")

doc.save("basic_spreadsheet.ods")

```

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

### Get Element Inner Text

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Element_Base_Class.md

Retrieves all text content within an element, including text from all descendant child elements. Useful for getting the complete textual representation.

```python
para = Paragraph("Hello ")
span = Span("world")
para.append(span)
print(para.inner_text)  # "Hello world"
```

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

### Create New Document from Template

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Document.md

Initialize a new Document instance using a predefined template name, a path to a custom template file, or a file-like object.

```python
from odfdo import Document

doc = Document.new('spreadsheet')
doc2 = Document.new('path/to/template.odt')
```

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

### contributors

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set document contributors.

```APIDOC
### contributors (read/write)

```python
@property
def contributors(self) -> list[str]:

@contributors.setter
def contributors(self, contributors: list[str] | str) -> None:
```

Get or set document contributors.
```

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

### Create Basic Text Document with List

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Constructs a basic text document that includes an unordered list.

```python
from odf.opendocument import OpenDocumentText
from odf.text import P, List, ListLevel, ListHeader, ListItem

txtdoc = OpenDocumentText()

# Add a header
txtdoc.text.addElement(P(text="List Example", headlevel=1))

# Create a list
list_ = List()

# Add list items
list_.addElement(ListItem(text="Item 1"))
list_.addElement(ListItem(text="Item 2"))
list_.addElement(ListItem(text="Item 3"))

txtdoc.text.addElement(list_)

txtdoc.save("list_document.odt")
```

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

### Create a New Text Document

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/INDEX.md

Use this snippet to create a new ODF text document and add a simple paragraph. Ensure the 'odfdo' library is installed.

```python
from odfdo import Document, Paragraph

doc = Document('text')  # Create text document
doc.body.append(Paragraph("Hello world!"))
doc.save("hello.odt")
```

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

### description

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the document description.

```APIDOC
### description (read/write)

```python
@property
def description(self) -> str | None:

@description.setter
def description(self, description: str) -> None:
```

Get or set the document description.
```

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

### Make presentation from images

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Create a presentation where each image is centered on its own page, scaled to fit the available space.

```python
from odfdo import Document

doc = Document()
doc.add_image("image1.png", "image2.png", "image3.png")
doc.save("presentation.odp")
```

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

### subject

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the document subject.

```APIDOC
### subject (read/write)

```python
@property
def subject(self) -> str | None:

@subject.setter
def subject(self, subject: str) -> None:
```

Get or set the document subject.
```

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

### Define a Bookmark

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Paragraph_and_Text_Elements.md

Create bookmarks for navigation using Bookmark, BookmarkStart, and BookmarkEnd classes. Bookmarks can mark specific points or the start/end of a range.

```python
from odfdo import Paragraph, Bookmark, BookmarkStart, BookmarkEnd

para1 = Paragraph("Target position")
para1.append(Bookmark("my_bookmark"))

para2 = Paragraph("Start of range")
para2.append(BookmarkStart("my_range"))

para3 = Paragraph("End of range")
para3.append(BookmarkEnd("my_range"))
```

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

### title

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the document title.

```APIDOC
### title (read/write)

```python
@property
def title(self) -> str | None:

@title.setter
def title(self, title: str) -> None:
```

Get or set the document title.

**Example:**
```python
doc = Document('text')
doc.metadata.title = "My Document"
```
```

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

### Create Protected Section

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Advanced_Features.md

Shows how to create a new section in an ODF document and append content to it. This example creates a section named 'Protected' and adds a paragraph inside it.

```python
from odfdo import Document, Section, Paragraph

doc = Document('text')

# Create a protected section
section = Section(name='Protected')
section.append(Paragraph('This section is protected.'))
doc.body.append(section)
```

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

### generator

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the application that generated the document.

```APIDOC
### generator (read/write)

```python
@property
def generator(self) -> str | None:

@generator.setter
def generator(self, generator: str) -> None:
```

Get or set the application that generated the document.
```

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

### Create Simple Table in Wiki Syntax

Source: https://github.com/jdum/odfdo/blob/main/tests/samples/rst2odt_sample.rst

Define a simple table using `=======`, `-------`, and `|` characters. This syntax is straightforward for basic tabular data.

```wiki
=======  =======  ======
Input 1  Input 2  Output
-------  -------  ------
A        B        A or B
=======
False    False    False
True     False    True
False    True     True
True     True     True
=======
```

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

### ConfigItem Class

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Types_Reference.md

Represents a single configuration item.

```python
class ConfigItem(Element):

```

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

### creation_date

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the document creation date.

```APIDOC
### creation_date (read/write)

```python
@property
def creation_date(self) -> datetime | None:

@creation_date.setter
def creation_date(self, creation_date: datetime | str) -> None:
```

Get or set the document creation date.

**Example:**
```python
from datetime import datetime

doc.metadata.creation_date = datetime.now()
# or
doc.metadata.creation_date = "2024-01-15T10:30:00"
```
```

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

### OfficeSettings

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Types_Reference.md

Settings body (`office:settings`).

```APIDOC
## class OfficeSettings

### Description
Settings body (`office:settings`).

### Module
odfdo.body
```

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

### Create a new Table

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Demonstrates creating a new ODF document and adding a table with specified dimensions to its body.

```python
from odfdo import Document, Table, Row, Cell

doc = Document('spreadsheet')
table = Table("MySheet", width=3, height=2)
doc.body.append(table)

```

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

### Paragraph.style

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Paragraph_and_Text_Elements.md

Get or set the paragraph's style name.

```APIDOC
### style (read/write)

```python
@property
def style(self) -> str | None:

@style.setter
def style(self, style: str) -> None:
```

Get or set the paragraph's style name.
```

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

### Column Width Property

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Gets or sets the width of the table column.

```APIDOC
## Column Width Property

### Description
Get or set the column width.

### Method
width (read/write)

### Parameters
#### Setter Parameters
- **width** (str) - Required - The new width specification for the column (e.g., '2.5cm', '1in').

### Example
```python
# Get width
current_width = col.width

# Set width
col.width = '4cm'
```
```

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

### How to copy some style from another document

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Demonstrates the minimal steps to copy a style from one ODF document to another.

```python
from odfdo import Document

# Load the source document containing the style
source_doc = Document("source_document.odt")

# Load the target document where the style will be copied
target_doc = Document("target_document.odt")

# Get the style (e.g., 'Yellow_20_Highlight') from the source document
style = source_doc.get_style(display_name="Yellow 20 Highlight")

# Copy the style to the target document
target_doc.copy_style(style)

target_doc.save("target_document_with_copied_style.odt")
```

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

### Create Basic Text Document with Annotations

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Creates a text document with paragraphs and headers, and adds annotations. Annotations are typically displayed in a sidebar and not printed.

```python
from odf.opendocument import OpenDocumentText
from odf.text import P, H, Annotation

txtdoc = OpenDocumentText()

txtdoc.text.addElement(H(text="Document with Annotations", level=1))

para1 = P(text="This is the first paragraph.")
annotation1 = Annotation(text="Note: This paragraph needs review.")
para1.addElement(annotation1)
txtdoc.text.addElement(para1)

para2 = P(text="This is the second paragraph.")
txtdoc.text.addElement(para2)

txtdoc.save("document_with_annotations.odt")
```

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

### Create New Text Document

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Document.md

Instantiate a new text document, add content, and save it to a file.

```python
from odfdo import Document, Paragraph

doc = Document('text')
doc.body.append(Paragraph("Hello world!"))
doc.save("hello.odt")
```

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

### Define Style Name

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Style_and_Styling.md

Get or set the internal identifier for a style.

```python
@property
def name(self) -> str:

@name.setter
def name(self, name: str) -> None:
```

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

### Document Constructor

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Document.md

Initializes a new Document instance. It can create a new document from a template, load an existing document from a file path or container, or create an empty document.

```APIDOC
## Document Constructor

### Description
Initializes a new `Document` instance. It can create a new document from a template, load an existing document from a file path or container, or create an empty document.

### Signature
```python
class Document(MDDocument):
    def __init__(
        self,
        target: str | bytes | Path | Container | io.BytesIO | None = "text",
    ) -> None:
```

### Parameters
#### Path Parameters
- **target** (str | bytes | Path | Container | io.BytesIO | None) - Required - The source to create or load the document. Can be a template name ("text", "spreadsheet", "presentation", "drawing"), file path, Container object, file-like object (io.BytesIO), bytes, or None for an empty container.

### Raises
- **TypeError**: If the target type is not recognized.
- **ValueError**: If the container is empty when calling certain methods.

### Examples
**Create a new text document:**
```python
from odfdo import Document, Paragraph

doc = Document('text')
doc.body.append(Paragraph("Hello world!"))
doc.save("hello.odt")
```

**Load an existing document:**
```python
from odfdo import Document

doc = Document('existing_file.ods')
sheet = doc.body.get_table(0)
print(sheet.name)
```

**Create from template:**
```python
from odfdo import Document

# Using default templates
doc = Document('spreadsheet')  # Create new spreadsheet
doc = Document('presentation')  # Create new presentation
doc = Document('drawing')  # Create new drawing

# Using custom template
doc = Document.new('path/to/custom_template.odt')
```
```

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

### Style Management

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Element_Base_Class.md

Allows getting or setting the style name attribute for an element.

```APIDOC
## Style Management

### style (read/write)

```python
@property
def style(self) -> str | None:

@style.setter
def style(self, style: str) -> None:
```

Get or set the style name attribute.

**Example:**
```python
para = Paragraph()
para.style = 'Heading1'
```
```

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

### Create and Style a Rectangle Shape

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Shapes_and_Drawings.md

Demonstrates how to instantiate a RectangleShape and set its dimensions, fill color, stroke color, and stroke width.

```python
from odfdo import RectangleShape

rect = RectangleShape(width='5cm', height='3cm')
rect.fill_color = '#FF0000'
rect.stroke_color = '#000000'
rect.stroke_width = '2pt'
```

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

### keywords

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set document keywords. Can be set as a list or comma-separated string.

```APIDOC
### keywords (read/write)

```python
@property
def keywords(self) -> list[str]:

@keywords.setter
def keywords(self, keywords: list[str] | str) -> None:
```

Get or set document keywords. Can be set as a list or comma-separated string.

**Example:**
```python
doc.metadata.keywords = ['python', 'odf', 'documents']
# or
doc.metadata.keywords = 'python, odf, documents'
```
```

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

### Basic Presentation Hello World

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Inserts 'Hello World' into the middle of the first page of a presentation.

```python
from odf.opendocument import OpenDocumentPresentation
from odf.text import P
from odf.draw import Page, Frame, TextBox

pres = OpenDocumentPresentation()

page = Page()
pres.callout.addElement(page)

frame = Frame(stylename="Standard", anchortype="page")
page.addElement(frame)

textbox = TextBox()
frame.addElement(textbox)

textbox.addElement(P(text="Hello World"))

pres.save("hello_world.odp")
```

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

### Get Form by Name

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Forms_and_Controls.md

Retrieves a specific form from the document using its name.

```python
def get_form(
    self,
    name: str,
) -> Form | None:
```

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

### Create Basic Cells

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Demonstrates the creation of basic table cells with different data types like strings, integers, floats, and booleans.

```python
from odfdo import Cell

cell1 = Cell("Text")
cell2 = Cell(42)
cell3 = Cell(3.14)
cell4 = Cell(True)
```

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

### modification_date

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the document modification date. Automatically updated when document is saved.

```APIDOC
### modification_date (read/write)

```python
@property
def modification_date(self) -> datetime | None:

@modification_date.setter
def modification_date(self, modification_date: datetime | str) -> None:
```

Get or set the document modification date. Automatically updated when document is saved.
```

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

### Create Basic Text Document

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Generates a basic text document with headers and paragraphs.

```python
from odf.opendocument import OpenDocumentText
from odf.text import H, P

txtdoc = OpenDocumentText()

txtdoc.text.addElement(H(text="My Header", level=1))
txtdoc.text.addElement(P(text="This is a paragraph."))

txtdoc.save("basic_text.odt")
```

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

### Paragraph.inner_text

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Paragraph_and_Text_Elements.md

Get the complete text content of the paragraph, including text from all nested elements.

```APIDOC
### inner_text (read-only)

```python
@property
def inner_text(self) -> str:
```

Get the complete text content of the paragraph, including text from all nested elements.

**Returns:** Combined text from the paragraph and all its children.
```

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

### Create Text Document from Plain Text with Layout

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Create a text document with custom styles, applying styles from an XML file or generated ones. Inserts plain text with specific spacing.

```python
from odfdo import Document

doc = Document(doctype='text')

# Example: Remove standard styles (if needed)
# doc.styles.clear_standard_styles()

# Example: Set custom styles (assuming styles.xml exists or styles are generated)
# doc.styles.set_style_from_file('styles.xml')

# Insert plain text with custom spacing
text_content = "This is the first line.\n\tThis line has a tab.\n  This line has spaces."
doc.add_paragraph(text_content)

doc.save('custom_layout_text.odt')

```

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

### Paragraph.text

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Paragraph_and_Text_Elements.md

Get or set the plain text content of a paragraph, excluding any child elements.

```APIDOC
## Paragraph Properties

### text (read/write)

```python
@property
def text(self) -> str:

@text.setter
def text(self, text: str | None) -> None:
```

Get or set the plain text content of the paragraph, excluding any child elements.

**Returns:** String representation of the paragraph's text content, or empty string if no text.

**Example:**
```python
para = Paragraph()
para.text = "New text"
print(para.text)  # "New text"
```
```

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

### Make a presentation from text with different styles

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Generate a presentation where each line of text becomes a slide, with styles changing based on line length.

```python
from odfdo import Document

doc = Document()
with open("text.txt", "r") as f:
    for line in f:
        doc.add_text(line.strip())
doc.save("presentation.odp")
```

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

### Create and Save Basic Paragraph

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Paragraph_and_Text_Elements.md

Demonstrates creating a simple paragraph with text content and appending it to an ODF document before saving.

```python
from odfdo import Document, Paragraph

doc = Document('text')
para = Paragraph("Hello world!")
doc.body.append(para)
doc.save('hello.odt')
```

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

### Define Parent Style

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Style_and_Styling.md

Get or set the name of the parent style from which this style inherits properties.

```python
@property
def parent_style(self) -> str | None:

@parent_style.setter
def parent_style(self, parent_style: str) -> None:
```

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

### Table Constructor

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Table_Row_Cell_Column.md

Initializes a new Table instance. Use the 'name' parameter for table identification and 'width'/'height' for initial dimensions.

```python
def __init__(
    self,
    name: str | None = None,
    width: int | str | None = None,
    height: int | str | None = None,
    protected: bool = False,
    protection_key: str | None = None,
    printable: bool = True,
    print_ranges: list[str] | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:

```

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

### Define Style Family

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Style_and_Styling.md

Get or set the family (e.g., paragraph, character) to which a style belongs.

```python
@property
def family(self) -> str | None:

@family.setter
def family(self, family: str) -> None:
```

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

### Get Pictures from Document

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Retrieves all embedded pictures from an ODF text document (.odt file).

```python
from odfdo import Document

# Load the document
doc = Document("my_document.odt")

# Get all images from the document body
images = doc.body.images

# Process each image (e.g., save them)
for i, img in enumerate(images):
    # The 'img' object is an odfdo.Image element
    # You can access its data or save it to a file
    # For simplicity, let's just print its tag name
    print(f"Found image {i+1}: {img.tag}")
    # To save the image, you would typically access its binary data
    # and write it to a file, e.g., img.save(f"image_{i+1}.png")
```

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

### Create Text Document with Tables

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Build a commercial document with numerical values displayed in both the text and in a table.

```python
from odfdo import Document, Table

doc = Document(doctype='text')

# Add a paragraph
para = doc.add_paragraph('Here is a table with some data:')

# Create a table
table = Table.new(rows=3, cols=3)

# Fill the table with data
table[0, 0].set_text('Header 1')
table[0, 1].set_text('Header 2')
table[0, 2].set_text('Header 3')
table[1, 0].set_text('10')
table[1, 1].set_text('20')
table[1, 2].set_text('30')
table[2, 0].set_text('40')
table[2, 1].set_text('50')
table[2, 2].set_text('60')

# Add the table to the document
doc.add_element(table)

doc.save('document_with_table.odt')

```

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

### Create a LineShape

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Shapes_and_Drawings.md

Instantiate a LineShape. No specific parameters are required for basic creation.

```python
from odfdo import LineShape

line = LineShape()
```

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

### Get Element Attributes

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Element_Base_Class.md

Retrieves all attributes of an element as a dictionary. Useful for inspecting or modifying element metadata.

```python
cell = table.get_cell('A1')
attrs = cell.attributes
print(attrs)  # {'xml:id': '...', 'office:value-type': 'string', ...}
```

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

### Get All Archive Part Paths

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Returns a list of all file paths contained within the ODF archive.

```python
@property
def parts(self) -> list[str]:

```

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

### Create a Basic Drawing

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Shows how to insert graphical elements, specifically a circle and multiple lines forming a fractal pattern, into a text document using odfdo.

```python
from odfdo import Document, Paragraph, Drawing

def fractal_lines(drawing, x, y, length, depth):
    if depth == 0:
        return
    # Draw a line segment
    drawing.add_line(x, y, x + length, y)
    # Recursive calls for fractal pattern
    fractal_lines(drawing, x + length, y, length * 0.8, depth - 1)
    fractal_lines(drawing, x, y + length * 0.2, length * 0.6, depth - 1)

doc = Document()

# Add a paragraph before the drawing
doc.body.append(Paragraph("Here is a drawing:"))

# Create a drawing object
drawing = Drawing()

# Add a circle
drawing.add_circle(50, 50, 20) # x, y, radius

# Add fractal lines
fractal_lines(drawing, 100, 100, 50, 4) # drawing, x, y, length, depth

# Add the drawing to the document body
doc.body.append(drawing)

doc.save("document_with_drawing.odt")
```

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

### Make a Presentation from Pictures

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Creates a new presentation (.odp) file from images found within a text document (.odt). Each image from the source document is placed on a separate frame in the presentation.

```python
from odfdo import Document, Slide, Image

# Load the source text document
source_doc = Document("document_with_images.odt")

# Create a new presentation document
presentation = Document()

# Iterate through images in the source document
for img in source_doc.body.images:
    # Create a new slide for each image
    slide = Slide()
    
    # Create an Image element from the source image data
    # Note: This assumes 'img' is directly usable as an Image source.
    # In practice, you might need to extract image data and create a new Image object.
    slide.append(img)
    
    # Add the slide to the presentation
    presentation.body.append(slide)

# Save the new presentation
presentation.save("presentation_from_images.odp")
```

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

### language

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Metadata_and_Document_Properties.md

Get or set the document language using RFC 3066 format (e.g., 'en-US', 'fr-FR').

```APIDOC
### language (read/write)

```python
@property
def language(self) -> str | None:

@language.setter
def language(self, language: str) -> None:
```

Get or set the document language using RFC 3066 format (e.g., 'en-US', 'fr-FR').

**Example:**
```python
doc.metadata.language = 'en-US'
```
```

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

### Get/Set Form Control Label

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Forms_and_Controls.md

Shows how to get or set the visible text label for a form control.

```python
@property
def label(self) -> str | None:

@label.setter
def label(self, label: str) -> None:
```

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

### Paragraph Constructor

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Paragraph_and_Text_Elements.md

Initializes a Paragraph instance with optional text content, style, and formatting options.

```python
def __init__(
    self,
    text_or_element: str | bytes | Element | None = None,
    style: str | None = None,
    formatted: bool = True,
    **kwargs: Any,
) -> None:
```

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

### Create Spreadsheet with Named Ranges

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Demonstrates creating a spreadsheet with multiple tables and using named ranges to populate cells.

```python
from odf.opendocument import OpenDocumentSpreadsheet
from odf.table import Table, TableRow, TableCell, NamedRanges, NamedRange
from odf.text import P


doc = OpenDocumentSpreadsheet()

# Table 1
table1 = Table(name="Table1")
doc.spreadsheet.addElement(table1)

row = TableRow()
table1.addElement(row)
cell = TableCell(valuetype="string")
row.addElement(cell)
cell.addElement(P(text="Value A"))

# Table 2
table2 = Table(name="Table2")
doc.spreadsheet.addElement(table2)

row = TableRow()
table2.addElement(row)
cell = TableCell(valuetype="string")
row.addElement(cell)
cell.addElement(P(text="Value B"))

# Named Ranges
nr = NamedRanges()
doc.spreadsheet.addElement(nr)

# Define a named range for a cell in Table1
range1 = NamedRange(name="RangeA", table=table1, cellrange="A1")
nr.addElement(range1)

# Define a named range for a cell in Table2
range2 = NamedRange(name="RangeB", table=table2, cellrange="A1")
nr.addElement(range2)

# You can now refer to these named ranges in formulas or other parts of the document.
# For demonstration, we'll just save the document.

doc.save("spreadsheet_with_named_ranges.ods")

```

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

### Create a Complex Drawing

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Shapes_and_Drawings.md

Demonstrates how to create a drawing document with various shapes, an image frame, and save it. Requires importing necessary classes from odfdo.

```python
from odfdo import Document, DrawPage, RectangleShape, CircleShape, LineShape, Frame, DrawImage

doc = Document('drawing')
page = doc.body.get_elements('descendant::draw:page')[0]

# Add a rectangle
rect = RectangleShape(
    x='1cm',
    y='1cm',
    width='5cm',
    height='3cm'
)
rect.fill_color = '#CCCCFF'
rect.stroke_color = '#0000FF'
page.append(rect)

# Add a circle
circle = CircleShape(
    x='7cm',
    y='1cm',
    width='2cm',
    height='2cm'
)
circle.fill_color = '#FFCCCC'
page.append(circle)

# Add a line
line = LineShape()
page.append(line)

# Add an image frame
frame = Frame(
    name='Image1',
    x='1cm',
    y='5cm',
    width='8cm',
    height='6cm'
)
image = DrawImage('path/to/image.jpg')
frame.append(image)
page.append(frame)

doc.save('drawing.odg')

```

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

### Get Element Attribute (Python)

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Element_Base_Class.md

Retrieves the value of a specified attribute from an element. Returns None if the attribute is not found.

```python
def get_attribute(
    self,
    name: str,
) -> str | None:
```

Get an attribute value.

| Parameter | Type | Description |
|-----------|------|-------------|
| name | str | Attribute name. |

**Returns:** Attribute value or None if not present.

**Example:**
```python
para = Paragraph(style='Heading1')
style = para.get_attribute('text:style-name')
```
```

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

### Create Basic Text Document with Table of Content

Source: https://github.com/jdum/odfdo/blob/main/doc_src/src/recipes.md

Generates a text document with paragraphs and headers, then adds a Table of Contents based on those headers.

```python
from odf.opendocument import OpenDocumentText
from odf.text import P, H, TableOfContent

txtdoc = OpenDocumentText()

# Add some content with headers
txtdoc.text.addElement(H(text="Chapter 1", level=1))
txtdoc.text.addElement(P(text="Content for chapter 1."))
txtdoc.text.addElement(H(text="Section 1.1", level=2))
txtdoc.text.addElement(P(text="Content for section 1.1."))
txtdoc.text.addElement(H(text="Chapter 2", level=1))
txtdoc.text.addElement(P(text="Content for chapter 2."))

# Add a Table of Content element
toc = TableOfContent()
txtdoc.text.addElement(toc)

txtdoc.save("document_with_toc.odt")
```

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

### Get Previous Sibling Element

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Element_Base_Class.md

Retrieve the immediate previous sibling element. Returns None if there is no previous sibling.

```python
def get_previous_sibling(self) -> Element | None:
```
```

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

### Get Next Sibling Element

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Element_Base_Class.md

Retrieve the immediate next sibling element. Returns None if there is no next sibling.

```python
def get_next_sibling(self) -> Element | None:
```
```

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

### Create Document from Template

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Document.md

Create new documents using built-in templates for spreadsheets, presentations, or drawings, or specify a custom template file.

```python
# Using default templates
doc = Document('spreadsheet')  # Create new spreadsheet
doc = Document('presentation')  # Create new presentation
doc = Document('drawing')  # Create new drawing

# Using custom template
doc = Document.new('path/to/custom_template.odt')
```

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

### Get Element Parent

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Element_Base_Class.md

Retrieves the parent element of the current element. Returns None if the element is the root of the document.

```python
parent_element = child_element.parent
```

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

### OfficeSettings Body Class - odfdo

Source: https://github.com/jdum/odfdo/blob/main/_autodocs/Types_Reference.md

Settings body (`office:settings`).

```python
class OfficeSettings(Body):
```