fcxref

Introduction
Motivation
Approach
Installation
Usage
Python API
Command Line
Supported FreeCAD Versions
Changelog
Contributing

Introduction

Manages FreeCAD external references.

“External references” are also known as external links or cross-document references.

The following operations are supported:

Finding external references
Renaming external references
and Removing external references (i.e. XLinks)

Motivation

On Expressions: 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.

fcxref aims to fill this gap until similiar functionality can be added to FreeCAD core.

See the following related FreeCAD forum discussions for additional motivation:

Approach

fcxref relies on parsing the Document.xml in compressed .FCStd files.

Installation

Available on the Python Package Index (PyPI).

pip install fcxref

Usage

There are two ways to use fcxref:

via the Python API
vai the Command Line

The following 2 sections cover these 2 usage methods with documents in the example/ directory.

Consider you have a MainDocument.FCStd containing a spreadsheet that drives your model, and ExampleDocument.FCStd that references aliases in that spreadsheet.

Python API

find

from fcxref import find, Query

base_path = './example'
references = find(base_path, Query('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

rename

The rename function takes:

the base path to look for FreeCAD documents in
the name or label of the document
the name or label of the object
and a 2-element tuple containing the property before and after renaming.

It returns a dictionary where keys are filepaths to updated .FCStd files, and values are XML Element objects representing updated Document.xml files.

from fcxref import rename

base_path = './example'
root_by_document_path = rename(base_path, 'MainDocument', 'Spreadsheet', ('Value', 'RenamedValue'))
print(root_by_document_path)

{'ExampleDocument.FCStd': <Element 'Document' at 0x7efcd281cc20>, 'MainDocument.FCStd': <Element 'Document' at 0x7f4d13c39270>}

remove

The remove function takes:

the base path to look for FreeCAD documents in
the name of the document (label is not supported)

It returns a dictionary where keys are filepaths to updated .FCStd files, and values are XML Element objects representing updated Document.xml files.

from fcxref import remove

base_path = './example'
root_by_document_path = remove(base_path, 'MainDocument')
print(root_by_document_path)

{'ExampleDocument.FCStd': <Element 'Document' at 0x7efcd281cc20>}

Command Line

Upon installing fcxref, the fcxref command will become globally accessible.

For usage information, pass --help to each command.

Each command scans for *.FCStd files recursively from the current working directory.

Thus, you should navigate to a directory where you store your FreeCAD documents before executing fcxref commands.

$ fcxref --help ↵
usage: fcxref [-h] [--version] {find,rename,remove} ...

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,remove}
    find                Find cross-document references to an object or property
    rename              Rename cross-document references to a property
    remove              Remove XLinks to specified document

find

$ 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 exit

Simple Queries

$ fcxref find MainDocument Spreadsheet Value ↵
ExampleDocument Spreadsheet.B1 content direct
ExampleDocument Spreadsheet.A1 content indirect
ExampleDocument Spreadsheet.B1 alias indirect
ExampleDocument Box.Length expression indirect

💡 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 exit

Simple Renames

The rename command 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.

remove

$ fcxref remove --help ↵
usage: fcxlink remove <document>

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

positional arguments:
  document    Document name of XLinks to remove.

optional arguments:
  -h, --help  show this help message and exit

Simple Removals

The remove command will prompt users for confirmation before modifying any files, and defaults to “No” if an explicit “Yes” is not provided.

$ fcxref remove MainDocument ↵
The following 1 document(s) contain XLinks to MainDocument:
  example/ExampleDocument.FCStd

Do you wish to remove XLinks to MainDocument? (this will break document linking) [y/N]
y ↵
1 document(s) updated.

Supported FreeCAD Versions

Currently only FreeCAD 19 and greater is supported.

If changes are minimal, then supporting older versions may be considered.

Changelog

See Changelog.

Contributing

See Contributing Guidelines.

Metadata

Release files for fcxref 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fcxref 0.4.0
File	Size	Uploaded	Provenance
fcxref-0.4.0.tar.gz	25.5 kB	Jan 2, 2025	Without provenance	Details

Release files / fcxref-0.4.0.tar.gz

Download URL	fcxref-0.4.0.tar.gz
Size	25.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`20df3d8e429a106a51caae87ee79578e425c5e67dc50a33690866996b005f153`
BLAKE2b-256 checksum How to use checksums	`9c0bee27b6c42fda7f242bc3d8cdcd29933a719ec681a8d71ca157f485696d03`
Upload date	Jan 2, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.10.12`

Security for fcxref 0.4.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.