Package: fcxref
IntroductionMotivationApproachInstallationUsagePython APICommand LineSupported FreeCAD VersionsChangelogContributingIntroductionManagesFreeCAD externalreferences.“External references” are also known as external links or cross-document references.The following operations are supported:Findingexternal referencesRenamingexternal referencesandRemovingexternal references (not yet implemented)MotivationOnExpressions: Known issues / remaining tasks, it’s mentioned:There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queried, etc.Large complex FreeCAD projects typically rely on extensive use of cross-document referencing to properties such as aliases in spreadsheets.When you have dozens of references to the same property, it becomes very difficult to find all the places where references exist or rename the property.fcxrefaims to fill this gap until similiar functionality can be added to FreeCAD core.See the following related FreeCAD forum discussions for additional motivation:Expression engine - Automatic renamingRename a file containing external linksApproachfcxrefrelies on parsing theDocument.xmlin compressed.FCStdfiles.InstallationAvailable on thePython Package Index (PyPI).pip install fcxrefUsageThere are two ways to usefcxref:via the Python APIvai the Command LineThe following 2 sections cover these 2 usage methods with documents in theexample/directory.Consider you have aMainDocument.FCStdcontaining a spreadsheet that drives your model,
andExampleDocument.FCStdthat references aliases in that spreadsheet.Python APIfindfromfcxrefimportfind,Propertybase_path='./example'references=find(base_path,Property('MainDocument','Spreadsheet','Value'))print('\n'.join(map(str,references)))ExampleDocument Spreadsheet.B1 (content)
ExampleDocument Spreadsheet.A1 (content)
ExampleDocument Spreadsheet.B1 (alias)
ExampleDocument Box.Length (expression)renameTherenamefunction takes:the base path to look for FreeCAD documents inthe name or label of the documentthe name or label of the objectand a 2-element tuple containing the property before and after renaming.It returns a dictionary where keys are filepaths to updated.FCStdfiles,
and values are XMLElementobjects representing updatedDocument.xmlfiles.fromfcxrefimportrenamebase_path='./example'root_by_document_path=find(base_path,'MainDocument','Spreadsheet',('Value','RenamedValue'))print(root_by_document_path){'ExampleDocument.FCStd': <Element 'Document' at 0x7efcd281cc20>, 'MainDocument.FCStd': <Element 'Document' at 0x7f4d13c39270>}Command LineUponinstallingfcxref, thefcxrefcommand will become globally accessible.For usage information, pass--helpto each command.Each command scans for*.FCStdfiles recursively from the current working directory.Thus, you should navigate to a directory where you store your FreeCAD documents before executingfcxrefcommands.$ fcxref --help ↵
usage: fcxref [-h] [--version] {find,rename} ...

Manage cross-document references to properties.

optional arguments:
  -h, --help     show this help message and exit
  --version      show program's version number and exit

Commands:
  {find,rename}
    find         Find cross-document references to a property
    rename       Rename cross-document references to a propertyfind$ fcxref find --help ↵
usage: fcxlink find <document> <object> <property>

Surround arguments containing special characters in quotes (e.g. "<<My Label>>").

positional arguments:
  document    Document name or label.
  object      Object name or label.
  property    Property.

optional arguments:
  -h, --help  show this help message and exitSimple Queries$ fcxref find MainDocument Spreadsheet Value ↵
ExampleDocument.FCStd
  ExampleDocument Spreadsheet.B1 (content) [direct]
  ExampleDocument Spreadsheet.A1 (content) [indirect]
  ExampleDocument Spreadsheet.B1 (alias) [indirect]
  ExampleDocument Box.Length (expression) [indirect]

4 references to MainDocument#Spreadsheet.Value across 1 document(s) found.💡TIP:When using special characters on the command line such as<and>for label names, surround the argument in double-quotes.rename$ fcxref rename --help ↵
usage: fcxlink rename <document> <object> <from_property> <to_property>

Surround arguments containing special characters in quotes (e.g. "<<My Label>>").

positional arguments:
  document       Document name or label of reference to rename.
  object         Object name or label of reference to rename.
  from_property  Property of reference before renaming.
  to_property    Property of reference after renaming.

optional arguments:
  -h, --help     show this help message and exitSimple RenamesTherenamecommand will prompt users for confirmation before modifying any files,
and defaults to “No” if an explicit “Yes” is not provided.$ fcxref rename MainDocument Spreadsheet Value RenamedValue ↵
The following 2 document(s) reference MainDocument#Spreadsheet.Value:
  ExampleDocument.FCStd
  MainDocument.FCStd

Do you wish to rename references to MainDocument#Spreadsheet.RenamedValue? [y/N]
y ↵
2 document(s) updated.Supported FreeCAD VersionsCurrently only FreeCAD 19 and greater is supported.If changes are minimal, then supporting older versions may be considered.ChangelogSeeChangelog.ContributingSeeContributing Guidelines.