### Install docxcompose

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/README.md

Install the core library using pip. For server support, use the [server] extra.

```bash
pip install docxcompose
```

```bash
pip install docxcompose[server]
```

```bash
pip install docxcompose[dev]
```

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

### Install DocxCompose for Development

Source: https://github.com/4teamwork/docxcompose/blob/master/README.rst

Install the docxcompose library for development using Poetry. Clone the repository first, then run the install command.

```sh
poetry install
```

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

### Example Docker Usage for API Testing

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Shows how to start the DocxCompose server in a Docker container and test its API endpoints using curl for file uploads and health checks.

```bash
docker run -it --rm -p 8080:8080 4teamwork/docxcompose

# In another terminal, test the API
curl -F "first=@template.docx" -F "second=@content.docx" \
  -o result.docx http://localhost:8080/

# Check health
curl http://localhost:8080/healthcheck
```

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

### Start docxcompose-server

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Start the docxcompose server. The server runs on port 8080, listens on all interfaces (0.0.0.0), and logs at INFO level.

```bash
docxcompose-server
```

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

### Install DocxCompose with Server Dependency

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Installs the docxcompose package including the optional 'server' dependency, which is required for server functionality.

```bash
pip install docxcompose[server]
```

```bash
pip install "docxcompose[server]>=2.0,<3.0"
```

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

### Python Argument Parser Setup

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/command.md

Sets up the argparse ArgumentParser with all necessary command-line arguments and their corresponding help text.

```python
setup_parser()
```

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

### Retrieve DocxCompose Package Version

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/types.md

Get the installed version of the docxcompose package. This is typically used for display on startup.

```python
version = importlib.metadata.version("docxcompose")
```

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

### Example Error Log from DocxCompose Server

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

This is an example of a detailed error log that might appear in the server's stderr, including a Python traceback.

```text
2024-03-01 10:15:23,456 ERROR docxcompose Failed composing documents.
Traceback (most recent call last):
  File "docxcompose/server.py", line 51, in compose
    composer = Composer(Document(documents.pop(0)), **compose_options(request))
  File "docxcompose/composer.py", line 48, in __init__
    self.pkg = doc.part.package
  File ".../python-docx/docx/document.py", line 39, in part
    return self.element.getparent()
  ...
```

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

### Example Logging Output

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Illustrates typical logging output from the DocxCompose server, showing informational messages and error tracebacks.

```text
2024-03-01 10:15:23,456 INFO docxcompose Composing 3 documents
2024-03-01 10:15:23,789 ERROR docxcompose Failed composing documents.
Traceback (
  ...
)
```

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

### HTTP 200 OK Response Example

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

This is an example of a successful HTTP 200 OK response for a document composition request. It includes the Content-Type and Content-Disposition headers, indicating a DOCX file is being returned.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="composed.docx"
Content-Length: 125432

[binary DOCX content]
```

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

### Server Error Logging Example

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

This is an example of the server's error logging output when document composition fails. It shows the timestamp, error message, and a traceback indicating the failure point.

```log
2024-03-01 10:15:23 ERROR docxcompose Failed composing documents.
Traceback (most recent call last):
  File "docxcompose/server.py", line 51, in compose
    composer = Composer(Document(documents.pop(0)), **compose_options(request))
  ...

```

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

### Blackbox Testing Example

Source: https://github.com/4teamwork/docxcompose/blob/master/README.rst

Example of a blackbox test helper function for comparing composed documents against expected fixtures. The assertion will store debug output if it fails.

```python
def test_example():
    fixture = FixtureDocument("expected.docx")
    composed = ComposedDocument("master.docx", "slave1.docx", "slave2.docx")
    assert fixture == composed
```

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

### Iterate through custom properties

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

This example demonstrates how to iterate through all custom properties, printing their names and values.

```python
props = CustomProperties(doc)
for key in props.keys():
    print(f"{key}: {props[key]}")
```

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

### Iterate through custom property items

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

This example shows how to iterate through all custom properties by their name-value pairs.

```python
props = CustomProperties(doc)
for name, value in props.items():
    print(f"{name}: {value}")
```

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

### Run DocxCompose Docker Container

Source: https://github.com/4teamwork/docxcompose/blob/master/README.rst

Start the docxcompose web service using Docker. This allows composing documents via a web API.

```sh
docker run -it --rm -p 8080:8080 4teamwork/docxcompose
```

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

### Start docxcompose Web Server

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Initiates the docxcompose web server. This function blocks while the server is active, handling document composition requests on the default port 8080.

```python
main()
```

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

### Handle Missing aiohttp Import

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Provides a fallback mechanism to raise a SystemExit if the 'aiohttp' library is not installed, indicating the 'server' extra is missing.

```python
try:
    from aiohttp import web
except ImportError:
    raise SystemExit("Install with server extra to use this command.")
```

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

### Web Server Document Composition

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/README.md

Start the docxcompose web server and use cURL to send documents for composition via HTTP requests.

```bash
# Start server
docxcompose-server

# In another terminal, compose documents
curl -F "master=@template.docx" -F "section=@content.docx" \
  http://localhost:8080/ -o output.docx
```

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

### Docker Compose for Docx-Compose Service

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Example Docker Compose configuration to run the docx-compose service. It maps the container port to the host and includes a healthcheck.

```yaml
version: '3.8'
services:
  docxcompose:
    image: 4teamwork/docxcompose:latest
    container_name: docxcompose_service
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
```

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

### Compose Documents with Python Requests

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

Utilize the Python Requests library to send DOCX files for composition. This example shows how to handle file uploads and process the response.

```python
import requests

with open('template.docx', 'rb') as f_master, \
     open('section1.docx', 'rb') as f_s1, \
     open('section2.docx', 'rb') as f_s2:
    
    files = {
        'master': f_master,
        'section1': f_s1,
        'section2': f_s2,
    }
    
    response = requests.post(
        'http://localhost:8080/',
        files=files,
        params={'preserve_styles': 'yes'},
        timeout=60,
    )

if response.status_code == 200:
    with open('output.docx', 'wb') as f:
        f.write(response.content)
else:
    print(f"Error: {response.status_code} - {response.text}")
```

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

### Get all custom property names

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

The `keys` method returns a list of all custom property names.

```python
keys()
```

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

### Compose Documents with JavaScript Fetch API

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

Use the Fetch API to upload multiple DOCX files and compose them into a single document. This example demonstrates client-side composition.

```javascript
const files = [
    new File([await fetch('template.docx').then(r => r.blob())], 'template.docx'),
    new File([await fetch('section1.docx').then(r => r.blob())], 'section1.docx'),
    new File([await fetch('section2.docx').then(r => r.blob())], 'section2.docx'),
];

const formData = new FormData();
files.forEach((file, i) => formData.append(`file${i}`, file));

const response = await fetch('http://localhost:8080/?preserve_styles=true', {
    method: 'POST',
    body: formData,
});

const blob = await response.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'composed.docx';
a.click();
```

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

### Docker Compose Configuration for DocxCompose

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Defines a Docker Compose setup for the DocxCompose service, including image, port mapping, and a healthcheck configuration.

```yaml
version: '3.8'
services:
  docxcompose:
    image: 4teamwork/docxcompose:latest
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 3
```

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

### Get DocxCompose Logger Instance

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/types.md

Obtain a logger instance for server operations. Used for info-level composition messages and exception logging.

```python
logger = logging.getLogger("docxcompose")
```

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

### Get all custom property values

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

The `values` method returns a list of all custom property values.

```python
values()
```

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

### POST Request with Style Preservation

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

This cURL example demonstrates composing documents while preserving styles. The 'preserve_styles' query parameter is set to 'true'. The output is saved to 'output.docx'.

```bash
curl -F "template=@master.docx" -F "section1=@part1.docx" -F "section2=@part2.docx" \
  "http://localhost:8080/?preserve_styles=true" \
  -o output.docx
```

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

### Add Images in Composer

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/image.md

Example of how ImageWrapper is used within the Composer class to add images from one document to another, including deduplication logic.

```python
def add_images(self, doc, element):
    """Add images from the given document used in the given element."""
    blips = xpath(element, "(.//a:blip|.//asvg:svgBlip)[@r:embed]")
    for blip in blips:
        rid = blip.get("{%s}embed" % NS["r"])
        img_part = doc.part.rels[rid].target_part

        new_img_part = self.pkg.image_parts._get_by_sha1(img_part.sha1)
        if new_img_part is None:
            image = ImageWrapper(img_part)
            new_img_part = self.pkg.image_parts._add_image_part(image)

        new_rid = self.doc.part.relate_to(new_img_part, RT.IMAGE)
        blip.set("{%s}embed" % NS["r"], new_rid)
```

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

### Kubernetes Liveness Probe Configuration

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

This YAML snippet shows how to configure a Kubernetes liveness probe for the docxcompose service. It specifies the HTTP GET path, port, and timing parameters for health checks.

```yaml
livenessProbe:
  httpGet:
    path: /healthcheck
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 30
  timeoutSeconds: 10
  failureThreshold: 3
```

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

### Get Text from First Structured Document Tag by Alias

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/sdt.md

Retrieves the text content from the first plain text SDT matching the alias. Line breaks in the SDT are returned as \n characters. Returns an empty string if no matching SDT is found.

```python
sdt = StructuredDocumentTags(doc)
current_name = sdt.get_text("ClientName")
print(f"Current value: {current_name}")

# Reading multiline content
address = sdt.get_text("Address")
lines = address.split("\n")
```

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

### Initialize Composer

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/composer.md

Instantiate the Composer with a master document. Use preserve_styles=True to keep conflicting styles from appended documents.

```python
from docx import Document
from docxcompose.composer import Composer

master = Document("master.docx")
composer = Composer(master, preserve_styles=True)
doc1 = Document("document1.docx")
composer.append(doc1)
composer.save("merged.docx")
```

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

### HTTP 500 Internal Server Error Example

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

This response indicates an Internal Server Error (HTTP 500) when document composition fails, possibly due to invalid or corrupted DOCX files. The server logs the full exception traceback.

```http
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8
Content-Length: 24

Failed composing documents
```

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

### Composer Initialization and Configuration

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Initialize the Composer with a master document and configure style preservation. Properties like `restart_numbering` can be set after initialization.

```python
from docx import Document
from docxcompose.composer import Composer

master = Document("master.docx")

# Configuration via constructor
composer = Composer(master, preserve_styles=True)

# Configuration via property
composer.restart_numbering = False

# Append documents
composer.append(Document("doc1.docx"))
composer.append(Document("doc2.docx"))

composer.save("output.docx")
```

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

### Get Custom Property with Default

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

Get a property value with a default fallback if the property does not exist. The default value is returned if the property is not found.

```python
props = CustomProperties(doc)
version = props.get("Version", 1)
```

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

### Create aiohttp Web Application

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Initializes and configures the aiohttp web application, setting up necessary routes and error handling for the docxcompose server.

```python
create_app()
```

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

### Test Document Composition Workflow

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

A step-by-step test suite for loading documents, creating a composer, appending content, and saving the result.

```python
from docx import Document
from docxcompose.composer import Composer

# Test 1: Load documents
master = Document("master.docx")
slave = Document("slave.docx")

# Test 2: Create composer
composer = Composer(master)

# Test 3: Append one document
composer.append(slave)

# Test 4: Save
composer.save("test_output.docx")

print("All tests passed!")
```

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

### Get Property with Default (get)

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

Retrieves the value of a custom property, providing a default value to return if the property is not found. This method is useful for safely accessing properties that may or may not exist.

```APIDOC
## get(key, default=None)

### Description
Get a property value with a default fallback if the property does not exist.

### Parameters
#### Path Parameters
- **key** (str) - Required - Property name
- **default** (Any) - Optional - Default value to return if property does not exist. Defaults to None.

### Returns
Property value or default

### Request Example
```python
props = CustomProperties(doc)
version = props.get("Version", 1)
```
```

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

### Basic Command-Line Usage

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/command.md

Appends a single document to a master template and saves the result to a specified output file.

```bash
docxcompose MASTER_FILE FILE1 [FILE2 ...] [-o OUTPUT_FILE] [--preserve-styles]
```

```bash
docxcompose master.docx content.docx -o output.docx
```

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

### Get Custom Property Value

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

Get the value of a custom property. Property name is case-insensitive. Returns the property value, automatically converted from XML to Python types (bool, int, float, datetime, or str). Throws KeyError if the property does not exist.

```python
props = CustomProperties(doc)
author = props["Author"]
version = props["Version"]  # Returns int or float
```

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

### Composer Constructor

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/composer.md

Initializes a Composer instance with a master document. The first document provided serves as the template, and subsequent documents are appended to it. Styles, headers, and footers from the master document are preserved.

```APIDOC
## Composer Constructor

### Description
Initialize a Composer instance with a master document.

### Method
__init__

### Parameters
#### Path Parameters
- **doc** (Document) - Required - Master document (from `python-docx`) that defines the base structure, styles, and headers/footers
- **preserve_styles** (bool) - Optional - If True, preserve and rename conflicting styles from appended documents instead of replacing them (Default: False)

### Request Example
```python
from docx import Document
from docxcompose.composer import Composer

master = Document("master.docx")
composer = Composer(master, preserve_styles=True)
doc1 = Document("document1.docx")
composer.append(doc1)
composer.save("merged.docx")
```
```

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

### GET /healthcheck endpoint

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/MANIFEST.md

Checks the health status of the docxcompose service.

```APIDOC
## GET /healthcheck

### Description
Checks the health status of the docxcompose service.

### Method
GET

### Endpoint
/healthcheck

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status, e.g., 'healthy'.

#### Response Example
{
  "status": "healthy"
}
```

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

### Basic Command-Line Composition

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Perform basic document composition using the `docxcompose` command-line tool, specifying master and slave documents, and an output file.

```bash
docxcompose master.docx slave1.docx slave2.docx -o result.docx
```

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

### Custom Property Format ID

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/types.md

The fixed GUID expected by Microsoft Office applications for custom properties.

```python
CUSTOM_PROPERTY_FMTID = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}"
```

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

### Batch Processing for Many Documents

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Illustrates a performance tuning strategy for composing many documents by suggesting batch processing or creating separate Composer instances instead of appending all to one.

```python
# Instead of:
# composer.append(doc1)
# composer.append(doc2)
# ... 100 more

# Consider:
# Create partial compositions first, then merge results
```

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

### GET /healthcheck

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Health check endpoint for monitoring the server's status. It returns a simple 'OK' response.

```APIDOC
## GET /healthcheck

### Description
Health check endpoint for monitoring the server's status. It returns a simple 'OK' response.

### Method
GET

### Endpoint
/healthcheck

### Response
#### Success Response (200 OK)
- **Content-Type**: `text/plain`
- **Body**: "OK"

### Usage
```bash
curl http://localhost:8080/healthcheck
```
```

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

### Initialize StructuredDocumentTags

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/sdt.md

Creates an interface for managing SDTs in the document. Only plain text SDTs are currently supported for text operations. Requires a Document instance from python-docx.

```python
from docx import Document
from docxcompose.sdt import StructuredDocumentTags

doc = Document("template.docx")
sdt = StructuredDocumentTags(doc)
sdt.set_text("ClientName", "Acme Corporation")
sdt.set_text("InvoiceNumber", "INV-2024-001")
```

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

### Direct ImageWrapper Instantiation

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/image.md

Demonstrates direct instantiation of ImageWrapper with a python-docx Document object. This is for advanced usage outside the Composer.

```python
from docx import Document
from docxcompose.image import ImageWrapper

# Load a document with images
doc = Document("document_with_images.docx")

```

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

### Python Entry Point Function

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/command.md

The main function executes the docxcompose command-line interface, parsing arguments and managing the document composition process.

```python
main(args=None)
```

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

### Get all custom property name-value pairs

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

The `items` method returns a list of tuples, where each tuple contains a property name and its corresponding value.

```python
items()
```

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

### Change Server Port with Docker

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Demonstrates how to change the server's listening port to 9000 when running the Docker image.

```bash
docker run -it --rm -p 9000:8080 4teamwork/docxcompose
```

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

### Get Separate Marker Run

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

Retrieves the XML element for the 'separate' fldChar marker. This marker is optional in OOXML. Returns None if the marker is not found.

```python
get_separate_run()
```

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

### Initialize CustomProperties

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

Initialize a CustomProperties instance for a document. Loads custom properties from the document's package. If no custom properties part exists, creates one from a template. Automatically detects the document's language from w:lang tags for date formatting.

```python
from docx import Document
from docxcompose.properties import CustomProperties

doc = Document("document.docx")
props = CustomProperties(doc)
props["Author"] = "John Doe"
props["Version"] = 1.0
```

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

### Initialize ImageWrapper

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/image.md

Initialize an ImageWrapper from an image part. This is used internally by the Composer when copying images.

```python
ImageWrapper(img_part)
```

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

### increment_name

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/utils.md

Increments the numeric suffix of a name string. If no suffix exists, it appends '_1'. This is useful for generating unique names, for example, when dealing with conflicting styles.

```APIDOC
## increment_name(name)

### Description
Increments the numeric suffix of a name, or adds "_1" if there is no suffix. This function is used by the Composer's style preservation system when renaming conflicting styles.

### Parameters
#### Path Parameters
- **name** (str) - Required - Name string (may contain underscores and numbers)

### Returns
- str - The modified name string.

### Examples
```python
from docxcompose.utils import increment_name

increment_name("Normal")           # "Normal_1"
increment_name("Normal_1")         # "Normal_2"
increment_name("Heading_Level_1")  # "Heading_Level_2"
increment_name("Style_10")         # "Style_11"
```
```

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

### Project File Structure

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/MANIFEST.md

The project's output directory contains various markdown files for documentation, organized by concern.

```text
output/
├── README.md                    # Main entry point
├── types.md                     # Type definitions and constants
├── configuration.md             # Setup and behavior options
├── endpoints.md                 # HTTP API reference
├── errors.md                    # Exception handling
└── api-reference/
    ├── composer.md              # Document composition class
    ├── properties.md            # Custom properties and fields
    ├── sdt.md                   # Content controls
    ├── image.md                 # Image handling
    ├── command.md               # CLI interface
    ├── server.md                # Web server
    └── utils.md                 # Utility functions
```

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

### Temporary File Management with TemporaryDirectory

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

Utilizes `tempfile.TemporaryDirectory` to create and manage temporary files, ensuring automatic cleanup after use.

```python
# Server handles this, but for custom code:
import tempfile
import os

with tempfile.TemporaryDirectory() as tmpdir:
    # Use tmpdir for temporary files
    # Automatically cleaned up
    pass
```

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

### Command-Line Composition with Style Preservation

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Execute document composition with style preservation enabled via a command-line flag.

```bash
docxcompose --preserve-styles template.docx doc1.docx doc2.docx -o output.docx
```

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

### Academic Paper Composition with Style Preservation

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Example of composing an academic paper while preserving styles from individual sections. This ensures that specific formatting nuances from each part are maintained in the final document.

```python
from docx import Document
from docxcompose.composer import Composer

# Preserve styles to maintain each section's formatting
master = Document("paper_template.docx")
composer = Composer(master, preserve_styles=True)

```

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

### Generate Report

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/command.md

Use this command to create a professional report by combining a template with multiple document sections. The output is saved to a specified file.

```bash
docxcompose report_template.docx executive_summary.docx methodology.docx findings.docx conclusion.docx \
  -o final_report_2024.docx
```

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

### Get Structured Document Tags by Alias

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/sdt.md

Searches the document body for SDTs matching the given alias. An alias is a user-friendly identifier assigned to SDTs in Word. Multiple SDTs can share the same alias.

```python
sdt = StructuredDocumentTags(doc)
matching_tags = sdt.tags_by_alias("CompanyName")
print(f"Found {len(matching_tags)} tags with alias 'CompanyName'")
```

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

### Compose Documents via Command Line

Source: https://github.com/4teamwork/docxcompose/blob/master/README.rst

Utilize the docxcompose console script to combine .docx files from the command line. Specify input files and an output file using the -o flag.

```sh
docxcompose files/master.docx files/content.docx -o files/composed.docx
```

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

### Document Composition Process

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

Orchestrates the document composition by extracting options, setting up a composer with a master document, appending other documents, saving to a temporary file, and streaming the response.

```python
# 1. Extract options from query parameters
options = compose_options(request)
# Result: {'preserve_styles': True/False}

# 2. Create Composer with first document as master
composer = Composer(Document(documents.pop(0)), **options)

# 3. Append remaining documents in order
for document in documents:
    composer.append(Document(document))

# 4. Save to temporary file
composer.save(composed_filename)

# 5. Stream response back to client
return await stream_file(request, composed_filename, content_type)
```

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

### Get Runs for Value Update

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

Retrieves a list of XML element runs located between the 'separate' and 'end' markers. These runs typically contain the cached field value. Returns an empty list if no 'separate' marker is present.

```python
get_runs_for_update()
```

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

### Get Custom Property (__getitem__)

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

Retrieves the value of a specified custom property. The property lookup is case-insensitive. The returned value is automatically converted from its XML representation to a Python type (bool, int, float, datetime, or str).

```APIDOC
## __getitem__(key)

### Description
Get the value of a custom property. Property name is case-insensitive. The value is automatically converted from XML to a Python type.

### Parameters
#### Path Parameters
- **key** (str) - Required - Property name (case-insensitive)

### Returns
Property value (type automatically converted from XML: bool, int, float, datetime, or str)

### Throws
KeyError if the property does not exist

### Request Example
```python
props = CustomProperties(doc)
author = props["Author"]
version = props["Version"]  # Returns int or float
```
```

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

### Command-Line Composition with Default Output

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Compose documents using the `docxcompose` CLI, relying on the default output file name (`composed.docx`).

```bash
docxcompose master.docx content.docx
```

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

### Console Script Configuration

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/command.md

This TOML snippet shows how the docxcompose command is registered as a console script in pyproject.toml, linking the command name to the main entry point function.

```toml
[project.scripts]
docxcompose = "docxcompose.command:main"
```

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

### Multiple Document Composition

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/command.md

Appends multiple documents in sequence to a master template, creating a merged output file.

```bash
docxcompose master.docx doc1.docx doc2.docx doc3.docx -o merged.docx
```

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

### Python File Composition and Saving

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/command.md

Composes multiple Word documents into a single output file based on parsed arguments and saves the result. Exits with a success message upon completion.

```python
compose_files(parser, parsed_args)
```

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

### Command-Line Document Composition

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/README.md

Utilize the docxcompose command-line tool to merge documents. Options include basic composition and style preservation.

```bash
# Compose multiple documents
docxcompose master.docx section1.docx section2.docx -o output.docx

# With style preservation
docxcompose --preserve-styles template.docx doc1.docx doc2.docx -o final.docx
```

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

### Constructing Namespaced Attributes

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/utils.md

Demonstrates how to use the NS dictionary to create namespaced attributes for XML elements, such as the 'id' attribute for relationships.

```python
from docxcompose.utils import NS, xpath

# Construct namespaced attribute
rid_attr = "{%s}id" % NS["r"]  # Result: {http://schemas.openxmlformats.org/officeDocument/2006/relationships}id
```

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

### keys

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

Retrieves a list of all custom property names.

```APIDOC
## keys

### Description
Get all custom property names.

### Method
```python
keys()
```

### Returns
list of str
```

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

### Fixing No Files Uploaded for POST Request

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

A 400 Bad Request indicating no documents were provided can be resolved by ensuring at least one .docx file is uploaded.

```bash
curl -F "text=hello" http://localhost:8080/  # No file fields
# Response: 400 No documents provided
```

```bash
curl -F "doc=@document.docx" http://localhost:8080/
```

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

### Document Template Processing with SDTs

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/sdt.md

Demonstrates how to load a document template, populate its Structured Document Tags (SDTs) with data using the StructuredDocumentTags class, and save the modified document. This is useful for generating documents from templates.

```python
from docx import Document
from docxcompose.sdt import StructuredDocumentTags

# Load a template with SDTs
doc = Document("invoice_template.docx")
sdt = StructuredDocumentTags(doc)

# Populate from data
invoice_data = {
    "ClientName": "Acme Corporation",
    "InvoiceNumber": "INV-2024-001",
    "InvoiceDate": "2024-03-01",
    "Amount": "$5,000.00",
    "Details": "Professional Services\nConsultation Hours\nSupport & Maintenance",
}

for alias, value in invoice_data.items():
    sdt.set_text(alias, value)

# Verify changes
print(f"Client: {sdt.get_text('ClientName')}")
print(f"Invoice: {sdt.get_text('InvoiceNumber')}")

doc.save("invoice_2024_001.docx")
```

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

### POST Request with Multiple Files

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

This cURL command shows how to upload multiple files for composition. The files are named 'a', 'b', 'c', and 'd', and the composed document is saved as 'result.docx'.

```bash
curl -F "a=@file1.docx" -F "b=@file2.docx" -F "c=@file3.docx" -F "d=@file4.docx" \
  http://localhost:8080/ \
  -o result.docx
```

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

### HTTP 400 Bad Request - No Documents Provided

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

This response indicates a Bad Request (HTTP 400) because no documents were uploaded. The server requires at least one document to perform composition.

```http
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
Content-Length: 19

No documents provided
```

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

### Simple cURL Composition

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

Performs a simple document composition using cURL by sending multiple files as multipart form data. The output is saved to 'result.docx'.

```bash
# Simple composition
curl -F "files=@doc1.docx" -F "files=@doc2.docx" \
  http://localhost:8080/ \
  -o result.docx
```

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

### Handling Composition Failures in Command-Line Tool

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

If a composition fails during command-line execution, it may be due to document corruption or unsupported formats. Test individual documents and simplify complexity.

```bash
Traceback (most recent call last):
  File "docxcompose/command.py", line 73, in main
    compose_files(parser, parsed_args)
  File "docxcompose/command.py", line 59, in compose_files
    composer.append(Document(slave_path))
  ...
```

```python
from docx import Document
doc = Document("file.docx")  # Will raise if file is invalid
```

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

### CustomProperties Constructor

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/properties.md

Initializes a CustomProperties instance for a given document. It loads custom properties from the document's package, creating a new part if one doesn't exist. It also automatically detects the document's language for correct date formatting.

```APIDOC
## CustomProperties(doc)

### Description
Initializes a CustomProperties instance for a document. Loads custom properties from the document's package. If no custom properties part exists, creates one from a template. Automatically detects the document's language from `w:lang` tags for date formatting.

### Parameters
#### Path Parameters
- **doc** (Document) - Required - Document instance from `python-docx`

### Request Example
```python
from docx import Document
from docxcompose.properties import CustomProperties

doc = Document("document.docx")
props = CustomProperties(doc)
props["Author"] = "John Doe"
props["Version"] = 1.0
```
```

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

### POST /

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Compose multiple Word documents via multipart form data upload. Each file uploaded as a form field with a .docx extension will be appended to the composition. An optional 'preserve_styles' query parameter can be used to retain styles during composition.

```APIDOC
## POST /

### Description
Compose multiple Word documents via multipart form data upload. Each file uploaded as a form field with a .docx extension will be appended to the composition. An optional 'preserve_styles' query parameter can be used to retain styles during composition.

### Method
POST

### Endpoint
/

### Parameters
#### Query Parameters
- **preserve_styles** (string) - Optional - Set to "1", "yes", "true", "on", or "ok" to enable style preservation.

#### Request Body
- **(files)** (multipart/form-data) - Required - Each file should be a form field with a `.docx` file extension.

### Request Example
```bash
curl -F "first=@first.docx" -F "second=@second.docx" -o composed.docx http://localhost:8080/
```

### Response
#### Success Response (200 OK)
- **Content-Type**: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
- **Content-Disposition**: `attachment; filename="{basename}"`
- **Body**: Binary DOCX file

#### Response Example
(Binary DOCX file content)

### Error Responses
- **400**: Content-Type is not multipart/form-data. Response Text: "Multipart request required"
- **400**: No documents provided in form data. Response Text: "No documents provided"
- **500**: Document composition failed. Response Text: "Failed composing documents"
```

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

### Providing Required Arguments for Command-Line Tool

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

When the 'docxcompose: error: the following arguments are required' message appears, ensure that the master document and at least one file argument are provided.

```bash
usage: docxcompose [-h] [-o file] [--preserve-styles] master file [file ...]
docxcompose: error: the following arguments are required: master, file
```

```bash
docxcompose master.docx doc1.docx doc2.docx -o output.docx
```

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

### Server HTTP Request with Style Preservation

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Send an HTTP POST request to the docxcompose server to compose documents with style preservation enabled. The `preserve_styles` query parameter is set to 'true'.

```bash
curl -F "master=@template.docx" -F "doc=@content.docx" \
  "http://localhost:8080/?preserve_styles=true" \
  -o result.docx
```

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

### Basic POST Request for Document Composition

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

Use this cURL command to compose multiple Word documents. The first file uploaded is treated as the master template, and subsequent files are appended in order. The output is saved to 'composed.docx'.

```bash
curl -F "first=@template.docx" -F "second=@content.docx" \
  http://localhost:8080/ \
  -o composed.docx
```

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

### Inspect Document Styles and Numbering

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

Retrieves and prints information about document styles and numbering definitions using docx and docxcompose utilities.

```python
from docx import Document
from docxcompose.utils import xpath

doc = Document("document.docx")

# List all styles
print("Styles:")
for style in doc.styles:
    print(f"  {style.style_id}: {style.name}")

# List all numbering definitions
from docxcompose.composer import Composer
composer = Composer(doc)
numbering_part = composer.numbering_part()
nums = xpath(numbering_part.element, ".//w:num")
print(f"Numbering definitions: {len(nums)}")
```

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

### Programmatic Document Composition

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/README.md

Use the Composer class to programmatically merge Word documents. Load a master document for styles and then append other documents.

```python
from docx import Document
from docxcompose.composer import Composer

# Load master document (defines styles, headers, footers)
master = Document("template.docx")

# Create composer
composer = Composer(master)

# Append documents
composer.append(Document("section1.docx"))
composer.append(Document("section2.docx"))

# Save result
composer.save("output.docx")
```

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

### Handle KeyError in CustomProperties

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

Shows how to safely access properties from CustomProperties, avoiding KeyError by checking for existence or using a try-except block. This is common when dealing with potentially missing properties.

```python
props = CustomProperties(doc)
value = props["NonexistentProperty"]  # Raises KeyError
```

```python
del props["NonexistentProperty"]  # Raises KeyError
```

```python
props.nullify("NonexistentProperty")  # Raises KeyError
```

```python
# Use get() with default
value = props.get("Property", default_value)

# Check existence
if "Property" in props:
    value = props["Property"]

# Catch the exception
try:
    value = props["Property"]
except KeyError:
    # Handle missing property
    pass
```

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

### Compose Documents with Style Preservation

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/server.md

Composes documents while preserving styles by setting the 'preserve_styles' query parameter to 'true'.

```bash
curl -F "file1=@doc1.docx" -F "file2=@doc2.docx" "http://localhost:8080/?preserve_styles=true" -o output.docx
```

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

### Enable Verbose Debug Logging

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

Configures the logging module to display all debug messages, useful for detailed troubleshooting.

```python
import logging
logging.basicConfig(level=logging.DEBUG)

# Now all debug messages will be printed
```

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

### Style Preservation Behavior

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Demonstrates the difference between preserve_styles=False (default) and preserve_styles=True when composing documents. Use preserve_styles=True to retain individual document style nuances, though it may increase file size.

```python
# Master has "Heading 1" in Arial
master = Document("master.docx")

# Slave has different "Heading 1" in Times New Roman
slave = Document("slave.docx")

composer = Composer(master, preserve_styles=False)
composer.append(slave)
# Result: "Heading 1" from master used throughout

composer2 = Composer(master, preserve_styles=True)
composer2.append(slave)
# Result: Master's "Heading 1" + Slave's "Heading 1_1" both in document
```

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

### Safe Property Access with Default Value

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

Use the .get() method for safe access to custom properties, providing a default value if the property does not exist.

```python
from docxcompose.properties import CustomProperties

props = CustomProperties(doc)

# Safe access pattern
value = props.get("PropertyName", default_value)

# Or with explicit check
if "PropertyName" in props:
    value = props["PropertyName"]
else:
    value = default_value
```

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

### cURL Composition with Style Preservation

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

Composes documents using cURL while enabling style preservation via a query parameter. Specifies a master document and content document, saving the output to 'output.docx'.

```bash
# With style preservation
curl -F "master=@template.docx" -F "content=@content.docx" \
  "http://localhost:8080/?preserve_styles=yes" \
  -o output.docx
```

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

### StructuredDocumentTags Constructor

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/sdt.md

Initializes a StructuredDocumentTags instance for a given Word document, providing an interface to manage SDTs. Supports plain text SDTs for text operations.

```APIDOC
## Constructor StructuredDocumentTags

### Description
Initializes a StructuredDocumentTags instance for a document.

### Parameters
#### Path Parameters
- **doc** (Document) - Required - Document instance from `python-docx`

### Response
#### Success Response (200)
- **StructuredDocumentTags instance** - An instance of the StructuredDocumentTags class.

### Example
```python
from docx import Document
from docxcompose.sdt import StructuredDocumentTags

doc = Document("template.docx")
sdt = StructuredDocumentTags(doc)
sdt.set_text("ClientName", "Acme Corporation")
sdt.set_text("InvoiceNumber", "INV-2024-001")
```
```

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

### Safely Set Document Properties

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

Converts unsupported value types to strings before setting document properties. Raises a TypeError if conversion is not possible.

```python
from docxcompose.properties import value2vt

def safe_set_property(props, name, value):
    # Convert unsupported types to string
    if not isinstance(value, (bool, int, float, str)):
        if hasattr(value, '__str__'):
            value = str(value)
        else:
            raise TypeError(f"Cannot convert {type(value)} to property value")
    
    props[name] = value
```

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

### Import PackURI for DOCX Package Paths

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/types.md

Imports the PackURI type from docx.opc.packuri. This type represents a path within the DOCX package structure and is used when creating new parts.

```python
from docx.opc.packuri import PackURI
```

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

### Compose Documents via Docker Web Service (curl)

Source: https://github.com/4teamwork/docxcompose/blob/master/README.rst

Send a multipart/form-data request to the running docxcompose Docker web service to compose documents. Upload files in the desired order.

```sh
curl -F "first=@first.docx" -F "second=@second.docx" -o composed.docx http://localhost:8080/
```

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

### Verifying File Paths for Command-Line Errors

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

If the 'docxcompose: error: file not found' error occurs, verify that the input file paths are correct using 'ls' and then re-run the command with correct paths.

```bash
usage: docxcompose [-h] [-o file] [--preserve-styles] master file [file ...]
docxcompose: error: file not found /path/to/master.docx
```

```bash
ls -la master.docx slave.docx
docxcompose ./master.docx ./slave.docx -o output.docx
```

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

### Handle AttributeError with Composer and Document Inputs

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/errors.md

Demonstrates how to prevent AttributeError by validating inputs, such as ensuring a document is opened before use or that inputs to Composer and CustomProperties are not None.

```python
from docxcompose.composer import Composer

composer = Composer(None)  # AttributeError in __init__
```

```python
doc = None
props = CustomProperties(doc)  # AttributeError: 'NoneType' has no attribute...
```

```python
from docx import Document

if not isinstance(doc, Document):
    raise TypeError("doc must be a python-docx Document instance")
```

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

### POST / endpoint (document composition)

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/MANIFEST.md

Composes a document based on a template and provided data. This is the primary endpoint for document generation.

```APIDOC
## POST /

### Description
Composes a document based on a template and provided data.

### Method
POST

### Endpoint
/

### Parameters
#### Query Parameters
- **template_name** (string) - Required - The name of the template to use for composition.
- **output_format** (string) - Optional - The desired output format (e.g., 'docx', 'pdf'). Defaults to 'docx'.

### Request Body
- **data** (object) - Required - A JSON object containing the data to populate the template.

### Response
#### Success Response (200)
- **document** (binary) - The generated document in the specified format.

#### Response Example
(Binary content of the generated document)
```

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

### Configure Docx-Compose Server Port

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Runs the docx-compose server application. The port can be customized via the DOCXCOMPOSE_PORT environment variable, defaulting to 8080 if not set.

```python
import os
from docxcompose.server import create_app
from aiohttp import web

app = create_app()

# Custom port via environment variable
port = int(os.getenv("DOCXCOMPOSE_PORT", 8080))

web.run_app(app, port=port)
```

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

### Python Requests POST for Document Composition

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/endpoints.md

This Python script uses the 'requests' library to perform document composition. It sends multiple files and includes the 'preserve_styles' parameter. The resulting DOCX content is saved to 'output.docx'.

```python
import requests

files = {
    'master': open('template.docx', 'rb'),
    'doc1': open('section1.docx', 'rb'),
    'doc2': open('section2.docx', 'rb'),
}

response = requests.post(
    'http://localhost:8080/',
    files=files,
    params={'preserve_styles': 'true'}
)

with open('output.docx', 'wb') as f:
    f.write(response.content)
```

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

### Merge Documents with Style Preservation

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/command.md

This command merges customer documents using a company template, ensuring brand consistency by preserving the original styles of the merged documents. The output is saved to a specified file.

```bash
docxcompose company_template.docx customer_letter_1.docx customer_letter_2.docx \
  --preserve-styles -o all_letters.docx
```

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

### Import Part for DOCX Package Components

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/types.md

Imports the Part type from docx.opc.part. This represents any file within the DOCX package, such as XML files or media assets.

```python
from docx.opc.part import Part
```

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

### Python Argument Parsing and Validation

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/api-reference/command.md

Parses raw command-line arguments using a configured ArgumentParser and validates that all specified files exist. Exits with an error if validation fails.

```python
parse_args(parser, args)
```

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

### Server Query Parameter Parsing Logic

Source: https://github.com/4teamwork/docxcompose/blob/master/_autodocs/configuration.md

Python function demonstrating how the server parses the `preserve_styles` query parameter from an HTTP request. It uses a `to_bool` utility for conversion.

```python
def compose_options(request):
    return {
        "preserve_styles": to_bool(request.rel_url.query.get("preserve_styles", "")),
    }
```