Disclaimer

The views and opinions expressed in this presentation are those of the individual presenters and do not represent those of their affiliated organizations or institutions.

Acknowledgements

Integrated Development Environments (IDEs)

Two recommended options:

GitHub Codespaces

• Cloud-based, pre-configured, convenient for collaboration
• Linux system with full admin access, so you can install any tools you need
• No local setup needed, only requires a GitHub account and a browser
• Free usage 120 hours/month
• Each codespace can be linked to an existing GitHub repo or empty template

VS Code

• Most popular choice
• Rich extension ecosystem for all programming languages and tools
• Leading platform for GitHub Copilot that provides the most feature-rich and integrated experience

GitHub Codespaces

VS Code

Alternative IDEs

Positron

• Posit’s next-gen IDE, built on Code OSS (the core of VS Code)
• Primarily support R and Python
• Native notebook support
• Built-in data viewer (similar four-panel layout as RStudio)
• Built-in AI assistant with native GitHub Copilot integration

JupyterLab

• Popular in data science community
• Interactive computing environment
• Supports code, data/figure visualization and documentation in cell-by-cell notebooks
• Additional kernels can be installed to work with a wide range of other programming languages

Python environment management

Python projects rely heavily on rapidly evolving open-source libraries that often have conflicting version requirements.

• In contrast, R often uses a single global library for all projects

• Python package and project managers are essential because they prevent version conflicts by isolating each project’s specific dependencies into its own dedicated environment.

Key goal: Ensure reproducibility across different machines/platforms and over time, which is critical for regulatory submissions!

What we need

Why uv?

uv is a modern Python package and project manager written in Rust.

All-in-One tool that handles Python environments, package dependencies, project maintenance, builds and publishing in a single workflow.

Replaces scattered toolchain:

• pip + venv + pyenv + pip-tools + setuptools + poetry…

Additional benefits:

• Fast: 10-100x faster than traditional Python package managers like pip
• Modern: Uses standard format pyproject.toml as the single source of truth, which prevents conflicting information scattered across multiple files
• Reliable: Automatically creates or updates the universal cross-platform lockfile uv.lock for to ensure reproducible and deterministic environments
• Independence: Has its own official standalone installer, coexist with Homebrew and the broader macOS ecosystem better than traditional tools like pyenv or Poetry

Installing uv

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify:

uv --version

More installation options here.

Quick start with uv - New project

Create a new project

uv init toyexample

Check the created files:

cd toyexample
ls -al

Create the first commit:

git status
git add --all
git commit -m "Initialize project with uv"

Pin Python version

uv python pin 3.14.0

List installed packages (empty at this point)

uv pip list

Quick start with uv - Package management

Add dependencies

uv add polars plotnine rtflite

Add dev dependencies

uv add --dev ruff mypy pytest pytest-cov

Manually edit pyproject.toml to add additional dependencies or dev-dependencies sections, e.g. dependencies = ["scikit-learn", "seaborn","dash"], then try the following commands -

Resolves dependencies:

uv lock --check  # check whether uv.lock is out-of-sync with pyproject.toml
uv lock # update the lock file with the new dependencies

Sync environment:

uv sync # install the new dependencies

Quick start with uv - Using the virtual environment

Revise the main.py file to test the installed packages, e.g.

import rtflite

def main():
    print("rtflite version:", rtflite.__version__)

Try running the two commands below -

uv run python main.py
python main.py

Activate the virtual environment installed by uv

source /workspace/codespaces-blank/toyexample/.venv/bin/activate

Deactivate the virtual environment when you are done

deactivate

Quick start with uv - Additional commands

Update uv itself

uv self update

Upgrade packages and sync environment

uv lock --upgrade-package plotnine # only updates the uv.lock file and pyproject.toml
uv sync # update the environment with the new plotnine version

Uninstall packages

uv remove scikit-learn seaborn dash

For more details, refer to the uv official guide

Alternatives

Conda

• Manages Python versions and packages by creating isolated environments
• Popular in data science, since it handles both Python and non-Python dependencies (e.g., C++ libraries, CUDA, or R)
• Not as fast or modern as uv
• Recommend Miniconda (the official minimal installer from Anaconda, Inc.) or Miniforge (community-driven alternative installer, 100% free and faster)

Poetry

• Python package manager that handles dependency, packaging and publishing
• Uses pyproject.toml
• Not as comprehensive as uv for environment management
• Long-standing and widely used in the Python community: Mature, stable and well-documented

Typical Development Workflow

• Code formatting and linting: Improves code format quality, readability, consistency, and catches errors early
• Verify data/variable types: Improves functional safety
• Run tests and check coverage: Validates code behavior, ensures correctness, and identifies untested code
• Generate documentation or reproducible user guides: Facilitate collaboration and application
• Use Git for version control and collaboration: Ensure all the changes are tracked and well-documented, and enable seamless collaboration across teams

Recommended Python Toolchain: Ruff

Ruff - Code formatting and linting

uv run ruff format . # spacing, line breaks, and indentation etc.
uv run ruff format --check . # check whether the code is properly formatted without making changes
uv run ruff check .  # check for linting issues (e.g., unused imports, naming conventions, potential bugs) without making changes
uv run ruff check --fix . # Try to automatically fix linting issues where possible

Add this function to main.py and run ruff to see the formatting and linting suggestions

def fun_add(a,b):
    output=a+b
    print("Results:", output)
    return output

Recommended Python Toolchain: mypy

mypy - Type checking

uv run mypy .
uv run mypy main.py

Add the following code to main.py and run mypy to see the type checking errors

def fun_add(a: int, b: int) -> int:
    output = a + b
    print("Results:", output)
    return output

def fun_concat(s1: str, s2: str) -> str:
    output = s1 + s2
    print("Results:", output)
    return output

def main():
    pass

if __name__ == "__main__":
    main()
    fun_add(1, 2)  # correct usage
    fun_add(1, "2")  # type error, mypy will catch this
    fun_concat("Hello, ", "world!")  # correct usage
    fun_concat("Hello, ", 5)  # type error, mypy will catch this

Recommended Python Toolchain: pytest

pytest - Testing framework

# (example syntax, do not run)
uv run pytest tests/
uv run pytest --cov=src/rtflite tests/

Save the code below to run_pytests.py

from main import fun_add, fun_concat

def test_fun_add_integers():
    assert fun_add(1, 2) == 3

def test_fun_concat_strings():
    assert fun_concat("Hello, ", "world!") == "Hello, world!"

Run the following terminal commands to see how pytest works with uv

uv run pytest run_pytests.py
uv run pytest run_pytests.py --cov=main
uv run pytest run_pytests.py --cov=main --cov-report=html

Recommended Python Toolchain: Documentation

quarto - Documentation and report generation

quartodoc build
quarto render report.qmd

Alternative tools:

• Docstrings: Use triple quotes to document functions and classes
• Sphinx: Generate documentation from docstrings
• Github Pages: Host documentation online
• GitHub Wiki: Internal documentation
• Jupyter Notebooks: Combine code, documentation, and visualizations in an interactive format

Key concepts

Virtual environments are mandatory in Python

• Isolate project dependencies
• Prevent conflicts
• Enable reproducibility

Dependency locking

• uv.lock pins exact versions
• Ensures reproducible environments
• Similar to R’s renv.lock

.python-version file

• Specifies exact Python version (for example, 3.14.0)
• Critical for regulatory submissions

Action Items

Pre-configured GitHub Codespaces:

# Dependencies are already synced on creation
uv run python scripts/tlf_t_ae.py   # run a script
uv run quarto render report.qmd     # render a report
uv run pytest tests/                # run tests

eBook: Python for Clinical Study Reports and Submission: pycsr.org

Resources

Regulatory:

• FDA Study Data Technical Conformance Guide
• eCTD specifications

Technical:

• rtflite
• pkglite for Python
• uv documentation

MiniConda and Miniforge

conda create -n myenv python=3.14
conda activate myenv
conda install numpy pandas matplotlib
conda install -c conda-forge polars plotnine
pip install rtflite
conda list
conda update numpy
conda remove matplotlib
conda env export > environment.yml
conda deactivate
conda info --envs // conda env list
conda env remove --name myenv

Python package and project manager: Traditional & Specialized Tools

• pip: The standard, built-in package installer for Python, essential for downloading packages from PyPI.
• Pipenv: Combines pip, pipfile, and virtualenv into a single toolchain, focusing on secure, locked dependency management.
• Poetry: Focuses on deterministic dependency management and packaging, using pyproject.toml for projects and publishing.
• Conda: A popular cross-platform manager (often used in data science) that handles Python packages and non-Python dependencies.
• pipx: Specialized in installing and running Python application CLI tools, keeping them isolated from project dependencies.

Key Concepts in Python Packaging

• pyproject.toml: The modern, standard file for configuring build systems and defining metadata/dependencies.
• Virtual Environments (venv): Isolated environments to prevent dependency conflicts between projects.
• PyPI (Python Package Index): The repository for all open-source Python packages.
• Modules & Packages: Structured code (files and directories) that enable reusability.

For modern projects, uv is heavily recommended for its efficiency, while pip remains the standard for basic needs.