python-repo-quickstart

name

python-repo-quickstart

description

Quickly analyzes Python repositories to understand their purpose, structure, and setup requirements. Use when Claude needs to onboard to a new Python codebase, understand project structure, identify entry points, determine dependencies, or generate setup instructions. Trigger when users ask to "analyze this Python repo", "understand this codebase", "how do I run this project", "what does this repo do", or provide a Python repository path for quick start guidance.

Python Repository Quick Start

Rapidly analyze and understand Python repositories to get started quickly.

Quick Start

When a user provides a Python repository:

1. Scan repository structure: Identify key files and directories
2. Determine project type: Web app, CLI tool, library, data science, etc.
3. Find entry points: Locate main execution files
4. Identify dependencies: Find requirements and dependency management
5. Extract setup instructions: Determine how to install and run
6. Summarize functionality: Understand what the project does

What This Skill Analyzes

Project Purpose & Type

• Identify project category (web app, CLI, library, data science)
• Understand main functionality from README and code structure
• Determine intended use case

Repository Structure

• Entry points (main.py, app.py, manage.py, etc.)
• Package organization (src/, app/, lib/)
• Test structure (tests/, test_*.py)
• Documentation (docs/, README.md)
• Configuration files

Dependencies & Requirements

• requirements.txt (pip)
• Pipfile/Pipfile.lock (Pipenv)
• pyproject.toml/poetry.lock (Poetry)
• environment.yml (Conda)
• setup.py/setup.cfg (setuptools)

Setup & Execution

• Virtual environment setup
• Installation commands
• Environment variables needed
• How to run the application
• How to run tests

Analysis Workflow

1. Initial Scan

Automated analysis:

python scripts/analyze_repo.py <repo_path>

Manual analysis:

• List top-level files and directories
• Identify key indicator files
• Check for README

2. Identify Project Type

Check for framework indicators:

Django:

• manage.py present
• settings.py in project
• Django in dependencies

Flask:

• app.py or application.py
• Flask imports in code
• templates/ and static/ directories

FastAPI:

• FastAPI imports
• main.py with app definition
• uvicorn in dependencies

CLI Tool:

• cli.py or __main__.py
• argparse, click, or typer usage
• Console scripts in setup

Library/Package:

• src/ directory structure
• setup.py or pyproject.toml
• No obvious entry point

Data Science:

• .ipynb files
• notebooks/ directory
• pandas, numpy, scikit-learn dependencies

See: python-patterns.md for detailed patterns

3. Find Entry Points

Common entry points:

• main.py - Standard entry point
• app.py / run.py - Web application
• manage.py - Django management
• cli.py - Command-line interface
• __main__.py - Package entry (python -m)

Check for:

• if __name__ == "__main__": blocks
• Function definitions that look like entry points
• Console scripts in setup.py/pyproject.toml

4. Analyze Dependencies

Find dependency files:

• requirements.txt - Most common
• requirements-dev.txt - Development dependencies
• Pipfile - Pipenv
• pyproject.toml - Poetry or modern setup
• environment.yml - Conda

Extract key dependencies:

• Web frameworks (Flask, Django, FastAPI)
• Database libraries (SQLAlchemy, psycopg2)
• Testing frameworks (pytest, unittest)
• CLI libraries (click, typer, argparse)
• Data science (pandas, numpy, scikit-learn)

5. Determine Setup Instructions

Virtual environment:

# Standard venv
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

Installation:

# pip
pip install -r requirements.txt

# Development mode
pip install -e .

# Poetry
poetry install

# Pipenv
pipenv install

# Conda
conda env create -f environment.yml

Configuration:

• Check for .env.example or .env.template
• Look for config.py or settings.py
• Identify required environment variables

Running:

# Direct execution
python main.py

# Module execution
python -m package_name

# Web frameworks
flask run
uvicorn main:app --reload
python manage.py runserver

# CLI tools
python cli.py --help
package-name --help

6. Extract Functionality

From README:

• Project description
• Features list
• Usage examples
• API documentation

From code structure:

• Module names indicate functionality
• Class and function names
• Comments and docstrings
• Test files reveal features

From dependencies:

• Web framework → web application
• Database libraries → data persistence
• ML libraries → machine learning
• API clients → integration with services

Output Format

Generate a quick start guide with:

Project Overview

Project: [Name]
Type: [Web App / CLI Tool / Library / Data Science / etc.]
Purpose: [Brief description]

Prerequisites

- Python [version]
- [Other system requirements]

Quick Setup

# 1. Clone repository (if needed)
git clone [url]

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment (if needed)
cp .env.example .env
# Edit .env with your settings

# 5. Run application
python main.py

Entry Points

- main.py: Main application entry
- cli.py: Command-line interface
- tests/: Test suite

Key Dependencies

- flask: Web framework
- sqlalchemy: Database ORM
- pytest: Testing framework

Main Functionality

- Feature 1: Description
- Feature 2: Description
- Feature 3: Description

Running Tests

pytest
# or
python -m pytest tests/

Additional Notes

- Configuration details
- Known issues
- Development tips

Example Usage Patterns

User: "Analyze this Python repository" → Scan structure, identify type, generate quick start guide

User: "How do I run this project?" → Find entry points, dependencies, provide setup and run instructions

User: "What does this codebase do?" → Analyze README, code structure, dependencies to summarize functionality

User: "Help me understand this Python repo structure" → Explain directory organization, identify key components

User: "What are the prerequisites for this project?" → Identify Python version, system requirements, dependencies

User: "Generate setup instructions for this repo" → Create step-by-step installation and configuration guide

Best Practices

Analysis

• Start with README for high-level understanding
• Check multiple dependency files (may have both requirements.txt and pyproject.toml)
• Look for .env.example to understand configuration needs
• Examine test files to understand features

Documentation

• Be specific about Python version requirements
• Include both installation and running instructions
• Note any system-level dependencies (databases, Redis, etc.)
• Mention common gotchas or setup issues

Clarity

• Use clear section headers
• Provide copy-paste ready commands
• Explain what each step does
• Include troubleshooting tips when relevant

Automated Analysis

Use the provided script for quick automated analysis:

python scripts/analyze_repo.py /path/to/repo

Output includes:

• Project type identification
• Entry points
• Dependency management approach
• Configuration files
• Test presence
• Documentation availability

Limitations:

• Heuristic-based detection
• May miss custom structures
• Requires manual verification for complex projects