Skip to content

03-scripting-basics.md

Latest commit

 

History

History
97 lines (74 loc) · 4.16 KB

03-scripting-basics.md

File metadata and controls

97 lines (74 loc) · 4.16 KB
Raw

3. Scripting basics

What every script can use

These names are predefined - no imports needed:

Name What it is
sw The SOLIDWORKS application (ISldWorks)
doc The active document (IModelDoc2, plus IPartDoc / IAssemblyDoc / IDrawingDoc members), or None
model Model(doc): the Pythonic wrapper of the active document (see The model API), or None
Model The wrapper class, for other documents: Model(other_doc)
mm, cm, m, inch, ft, deg, rad, kg, g Units (SI factors): 30 * mm == 0.03
to(value, unit) Convert an SI value to a unit: to(0.03, mm) == 30.0
X, Y, Z, Vec Unit vectors and the 3D vector type
swconst All SOLIDWORKS API enums: swconst.swDocumentTypes_e.swDocPART
sldworks Typed casts: sldworks.IPartDoc(obj) (rarely needed, see chapter 5)
on, off Subscribe / unsubscribe event handlers (see Events)
ui Progress bar, messages, questions, prompts, file dialogs (see chapter 11)
cosworks, swmotionstudy, ... The other SOLIDWORKS API libraries (see chapter 5)
FeatureError Raised when SOLIDWORKS refuses to build something (see Building models)
_ The value of the last expression shown

doc and model are refreshed at the start of every run, so they always follow the document you are looking at. Inside one run they do not change: if your script creates or opens a document, keep the returned object instead.

part = doc                      # remember it: `doc` is fixed for this run anyway
print(part.GetTitle(), part.GetType() == swconst.swDocumentTypes_e.swDocPART)

Anything else comes from regular imports: the whole standard library (math, csv, json, pathlib, datetime ...) and any pip package (see Packages).

Sessions: variables persist

All runs from the editor tabs and the REPL share one session. Variables, functions and imports stay defined between runs until you press Reset:

counter = globals().get("counter", 0) + 1
counter                          # 1, then 2, 3 ... on every run

This makes the REPL a great inspector: run a script once, then poke at its variables (faces[0], len(rows) ...) in the >>> line.

Output

  • print writes to the output panel as the script runs.
  • If the last line of a script is an expression, its value is shown (like Jupyter), and stored in _.
  • Errors print a traceback that only contains your code; the failing line is marked in the editor.
import math
for i in range(3):
    print("step", i)
math.pi * 2                     # shown as the result

Units

The SOLIDWORKS API is SI-only, and so is SwPy. Multiply by a unit when writing a value, divide (or use to) when reading:

width = 120 * mm                 # 0.12
angle = 45 * deg                 # 0.785...
print(width, to(width, inch), to(angle, deg))
area = model.faces.largest().GetArea()
print(f"largest face: {to(area, mm**2):.1f} mm^2")

Scripts run on the SOLIDWORKS UI thread

Your code runs inside SOLIDWORKS, on its main thread. That is what makes API calls fast (microseconds) and safe, but it also means SOLIDWORKS waits while a script runs. For long jobs:

  • use model.batch() to switch off graphics and rebuild once (details),
  • print progress - output appears live,
  • wrap long loops in ui.progress(...): Esc then stops them (details),
  • otherwise there is no "stop" button: avoid infinite loops (save your work before experimenting).

Organising code

  • Save scripts as .py files and open them in tabs.

  • To import your own modules, add their folder to sys.path once per session:

    import sys
sys.path.append(r"C:\work\sw-scripts")
import my_helpers

    After editing my_helpers.py, reload it with importlib.reload(my_helpers).

  • __name__ == "__main__" is true in the editor, so if __name__ == "__main__": blocks run as usual.