git-pandas 2.7.0__tar.gz → 2.7.1__tar.gz

{git_pandas-2.7.0 → git_pandas-2.7.1}/CHANGELOG.md

@@ -1,6 +1,33 @@
 Unreleased
 ==========
 
+v2.7.1
+======
+
+## Documentation
+
+* **NEW**: A "Result schemas" docs page lists the exact columns, index levels and dtype kinds of populated results for the core analysis methods on `Repository` and `ProjectDirectory`. It is generated from constants that `tests/test_schema_contracts.py` checks against real output.
+
+## Bug Fixes
+
+### Tag History Compatibility
+
+* **FIXED**: `commits_in_tags()` converts time bounds to epoch seconds without deprecated generic-unit Timedelta division, avoiding the NumPy deprecation warning while preserving whole-second flooring.
+
+### MCP Datetime Serialization
+
+* **FIXED**: The standalone MCP adapter serializes pandas 3 datetime columns at any resolution as timestamp strings, rather than overlooking columns that are not nanosecond-based.
+
+### Limit Validation
+
+**Behavior change: a negative `limit` now raises `ValueError` instead of returning a result.** Git treats `max_count=-1` as unlimited, so a negative `limit` used to mean "everything" on some methods and "nothing" on others (a project-level `limit=-1` over two repositories returned 5, 0, 1 and 5 rows from `commit_history`, `file_change_history`, `hours_estimate` and `revs` on a 2x5-commit fixture).
+
+* **FIXED**: `limit` must be `None` or a non-negative integer on `Repository.commit_history`, `file_change_history`, `file_change_rates`, `hours_estimate`, `revs`, `punchcard`, `cumulative_blame`, `parallel_cumulative_blame` and the matching `ProjectDirectory` methods. Negative values, booleans, floats and NaN raise `ValueError` before Git or cache access, so nothing is cached. `limit=0` (zero commits), `None` and positive integers behave as before; floats such as `limit=2.0` are now rejected rather than floored.
+
+## Testing & Quality
+
+* **ENHANCED**: Value-level cached-versus-uncached parity coverage now checks every public analysis method and flags public methods missing from the coverage table.
+
 v2.7.0
 ======
 

{git_pandas-2.7.0 → git_pandas-2.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-pandas
-Version: 2.7.0
+Version: 2.7.1
 Summary: A utility for interacting with data from git repositories as Pandas dataframes
 Project-URL: Documentation, https://gitpandas.mcginniscommawill.com
 Project-URL: Source, https://github.com/wdm0006/git-pandas

{git_pandas-2.7.0 → git_pandas-2.7.1}/docs/source/conf.py

@@ -80,9 +80,9 @@ author = "Will McGinnis"
 # built documents.
 #
 # The short X.Y version.
-version = "2.5.0"
+version = "2.7.1"
 # The full version, including alpha/beta/rc tags.
-release = "2.5.0"
+release = "2.7.1"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

{git_pandas-2.7.0 → git_pandas-2.7.1}/docs/source/index.rst

@@ -117,6 +117,7 @@ For detailed information about the components and their usage, see:
    remote_operations
    performance
    usecases
+   result_schemas
    contributors
 
 Additional Resources

{git_pandas-2.7.0 → git_pandas-2.7.1}/docs/source/project.rst

@@ -114,7 +114,7 @@ Common Parameters
 Most analysis methods support these filtering parameters:
 
 * **branch**: Branch to analyze (defaults to repository's default branch)
-* **limit**: Maximum number of commits to analyze
+* **limit**: Maximum number of commits to analyze; must be ``None`` or a non-negative integer (excluding booleans). Invalid values raise ``ValueError``; zero selects no commits
 * **days**: Limit analysis to last N days
 * **ignore_globs**: List of glob patterns for files to ignore
 * **include_globs**: List of glob patterns for files to include

{git_pandas-2.7.0 → git_pandas-2.7.1}/docs/source/repository.rst

@@ -135,7 +135,7 @@ Common Parameters
 Most analysis methods support these filtering parameters:
 
 * **branch**: Branch to analyze (defaults to repository's default branch)
-* **limit**: Maximum number of commits to analyze
+* **limit**: Maximum number of commits to analyze; must be ``None`` or a non-negative integer (excluding booleans). Invalid values raise ``ValueError``; zero selects no commits
 * **days**: Limit analysis to last N days
 * **ignore_globs**: List of glob patterns for files to ignore
 * **include_globs**: List of glob patterns for files to include

git_pandas-2.7.1/docs/source/result_schemas.rst

@@ -0,0 +1,557 @@
+.. This page is generated: python docs/source/schema_contracts.py > docs/source/result_schemas.rst
+
+Result schemas
+==============
+
+Exact column order, index levels and dtype kinds of populated results, pinned by
+``tests/test_schema_contracts.py``. Kinds are ``str``, ``int``, ``float``, ``bool`` and ``datetime``
+(UTC); they hold on pandas 2 and 3. Shapes differ between ``Repository`` and ``ProjectDirectory`` and
+between populated and empty results; both are listed as they are today.
+
+Repository.commit_history()
+---------------------------
+
+Index: ``date`` (datetime)
+
+UTC ``date`` index; includes a ``branch`` column.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``author``
+     - str
+   * - ``committer``
+     - str
+   * - ``message``
+     - str
+   * - ``commit_sha``
+     - str
+   * - ``lines``
+     - int
+   * - ``insertions``
+     - int
+   * - ``deletions``
+     - int
+   * - ``net``
+     - int
+   * - ``branch``
+     - str
+   * - ``repository``
+     - str
+
+ProjectDirectory.commit_history()
+---------------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+``date`` is a column; the integer index restarts at 0 for each repository; no ``branch`` column.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``repository``
+     - str
+   * - ``author``
+     - str
+   * - ``committer``
+     - str
+   * - ``date``
+     - datetime
+   * - ``message``
+     - str
+   * - ``commit_sha``
+     - str
+   * - ``lines``
+     - int
+   * - ``insertions``
+     - int
+   * - ``deletions``
+     - int
+   * - ``net``
+     - int
+
+Repository.file_change_history()
+--------------------------------
+
+Index: ``date`` (datetime)
+
+``date`` is both the index and a column.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``filename``
+     - str
+   * - ``insertions``
+     - int
+   * - ``deletions``
+     - int
+   * - ``lines``
+     - int
+   * - ``message``
+     - str
+   * - ``committer``
+     - str
+   * - ``author``
+     - str
+   * - ``date``
+     - datetime
+   * - ``repository``
+     - str
+
+ProjectDirectory.file_change_history()
+--------------------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+No ``lines`` column; ``date`` is a column on a default integer index.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``repository``
+     - str
+   * - ``date``
+     - datetime
+   * - ``author``
+     - str
+   * - ``committer``
+     - str
+   * - ``message``
+     - str
+   * - ``filename``
+     - str
+   * - ``insertions``
+     - int
+   * - ``deletions``
+     - int
+
+Repository.revs()
+-----------------
+
+Index: ``(unnamed integer index)`` (int)
+
+``date`` is epoch seconds stored as an integer column.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``date``
+     - int
+   * - ``rev``
+     - str
+   * - ``repository``
+     - str
+
+ProjectDirectory.revs()
+-----------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+``date`` is epoch seconds stored as a float column.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``repository``
+     - str
+   * - ``rev``
+     - str
+   * - ``date``
+     - float
+
+Repository.blame(by='repository')
+---------------------------------
+
+Index: ``committer`` (str)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``loc``
+     - int
+   * - ``repository``
+     - str
+
+ProjectDirectory.blame(by='repository')
+---------------------------------------
+
+Index: ``committer`` (str)
+
+No ``repository`` column.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``loc``
+     - int
+
+Repository.blame(by='file')
+---------------------------
+
+Index: ``committer`` (str), ``file`` (str)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``loc``
+     - int
+   * - ``repository``
+     - str
+
+ProjectDirectory.blame(by='file')
+---------------------------------
+
+Index: ``committer`` (str), ``file`` (str), ``repository`` (str)
+
+``repository`` is an index level, not a column.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``loc``
+     - int
+
+Repository.tags()
+-----------------
+
+Index: ``tag_date`` (datetime), ``commit_date`` (datetime)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``tag``
+     - str
+   * - ``annotated``
+     - bool
+   * - ``annotation``
+     - nullable_str
+   * - ``tag_sha``
+     - nullable_str
+   * - ``commit_sha``
+     - str
+   * - ``repository``
+     - str
+
+ProjectDirectory.tags()
+-----------------------
+
+Index: ``tag_date`` (datetime), ``commit_date`` (datetime)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``tag``
+     - str
+   * - ``annotated``
+     - bool
+   * - ``annotation``
+     - nullable_str
+   * - ``tag_sha``
+     - nullable_str
+   * - ``commit_sha``
+     - str
+   * - ``repository``
+     - str
+
+Repository.commits_in_tags()
+----------------------------
+
+Index: ``tag_date`` (datetime), ``commit_date`` (datetime)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``commit_sha``
+     - str
+   * - ``tag``
+     - str
+   * - ``repository``
+     - str
+
+ProjectDirectory.commits_in_tags()
+----------------------------------
+
+Index: ``tag_date`` (datetime), ``commit_date`` (datetime)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``commit_sha``
+     - str
+   * - ``tag``
+     - str
+   * - ``repository``
+     - str
+
+Repository.punchcard()
+----------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``hour_of_day``
+     - int
+   * - ``day_of_week``
+     - int
+   * - ``lines``
+     - int
+   * - ``insertions``
+     - int
+   * - ``deletions``
+     - int
+   * - ``net``
+     - int
+
+ProjectDirectory.punchcard()
+----------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``hour_of_day``
+     - int
+   * - ``day_of_week``
+     - int
+   * - ``lines``
+     - int
+   * - ``insertions``
+     - int
+   * - ``deletions``
+     - int
+   * - ``net``
+     - int
+
+Repository.hours_estimate()
+---------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``committer``
+     - str
+   * - ``hours``
+     - float
+   * - ``repository``
+     - str
+
+ProjectDirectory.hours_estimate()
+---------------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``committer``
+     - str
+   * - ``hours``
+     - float
+   * - ``repository``
+     - str
+
+Repository.file_detail()
+------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+``file`` is a column.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``file``
+     - str
+   * - ``loc``
+     - int
+   * - ``file_owner``
+     - str
+   * - ``ext``
+     - str
+   * - ``last_edit_date``
+     - datetime
+   * - ``repository``
+     - str
+
+ProjectDirectory.file_detail()
+------------------------------
+
+Index: ``file`` (str), ``repository`` (str)
+
+``(file, repository)`` index; a stray ``index`` column of row numbers leaks through.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``index``
+     - int
+   * - ``loc``
+     - int
+   * - ``file_owner``
+     - str
+   * - ``ext``
+     - str
+   * - ``last_edit_date``
+     - datetime
+
+Repository.bus_factor(by='repository')
+--------------------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``repository``
+     - str
+   * - ``bus factor``
+     - int
+
+ProjectDirectory.bus_factor(by='projectd')
+------------------------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+Default grouping; the first column is named ``projectd``.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``projectd``
+     - str
+   * - ``bus factor``
+     - int
+
+Repository.bus_factor(by='file')
+--------------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``file``
+     - str
+   * - ``bus factor``
+     - int
+   * - ``repository``
+     - str
+
+ProjectDirectory.bus_factor(by='file')
+--------------------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``file``
+     - str
+   * - ``bus factor``
+     - int
+   * - ``repository``
+     - str
+
+ProjectDirectory.bus_factor(by='repository')
+--------------------------------------------
+
+Index: ``(unnamed integer index)`` (int)
+
+``bus factor`` has object dtype.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Column
+     - Kind
+   * - ``repository``
+     - str
+   * - ``bus factor``
+     - object
+
+Empty results
+-------------
+
+Where the empty frame differs from the populated one:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Method
+     - Columns
+     - Index
+   * - Repository.file_change_history
+     - ``filename``, ``insertions``, ``deletions``, ``lines``, ``message``, ``committer``, ``author``
+     - (unnamed integer index)
+   * - Repository.revs
+     - ``date``, ``rev``
+     - (unnamed integer index)
+   * - Repository.tags
+     - ``tag_date``, ``commit_date``, ``tag``, ``annotated``, ``annotation``, ``tag_sha``, ``commit_sha``, ``repository``
+     - (unnamed integer index)
+   * - Repository.commits_in_tags
+     - ``commit_sha``, ``tag``, ``tag_date``, ``commit_date``
+     - (unnamed integer index)
+   * - ProjectDirectory.revs
+     - ``repository``, ``rev``
+     - (unnamed integer index)
+   * - ProjectDirectory.tags
+     - (none)
+     - (unnamed integer index)
+   * - ProjectDirectory.commits_in_tags
+     - ``commit_sha``, ``tag``, ``tag_date``, ``commit_date``
+     - (unnamed integer index)