SimpleIDML

SimpleIDML can insert content from a source IDML document into a target IDML document using XPath syntax.

Best Practices:

1. Always make a backup of your files before altering them.
2. Use .prefix() on both documents before inserting to avoid ID/reference collisions.

Use insert_idml(source_package, at="XPATH_TARGET", only="XPATH_SOURCE") within a context manager.

from simple_idml import idml

idml_main = idml.IDMLPackage("/path/to/my_main_document.idml")
idml_module = idml.IDMLPackage("/path/to/my_small_document.idml")

# Prefix both to avoid collisions
with idml_main.prefix("main") as p_idml_main, \
     idml_module.prefix("article") as p_idml_article:

    # Insert article from module into main at a specific XPath
    with p_idml_main.insert_idml(p_idml_article, at="/Root/article[3]", 
                                 only="/Root/module[1]") as f:
        print(f.stories)

You can inspect the contents of an IDML file using the IDMLPackage class. Key attributes include:

• spreads: A list of paths to spread XML files.
• stories: A list of paths to story XML files.
• font_families: A list of lxml.etree Elements representing font families. You can extract names using the Name attribute.
• xml_structure: An lxml.etree Element representing the InDesign XML-ready structure. This structure is used to map external XML data to the document.
• xml_structure_pretty(): A shortcut to print the XML structure as a pretty-printed string.

from simple_idml import idml
my_idml_package = idml.IDMLPackage("/path/to/my_main_document.idml")

# List spreads and stories
print(my_idml_package.spreads)
print(my_idml_package.stories)

# Access font names
font_names = [e.get("Name") for e in my_idml_package.font_families]
print(font_names)

# View XML structure
print(my_idml_package.xml_structure_pretty())

The simple_idml.indesign.indesign.save_as function allows you to trigger file conversions (e.g., IDML to PDF) via an InDesign Server instance.

Arguments:

• file_path: Path to the source file.
• formats: A list of dictionaries defining the target format and parameters. Supported formats: "jpeg", "idml", "pdf", "indd", "zip".
• server_url: The URL of the InDesign Server.
• client_workdir: Directory accessible by the client.
• server_workdir: Directory accessible by the server.

Special Configurations:

• Windows Server: Set indesign_server_path_style="windows" if the server is on Windows.
• FTP Access: If the client accesses the workdir via FTP, provide ftp_params containing auth (tuple of (url, user, password)), passive, keepalive, etc.

from simple_idml.indesign import indesign

# Example: Convert to PDF with CMYK color space
response = indesign.save_as(
    "/path_to_file.indd",
    [{"fmt": "pdf", "params": {"colorSpace": "CMYK"}}],
    "http://url-to-indesign-server:port",
    "/path/to/client/workdir",
    "/path/to/indesign-server/workdir"
)[0]

with open("my_file.pdf", "wb+") as f:
    f.write(response)

You can merge pages from several documents into a single document using add_page_from_idml (for a single page) or add_pages_from_idml (for multiple pages).

Workflow:

1. Prefix all packages to avoid collisions.
2. For add_pages_from_idml, provide a list of tuples: (package, page_number, at_xpath, only_xpath).

from simple_idml import idml

edito_idml_file = idml.IDMLPackage("magazineA-edito.idml")
courrier_idml_file = idml.IDMLPackage("magazineA-courrier-des-lecteurs.idml")

with edito_idml_file.prefix("edito") as p_edito, \
     courrier_idml_file.prefix("courrier") as p_courrier:

    # Add a single page
    new_idml = p_edito.add_page_from_idml(p_courrier, 
                                          page_number=1, 
                                          at="/Root", 
                                          only="/Root/page[1]")

    # Add multiple pages at once
    packages_to_add = [
        (p_courrier, 1, "/Root", "/Root/page[1]"),
    ]
    new_idml_bulk = p_edito.add_pages_from_idml(packages_to_add)