Gatlen's Opinionated Template (GOTem)

Cutting-edge, opinionated, and ambitious project builder for power users and researchers.

Warning

Not yet ready for production and template may fail to work between versions.

Gatlen's Opinionated Template
(Logo = CookieCutter + Gatlen's Stylistic Motif - The Troublesome Goose)

GOTem is forked from (and synced with) CookieCutter Data Science (CCDS) V2, one of the most popular, flexible, and well maintained Python templates out there. GOTem extends CCDS with carefully selected defaults, dependency stack, customizations, additional features (that I maybe should have spent time contributing to the original project), and contemporary best practices. Ready for not just data science but also general Python development, research projects, and academic work.

Key Features

• 🚀 Modern Tooling & Living Template – Start with built-in support for UV, Ruff, FastAPI, Pydantic, Typer, Loguru, and Polars so you can tackle cutting-edge Python immediately. Template updates as environment changes.
• 🙌 Instant Git & CI/CD – Enjoy automatic repo creation, branch protections, and preconfigured GitHub Actions that streamline your workflow from day one.
• 🤝 Small-Scale to Scalable – Ideal for solo projects or small teams, yet robust enough to expand right along with your growth.
• 🏃‍♂️ Start Fast, Stay Strong – Encourages consistent structure, high-quality code, and minimal friction throughout your project's entire lifecycle.
• 🌐 Full-Stack + Rare Boilerplates – Covers standard DevOps, IDE configs, and publishing steps, plus extra setups for LaTeX assignments, web apps, CLI tools, and more—perfect for anyone seeking a "one-stop" solution.

Who is this for?

CCDS is white bread: simple, familiar, unoffensive, and waiting for your choice of toppings. GOTem is the expert-crafted and opinionated "everything burger," fully loaded from the start for any task you want to do (so long as you want to do it in a specific way). Some of the selections might be an acquired taste and users are encouraged to leave them off as they start and perhaps not all will appreciate my tastes even with time, but it is the setup I find delicious.

✅ Use GOTem if…	❌ Might Not Be for You if…
🍔 You Want the "Everything Burger" - You're cool with an opinionated, "fully loaded" setup, even if you don't use all the bells and whistles up front. - You love having modern defaults (FastAPI, Polars, Loguru). at the ready for any case life throws at you from school work to research to websites	🛣️ You're a Minimalist - You prefer the bare bones or "default" approach. - GOTem's many integrations and new libraries feel too "extra" or opinionated for you, adding more complexity than you want. When you really just want to "get the task done".
🎓 You're a Learner / Explorer - You like experimenting with cutting-edge tools (Polars, Typer, etc.) even if they're not as common. - "Modern Over Ubiquitous" libraries excite you.	🕰️ You're a Legacy Lover - Tried-and-true frameworks (e.g., Django, Pandas, standard logging) give you comfort. - You'd rather stick to old favorites than wrestle with fresh tech that might be less documented.
��‍💻 You're a Hacker / Tinkerer - You want code that's as sexy and elegant as it is functional. - You love tinkering, customizing, and "pretty colors" that keep the ADHD brain wrinkled.	🔎 You're a Micro-Optimizer - You need to dissect every configuration before even starting. - GOTem's "Aspirational Over Practical" angle might make you wary of unproven or cutting-edge setups.
⚡ You're a Perfection & Performance Seeker - You enjoy pushing Python's boundaries in speed, design, and maintainability. - You're always looking for the best solution, not just quick patches.	🏛️ You Need Old-School Stability - You want a large, established user base and predictable release cycles. - You get uneasy about lesser-known or younger libraries that might break your production environment.
🏃‍♂️ You're a Quick-Start Enthusiast - You want a template that practically configures itself so you can jump in. - You like having robust CI/CD, Git setup, and docs all done for you.	🚶‍♂️ You Prefer Slow, Manual Setups - You don't mind spending time creating everything from scratch for each new project. - Doing things the classic or "official" way is more comfortable than using "opinionated" shortcuts.

If the right-hand column describes you better, CookieCutter Data Science (CCDS) or another minimal template might be a better fit.

View the full documentation here ➡️

---

Getting Started

⚡️ With UV (Recommended)

uv tool install gatlens-opinionated-template

# From the parent directory where you want your project
uvx --from gatlens-opinionated-template gotem

📦 With Pipx

pipx install gatlens-opinionated-template

# From the parent directory where you want your project
gotem

🐍 With Pip

pip install gatlens-opinionated-template

# From the parent directory where you want your project
gotem

Note: If using GitHub, you will verst have to run gh auth login

The resulting directory structure

The directory structure of your new project will look something like this (depending on the settings that you choose):

📁 .
├── ⚙️ .cursorrules                    <- LLM instructions for Cursor IDE
├── 💻 .devcontainer                   <- Devcontainer config
├── ⚙️ .gitattributes                  <- GIT-LFS Setup Configuration
├── 🧑‍💻 .github
│   ├── ⚡️ actions
│   │   └── 📁 setup-python-env       <- Automated python setup w/ uv
│   ├── 💡 ISSUE_TEMPLATE             <- Templates for Raising Issues on GH
│   ├── 💡 pull_request_template.md   <- Template for making GitHub PR
│   └── ⚡️ workflows
│       ├── 🚀 main.yml               <- Automated cross-platform testing w/ uv, precommit, deptry,
│       └── 🚀 on-release-main.yml    <- Automated mkdocs updates
├── 💻 .vscode                        <- Preconfigured extensions, debug profiles, workspaces, and tasks for VSCode/Cursor powerusers
│   ├── 🚀 launch.json
│   ├── ⚙️ settings.json
│   ├── 📋 tasks.json
│   └── ⚙️ '{{ cookiecutter.repo_name }}.code-workspace'
├── 📁 data
│   ├── 📁 external                      <- Data from third party sources
│   ├── 📁 interim                       <- Intermediate data that has been transformed
│   ├── 📁 processed                     <- The final, canonical data sets for modeling
│   └── 📁 raw                           <- The original, immutable data dump
├── 🐳 docker                            <- Docker configuration for reproducability
├── 📚 docs                              <- Project documentation (using mkdocs)
├── 👩‍⚖️ LICENSE                           <- Open-source license if one is chosen
├── 📋 logs                              <- Preconfigured logging directory for
├── 👷‍♂️ Makefile                          <- Makefile with convenience commands (PyPi publishing, formatting, testing, and more)
├── 🚀 Taskfile.yml                    <- Modern alternative to Makefile w/ same functionality
├── 📁 notebooks                         <- Jupyter notebooks
│   ├── 📓 01_name_example.ipynb
│   └── 📰 README.md
├── 🗑️ out
│   ├── 📁 features                      <- Extracted Features
│   ├── 📁 models                        <- Trained and serialized models
│   └── 📚 reports                       <- Generated analysis
│       └── 📊 figures                   <- Generated graphics and figures
├── ⚙️ pyproject.toml                     <- Project configuration file w/ carefully selected dependency stacks
├── 📰 README.md                         <- The top-level README
├── 🔒 secrets                           <- Ignored project-level secrets directory to keep API keys and SSH keys safe and separate from your system (no setting up a new SSH-key in ~/.ssh for every project)
│   └── ⚙️ schema                         <- Clearly outline expected variables
│       ├── ⚙️ example.env
│       └── 🔑 ssh
│           ├── ⚙️ example.config.ssh
│           ├── 🔑 example.something.key
│           └── 🔑 example.something.pub
└── 🚰 '{{ cookiecutter.module_name }}'  <- Easily publishable source code
    ├── ⚙️ config.py                     <- Store useful variables and configuration (Preset)
    ├── 🐍 dataset.py                    <- Scripts to download or generate data
    ├── 🐍 features.py                   <- Code to create features for modeling
    ├── 📁 modeling
    │   ├── 🐍 __init__.py
    │   ├── 🐍 predict.py               <- Code to run model inference with trained models
    │   └── 🐍 train.py                 <- Code to train models
    └── 🐍 plots.py                     <- Code to create visualizations

Contributing ❤️

If you plan major changes, consider upstreaming them to CookieCutter Data Science (CCDS). For minor fixes or adjustments to GOTem, submit an issue or pull request here. See CONTRIBUTING.md for more details.

Known Issues

Some users have experienced an issue with Git LFS being improperly configured. I'm currently working to get this resolved. It's reported that the following may fix the problem:

1. Clone the package manually git clone <this-repo>
2. Set up git lfs, skipping smudge git lfs install --skip-smudge as suggested here
3. Install the package with pip install .