API Reference

API Reference

This page documents all public APIs available in githubauthlib.

Core Functions

get_github_token()

from githubauthlib import get_github_token

def get_github_token() -> Optional[str]:
    """
    Retrieves the GitHub token from the system's secure storage.

    Returns:
        Optional[str]: The GitHub token if found and valid, None otherwise

    Raises:
        CredentialHelperError: If there's an error accessing the credential helper
        UnsupportedPlatformError: If the operating system is not supported
        GitHubAuthError: Base exception for GitHub authentication errors
    """

Example Usage

try:
    token = get_github_token()
    if token:
        print("Token retrieved successfully")
except GitHubAuthError as e:
    print(f"Error: {e}")

validate_token()

from githubauthlib.github_auth import validate_token

def validate_token(token: str) -> bool:
    """
    Validate the format of a GitHub token.
    
    Args:
        token (str): The token to validate
        
    Returns:
        bool: True if the token format is valid, False otherwise
    """

Example Usage

token = "ghp_1234567890abcdef1234567890abcdef123456"
is_valid = validate_token(token)

Exceptions

GitHubAuthError

class GitHubAuthError(Exception):
    """Base exception for GitHub authentication errors."""
    pass

CredentialHelperError

class CredentialHelperError(GitHubAuthError):
    """Raised when there's an error with the credential helper."""
    pass

UnsupportedPlatformError

class UnsupportedPlatformError(GitHubAuthError):
    """Raised when the operating system is not supported."""
    pass

Internal Functions

These functions are used internally but may be useful for debugging or extending the library:

_get_token_macos()

def _get_token_macos() -> Optional[str]:
    """Retrieve token from macOS keychain."""

_get_token_windows()

def _get_token_windows() -> Optional[str]:
    """Retrieve token from Windows Credential Manager."""

_get_token_linux()

def _get_token_linux() -> Optional[str]:
    """Retrieve token from Linux libsecret."""

Type Hints

The library uses Python type hints throughout:

from typing import Optional

# Common return type for token retrieval functions
Token = Optional[str]

Constants

The library doesn't expose any public constants, but internally uses:

• Regular expression for token validation
• Logging configuration
• Platform-specific command strings

Logging

The library uses Python's standard logging module:

import logging

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

Platform Support

The library supports the following platforms:

• macOS (Darwin)

  • Uses git credential-osxkeychain
  • Requires Keychain Access

• Windows

  • Uses Windows Credential Manager
  • Supports manager, manager-core, and wincred helpers

• Linux

  • Uses libsecret
  • Requires secret-tool command-line utility

Error Handling

All errors inherit from GitHubAuthError:

Exception
└── GitHubAuthError
    ├── CredentialHelperError
    └── UnsupportedPlatformError

Best Practices

1. Always handle exceptions:

try:
    token = get_github_token()
except GitHubAuthError as e:
    # Handle error

2. Validate tokens before use:

token = get_github_token()
if token and validate_token(token):
    # Use token

3. Configure logging as needed:

logging.getLogger('githubauthlib').setLevel(logging.DEBUG)

Version Information

The current version can be accessed via:

from githubauthlib import __version__
print(__version__)  # e.g., '1.0.0'