uproot

About

uproot is a modern software framework for developing and conducting browser-based behavioral experiments. This includes studies with hundreds of participants such as large-scale surveys and experiments with real-time interaction between the participants.

uproot is 100% Free/Libre Open Source Software, and contains only unencumbered code. All libraries, styles and fonts are included and served locally (no CDNs).

We are working on producing the first alpha version (0.0.1), and invite you to join us.

Important

This repository contains a pre-alpha version. Breaking changes are made with reckless abandon.

Getting started

Installing uproot via the command line

Prerequisites: You need Python 3.11+ and be within an activated virtual environment. If you don't have Python installed yet, see the detailed setup guide below.

1. Run this from within a Python venv:

   pip install -U 'uproot-science[dev] @ git+https://github.com/mrpg/uproot.git@main'

   If this does not work, try

   pip install -U 'uproot-science[dev] @ https://github.com/mrpg/uproot/archive/main.zip'

   or

   pip install -U https://github.com/mrpg/uproot/archive/main.zip

2. Then, you may do:

   uproot setup my_project

3. The resulting output shows you how to proceed. Have fun!

After running uproot run, we recommend you visit the admin area with the provided credential.

Example apps

Example apps may be found here.

Detailed Python and virtual environment setup

If you're new to Python or don't have Python 3.11+ installed, follow these platform-specific guides:

Windows

1. Install Python (requires administrator privileges):

   • Download Python 3.11+ from python.org
   • Run the installer as administrator
   • Select the following advanced options:
     • Important: During installation, check "Add Python to PATH" - this is crucial
     • Choose "Install for all users"
   • Verify installation by opening Command Prompt and running:

     python --version

2. Create and activate virtual environment: Start PowerShell and run:

   python -m venv env

   Before activating: You may need to allow script execution by running PowerShell as administrator and executing:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

   Then activate the environment:

   env\Scripts\activate

3. Continue with the main installation guide above

macOS

1. Install Python:

   • Option 1 - Using Homebrew (recommended):

     brew install python

   • Option 2 - Download Python 3.11+ from python.org

   • Verify installation:

     python3 --version

2. Create and activate virtual environment:

   python3 -m venv env
   source env/bin/activate

3. Continue with the main installation guide above

Linux

Most Linux distributions include Python, but you may need to install the virtual environment module:

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-venv

# Create and activate virtual environment
python3 -m venv env
source env/bin/activate

Note: Always activate your virtual environment (env) before installing or running uproot. You'll know it's active when you see (env) at the beginning of your command prompt.

Development best practices

We follow these development practices to maintain code quality:

Code Quality Tools

• Code formatting: Black for consistent code formatting
• Import sorting: isort with Black profile compatibility
• Type checking: mypy with strict typing enabled
• Linting: Ruff for fast Python linting
• Complexity analysis: Radon for measuring code complexity and maintainability
• Dependency management: pip-tools for reproducible dependency pinning

Security Tools

• Security scanning: Bandit for detecting security vulnerabilities
• Dependency auditing: pip-audit for scanning dependencies for known CVEs
• Advanced analysis: Semgrep for pattern-based security and correctness checking
• Dependency checking: Deptry for finding unused and missing dependencies

Testing

• Testing framework: pytest with coverage reporting via pytest-cov
• Async testing: pytest-asyncio for testing asynchronous code
• Code coverage: Coverage reports show missing lines for comprehensive testing

Automation

• Pre-commit hooks: Automated checks before each commit
• CI/CD: GitHub Actions workflow running all checks on pull requests
• Make commands: Convenient make targets for common tasks

Quick Start for Development

1. Install development dependencies:

   make install

2. Run all checks:

   make all

3. Available commands:

   make help              # Show all available commands
   make format            # Auto-format code
   make lint              # Run linting checks
   make type-check        # Run mypy
   make security          # Run security scans
   make quality           # Run code quality checks
   make test              # Run tests with coverage
   make requirements      # Compile requirements.txt

4. Pre-commit hooks: Automatically installed with make install. Manually run with:

   pre-commit run --all-files

Standards

• Python version: Minimum Python 3.11 required
• Database support: Optional PostgreSQL support via psycopg
• Versioning: Semantic versioning (MAJOR.MINOR.PATCH)

All development dependencies are included in the [dev] optional dependency group.

License

uproot is licensed under the GNU LGPL version 3.0, or, at your option, any later version. Among other things, that means: (1) there is no warranty; (2) changes to uproot’s core are automatically licensed under the LGPL as well, (3) you are free to license your own experiments under whatever license you deem appropriate, or no license at all.

© Max R. P. Grossmann, Holger Gerhardt, et al., 2025. A full alphabetical overview of contributors may be viewed here.