Skip to content

Installation Guide

Preview Version

This documentation is currently being worked on and may be incomplete or subject to change. If you spot any mistakes or have suggestions, please contact one of the maintainers.

System requirements

Python Version

  • This project requires Python version 3.12 or higher. Ensure you have the correct version installed on your system.

Operating System

  • Cross-Platform: Support for .ppttc generation and basic .pptx generation on Windows, macOS, and Linux.
  • Windows and MacOS Only: For advanced .pptx generation with Think-Cell integration, an active Think-Cell installation and license is required.

.ppttc to .pptx conversion

While you can generate a .ppttc file on any Operating System, conversion from .ppttc to .pptx requires a Think-Cell installation, which is only available on Windows and MacOS.

Think-Cell Requirements

Think-Cell integration is optional and only required for Think-Cell objects.

  • Valid Think-Cell license and active Think-Cell installation is required for .pptx generation with Think-Cell objects.
  • Download Think-Cell from the official website.
  • Default installation paths:
    • Windows: C:/Program Files (x86)/think-cell/ppttc.exe
    • MacOS: /Users/{YOUR_USERNAME}/Library/Application Support/think-cell

Dependencies

This project relies on several Python packages. You can install them using pip or uv:

Package Version Purpose
pandas ≥ 2.0.0 Data handling and manipulation
python-pptx ≥ 0.6.21 PowerPoint file generation and manipulation
openpyxl ≥ 3.1.0 Excel file reading and writing
thinkcellbuilder ≥ 0.1.1* Think-Cell file support

Thinkcellbuilder Dependency

The project uses a patched version of thinkcellbuilder that includes a NaN bug fix. The dependency is sourced from this fork.

Installation Methods

Method 1: Default Installation

Clone the repository and install the required dependencies:

git clone https://github.com/Effctl/effctl-report-generator/
cd effctl-report-generator
pip install -e .

Editable Mode

The -e flag installs the package in editable mode, meaning any changes you make to the source code, will immediatelly be reflected without needing to reinstall the package.

Using a virtual environment helps isolate project dependencies. This helps debugging but also setting up a clean workspace. Follow these steps:

git clone https://github.com/Effctl/effctl-report-generator/
cd effctl-report-generator
python -m venv .venv
.venv\Scripts\activate.bat
pip install -e .

git clone https://github.com/Effctl/effctl-report-generator/
cd effctl-report-generator
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .

git clone https://github.com/Effctl/effctl-report-generator/
cd effctl-report-generator
python -m venv .venv
source .venv/bin/activate
pip install -e .

Method 3: Development Installation

For contributors and developers, install the package with development dependencies:

pip install -e ".[dev]"

This installs additional tools for testing and code quality measures including:

  • pytest for testing
  • pytest-cov for test coverage analysis
  • flake8 for code style enforcement
  • black for code formatting

Verifying Installation

Verify your installation by importing the library:

from effctl_lib import (
    format_excel_data,
    traverse_pptx,
    ppttc_to_pptx,
    TOMLConfig
)
print("Installation successful!")

Post-Installation Steps

Directory Structure

After installation, your project directory should look like this:

effctl-report-generator/
├── effctl_lib/ # Core library code
├── data        # Data files stored during processing
├── notebooks/  # Interactive Jupyter Notebooks
├── output/     # Generated output files
└── resources/  # Sample resources (templates, data files)

Creating missing directories:

mkdir data notebooks output resources

Configuration

The project can be configured using a config.toml file. A default configuration file is provided in the repository. You can customize it as needed. If the file is missing, create one with: 

touch config.toml

See the Configuration Guide for more details on available configuration options.

Troubleshooting

Common Issues

Import Error: Module Not Found

ModuleNotFoundError: No module named 'effctl_lib'

Solution: Ensure you have installed the package in editable mode using pip install -e . and that you are running your script in the correct environment.

Think-Cell Path Issues

FileNotFoundError: ppttc.exe not found

Think-Cell Path Error Message

This error message may vary depending on your operating system and the specific issue encountered.

Solution: Verify that Think-Cell is installed and that the path to ppttc.exe is correct. Update the path in your script or configuration file if necessary:

ppttc_path = "C:/Program Files (x86)/think-cell/ppttc.exe"  
# or your custom installation path

Permission Denied Errors on Windows

Solution: Run your terminal as Adminstrator when installing. Alternatively, ensure you have write permissions to the installation directory.

Virtual Environment Issues

Windows PowerShell: You may need to enable script execution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Updating the Project

To update the project to the latest version, run:

cd effctl-report-generator
git pull origin main
pip install -e .

Uninstallation Guide

You can uninstall the package using pip:

pip uninstall effctl-lib

To remove the cloned repository, simply delete the project directory:

rmdir /s /q effctl-report-generator

rm -rf effctl-report-generator

Recursive deletion commands

Both rm -rf (MacOS/Linux) and rmdir /s /q (Windows) permanently delete directories and their contents without confirmation. Only use them if you fully understand what you are deleting. Otherwise, delete the folder using your file manager (e.g. File Explorer)