Writing Scripts

Writing Scripts

Scripts for CatiaMenuWin32 live in the KaiUR/Pycatia_Scripts repository. You can also add your own via a local folder or extra GitHub repo.

Folder Structure

Scripts must be placed in a subfolder — the subfolder name becomes the tab name in the app:

Any_Document_Scripts\
Drawing_Document_Scripts\
Part_Document_Scripts\
Process_Document_Scripts\
Product_Document_Scripts\
Shape_Generation_Scripts\
Utility_Scripts\

The setup\ folder is reserved for requirements.txt and never becomes a tab.

Required Header

Every script must include a structured metadata header that the app reads to display the tooltip and Script Details:

'''
    -----------------------------------------------------------------------------------------------------------------------
    Script name:    Your_Script_Name.py
    Version:        1.0
    Code:           Python3.10.4, Pycatia 0.8.3
    Release:        V5R32
    Purpose:        One line summary shown on the script button.
    Author:         Your Name
    Date:           DD.MM.YY
    Description:    Full description of what the script does.
                    Continuation lines must be indented.
    dependencies = [
                    "pycatia",
                    ]
    requirements:   Python >= 3.10
                    pycatia
                    Catia V5 running with an open part document.
    -----------------------------------------------------------------------------------------------------------------------

    Change:

    -----------------------------------------------------------------------------------------------------------------------
'''

Header Rules

• Must be inside a triple-quoted string at the top of the file
• Purpose — one line only; shown as subtitle on the script button
• Description — full detail; continuation lines must be indented
• dependencies — list all pip packages required
• requirements — describes the CATIA state needed to run the script
• Change — required change log; add one entry per version bump with the date and a short description of what changed

Naming

Use Snake_Case_Descriptive_Name.py. The app converts underscores to spaces automatically — Export_Points_To_CSV.py becomes Export Points To CSV in the button.

Dependencies

Add any pip packages your script requires to setup/requirements.txt in your repository. The app's ↓ Deps button installs them automatically.

Persistent Data

Never ask users to edit a script to change settings or parameters. CatiaMenuWin32 verifies the SHA hash of every downloaded script against GitHub before running it. A script edited locally will fail the integrity check and the app will refuse to run it. All user-configurable data must be stored outside the script file.

Where to Save Data

Store settings in a per-script folder under %APPDATA%\pycatia_scripts\:

%APPDATA%\pycatia_scripts\<Your_Script_Name>\user_settings.json

Use the script filename (without .py) as the folder name. This keeps each script's data isolated and easy to locate or clean up.

Implementation Pattern

import os
import json

SETTINGS_DIR  = os.path.join(os.environ['APPDATA'], 'pycatia_scripts', 'Your_Script_Name')
SETTINGS_FILE = os.path.join(SETTINGS_DIR, 'user_settings.json')

# --- In your dialog __init__ ---
hardcoded_defaults = {
    "my_param":      "10.0",
    "another_param": "5.0",
}
settings = hardcoded_defaults.copy()

if os.path.exists(SETTINGS_FILE):
    try:
        with open(SETTINGS_FILE, 'r') as f:
            settings.update(json.load(f))
    except:
        pass  # Fall back to hardcoded defaults on corrupt or missing file

# Pre-fill dialog fields from settings ...

# --- After user clicks OK ---
if not os.path.exists(SETTINGS_DIR):
    os.makedirs(SETTINGS_DIR)

current_data = {
    "my_param":      dlg.my_field.GetValue(),
    "another_param": dlg.other_field.GetValue(),
}
with open(SETTINGS_FILE, 'w') as f:
    json.dump(current_data, f, indent=4)

Rules

• Always define hardcoded_defaults in the script — these are the factory defaults used when no saved file exists
• Wrap the file read in try/except and fall back to defaults if the file is corrupt or unreadable
• Create the directory before writing: use os.makedirs(SETTINGS_DIR) after checking it does not exist
• Save only on successful completion (when the user clicks OK), not on cancel or error

Provide a Clear Saved Button

Any script that saves settings should include a Clear Saved button in its dialog. This lets users delete the settings file and return to factory defaults without touching any script files:

def on_clear_saved(self, event):
    if os.path.exists(SETTINGS_FILE):
        os.remove(SETTINGS_FILE)
        # Reset all dialog fields back to hardcoded_defaults values
    else:
        wx.MessageBox("No saved settings file found.", "Information", wx.OK | wx.ICON_INFORMATION)

See the Involute Gear Generator and Check Operation Parameters Against Limits scripts for complete working examples.

Contributing Scripts

See CONTRIBUTING.md in the scripts repository for full contribution guidelines.