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

{git_pandas-2.1.0 → git_pandas-2.2.0}/CHANGELOG.md

@@ -1,3 +1,11 @@
+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
 ======
 

{git_pandas-2.1.0 → git_pandas-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-pandas
-Version: 2.1.0
+Version: 2.2.0
 Summary: A utility for interacting with data from git repositories as Pandas dataframes
 Author-email: Will McGinnis <will@pedalwrencher.com>
 License: BSD

git_pandas-2.2.0/docs/source/cache.rst

@@ -0,0 +1,121 @@
+Caching
+=======
+
+Git-Pandas supports pluggable cache backends to optimize performance for expensive, repetitive operations. This is particularly useful for large repositories or when running multiple analyses.
+
+Overview
+--------
+
+The caching system provides:
+* In-memory caching for temporary results
+* Redis-based caching for persistent storage
+* Configurable cache durations
+* Automatic cache invalidation
+* Decorator-based caching for expensive operations
+
+Available Cache Backends
+----------------------
+
+In-Memory Cache (EphemeralCache)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The default in-memory cache is ephemeral and will be cleared when the process ends:
+
+.. code-block:: python
+
+    from gitpandas import Repository
+    from gitpandas.cache import EphemeralCache
+    
+    # Create an in-memory cache with default settings
+    cache = EphemeralCache()
+    
+    # Or customize the cache size
+    cache = EphemeralCache(max_keys=500)
+    
+    # Use the cache with a repository
+    repo = Repository('/path/to/repo', cache_backend=cache)
+
+Redis Cache (RedisDFCache)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+For persistent caching across sessions, use Redis:
+
+.. code-block:: python
+
+    from gitpandas import Repository
+    from gitpandas.cache import RedisDFCache
+    
+    # Create a Redis cache with default settings
+    cache = RedisDFCache()
+    
+    # Or customize Redis connection and cache settings
+    cache = RedisDFCache(
+        host='localhost',
+        port=6379,
+        db=12,
+        max_keys=1000,
+        ttl=3600  # Cache entries expire after 1 hour
+    )
+    
+    # Use the cache with a repository
+    repo = Repository('/path/to/repo', cache_backend=cache)
+
+Using the Cache Decorator
+----------------------
+
+The `@multicache` decorator can be used to cache method results:
+
+.. code-block:: python
+
+    from gitpandas.cache import multicache
+    
+    @multicache(
+        key_prefix="method_name",
+        key_list=["param1", "param2"],
+        skip_if=lambda x: x.get("param1") is None
+    )
+    def expensive_method(self, param1, param2):
+        # Method implementation
+        pass
+
+Configuration
+------------
+
+Cache backends can be configured with various parameters:
+
+EphemeralCache:
+* ``max_keys``: Maximum number of keys to store in memory (default: 1000)
+
+RedisDFCache:
+* ``host``: Redis host (default: 'localhost')
+* ``port``: Redis port (default: 6379)
+* ``db``: Redis database number (default: 12)
+* ``max_keys``: Maximum number of keys to store (default: 1000)
+* ``ttl``: Time-to-live in seconds for cache entries (default: None, no expiration)
+* Additional keyword arguments are passed to redis.StrictRedis
+
+API Reference
+------------
+
+.. currentmodule:: gitpandas.cache
+
+.. autoclass:: CacheBackend
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __init__, __getitem__, __setitem__, __delitem__, __contains__, __len__
+
+.. autoclass:: EphemeralCache
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+
+.. autoclass:: RedisDFCache
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+
+.. autofunction:: multicache

{git_pandas-2.1.0 → git_pandas-2.2.0}/docs/source/project.rst

@@ -26,15 +26,20 @@ Create a ProjectDirectory from a directory containing multiple repositories:
 .. code-block:: python
 
     from gitpandas import ProjectDirectory
-    project = ProjectDirectory(working_dir='/path/to/dir/', ignore=None, verbose=True)
+    project = ProjectDirectory(
+        working_dir='/path/to/dir/',
+        ignore_repos=['repo_to_ignore'],
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
+    )
 
-The `ignore` parameter can be a list of directories to exclude. This method uses `os.walk` to search for `.git` directories recursively.
+The `ignore_repos` parameter can be a list of repository names to exclude. This method uses `os.walk` to search for `.git` directories recursively.
 
 To check which repositories are included:
 
 .. code-block:: python
 
-    print(project._repo_name())
+    print(project.repo_name())
 
 Explicit Local Repositories
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -46,8 +51,9 @@ Create a ProjectDirectory from a list of local repositories:
     from gitpandas import ProjectDirectory
     project = ProjectDirectory(
         working_dir=['/path/to/repo1/', '/path/to/repo2/'],
-        ignore=None,
-        verbose=True
+        ignore_repos=['repo_to_ignore'],
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
     )
 
 Explicit Remote Repositories
@@ -60,8 +66,9 @@ Create a ProjectDirectory from a list of remote repositories:
     from gitpandas import ProjectDirectory
     project = ProjectDirectory(
         working_dir=['git://github.com/user/repo1.git', 'git://github.com/user/repo2.git'],
-        ignore=None,
-        verbose=True
+        ignore_repos=['repo_to_ignore'],
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
     )
 
 Common Operations
@@ -72,7 +79,7 @@ Here are some common operations you can perform with a ProjectDirectory object:
 .. code-block:: python
 
     # Get commit history across all repositories
-    commits_df = project.commit_history(branch='master')
+    commits_df = project.commit_history()
     
     # Get blame information across all repositories
     blame_df = project.blame()
@@ -85,6 +92,9 @@ Here are some common operations you can perform with a ProjectDirectory object:
     
     # Get file change history across all repositories
     changes_df = project.file_change_history()
+    
+    # Get detailed repository information
+    repo_info = project.repo_information()
 
 API Reference
 ------------
@@ -110,11 +120,5 @@ API Reference
       ~ProjectDirectory.tags
       ~ProjectDirectory.revs
       ~ProjectDirectory.bus_factor
-      ~ProjectDirectory.is_bare
-      ~ProjectDirectory.has_coverage
-
-   .. rubric:: Properties
-
-   .. autosummary::
-      :nosignatures:
+      ~ProjectDirectory.repo_information
       ~ProjectDirectory.repo_name

{git_pandas-2.1.0 → git_pandas-2.2.0}/docs/source/repository.rst

@@ -26,7 +26,11 @@ Create a Repository from a local Git repository:
 .. code-block:: python
 
     from gitpandas import Repository
-    repo = Repository(working_dir='/path/to/repo/', verbose=True)
+    repo = Repository(
+        working_dir='/path/to/repo/',
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
+    )
 
 The directory must contain a `.git` directory. Subdirectories are not searched.
 
@@ -38,7 +42,11 @@ Create a Repository from a remote Git repository:
 .. code-block:: python
 
     from gitpandas import Repository
-    repo = Repository(working_dir='git://github.com/user/repo.git', verbose=True)
+    repo = Repository(
+        working_dir='git://github.com/user/repo.git',
+        verbose=True,
+        default_branch='main'  # Optional, will auto-detect if not specified
+    )
 
 The repository will be cloned locally into a temporary directory. This can be slow for large repositories.
 
@@ -63,6 +71,9 @@ Here are some common operations you can perform with a Repository object:
     
     # Get file change history
     changes_df = repo.file_change_history()
+    
+    # Get repository name
+    repo_name = repo.repo_name
 
 API Reference
 ------------
@@ -90,12 +101,16 @@ API Reference
       ~Repository.bus_factor
       ~Repository.is_bare
       ~Repository.has_coverage
+      ~Repository.has_branch
+      ~Repository.get_branches_by_commit
+      ~Repository.commits_in_tags
 
    .. rubric:: Properties
 
    .. autosummary::
       :nosignatures:
       ~Repository.repo_name
+      ~Repository.default_branch
 
 .. autoclass:: GitFlowRepository
    :members:

{git_pandas-2.1.0 → git_pandas-2.2.0}/docs/source/usecases.rst

@@ -17,7 +17,7 @@ Get basic information about a repository:
     repo = Repository('/path/to/repo')
     
     # Get repository name
-    print(repo._repo_name())
+    print(repo.repo_name)
     
     # Check if repository is bare
     print(repo.is_bare())
@@ -52,6 +52,9 @@ Analyze commit patterns and history:
     
     # Filter by directory
     src_changes = repo.file_change_history(include_globs=['src/*'])
+    
+    # Get commits in tags
+    tag_commits = repo.commits_in_tags()
 
 Project-Level Analysis
 --------------------
@@ -71,17 +74,17 @@ Analyze multiple repositories simultaneously:
         'git://github.com/user/repo2.git'
     ])
     
-    # Get aggregated metrics
-    print(project.general_information())
+    # Get repository information
+    print(project.repo_information())
     
     # Calculate bus factor
     print(project.bus_factor())
     
-    # Get file change rates
-    print(project.file_change_rates())
+    # Get file change history
+    print(project.file_change_history())
     
-    # Generate punchcard data
-    print(project.punchcard())
+    # Get blame information
+    print(project.blame())
 
 Advanced Analysis
 ---------------
@@ -96,7 +99,7 @@ Track code ownership over time:
     # Get cumulative blame
     blame_df = repo.cumulative_blame()
     
-    # Plot cumulative blame
+    # Plot cumulative blame using pandas plotting
     import matplotlib.pyplot as plt
     blame_df.plot(x='date', y='loc', title='Cumulative Blame Over Time')
     plt.show()
@@ -108,14 +111,14 @@ Analyze project sustainability:
 
 .. code-block:: python
 
-    # Calculate bus factor
-    bus_factor = project.bus_factor()
+    # Calculate bus factor for repository
+    bus_factor = repo.bus_factor()
     
-    # Get detailed contributor metrics
-    contributors_df = project.contributor_metrics()
+    # Get detailed blame information
+    blame_df = repo.blame(by='file')  # Get file-level blame details
     
-    # Analyze file ownership
-    ownership_df = project.file_ownership()
+    # Analyze ownership patterns
+    ownership_patterns = repo.blame(committer=True, by='repository')
 
 Performance Optimization
 ---------------------
@@ -127,33 +130,40 @@ Optimize performance with caching:
 
 .. code-block:: python
 
-    # Enable in-memory caching
-    repo = Repository('/path/to/repo', cache=True)
-    
-    # Use Redis for persistent caching
-    repo = Repository(
-        '/path/to/repo',
-        cache=True,
-        cache_backend='redis',
-        redis_url='redis://localhost:6379/0'
+    from gitpandas import Repository
+    from gitpandas.cache import EphemeralCache, RedisDFCache
+    
+    # Use in-memory caching
+    cache = EphemeralCache()
+    repo = Repository('/path/to/repo', cache_backend=cache)
+    
+    # Or use Redis for persistent caching
+    redis_cache = RedisDFCache(
+        host='localhost',
+        port=6379,
+        db=12,
+        ttl=3600  # Cache entries expire after 1 hour
     )
+    repo = Repository('/path/to/repo', cache_backend=redis_cache)
 
 Visualization Examples
 -------------------
 
-Commit Patterns
+Commit Analysis
 ~~~~~~~~~~~~~
 
 Visualize commit patterns:
 
 .. code-block:: python
 
-    # Generate punchcard data
-    punchcard_df = repo.punchcard()
+    # Get commit history
+    commit_df = repo.commit_history()
     
-    # Plot commit patterns
-    import matplotlib.pyplot as plt
-    punchcard_df.plot(kind='heatmap', title='Commit Patterns')
+    # Plot commits over time using pandas
+    commit_df.resample('D').size().plot(
+        kind='bar',
+        title='Commits per Day'
+    )
     plt.show()
 
 File Change Analysis
@@ -166,17 +176,21 @@ Visualize file changes:
     # Get file change history
     changes_df = repo.file_change_history()
     
-    # Plot changes over time
-    changes_df.plot(x='date', y='changes', title='File Changes Over Time')
+    # Plot changes over time using pandas
+    changes_df.groupby('filename')['insertions'].sum().plot(
+        kind='bar',
+        title='Lines Added by File'
+    )
     plt.show()
 
 Best Practices
 ------------
 
-* Use caching for expensive operations
-* Filter data early to improve performance
+* Use caching for expensive operations like blame analysis
+* Filter data early using include_globs/ignore_globs
 * Leverage pandas operations for analysis
 * Consider memory usage with large repositories
-* Use appropriate visualization tools
+* Use appropriate branch names (main/master)
+* Handle repository cleanup properly when using remote repositories
 
 For more examples and detailed API documentation, see the :doc:`repository` and :doc:`project` pages.