How emuuli/tsl-tiivad works
Project type and purpose
• This is an open-source Python library (published on PyPI as “tiivad”) that provides automated code‐analysis and evaluation functionality.
• It also includes a Docker-based evaluation environment, where assessment code and sample solutions are run under controlled conditions.
File structure
Top level:
• setup.py, requirements.txt, LICENSE, README.md → packaging, dependencies, meta-information
• tiivad/ → the core Python package with submodules for capturing I/O, analyzing syntax trees, execution, file contents, and orchestrating handlers
• docker/ → Docker context for building two images:
– tiivad-base: installs the tiivad library
– evaluate: bundles assessment_code.py, sample solution (lahendus.py), and an evaluate.sh script
README for additional insights
• Describes how to install, package, and publish to PyPI
• Outlines local testing with pytest
• Gives step-by-step Docker build/run commands for the “evaluator” container
a. Main components:
1. Core Library (“tiivad” package)
• capture_io.py
• syntax_tree_analyzer.py
• execution_analyzer.py
• file_analyzer.py
• handler.py (orchestrates analysis flow)
• results.py (collects and formats outcomes)
2. CLI / Entry Points
• setup.py → installs console scripts (if any)
• assessment_code.py → sample runner for Docker evaluate image
3. Testing Layer
• pytest test suite (invoked via python ‑m pytest)
4. Packaging & Distribution
• setup.py + version.py → sdist → twine → PyPI
5. Docker Environment
• Dockerfile-tiivad-base → builds base image with tiivad
• Dockerfile-evaluate → builds evaluation image with assessment code & sample solution
• evaluate.sh → runs code under tiivad and emits logs
6. External Services
• PyPI (package registry)
• Docker Hub or local Docker daemon
b. Relationships and interactions:
• The Core Library modules collaborate: handler.py invokes capture_io, syntax_tree_analyzer, execution_analyzer, file_analyzer; results are aggregated in results.py.
• CLI scripts or the evaluate.sh wrapper call the handler entry-point in the container.
• Tests import tiivad modules and assert analyzer behavior.
• setup.py packages the library, updates version.py, and pushes to PyPI.
• Docker build of tiivad-base uses PyPI to install the released library version.
• Docker evaluate image layers on the base, adds assessment & solution code, then runs evaluate.sh to exercise tiivad.
• Users pull the evaluate image, start a container, and view logs via docker logs.
c. Architectural patterns & design principles:
• Modularity: distinct analyzers for different concerns (I/O capture, syntax analysis, execution tracing).
• Single Responsibility: each module has a clear purpose; handler orchestrates.
• Layered deployment: library → packaging → Docker base → Docker evaluator.
• Testable: decoupled modules allow pytest coverage.
d. Relevant technologies & libraries:
• Python 3.10
• pytest for testing
• setuptools (setup.py) for packaging
• twine for PyPI upload
• Docker & shell scripts (evaluate.sh)
Final recommendation
• Every module and script as its own node.
• How code flows from source files, through the handler, into analyzers, then out to results.
• Multi-stage Docker build and runtime evaluation environment separately but connected via the library’s PyPI distribution.