Source extraction

Raw structures produced by source adapters before transformation.

type acmad_uploader.sources.models.CellValue = str | int | float | bool | date | datetime | time | None

class acmad_uploader.sources.models.SourceFile(path, relative_path, size_bytes)

Bases: object

File discovered inside an upload package.

path: Path

relative_path: PurePosixPath

size_bytes: int

property extension: str

Return the lower-case extension, including the leading dot.

class acmad_uploader.sources.models.SourcePackage(root, files)

Bases: object

Immutable inventory of files beneath an upload root.

root: Path

files: tuple[SourceFile, ...]

property size_bytes: int

Return the total size of all discovered files.

class acmad_uploader.sources.models.SourceField(key, value, location)

Bases: object

Raw field value and its workbook provenance.

key: str

value: CellValue

location: SourceLocation

class acmad_uploader.sources.models.VerticalForm(path, sheet, version, fields)

Bases: object

Extracted two-column workbook form.

Fields remain ordered and may contain duplicate keys. Version-specific transformers decide how duplicate or repeated keys should be interpreted.

path: Path

sheet: str

version: str | None

fields: tuple[SourceField, ...]

values_for(key)

Return every value recorded for key in source order.

Return type:

tuple[str | int | float | bool | date | datetime | time | None, ...]

value_for(key)

Return the sole value for key.

Raises:

• KeyError – When the key is absent.

• ValueError – When the key occurs more than once.

Return type:

str | int | float | bool | date | datetime | time | None

Filesystem source discovery without clinical or API interpretation.

class acmad_uploader.sources.filesystem.FilesystemPackageExtractor

Bases: object

Inventory regular files beneath a source directory.

extract(source)

Discover source files in deterministic relative-path order.

Return type:

StageResult[SourcePackage]

Extraction of vertical two-column Excel forms.

class acmad_uploader.sources.excel.VerticalFormExtractor(*, sheet_name=None)

Bases: object

Read one worksheet whose keys and values occupy columns A and B.

extract(source)

Extract a vertical form while retaining cell provenance.

Return type:

StageResult[VerticalForm]

Shared discovery and extraction of vertical-form workbook packages.

acmad_uploader.sources.workbooks.discover_workbooks(path, names)

Return workbooks matching names beneath path, in path order.

Return type:

tuple[Path, ...]

acmad_uploader.sources.workbooks.extract_workbooks(source, *, names, form_extractor, missing_code, missing_message)

Discover matching workbooks and extract each into a vertical form.

Return type:

StageResult[tuple[VerticalForm, ...]]

Loading of the optional package-level configuration file.

A YAML file at the package root persists settings a site would otherwise repeat on every invocation: the site acronym and the API/OIDC endpoints. Precedence is always CLI flag > config file > built-in default, so the config never silently overrides an explicit flag. Nothing is inferred from folder names - see CLAUDE.md’s “folder names are a human-browsing convenience, not the source of truth” principle, which this deliberately does not override.

class acmad_uploader.sources.config.AppConfig(site=None, api_url=None, realm_url=None, client_id=None)

Bases: object

Values loaded from the package-level config file (all optional).

site: str | None

api_url: str | None

realm_url: str | None

client_id: str | None

acmad_uploader.sources.config.load_config(path)

Load the config file next to a package, if present.

Looks at path itself (or its parent, if path is a single workbook rather than a package directory) - never searched recursively, since this is a package-level setting. An absent file is not an error (an empty AppConfig is returned); a malformed one is.

Return type:

tuple[AppConfig, tuple[PipelineIssue, ...]]

acmad_uploader.sources.config.resolve_site_override(config, *, cli_value)

Resolve the effective site override from the CLI flag or config.

The CLI --site flag wins; the config file’s site is the fallback. Returns None when neither supplies a value, preserving the “no override” behaviour for callers that use neither.

Return type:

SiteOverride | None

Discovery and extraction of patient record workbooks.

class acmad_uploader.sources.patient.PatientWorkbookExtractor(form_extractor=None)

Bases: object

Extract all patient_record.xlsx workbooks beneath a package path.

extract(source)

Discover patient workbooks and extract their vertical forms.

Return type:

StageResult[tuple[VerticalForm, ...]]

Discovery and extraction of patient record workbooks for diagnoses.

class acmad_uploader.sources.diagnosis.DiagnosisWorkbookExtractor(form_extractor=None)

Bases: object

Extract diagnosis fields carried by patient_record.xlsx workbooks.

Diagnoses are recorded inline on the patient record rather than in a dedicated workbook: each upload carries at most one primary and one secondary diagnosis snapshot, and a patient’s full diagnosis history accumulates across repeated uploads over time as new snapshots are taken (see DiagnosisTransformer).

extract(source)

Discover patient workbooks and extract their vertical forms.

Return type:

StageResult[tuple[VerticalForm, ...]]

Discovery and extraction of gait assessment workbooks.

class acmad_uploader.sources.gait_assessment.GaitAssessmentWorkbookExtractor(form_extractor=None)

Bases: object

Extract every gait assessment workbook beneath a package path.

Physical exam, function/PROMs and mocap workbooks each record their own site_patient_id and gaitass_age, so assessments are joined by that pair at the transform stage rather than by folder position.

extract(source)

Discover gait assessment workbooks and extract their vertical forms.

Return type:

StageResult[tuple[VerticalForm, ...]]

Discovery and extraction of function/PROMs workbooks.

class acmad_uploader.sources.function_assessment.FunctionAssessmentWorkbookExtractor(form_extractor=None)

Bases: object

Extract all function_proms.xlsx workbooks beneath a package path.

extract(source)

Discover function/PROMs workbooks and extract their vertical forms.

Return type:

StageResult[tuple[VerticalForm, ...]]

Discovery and extraction of mocap workbooks.

class acmad_uploader.sources.mocap_data.MocapDataWorkbookExtractor(form_extractor=None)

Bases: object

Extract all mocap.xlsx workbooks beneath a package path.

Each mocap session/condition (mocap_<condition>/mocap.xlsx) is its own workbook, unlike gait assessment’s siblings which get joined by natural key — every mocap.xlsx becomes its own canonical record.

extract(source)

Discover mocap workbooks and extract their vertical forms.

Return type:

StageResult[tuple[VerticalForm, ...]]

Discovery of mocap session folders and their associated biomechanics files.

class acmad_uploader.sources.biomechanics_artifact.BiomechanicsArtifactSource(mocap_forms, package)

Bases: object

Every mocap.xlsx form plus the full file inventory for the package.

mocap_forms: tuple[VerticalForm, ...]

package: SourcePackage

class acmad_uploader.sources.biomechanics_artifact.BiomechanicsArtifactSourceExtractor(mocap_extractor=None, filesystem_extractor=None)

Bases: object

Combine mocap workbook discovery with a full filesystem inventory.

Each mocap_<condition> folder’s own mocap.xlsx anchors which files belong to that session — transformers/biomechanics_artifact.py groups the filesystem inventory by that folder. The file layout itself is the real biomechanics package structure exported by the C3D-Parser pipeline, not something the ETL otherwise interprets or converts.

extract(source)

Discover every mocap workbook and the package’s full file inventory.

Return type:

StageResult[BiomechanicsArtifactSource]

Discovery and extraction of physical examination workbooks.

class acmad_uploader.sources.physical_examination.PhysicalExaminationWorkbookExtractor(form_extractor=None)

Bases: object

Extract all physical_exam.xlsx workbooks beneath a package path.

extract(source)

Discover physical exam workbooks and extract their vertical forms.

Return type:

StageResult[tuple[VerticalForm, ...]]

Discovery and extraction of function/PROMs workbooks for the PROMs family.

class acmad_uploader.sources.proms.PromsWorkbookExtractor(form_extractor=None)

Bases: object

Extract all function_proms.xlsx workbooks beneath a package path.

extract(source)

Discover function/PROMs workbooks and extract their vertical forms.

Return type:

StageResult[tuple[VerticalForm, ...]]

Discovery and extraction of surgery workbooks.

class acmad_uploader.sources.surgery.SurgeryWorkbookExtractor(form_extractor=None)

Bases: object

Extract all surgery.xlsx workbooks beneath a package path.

extract(source)

Discover surgery workbooks and extract their vertical forms.

Return type:

StageResult[tuple[VerticalForm, ...]]