git-pandas 1.2.0__tar.gz → 2.2.0__tar.gz

git_pandas-2.2.0/.cursor/rules/project_overview.mdc

@@ -0,0 +1,228 @@
+---
+description: Overview of the gitpandas project
+globs: 
+alwaysApply: false
+---
+I'll do a thorough analysis of the gitpandas library to help new developers understand it. Let me start by exploring the codebase to get a comprehensive understanding.
+
+Ran tool
+Let's first look at the README to get an overview of the project:
+
+Read file: README.md
+Now let's look at the main module structure:
+
+Ran tool
+Let's check the __init__.py file to understand the main components:
+
+Read file: gitpandas/__init__.py
+Now let's look at the repository.py file, which seems to be one of the main components:
+
+Read file: gitpandas/repository.py
+Let's also look at the project.py file to understand the ProjectDirectory class:
+
+Read file: gitpandas/project.py
+Let's also check the cache.py file to understand the caching mechanism:
+
+Read file: gitpandas/cache.py
+Let's check the utilities directory to understand what helper functions are available:
+
+Ran tool
+Let's look at the utilities/__init__.py file:
+
+Read file: gitpandas/utilities/__init__.py
+Let's look at the plotting utilities:
+
+Read file: gitpandas/utilities/plotting.py
+Let's check the examples directory to see how the library is used:
+
+Ran tool
+Let's look at a couple of example files to understand how the library is used:
+
+Read file: examples/commit_history.py
+
+Read file: examples/bus_analysis.py
+
+Read file: examples/cumulative_blame.py
+Let's check the pyproject.toml file to understand the project dependencies and metadata:
+
+Read file: pyproject.toml
+Based on my thorough analysis of the gitpandas library, here's a comprehensive overview for new developers:
+
+# GitPandas: A Comprehensive Overview
+
+## What is GitPandas?
+
+GitPandas is a Python library that provides a set of wrappers around GitPython for creating pandas DataFrames from git repository data. It enables data-driven analysis of git repositories, allowing developers and data scientists to extract meaningful insights from their codebase's history and structure.
+
+## Core Components
+
+GitPandas is built around two primary objects:
+
+1. **Repository**: Represents a single git repository and provides methods to analyze it.
+2. **ProjectDirectory**: Represents a directory containing multiple git repositories, allowing for aggregated analysis across all repositories.
+3. **GitHubProfile**: A specialized ProjectDirectory that analyzes all repositories owned by a GitHub user.
+
+## Key Features
+
+### Repository Analysis
+- **Commit History**: Extract detailed commit history with filtering by file extensions and directories
+- **File Change History**: Track how files have changed over time
+- **Blame Analysis**: Determine who wrote each line of code in the repository
+- **Branch and Tag Information**: Extract metadata about branches and tags
+- **Bus Factor Analysis**: Estimate the project's "bus factor" (risk if key contributors leave)
+- **Cumulative Blame**: Track how code ownership changes over time
+- **Punchcard Analysis**: Visualize when code is written (day/hour patterns)
+- **Hours Estimation**: Estimate time spent on the project by contributors
+
+### Project Directory Analysis
+- Aggregate all the above analyses across multiple repositories
+- Compare metrics across repositories
+- Generate project-wide statistics and visualizations
+
+### Visualization Utilities
+- Plot cumulative blame over time
+- Create punchcard visualizations of commit patterns
+
+### Caching System
+- In-memory caching via `EphemeralCache`
+- Redis-based caching via `RedisDFCache`
+- Decorator-based caching system for expensive operations
+
+## Core Concepts
+
+### Data Representation
+All data in GitPandas is represented as pandas DataFrames, making it easy to:
+- Filter and transform the data
+- Visualize results
+- Export to various formats
+- Integrate with other data analysis workflows
+
+### Filtering Mechanisms
+GitPandas provides consistent filtering options across most methods:
+- `ignore_globs`: Glob patterns for files to exclude (e.g., `['tests/*', 'docs/*']`)
+- `include_globs`: Glob patterns for files to include (e.g., `['*.py', '*.js']`)
+- `limit`: Limit the number of commits to analyze
+- `days`: Limit analysis to commits within a certain number of days
+- `branch`: Specify which branch to analyze
+
+### Caching
+GitPandas implements a flexible caching system to improve performance:
+- The `multicache` decorator allows caching results of expensive operations
+- Cache backends can be swapped (memory or Redis)
+- Cache keys are generated based on repository name and method parameters
+
+## Usage Patterns
+
+### Single Repository Analysis
+```python
+from gitpandas import Repository
+
+# Create a Repository object
+repo = Repository(working_dir='/path/to/repo')
+
+# Get commit history
+commit_history = repo.commit_history(branch='master', include_globs=['*.py'])
+
+# Analyze blame
+blame = repo.blame(committer=True)
+
+# Estimate bus factor
+bus_factor = repo.bus_factor()
+```
+
+### Multi-Repository Analysis
+```python
+from gitpandas import ProjectDirectory
+
+# Create a ProjectDirectory object
+project = ProjectDirectory(working_dir='/path/to/project')
+
+# Get aggregated commit history
+commit_history = project.commit_history(branch='master')
+
+# Get aggregated blame
+blame = project.blame()
+```
+
+### GitHub Profile Analysis
+```python
+from gitpandas import GitHubProfile
+
+# Analyze a GitHub user's repositories
+profile = GitHubProfile(username='username')
+
+# Get repository information
+repo_info = profile.repo_information()
+```
+
+### Visualization
+```python
+from gitpandas import Repository
+from gitpandas.utilities.plotting import plot_cumulative_blame
+
+repo = Repository(working_dir='/path/to/repo')
+blame = repo.cumulative_blame(branch='master')
+plot_cumulative_blame(blame)
+```
+
+## Technical Implementation Details
+
+### Git Integration
+- Uses GitPython under the hood to interact with git repositories
+- Can work with local repositories or clone remote ones
+- Handles bare repositories appropriately
+
+### Performance Considerations
+- Caching system for expensive operations
+- Optional parallel processing for certain operations (requires joblib)
+- Filtering mechanisms to limit analysis scope
+
+### Data Processing
+- Heavy use of pandas for data manipulation and aggregation
+- Consistent DataFrame structures across different analyses
+- Time series analysis capabilities
+
+## Development Conventions
+
+### Code Organization
+- Core classes in separate modules (`repository.py`, `project.py`)
+- Utility functions in the `utilities` package
+- Caching mechanisms in `cache.py`
+
+### Error Handling
+- Graceful handling of missing repositories
+- Proper cleanup of temporary repositories
+- Appropriate warnings for deprecated functionality
+
+### Dependencies
+- Core dependencies: GitPython, pandas, numpy
+- Optional dependencies: matplotlib (for plotting), redis (for Redis caching), joblib (for parallel processing)
+
+## Practical Applications
+
+GitPandas can be used for:
+1. **Project Management**: Track contributor activity and estimate effort
+2. **Code Quality Analysis**: Identify areas with high churn or single-owner code
+3. **Team Dynamics**: Understand how team members collaborate and contribute
+4. **Historical Analysis**: Track how a project evolves over time
+5. **Risk Assessment**: Identify bus factor and knowledge silos
+6. **Performance Metrics**: Generate developer and team performance metrics
+
+## Extending GitPandas
+
+Developers can extend GitPandas by:
+1. Adding new analysis methods to the Repository or ProjectDirectory classes
+2. Creating new visualization utilities
+3. Implementing additional caching backends
+4. Building higher-level abstractions for specific use cases
+
+## Best Practices
+
+When working with GitPandas:
+1. Use appropriate filtering to limit analysis scope for large repositories
+2. Implement caching for repeated analyses
+3. Consider using parallel processing for intensive operations
+4. Combine multiple analyses for comprehensive insights
+5. Visualize results for easier interpretation
+
+This overview should provide new developers with a solid understanding of GitPandas, its capabilities, and how to effectively use it for git repository analysis.

git_pandas-2.2.0/.cursor/rules/pytest_standards.mdc

@@ -0,0 +1,48 @@
+---
+description: 
+globs: tests/*
+---
+# Pytest Standards
+
+## Test Organization
+- All test files should be named with the prefix `test_` (e.g., `test_module.py`)
+- Test classes should be named with the prefix `Test` (e.g., `TestClassName`)
+- Test methods should be named with the prefix `test_` (e.g., `test_function_name`)
+- Tests should be organized in the same directory structure as the source code they test
+
+## Test Structure
+- Each test should focus on testing a single functionality
+- Use descriptive test names that explain what is being tested
+- Group related tests in test classes
+- Use appropriate fixtures for test setup and teardown
+- Avoid test interdependence - tests should be able to run in any order
+
+## Assertions
+- Use pytest's built-in assertions instead of Python's `assert` statement when possible
+- Use appropriate assertion methods for the type being tested (e.g., `assert_almost_equal` for floats)
+- Include descriptive error messages in assertions to aid debugging
+
+## Fixtures
+- Use fixtures for common setup and teardown operations
+- Define fixtures at the appropriate scope (function, class, module, or session)
+- Use parameterized fixtures for testing multiple inputs
+- Use conftest.py for sharing fixtures across multiple test files
+
+## Coverage
+- Aim for at least 80% code coverage
+- Write tests for both success and failure cases
+- Test edge cases and boundary conditions
+- Use `pytest-cov` to generate coverage reports
+
+## Best Practices
+- Keep tests fast and independent
+- Avoid mocking unless necessary
+- Use markers to categorize tests (e.g., `@pytest.mark.slow`)
+- Use parametrize for testing multiple inputs
+- Write tests before or alongside code (TDD approach)
+- Run the full test suite before committing changes
+
+## Commands
+- Run tests with `pytest`
+- Generate coverage reports with `pytest --cov=gitpandas`
+- Run specific tests with `pytest path/to/test_file.py::TestClass::test_method` 

git_pandas-2.2.0/.cursor/rules/python_standards.mdc

@@ -0,0 +1,68 @@
+---
+description: 
+globs: *.py
+---
+# Python Coding Standards
+
+## Important Notes
+- Do not ever ever add test-case specific handling into the library code. Do not add handling for "special cases", "test cases" or any other logic branches that attempt to skip the normal buisness logic to get a test to pass.
+
+## Code Style
+- Follow PEP 8 style guide for Python code
+- Use 4 spaces for indentation (no tabs)
+- Maximum line length of 88 characters (Black default)
+- Use snake_case for variables, functions, and methods
+- Use CamelCase for classes
+- Use UPPER_CASE for constants
+- Add a blank line at the end of each file
+
+## Imports
+- Group imports in the following order:
+  1. Standard library imports
+  2. Related third-party imports
+  3. Local application/library specific imports
+- Use absolute imports when possible
+- Avoid wildcard imports (`from module import *`)
+- Use import aliases for long module names
+
+## Documentation
+- Document all public modules, classes, methods, and functions
+- Use docstrings that follow the Google style guide
+- Include type hints for function parameters and return values
+- Document parameters, return values, and exceptions raised
+
+## Error Handling
+- Use specific exception types instead of generic ones
+- Handle exceptions at the appropriate level
+- Use context managers (`with` statements) for resource management
+- Avoid catching exceptions without proper handling
+
+## Code Organization
+- Keep functions and methods short and focused
+- Follow the Single Responsibility Principle
+- Use classes to encapsulate related functionality
+- Separate concerns into different modules
+
+## Testing
+- Write unit tests for all code
+- Use meaningful test names
+- Test both normal and edge cases
+- Mock external dependencies in tests
+
+## Performance
+- Prefer list/dict/set comprehensions over loops when appropriate
+- Use generators for large data sets
+- Profile code before optimizing
+- Consider using NumPy/Pandas for numerical operations
+
+## Tools
+- Use Black for code formatting
+- Use Ruff for linting and static analysis
+- Use mypy for type checking
+- Use isort for import sorting
+
+## Version Control
+- Write meaningful commit messages
+- Keep commits focused on a single change
+- Use feature branches for development
+- Review code before merging 

git_pandas-2.2.0/.cursor/rules/sphinx_docs_standards.mdc

@@ -0,0 +1,62 @@
+---
+description: 
+globs: docs/*
+---
+# Sphinx Documentation Standards
+
+## Project Setup
+- Use `sphinx-quickstart` to initialize the documentation structure
+- Configure `conf.py` with appropriate project information
+- Use the ReadTheDocs theme for consistent styling
+- Enable necessary extensions (e.g., `autodoc`, `napoleon`, `viewcode`)
+
+## Directory Structure
+- Keep documentation source files in the `docs/` directory
+- Organize documentation into logical sections (e.g., user guide, API reference)
+- Use a clear and consistent file naming convention
+- Include an `index.rst` file as the documentation entry point
+
+## Documentation Style
+- Write in clear, concise language
+- Use present tense and active voice
+- Be consistent with terminology
+- Include examples where appropriate
+- Target the appropriate audience (users, developers, etc.)
+
+## reStructuredText Formatting
+- Use proper heading hierarchy (=, -, ~, ^, ")
+- Use bullet lists for unordered items and numbered lists for sequences
+- Use code blocks with appropriate language for syntax highlighting
+- Use cross-references to link between documentation sections
+- Include images and diagrams where they add value
+
+## API Documentation
+- Use autodoc to generate API documentation from docstrings
+- Document all public modules, classes, methods, and functions
+- Follow Google or NumPy docstring style consistently
+- Include type information for parameters and return values
+- Document exceptions that may be raised
+
+## Examples and Tutorials
+- Include practical examples for common use cases
+- Provide step-by-step tutorials for complex operations
+- Ensure all examples are tested and working
+- Use `literalinclude` to include code examples from actual source files
+
+## Building and Testing
+- Build documentation locally before committing changes
+- Check for and fix all warnings during the build process
+- Verify that cross-references work correctly
+- Test documentation on different screen sizes
+
+## Deployment
+- Configure automatic documentation builds on ReadTheDocs or GitHub Pages
+- Include a link to the documentation in the project README
+- Version documentation to match software releases
+- Provide a changelog or release notes section
+
+## Maintenance
+- Keep documentation up-to-date with code changes
+- Review and update documentation during each release cycle
+- Address user feedback and questions in the documentation
+- Remove outdated or deprecated information 

git_pandas-2.2.0/.cursor/rules/testing.mdc

@@ -0,0 +1,53 @@
+---
+description: how to use the makefile to run tests
+globs: 
+---
+ # Gitpandas Testing Standards
+
+## Running Tests
+
+### Using Make Commands
+- Always use `make test` to run the test suite
+- Use `make test-cov` to run tests with coverage reports
+- Use `make test-all` to run tests on all supported Python versions using tox
+
+### Test Commands
+```bash
+# Run the standard test suite
+make test
+
+# Run tests with coverage
+make test-cov
+
+# Run tests on all supported Python versions
+make test-all
+
+# Run a specific test file
+make test PYTEST_ARGS="tests/test_unified_interface.py"
+
+# Run a specific test class
+make test PYTEST_ARGS="tests/test_unified_interface.py::TestUnifiedInterface"
+
+# Run a specific test method
+make test PYTEST_ARGS="tests/test_unified_interface.py::TestUnifiedInterface::test_base_methods_elo"
+```
+
+### Test Environment
+- Tests are run using `uv run pytest` through the Makefile
+- The test environment is automatically set up with the correct dependencies
+- Always run tests in a clean environment to avoid dependency conflicts
+
+### Continuous Integration
+- All tests must pass in CI before merging
+- Coverage should not decrease with new code
+- New features should include corresponding tests
+
+### Benchmarks
+- Use `make benchmark` to run performance benchmarks
+- Benchmark results are stored in the `benchmark_results` directory
+- Performance regressions should be addressed before merging
+
+### Linting and Formatting
+- Use `make lint` to check code quality
+- Use `make lint-fix` to automatically fix linting issues
+- Use `make format` to format code according to project standards

git_pandas-2.2.0/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Expected Behavior
+
+
+## Actual Behavior
+
+
+## Steps to Reproduce the Problem
+
+  1.
+  1.
+  1.
+
+## Specifications
+
+  - Version:
+  - Platform:
+  - Subsystem:

git_pandas-2.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+Fixes #
+
+## Proposed Changes
+
+  -
+  -
+  -

git_pandas-2.2.0/.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+name: "Master Docs Publication"
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone
+        uses: actions/checkout@v1
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+      
+      - name: Install Dependencies
+        run: |
+          uv pip install --system -e ".[dev]"
+      
+      - name: Build Docs
+        uses: ammaraskar/sphinx-action@master
+        with:
+          docs-folder: "./docs/"
+      
+      - name: Create CNAME file
+        run: |
+          echo "gitpandas.mcginniscommawill.com" > ./docs/build/html/CNAME
+      
+      - name: Deploy Docs
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: "./docs/build/html/"

git_pandas-2.2.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,55 @@
+name: "PyPI Packaging"
+on:
+  release:
+    types: created
+
+jobs:
+  build_and_publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # IMPORTANT: this permission is mandatory for Trusted Publishing
+      id-token: write
+    steps:
+      - name: Clone
+        uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      
+      - name: Install uv
+        run: |
+          python -m pip install --upgrade pip
+          pip install uv
+      
+      - name: Setup virtual environment
+        run: |
+          uv venv
+          echo "VIRTUAL_ENV=$(pwd)/.venv" >> $GITHUB_ENV
+          echo "$(pwd)/.venv/bin" >> $GITHUB_PATH
+      
+      - name: Install dependencies
+        run: |
+          uv pip install -e ".[dev]"
+          uv pip install build
+      
+      - name: Build source distribution
+        run: |
+          # Clean the build directories first
+          rm -rf build/
+          rm -rf dist/
+          rm -rf .eggs/
+          
+          # Find and remove egg-info directories, excluding the virtual environment
+          find . -path ./.venv -prune -o -name '*.egg-info' -type d -exec rm -rf {} \; 2>/dev/null || true
+          find . -path ./.venv -prune -o -name '*.egg' -type f -exec rm -f {} \; 2>/dev/null || true
+          find . -path ./.venv -prune -o -name '__pycache__' -type d -exec rm -rf {} \; 2>/dev/null || true
+          
+          # Build only the source distribution
+          python -m build --sdist
+      
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

git_pandas-2.2.0/.github/workflows/test-docs-build.yml

@@ -0,0 +1,29 @@
+name: "Pull Request Docs Check"
+on:
+- pull_request
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v1
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+    
+    - name: Install uv
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+    
+    - name: Install Dependencies
+      run: |
+        uv pip install --system -e ".[dev]"
+    
+    - name: Build Docs
+      uses: ammaraskar/sphinx-action@master
+      with:
+        docs-folder: "docs/"

git_pandas-2.2.0/.github/workflows/test-suite.yml

@@ -0,0 +1,45 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: "Test Suite and Linting"
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+      
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+    
+    - name: Install uv
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+    
+    - name: Install dependencies
+      run: |
+        uv pip install --system -e ".[dev,datasets]"
+    
+    - name: Configure Git
+      run: |
+        git config --global user.email "github-actions@github.com"
+        git config --global user.name "GitHub Actions"
+    
+    - name: Run tests
+      run: |
+        make test
+    
+    - name: Run linting
+      run: |
+        make lint