How marnunez/basictdf works
Project type and purpose
• This is an open-source Python library (basictdf) for reading and writing the BTS Bioengineering TDF binary data format.
• Its core responsibility is to parse a .tdf file into in-memory Python objects (and vice versa), expose a clean API for clients, and ship documentation and tests with CI/CD.
File structure
• src/basictdf/: the heart of the parser. Contains:
• basictdf.py – top-level façade
• tdfBlock.py, tdfCalibrationData.py, tdfData2D.py, tdfData3D.py, tdfEMG.py, tdfEvents.py, tdfForce3D.py, tdfForcePlatformsCalibration.py, tdfForcePlatformsData.py, tdfOpticalSystem.py, tdfTypes.py, tdfUtils.py
– these map to the various components (blocks) of the TDF format.
• tests/: unit tests for each component and end-to-end file parsing.
• .github/workflows/: CI pipelines for testing and publishing to TestPyPI.
• docs/: generated HTML docs for each module.
• pyproject.toml & tox.ini: build, test, and packaging config.
README for additional insights
• It confirms usage via pip install basictdf (PyPI distribution) and docs hosted on GitHub Pages.
• Development uses Poetry for dependency management.
• No external microservices or DB—just file I/O and in-process parsing.
a. Main components
• Client Application – any user script that calls basictdf API
• I/O Layer – file reader/writer (wrapped around Python’s open, io, struct)
• Parser Engine – orchestrates parsing: reads block headers, dispatches to specific block parsers
• Block Parsers & Data Models – modules for each TDF block type (Block, CalibrationData, Data2D, Data3D, EMG, Events, Force3D, ForcePlatformsCalibration, ForcePlatformsData, OpticalSystem)
• Utility Module – common functions (byte conversions, checksum, etc.)
• Packaging & Distribution – Poetry, PyPI
• Documentation Generator – Sphinx (via docs folder)
• CI/CD – GitHub Actions (test.yml, publish-to-test-pypi.yml)
b. Relationships & interactions
1. Client calls basictdf.read_tdf(filename)
2. I/O Layer reads raw bytes → feeds Parser Engine
3. Parser Engine uses Utility Module to interpret headers and routes payload to the proper Block Parser
4. Block Parser instantiates a Data Model object, populates fields, returns it to the engine
5. Engine assembles all blocks into a high-level Python object and returns to client
6. Client can manipulate objects, then call basictdf.write_tdf(obj, filename) to reverse the flow
7. On commit, CI/CD runs tests, builds docs, optionally publishes to TestPyPI
8. Documentation Generator consumes docstrings in source to produce HTML in docs/
c. Architectural patterns & design principles
• Modular parsing: one parser per block type (Separation of Concerns)
• Layered design: I/O → Engine → Data Models → Client
• Convention over configuration: naming of modules matches TDF block names
• CI/CD as code: GitHub workflows define build/test/publish steps
d. Key technologies & libraries
• Python’s built-ins: io, struct, pathlib
• Poetry for dependency & packaging
• Sphinx (implied by docs) for documentation
• pytest or unittest for tests
• GitHub Actions for CI/CD
Diagramming recommendations
• Blue for runtime components (I/O, Engine, Parsers)
• Green for external dependencies (file system, PyPI, GitHub Actions)
• Yellow for development tooling (Poetry, Sphinx)