git-pandas 2.2.1__tar.gz → 2.5.0__tar.gz

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

@@ -0,0 +1,37 @@
+name: "Master Docs Publication"
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - 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]"
+          uv pip install --system -r docs/requirements.txt
+
+      - name: Build Docs
+        run: |
+          cd docs
+          sphinx-build -b html source build/html
+
+      - name: Deploy Docs
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: "./docs/build/html/"

{git_pandas-2.2.1 → git_pandas-2.5.0}/.github/workflows/pypi-publish.yml

@@ -11,10 +11,10 @@ jobs:
       id-token: write
     steps:
       - name: Clone
-        uses: actions/checkout@v3
-      
+        uses: actions/checkout@v5
+
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.11'
       

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

@@ -0,0 +1,31 @@
+name: "Pull Request Docs Check"
+on:
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - 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]"
+          uv pip install --system -r docs/requirements.txt
+
+      - name: Build Docs
+        run: |
+          cd docs
+          sphinx-build -b html source build/html

{git_pandas-2.2.1 → git_pandas-2.5.0}/.github/workflows/test-suite.yml

@@ -9,27 +9,39 @@ on:
   pull_request:
     branches: [ master ]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
     
     steps:
     - name: Checkout code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
       
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
-        python-version: '3.10'
-    
+        python-version: ${{ matrix.python-version }}
+
     - name: Install uv
-      run: |
-        curl -LsSf https://astral.sh/uv/install.sh | sh
-        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Check uv version
+      run: uv --version
     
     - name: Install dependencies
       run: |
-        uv pip install --system -e ".[dev,datasets]"
+        uv pip install --system -e ".[dev]"
     
     - name: Configure Git
       run: |
@@ -38,8 +50,8 @@ jobs:
     
     - name: Run tests
       run: |
-        make test
+        MPLBACKEND=Agg uv run pytest -v -m "not slow"
     
     - name: Run linting
       run: |
-        make lint
+        uv run ruff check .

{git_pandas-2.2.1 → git_pandas-2.5.0}/.gitignore

@@ -18,7 +18,7 @@ __pycache__/
 .DS_Store
 # C extensions
 *.so
-
+gitnoc_desktop/.venv/
 # Distribution / packaging
 .Python
 env/

git_pandas-2.5.0/CHANGELOG.md

@@ -0,0 +1,244 @@
+Unreleased
+==========
+
+v2.5.0
+======
+
+## New Features
+
+### Remote Operations & Cache Warming
+ * **NEW**: `Repository.safe_fetch_remote()` - Safely fetch changes from remote repositories without modifying working directory
+   - Read-only operation with comprehensive error handling
+   - Support for dry-run preview and remote validation
+   - Configurable remote names and pruning options
+ * **NEW**: `Repository.warm_cache()` - Pre-populate repository cache for improved performance
+   - Configurable method selection with intelligent parameter handling
+   - Performance metrics and cache entry tracking
+   - Significant performance improvements (1.5-10x speedup demonstrated)
+ * **NEW**: `ProjectDirectory.bulk_fetch_and_warm()` - Efficiently process multiple repositories
+   - Parallel processing support when joblib is available
+   - Error isolation (failures in one repo don't affect others)
+   - Comprehensive summary statistics and progress tracking
+
+### Enhanced Caching System
+ * **NEW**: `CacheEntry` class with metadata tracking (timestamps, age calculation)
+ * **ENHANCED**: Thread-safe cache operations with proper locking mechanisms
+ * **ENHANCED**: Cache key consistency improvements using `||` delimiter format
+ * **ENHANCED**: Cache timestamp and metadata access methods (`get_cache_info()`, `list_cached_keys()`)
+
+### Documentation & Examples
+ * **NEW**: Comprehensive remote operations documentation (`docs/source/remote_operations.rst`)
+ * **NEW**: Cache warming and remote fetch example (`examples/remote_fetch_and_cache_warming.py`)
+ * **NEW**: Cache timestamp usage example (`examples/cache_timestamps.py`)
+ * **NEW**: Release analytics example (`examples/release_analytics.py`)
+
+## Bug Fixes
+
+### Commits In Tags History Walking
+ * **FIXED**: `Repository.commits_in_tags()` never walked history. It returned exactly one row per tag — the tagged commit — rather than attributing every commit to the release that shipped it, as documented. The backwards walk now runs, so each commit is attributed to the first tag that contains it, stopping at the previous tag, at the `start`/`end` bounds, or at a root commit. The walk uses an explicit worklist, so a release spanning more commits than the interpreter's recursion limit no longer raises `RecursionError`.
+ * **FIXED**: Tag lookup used positional `Series.__getitem__`, which emitted a pandas `FutureWarning` and would become a `KeyError` on a future pandas release.
+
+**Note**: This is a user-visible output change. `commits_in_tags()` — and `ProjectDirectory.commits_in_tags()`, which aggregates it — now return one row per commit instead of one row per tag. Code that counted rows to count releases needs updating; count distinct values of the `tag` column instead.
+
+### Project Default Branch Detection
+ * **FIXED**: `ProjectDirectory` and `GitHubProfile` now let each repository auto-detect `main` or `master` by default, so mixed-branch projects include every repository in branch-based history metrics. Passing an explicit `default_branch` continues to force that branch across all repositories.
+
+**Note**: Repositories with neither a `main` nor `master` branch are now skipped with a warning during project initialization. Previously they were included but returned empty branch-based history.
+
+### Cumulative Blame
+ * **FIXED**: `Repository.cumulative_blame()` and `parallel_cumulative_blame()` no longer duplicate rows when multiple commits share a timestamp.
+
+### File Change History
+ * **FIXED**: `Repository.file_change_history()` now reports actual per-file insertions and deletions, including root commits, which restores non-zero churn metrics in `file_change_rates()`.
+
+### Project Punchcard Aggregation
+ * **FIXED**: `ProjectDirectory.punchcard()` now returns a well-formed empty DataFrame when no repository yields commit data and avoids pandas aggregation `FutureWarning`s.
+
+### File Ownership
+ * **FIXED**: `Repository.file_owner()` always read the commit's *committer* regardless of the `committer` flag, so `committer=False` returned the top committer under a column labelled `author`. It now selects the identity to match the flag, matching `Repository.blame()`. This also fixes `Repository.file_detail(committer=False)` and `ProjectDirectory.file_detail(committer=False)`, whose `file_owner` column reported the committer on rebased, cherry-picked, squash-merged, or web-UI-committed history.
+
+### MCP Server Serialization
+ * **FIXED**: `serialize_pandas_object()` dropped every non-datetime DataFrame index during `orient="records"` conversion, so index-carried identity disappeared from tool results (e.g. a blame-shaped frame serialized as `[{"loc": 7}]` without the `committer`/`author` it belongs to). Named index levels, including `MultiIndex` levels such as `file` and `(tag_date, commit_date)`, are now materialized as columns.
+ * **FIXED**: Serialization mutated the DataFrame it was given — rewriting a `DatetimeIndex` into formatted strings and replacing datetime columns in place — which corrupted shared cached frames. Serialization now works on a copy and leaves its input untouched.
+ * **FIXED**: Serializing a frame that keeps a column and index level of the same name (e.g. `file_change_history()`'s `date`) raised `ValueError: cannot insert date, already exists`.
+
+### GitHub Profile Discovery
+ * **FIXED**: `GitHubProfile` now follows GitHub API pagination links and requests up to 100 repositories per page. If any page fails, discovery returns an empty profile instead of silently analyzing partial results.
+
+### Hours Estimation
+ * **FIXED**: `Repository.hours_estimate()` now includes the first-commit allowance, increasing estimates by `single_commit_hours` per contributor and giving single-commit contributors a non-zero estimate.
+
+### Project Blame Aggregation
+ * **FIXED**: `ProjectDirectory.blame()` now preserves committer/author and file grouping keys when combining multiple repositories. Contributors are aggregated by name across repositories, `blame(by="file")` no longer raises `KeyError`, and project-level bus factors are calculated from contributors instead of row numbers.
+
+### Project File Blame Aggregation
+ * **FIXED**: `ProjectDirectory.blame(by="file")` grouped on `(committer/author, file)` only. Because `file` is a repository-relative path, files sharing a path across repositories (`README.md`, `setup.py`, `__init__.py`, ...) were silently summed into a single row reporting a line count that matched neither repository, and the originating repository was discarded entirely. The repository is now part of the grouping, so the result is indexed by `(committer/author, file, repository)` — matching the identification that `file_detail()`, `file_change_rates()`, and `bus_factor(by="file")` already carry. `blame(by="repository")` is unchanged; aggregating a contributor across repositories there remains correct.
+
+**Note**: This adds an index level to `blame(by="file")` output. Code that indexes that result by `(committer, file)` needs updating.
+
+### Cumulative Blame Cache Mutation
+ * **FIXED**: `Repository.cumulative_blame()` reshaped the `revs()` frame it received in place — adding a column per committer, deleting `rev`, and replacing the index with the commit dates. Because a cache backend hands out the stored DataFrame by reference, a later `revs()` call returned that wrecked frame, and a *second* `cumulative_blame()` call raised `ValueError: Internal Error: self.revs() returned DataFrame without 'rev' column.` (`parallel_cumulative_blame()` swallowed the same failure and returned an empty DataFrame). It now works on a copy.
+ * **FIXED**: `ProjectDirectory.cumulative_blame()` renamed each member repository's cached `cumulative_blame()` columns in place while suffixing them with the repository name, so a later per-repository call returned `Alice__repo1` instead of `Alice`. The suffixing now happens on copies.
+
+### Project Bus Factor Glob Filtering
+ * **FIXED**: `ProjectDirectory.bus_factor(by="repository")` passed the caller's `include_globs` into each repository's `ignore_globs` argument. The caller's `ignore_globs` was silently discarded and `include_globs` doubled as an exclusion list, so the bus factor was computed over the wrong set of files — typically excluding exactly the files the caller asked to include. (`by="file"` was already correct.)
+
+### Project Empty-Result Guards
+ * **FIXED**: `ProjectDirectory.blame()` and `file_detail()` raised `AttributeError: 'NoneType' object has no attribute 'reset_index'` when the project contained no repositories, or when every repository raised `GitCommandError` (repositories with no commits, or a branch that doesn't exist). Both now return a well-formed empty DataFrame matching their normal output shape, as sibling methods such as `file_change_history()` already did.
+ * **FIXED**: `ProjectDirectory.commits_in_tags()` raised `ValueError: No objects to concatenate` when no repository yielded tagged commits. It now returns an empty DataFrame carrying the usual `commit_sha`, `tag`, and `repository` columns and the `(tag_date, commit_date)` index.
+
+### Punchcard Cache Mutation
+ * **FIXED**: `Repository.punchcard()` wrote `day_of_week` and `hour_of_day` columns straight into the `commit_history()` frame it was handed. Because a cache backend returns the stored DataFrame *by reference*, every later `commit_history()` call then returned those two extra columns. The same in-place write affected `ProjectDirectory.commit_history()`, `file_detail()`, and `revs()`, which added a `repository` column to borrowed per-repository frames. All of these now copy before writing.
+
+### Cache Warming
+ * **FIXED**: `Repository.warm_cache()` silently substituted `limit=100` for `commit_history` and `file_change_rates`, so it populated a cache key that no ordinary call would ever hit — the default `warm_cache()` gave those two methods no speedup whatsoever. The injected limit is gone, so warming populates the keys callers actually use.
+ * **FIXED**: `hours_estimate()`, `punchcard()`, `cumulative_blame()`, and `parallel_cumulative_blame()` resolved `branch=None` to the default branch *before* delegating to `commit_history()`/`revs()`. The inner call therefore keyed on `"master"` while a user's own `commit_history()` keyed on `None`, storing several copies of the same history and defeating cache reuse between them. The caller's `branch` value is now passed through unchanged; resolution happens only where a branch name is genuinely needed.
+
+### Cached Method Introspection
+ * **FIXED**: `@multicache` returned a bare wrapper, so every decorated `Repository` method lost its name, docstring, and signature. `help()`, `inspect.signature()`, and any reflection over the API saw `(self, *args, **kwargs)`. The decorator now applies `functools.wraps`, which restores introspection and — because the MCP server generates its tool schemas by reflecting over `Repository` — restores the real parameter names and defaults in every MCP tool schema.
+
+### Cache Correctness
+ * **FIXED**: `Repository.invalidate_cache()` now targets the method-first cache key layout, processes every key when combined with a pattern, and returns accurate removal counts for in-memory and Redis backends.
+ * **FIXED**: `@multicache` built cache keys from `kwargs` only, so any argument passed *positionally* was invisible to the key and collapsed to `None`. Keys are now resolved against the decorated method's signature (`inspect.signature().bind()` + `apply_defaults()`), so positional and keyword calls key identically. This fixes:
+   - `Repository(working_dir=<master-only repo>, cache_backend=...)` raising `ValueError: Could not detect default branch` — the internal `has_branch("main")` / `has_branch("master")` probes shared one key.
+   - `file_detail()` reporting the first file's owner for every file — the internal `file_owner(rev, file_path, ...)` calls shared one key.
+ * **FIXED**: `blame()`'s `key_list` misspelled `ignore_globs` as `ignore_blobs`, so `ignore_globs` never contributed to the cache key and all variants collided. `blame(ignore_globs=[...])` and `bus_factor(ignore_globs=[...])` now return the same results with and without a cache backend.
+ * **FIXED**: `skip_broken` was missing from the cache key of `file_change_history`, `file_change_rates`, `revs`, `cumulative_blame`, `parallel_cumulative_blame`, and `tags`, so `skip_broken=True` and `skip_broken=False` shared an entry.
+ * **FIXED**: Cache key parts are now joined with `||` instead of `_`, which could occur inside the values themselves (e.g. `get_file_content(path="docs", rev="release_2")` collided with `path="docs_release", rev="2"`).
+ * **NEW**: `@multicache` validates `key_list` against the decorated method's signature at decoration time and raises `ValueError` on a name that isn't a parameter, turning the typo class of bug into a loud failure.
+
+**Note**: The cache key format has changed. Stale `EphemeralCache`/`DiskCache` entries simply miss and recompute, but `RedisDFCache` users sharing a cache across versions should flush it (or use a new key prefix) to avoid retaining entries under the old format.
+
+## Testing & Quality
+ * **NEW**: 38 comprehensive tests for remote operations and cache warming
+ * **NEW**: Thread safety tests for cache operations
+ * **NEW**: Edge case and error handling test coverage
+ * **NEW**: Regression coverage for every fix above, including cached-vs-uncached parity, multi-repository aggregation against repositories that share file paths, and cache-immutability checks that fail if a method writes into a frame it was handed
+ * **NEW**: Exact rev-to-rev regression tests pinning churn, file, elapsed-time, author, and committer values, and covering `include_globs`/`ignore_globs` through `release_tag_summary()`
+ * **IMPROVED**: Overall test coverage and reliability
+ * **FIXED**: Various minor bugs and future warnings
+
+## Backward Compatibility
+ * No API was removed, renamed, or given a new required argument; every existing call still runs.
+ * Three changes are user-visible in the *data* returned, and are called out in full above:
+   - `commits_in_tags()` now returns one row per commit rather than one row per tag.
+   - `blame(by="file")` on a `ProjectDirectory` gains a `repository` index level.
+   - The cache key format changed; `RedisDFCache` users sharing a cache across versions should flush it.
+ * Beyond those, results change only where they were previously wrong — the bug fixes above return corrected numbers for churn, hours, ownership, bus factor, and blame. Analyses pinned to specific values from an earlier release should expect them to move.
+ * Existing cache backends work seamlessly with new features.
+
+v2.4.0
+======
+
+ * Significant caching bugfixes and updates
+ * Added a DiskCache that persists across runs
+ * Added release analytics 
+
+v2.3.0
+======
+
+ * Updated coverage file parsing to use coverage.py API instead of direct file parsing
+ * Added coverage>=5.0.0 as a core dependency
+ * Added a basic MCP server
+ * Added methods to `Repository` for getting files in repo, getting content of a file, and getting diffs of a revision
+
+
+v2.2.1
+======
+
+ * Docs CI bugfix
+
+v2.2.0
+======
+
+ * Support for default branch setting instead of assuming master, will infer if not passed
+ * Better handling of ignore repos in project directory setup
+ * Added a branch exists helper in repository 
+ * Docs corrections
+
+v2.1.0
+======
+
+ * Imrpoved test suite
+ * Many bugfixes
+ * Updates for pandas v2
+
+v2.0.0
+======
+
+ * Fully transitioned to ignore_globs and include_globs style syntax
+ * Parallelized cumulative blame support with joblib threading backend
+ * Added threading parallelism to many project directory functions.
+ * Added a chaching module for optional redis or memory backed caching of certain resultsets
+ 
+v1.2.0
+======
+
+ * Added ignore_globs option alongside all methods with ignore_dir and extensions, will be the only method for filtering files in v2.0.0
+ 
+v1.1.0
+======
+
+ * _repo_name changed to repo_name in project directories (old method left with deprecation warning)
+ * repo_name property added to repositories
+ 
+v1.0.3
+======
+
+ * Support for estimating time spent developing on projects.
+ 
+v1.0.2
+======
+
+ * bugfix in ignore_dir option for root level directories
+
+v1.0.1
+======
+
+ * file details function
+ 
+v1.0.0
+======
+
+ * Stable API
+ * Punchcard dataframe added
+ * Plotting helpers added to library under utilities module
+ * Added github.com profile object
+
+v0.0.6
+======
+
+ * Added file owner utility
+ * Added lifelines example
+ * Added rev to file change history table
+ * Added file-wise blame using by='file' parameter
+ * Bus Factor returns a dataframe
+ * Now supporting python 2.7+ and 3.3+
+
+v0.0.5
+======
+
+ * Added file change rates table with risk metrics
+ * Added basic functionality with coverage files
+ * Added limited time window based dataset functionality
+ * Expanded docs
+ 
+v0.0.4
+======
+
+ * Added cumulative blame and revision history
+ 
+v0.0.3
+======
+
+ * Added approximate bus factor analysis
+
+v0.0.2
+======
+
+ * Added blame
+
+v0.0.1
+======
+
+ * Initial release, basic interface to commit history and descriptors

{git_pandas-2.2.1 → git_pandas-2.5.0}/CONTRIBUTING.md

@@ -49,8 +49,6 @@ Easy Issues / Getting Started
 There are a number of issues on the near term horizon that would be great to have help with.
 
  1. Diff: it would be really nice to be able to call a function with 2 revs and return the diff as a dataframe. So columns for line number, filename, path, change, author, timestamp, etc. 
- 2. Docs: We have a lot of examples, but they are largely not present in the documentation.  Adding some plotting to the examples using pyplot and putting them into the docs would help out new users a lot.
- 3. Docs Deployment: currently we host the docs on Github pages, which has a kind of awkward deployment process. Anyone with experience automating this (or scripting even) would be very useful.
  4. File-level tracking: it would be really cool to be able to get a dataframe of one file's history in great detail. It likely would be a subset of the existing file change history function.
  5. Cross-Branch Analytics: finding differences between different branches of a single repository. Or aggregating the  results of other functions across multiple branches.
  6. Verbose Mode: add logging in more functions when verbose is set to True.

{git_pandas-2.2.1 → git_pandas-2.5.0}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: setup test test-all lint format clean docs build run-example test-single
+.PHONY: setup test test-all lint format clean docs build run-example test-single mcp gitnoc
 
 # Use uv for all Python operations
 PYTHON = python
@@ -20,10 +20,10 @@ setup-examples:
 setup-all:
 	$(UV) pip install -e ".[all]"
 
-test:
+test: setup-all
 	MPLBACKEND=Agg $(UV) run pytest $(TESTS_DIR) --cov=$(PACKAGE_NAME) --cov-report=term-missing -m "not slow"
 
-test-single:
+test-single: setup-all
 	@if [ "$(test)" = "" ]; then \
 		echo "Error: Please specify a test using test=<path_to_test>"; \
 		echo "Example: make test-single test=tests/test_Repository/test_advanced.py::TestRepositoryAdvanced::test_parallel_cumulative_blame"; \
@@ -32,15 +32,14 @@ test-single:
 	MPLBACKEND=Agg $(UV) run pytest $(test) -v
 
 test-all:
-	MPLBACKEND=Agg $(UV) run pytest $(TESTS_DIR) --cov=$(PACKAGE_NAME) --cov-report=term-missing
+	MPLBACKEmND=Agg $(UV) run pytest $(TESTS_DIR) --cov=$(PACKAGE_NAME) --cov-report=term-missing
 
 lint:
-	$(UV) run ruff check .
+	$(UV) run ruff check --fix --unsafe-fixes .
 
 format:
 	$(UV) run ruff format .
-	$(UV) run ruff check --fix --unsafe-fixes .
-
+	
 docs:
 	$(MAKE) -C $(DOCS_DIR) html
 
@@ -78,11 +77,18 @@ run-example:
 	fi
 	MPLBACKEND=Agg $(UV) run python $(EXAMPLES_DIR)/$(example).py
 
+mcp:
+	$(UV) run python mcp_server/server.py
+
+gitnoc:
+	$(UV) run python gitnoc/app.py
+
 help:
 	@echo "Available commands:"
 	@echo "  setup         Install the package in development mode"
 	@echo "  setup-examples Install the package with examples dependencies"
 	@echo "  setup-all     Install the package with all dependencies"
+	@echo "  setup-gitnoc   Install GitNOC dependencies"
 	@echo "  test          Run tests with pytest (excluding slow tests)"
 	@echo "  test-single   Run a single test (usage: make test-single test=<path_to_test>)"
 	@echo "  test-all      Run all tests including slow tests"
@@ -94,4 +100,6 @@ help:
 	@echo "  build         Build distribution packages"
 	@echo "  publish       Publish package to PyPI"
 	@echo "  env-export    Export dependencies to requirements.txt"
-	@echo "  run-example   Run a specific example (usage: make run-example example=<name>)" 
+	@echo "  run-example   Run a specific example (usage: make run-example example=<name>)"
+	@echo "  mcp           Run the MCP server"
+	@echo "  gitnoc        Run the GitNOC Streamlit app"