gitlabber 2.0.0__tar.gz → 2.1.0__tar.gz

{gitlabber-2.0.0/gitlabber.egg-info → gitlabber-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlabber
-Version: 2.0.0
+Version: 2.1.0
 Summary: A Gitlab clone/pull utility for backing up or cloning Gitlab groups
 Author-email: Erez Mazor <erezmazor@gmail.com>
 License: MIT
@@ -34,9 +34,11 @@ Requires-Dist: coverage; extra == "test"
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
 Requires-Dist: pytest-integration; extra == "test"
+Provides-Extra: keyring
+Requires-Dist: keyring>=24.0.0; extra == "keyring"
 Dynamic: license-file
 
-.. image:: https://github.com/ezbz/gitlabber/actions/workflows/python-app.yml/badge.svg?branch=master
+.. image:: https://github.com/ezbz/gitlabber/actions/workflows/python-app.yml/badge.svg?branch=main
     :target: https://github.com/ezbz/gitlabber/actions/workflows/python-app.yml
 
 .. image:: https://codecov.io/gh/ezbz/gitlabber/branch/main/graph/badge.svg
@@ -44,6 +46,9 @@ Dynamic: license-file
   
 .. image:: https://badge.fury.io/py/gitlabber.svg
     :target: https://badge.fury.io/py/gitlabber
+
+.. image:: https://img.shields.io/pypi/dm/gitlabber
+    :target: https://pypi.org/project/gitlabber/
   
 .. image:: https://img.shields.io/pypi/l/gitlabber.svg
     :target: https://pypi.python.org/pypi/gitlabber/
@@ -71,7 +76,7 @@ Installation
 ------------
 
 System Requirements
--------------------
+~~~~~~~~~~~~~~~~~~~
 * Python 3.11 or higher
 * Git 2.0 or higher
 * Network access to GitLab instance
@@ -92,6 +97,12 @@ Installation Methods
       cd gitlabber
       pip install -e .
 
+* Optional: Install with secure token storage support:
+
+  .. code-block:: bash
+
+      pip install gitlabber[keyring]
+
 * You'll need to create an `access token <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_ from GitLab with API scopes `read_repository`
   and ``read_api`` (or ``api``, for GitLab versions <12.0)
 
@@ -127,6 +138,34 @@ Usage
     | exclude          | -x               | `GITLABBER_EXCLUDE`       |
     +------------------+------------------+---------------------------+
 
+* **Secure Token Storage**: Gitlabber supports secure token storage using OS-native keyring (Keychain on macOS, Secret Service on Linux, Windows Credential Manager). This allows you to store your GitLab token securely and avoid passing it via CLI or environment variables.
+
+  **Token Resolution Priority:**
+  
+  1. CLI argument (``-t/--token``) - highest priority
+  2. Stored token (from secure storage)
+  3. Environment variable (``GITLAB_TOKEN``)
+
+  **Usage:**
+
+  .. code-block:: bash
+
+      # Install keyring (optional, for secure storage)
+      pip install gitlabber[keyring]
+
+      # Store token securely (one-time setup)
+      gitlabber --store-token -u https://gitlab.com
+      Enter token: [hidden input]
+      Token stored securely in keyring for https://gitlab.com ✓
+
+      # Use stored token automatically (no -t flag needed)
+      gitlabber -u https://gitlab.com .
+
+      # Override with CLI token if needed
+      gitlabber -t <token> -u https://gitlab.com .
+
+  **Note:** If keyring is not installed, gitlabber falls back to environment variables or CLI arguments (current behavior).
+
 * To view the tree run the command with your includes/excludes and the ``-p`` flag. It will print your tree like so:
 
     .. code-block:: bash
@@ -157,7 +196,7 @@ Usage
 .. code-block:: bash
 
     usage: gitlabber [-h] [-t token] [-T] [-u url] [--verbose] [-p] [--print-format {json,yaml,tree}] [-n {name,path}] [-m {ssh,http}]
-                    [-a {include,exclude,only}] [-i csv] [-x csv] [-c N] [--api-concurrency N] [-r] [-F] [-d] [-s] [-g term] [-U] [-o options] [--version]
+                    [-a {include,exclude,only}] [-i csv] [-x csv] [-c N] [--api-concurrency N] [-r] [-F] [-d] [-s] [-g term] [-U] [-o options] [--version] [--store-token]
                     [dest]
 
     Gitlabber - clones or pulls entire groups/projects tree from gitlab
@@ -198,6 +237,7 @@ Usage
     -o options, --git-options options
                             provide additional options as csv for the git command (e.g., --depth=1). See: clone/multi_options https://gitpython.readthedocs.io/en/stable/reference.html#
     --version             print the version
+    --store-token         store token securely in OS keyring (requires keyring package)
 
     examples:
 
@@ -233,6 +273,12 @@ Usage
         # API concurrency speeds up tree discovery, git concurrency speeds up cloning
         gitlabber --api-concurrency 5 -c 10 -t <token> -u <url> .
 
+        store token securely for future use (one-time setup)
+        gitlabber --store-token -u https://gitlab.com
+
+        use stored token (no -t flag needed)
+        gitlabber -u https://gitlab.com .
+
         **Performance Results:**
         * Sequential (``--api-concurrency 1``): ~96 seconds
         * With ``--api-concurrency 5``: ~21 seconds (**4.6x speedup**)
@@ -246,27 +292,27 @@ Common Use Cases
 Clone Specific Groups
 ---------------------
 
-    .. code-block:: bash
+.. code-block:: bash
 
-        # Clone only projects from a specific group
-        gitlabber -i '/MyGroup/**' .
+    # Clone only projects from a specific group
+    gitlabber -i '/MyGroup/**' .
 
 Exclude Archived Projects
 -------------------------
 
-    .. code-block:: bash
+.. code-block:: bash
 
-        # Clone all non-archived projects
-        gitlabber -a exclude .
+    # Clone all non-archived projects
+    gitlabber -a exclude .
 
 Debugging
 ---------
 * You can use the ``--verbose`` flag to print Gitlabber debug messages
 * For more verbose GitLab messages, you can get the `GitPython <https://gitpython.readthedocs.io/en/stable>`_ module to print more debug messages by setting the environment variable:
 
-    .. code-block:: bash
+.. code-block:: bash
 
-        export GIT_PYTHON_TRACE='full'
+    export GIT_PYTHON_TRACE='full'
 
 Troubleshooting
 ---------------

{gitlabber-2.0.0 → gitlabber-2.1.0}/README.rst

@@ -1,4 +1,4 @@
-.. image:: https://github.com/ezbz/gitlabber/actions/workflows/python-app.yml/badge.svg?branch=master
+.. image:: https://github.com/ezbz/gitlabber/actions/workflows/python-app.yml/badge.svg?branch=main
     :target: https://github.com/ezbz/gitlabber/actions/workflows/python-app.yml
 
 .. image:: https://codecov.io/gh/ezbz/gitlabber/branch/main/graph/badge.svg
@@ -6,6 +6,9 @@
   
 .. image:: https://badge.fury.io/py/gitlabber.svg
     :target: https://badge.fury.io/py/gitlabber
+
+.. image:: https://img.shields.io/pypi/dm/gitlabber
+    :target: https://pypi.org/project/gitlabber/
   
 .. image:: https://img.shields.io/pypi/l/gitlabber.svg
     :target: https://pypi.python.org/pypi/gitlabber/
@@ -33,7 +36,7 @@ Installation
 ------------
 
 System Requirements
--------------------
+~~~~~~~~~~~~~~~~~~~
 * Python 3.11 or higher
 * Git 2.0 or higher
 * Network access to GitLab instance
@@ -54,6 +57,12 @@ Installation Methods
       cd gitlabber
       pip install -e .
 
+* Optional: Install with secure token storage support:
+
+  .. code-block:: bash
+
+      pip install gitlabber[keyring]
+
 * You'll need to create an `access token <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_ from GitLab with API scopes `read_repository`
   and ``read_api`` (or ``api``, for GitLab versions <12.0)
 
@@ -89,6 +98,34 @@ Usage
     | exclude          | -x               | `GITLABBER_EXCLUDE`       |
     +------------------+------------------+---------------------------+
 
+* **Secure Token Storage**: Gitlabber supports secure token storage using OS-native keyring (Keychain on macOS, Secret Service on Linux, Windows Credential Manager). This allows you to store your GitLab token securely and avoid passing it via CLI or environment variables.
+
+  **Token Resolution Priority:**
+  
+  1. CLI argument (``-t/--token``) - highest priority
+  2. Stored token (from secure storage)
+  3. Environment variable (``GITLAB_TOKEN``)
+
+  **Usage:**
+
+  .. code-block:: bash
+
+      # Install keyring (optional, for secure storage)
+      pip install gitlabber[keyring]
+
+      # Store token securely (one-time setup)
+      gitlabber --store-token -u https://gitlab.com
+      Enter token: [hidden input]
+      Token stored securely in keyring for https://gitlab.com ✓
+
+      # Use stored token automatically (no -t flag needed)
+      gitlabber -u https://gitlab.com .
+
+      # Override with CLI token if needed
+      gitlabber -t <token> -u https://gitlab.com .
+
+  **Note:** If keyring is not installed, gitlabber falls back to environment variables or CLI arguments (current behavior).
+
 * To view the tree run the command with your includes/excludes and the ``-p`` flag. It will print your tree like so:
 
     .. code-block:: bash
@@ -119,7 +156,7 @@ Usage
 .. code-block:: bash
 
     usage: gitlabber [-h] [-t token] [-T] [-u url] [--verbose] [-p] [--print-format {json,yaml,tree}] [-n {name,path}] [-m {ssh,http}]
-                    [-a {include,exclude,only}] [-i csv] [-x csv] [-c N] [--api-concurrency N] [-r] [-F] [-d] [-s] [-g term] [-U] [-o options] [--version]
+                    [-a {include,exclude,only}] [-i csv] [-x csv] [-c N] [--api-concurrency N] [-r] [-F] [-d] [-s] [-g term] [-U] [-o options] [--version] [--store-token]
                     [dest]
 
     Gitlabber - clones or pulls entire groups/projects tree from gitlab
@@ -160,6 +197,7 @@ Usage
     -o options, --git-options options
                             provide additional options as csv for the git command (e.g., --depth=1). See: clone/multi_options https://gitpython.readthedocs.io/en/stable/reference.html#
     --version             print the version
+    --store-token         store token securely in OS keyring (requires keyring package)
 
     examples:
 
@@ -195,6 +233,12 @@ Usage
         # API concurrency speeds up tree discovery, git concurrency speeds up cloning
         gitlabber --api-concurrency 5 -c 10 -t <token> -u <url> .
 
+        store token securely for future use (one-time setup)
+        gitlabber --store-token -u https://gitlab.com
+
+        use stored token (no -t flag needed)
+        gitlabber -u https://gitlab.com .
+
         **Performance Results:**
         * Sequential (``--api-concurrency 1``): ~96 seconds
         * With ``--api-concurrency 5``: ~21 seconds (**4.6x speedup**)
@@ -208,27 +252,27 @@ Common Use Cases
 Clone Specific Groups
 ---------------------
 
-    .. code-block:: bash
+.. code-block:: bash
 
-        # Clone only projects from a specific group
-        gitlabber -i '/MyGroup/**' .
+    # Clone only projects from a specific group
+    gitlabber -i '/MyGroup/**' .
 
 Exclude Archived Projects
 -------------------------
 
-    .. code-block:: bash
+.. code-block:: bash
 
-        # Clone all non-archived projects
-        gitlabber -a exclude .
+    # Clone all non-archived projects
+    gitlabber -a exclude .
 
 Debugging
 ---------
 * You can use the ``--verbose`` flag to print Gitlabber debug messages
 * For more verbose GitLab messages, you can get the `GitPython <https://gitpython.readthedocs.io/en/stable>`_ module to print more debug messages by setting the environment variable:
 
-    .. code-block:: bash
+.. code-block:: bash
 
-        export GIT_PYTHON_TRACE='full'
+    export GIT_PYTHON_TRACE='full'
 
 Troubleshooting
 ---------------

{gitlabber-2.0.0 → gitlabber-2.1.0}/gitlabber/__init__.py

@@ -5,4 +5,4 @@ while maintaining the directory structure. It supports filtering, progress
 tracking, and various configuration options.
 """
 
-__version__ = '2.0.0'
+__version__ = '2.1.0'

{gitlabber-2.0.0 → gitlabber-2.1.0}/gitlabber/auth.py

@@ -6,9 +6,7 @@ authentication and provides a no-op provider for testing.
 """
 
 from abc import ABC, abstractmethod
-from typing import Optional
 from gitlab import Gitlab
-from gitlab.exceptions import GitlabAuthenticationError
 
 class AuthProvider(ABC):
     """Interface for GitLab authentication providers."""

{gitlabber-2.0.0 → gitlabber-2.1.0}/gitlabber/cli.py

@@ -23,6 +23,7 @@ from .format import PrintFormat
 from .gitlab_tree import GitlabTree
 from .method import CloneMethod
 from .naming import FolderNaming
+from .token_storage import TokenStorage, TokenStorageError
 
 logging.basicConfig(
     level=logging.INFO,
@@ -140,6 +141,57 @@ def _require(value: Optional[str], message: str) -> str:
     return value
 
 
+def _resolve_token(
+    cli_token: Optional[str],
+    url: str,
+    settings: GitlabberSettings,
+) -> str:
+    """Resolve token from various sources in priority order.
+    
+    Priority:
+    1. CLI argument (-t/--token) - highest priority
+    2. Stored token (from secure storage)
+    3. Environment variable (GITLAB_TOKEN) - from settings
+    
+    Args:
+        cli_token: Token from CLI argument
+        url: GitLab instance URL
+        settings: Settings loaded from environment variables
+        
+    Returns:
+        Resolved token string
+        
+    Raises:
+        typer.Exit: If no token found
+    """
+    # 1. CLI token (highest priority)
+    if cli_token:
+        return cli_token
+    
+    # 2. Stored token (if available)
+    storage = TokenStorage()
+    if storage.is_available():
+        stored = storage.retrieve(url)
+        if stored:
+            return stored
+    
+    # 3. Environment variable (current behavior)
+    if settings.token:
+        return settings.token
+    
+    # 4. Error - no token found
+    from .exceptions import format_error_with_suggestion
+    error_msg, suggestion = format_error_with_suggestion(
+        'config_missing',
+        "Please specify a valid token with -t/--token or the GITLAB_TOKEN environment variable.",
+        {}
+    )
+    typer.secho(error_msg, err=True)
+    if suggestion:
+        typer.secho(f"\n💡 {suggestion}", err=True)
+    raise typer.Exit(1)
+
+
 def run_gitlabber(
     *,
     dest: Optional[str],
@@ -202,14 +254,13 @@ def run_gitlabber(
     Raises:
         typer.Exit: If required parameters are missing or tree is empty
     """
-    token_value = _require(
-        token or settings.token,
-        "Please specify a valid token with -t/--token or the GITLAB_TOKEN environment variable.",
-    )
     url_value = _require(
         url or settings.url,
         "Please specify a valid gitlab base url with -u/--url or the GITLAB_URL environment variable.",
     )
+    
+    # Resolve token with priority: CLI -> Stored -> Env var
+    token_value = _resolve_token(token, url_value, settings)
     if not print_tree_only and dest is None and not user_projects:
         typer.secho(
             "Please specify a destination for the gitlab tree.",
@@ -279,10 +330,10 @@ def run_gitlabber(
     tree.load_tree()
 
     if print_tree_only:
-        # Always print tree, even if empty (so JSON output is valid)
+        # In print mode, allow empty trees to be printed (user might want to see empty result)
         tree.print_tree(print_format)
     else:
-        # Only error if trying to sync an empty tree
+        # In sync mode, empty tree is an error
         if tree.is_empty():
             from .exceptions import format_error_with_suggestion
             error_msg, suggestion = format_error_with_suggestion(
@@ -439,6 +490,11 @@ def cli(
         is_eager=True,
         help="Print version and exit",
     ),
+    store_token: bool = typer.Option(
+        False,
+        "--store-token",
+        help="Store token securely in OS keyring (requires keyring package)",
+    ),
 ) -> None:
     """Main CLI command for gitlabber.
     
@@ -453,6 +509,37 @@ def cli(
         sys.exit(0)
     
     settings = GitlabberSettings()
+    
+    # Handle token storage
+    if store_token:
+        url_value = url or settings.url
+        if not url_value:
+            typer.secho(
+                "Error: URL required for storing token. Use -u/--url or GITLAB_URL.",
+                err=True,
+            )
+            raise typer.Exit(1)
+        
+        # Get token from CLI or prompt
+        token_to_store = token
+        if not token_to_store:
+            token_to_store = typer.prompt("Enter token", hide_input=True)
+        
+        try:
+            storage = TokenStorage()
+            if not storage.is_available():
+                typer.secho(
+                    "Error: keyring not available. Install with: pip install keyring",
+                    err=True,
+                )
+                raise typer.Exit(1)
+            storage.store(url_value, token_to_store)
+            typer.echo(f"Token stored securely in keyring for {url_value} ✓")
+        except TokenStorageError as e:
+            typer.secho(f"Error: {str(e)}", err=True)
+            raise typer.Exit(1)
+        raise typer.Exit(0)  # Exit after storing
+    
     include_shared_value = not exclude_shared
 
     run_gitlabber(

{gitlabber-2.0.0 → gitlabber-2.1.0}/gitlabber/gitlab_tree.py

@@ -5,7 +5,7 @@ the project hierarchy from GitLab, filtering it, and synchronizing
 repositories to the local filesystem.
 """
 
-from typing import Optional, Any, Union
+from typing import Optional, Union
 from gitlab import Gitlab
 from gitlab.exceptions import GitlabAuthenticationError
 from anytree import Node, RenderTree

{gitlabber-2.0.0 → gitlabber-2.1.0}/gitlabber/rate_limiter.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import threading
 import time
-from typing import Optional
 
 
 class RateLimitedExecutor:

gitlabber-2.1.0/gitlabber/token_storage.py

@@ -0,0 +1,117 @@
+"""Secure token storage using OS keyring.
+
+This module provides a simple interface for storing and retrieving GitLab
+tokens securely using the OS-native keyring. If keyring is not available,
+the storage gracefully degrades and returns None.
+"""
+
+from typing import Optional
+
+
+class TokenStorageError(Exception):
+    """Exception raised for token storage errors."""
+    pass
+
+
+class TokenStorage:
+    """Simple token storage using OS keyring.
+    
+    This class provides secure storage for GitLab tokens using the OS-native
+    keyring (Keychain on macOS, Secret Service on Linux, Credential Manager
+    on Windows). If the keyring library is not available, all operations
+    gracefully fail and return None.
+    
+    Attributes:
+        SERVICE_NAME: Service name used in keyring (identifies gitlabber)
+    """
+    
+    SERVICE_NAME = "gitlabber"
+    
+    def __init__(self):
+        """Initialize token storage.
+        
+        Attempts to import the keyring library. If unavailable, storage
+        operations will return None or raise TokenStorageError.
+        """
+        self._keyring = None
+        self._try_import_keyring()
+    
+    def _try_import_keyring(self) -> None:
+        """Try to import keyring, fail silently if unavailable."""
+        try:
+            import keyring
+            self._keyring = keyring
+        except ImportError:
+            self._keyring = None
+    
+    def is_available(self) -> bool:
+        """Check if keyring storage is available.
+        
+        Returns:
+            True if keyring is available, False otherwise
+        """
+        return self._keyring is not None
+    
+    def store(self, url: str, token: str) -> None:
+        """Store token for a GitLab URL.
+        
+        Args:
+            url: GitLab instance URL (e.g., https://gitlab.com)
+            token: GitLab personal access token
+            
+        Raises:
+            TokenStorageError: If keyring is not available or storage fails
+        """
+        if not self.is_available():
+            raise TokenStorageError(
+                "Keyring not available. Install with: pip install keyring"
+            )
+        try:
+            self._keyring.set_password(self.SERVICE_NAME, url, token)
+        except Exception as e:
+            raise TokenStorageError(f"Failed to store token: {str(e)}") from e
+    
+    def retrieve(self, url: str) -> Optional[str]:
+        """Retrieve token for a GitLab URL.
+        
+        Args:
+            url: GitLab instance URL
+            
+        Returns:
+            Token if found and keyring is available, None otherwise
+        """
+        if not self.is_available():
+            return None
+        try:
+            return self._keyring.get_password(self.SERVICE_NAME, url)
+        except Exception:
+            # Keyring errors (permissions, etc.) - return None gracefully
+            return None
+    
+    def delete(self, url: str) -> None:
+        """Delete stored token for a GitLab URL.
+        
+        Args:
+            url: GitLab instance URL
+        """
+        if not self.is_available():
+            return
+        try:
+            self._keyring.delete_password(self.SERVICE_NAME, url)
+        except Exception:
+            # Ignore if not found or other errors
+            pass
+    
+    def list_stored_urls(self) -> list[str]:
+        """List all URLs with stored tokens.
+        
+        Note: Most keyring backends don't support listing credentials.
+        This method returns an empty list for compatibility.
+        
+        Returns:
+            List of URLs (empty for keyring backends)
+        """
+        # Keyring doesn't support listing credentials
+        # This is a limitation of most keyring backends
+        return []
+