tessl/pypi-certbot

ACME client that automates the process of obtaining, installing, and renewing SSL/TLS certificates from Let's Encrypt certificate authority.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Error Handling & Exceptions

Name: tessl/pypi-certbot
Author: tessl

Comprehensive exception hierarchy for handling different types of errors that can occur during certificate operations, plugin usage, and configuration management.

Capabilities

Base Error Classes

Foundation exception classes that provide the base hierarchy for all Certbot errors.

class Error(Exception):
    """
    Generic Certbot client error.
    
    Base class for all Certbot-specific exceptions.
    """

class ReverterError(Error):
    """
    Certbot Reverter error.
    
    Raised when configuration backup/restore operations fail.
    """

class SubprocessError(Error):
    """
    Subprocess handling error.
    
    Raised when external command execution fails.
    """

class SignalExit(Error):
    """
    A Unix signal was received while in the ErrorHandler context manager.
    
    Used to handle graceful shutdown on signals like SIGINT, SIGTERM.
    """

class LockError(Error):
    """
    File locking error.
    
    Raised when Certbot cannot acquire necessary file locks.
    """

class HookCommandNotFound(Error):
    """
    Failed to find a hook command in the PATH.
    
    Raised when pre/post/deploy hook commands cannot be executed.
    """

class OverlappingMatchFound(Error):
    """
    Multiple lineages matched what should have been a unique result.
    
    Raised when certificate selection is ambiguous.
    """

Account Management Errors

Errors related to ACME account operations and storage.

class AccountStorageError(Error):
    """
    Generic account storage error.
    
    Base class for account-related storage operations.
    """

class AccountNotFound(AccountStorageError):
    """
    Account not found error.
    
    Raised when trying to load an account that doesn't exist.
    """

Usage examples:

from certbot import errors

try:
    account = account_storage.load('nonexistent-account-id')
except errors.AccountNotFound:
    print("Account does not exist")
except errors.AccountStorageError as e:
    print(f"Account storage error: {e}")

Authorization and Challenge Errors

Errors that occur during ACME authorization and challenge processes.

class AuthorizationError(Error):
    """
    Authorization error.
    
    Base class for ACME authorization failures.
    """

class FailedChallenges(AuthorizationError):
    """
    Failed challenges error.
    
    Raised when one or more ACME challenges fail during authorization.
    Contains information about which challenges failed and why.
    """
    
    def __init__(self, failed_achalls: set[AnnotatedChallenge]):
        """
        Initialize with failed challenges.
        
        Args:
            failed_achalls: Set of failed AnnotatedChallenge instances
        """
        self.failed_achalls = failed_achalls
        super().__init__()
    
    def __str__(self) -> str:
        """
        Return formatted error message with challenge details.
        
        Returns:
            Detailed error message listing failed challenges
        """

Usage examples:

from certbot import errors

try:
    # Perform ACME challenges
    authenticator.perform(challenges)
except errors.FailedChallenges as e:
    print("Challenge failures:")
    for achall in e.failed_achalls:
        print(f"  Domain: {achall.domain}, Type: {achall.typ}, Error: {achall.error}")
except errors.AuthorizationError:
    print("Authorization failed")

Plugin Errors

Errors specific to plugin operations and development.

class PluginError(Error):
    """
    Certbot Plugin error.
    
    Base class for plugin-related errors.
    """

class PluginSelectionError(Error):
    """
    A problem with plugin/configurator selection or setup.
    
    Raised when plugins cannot be loaded or configured properly.
    """

class MisconfigurationError(PluginError):
    """
    Certbot Plugin misconfiguration error.
    
    Raised when plugin configuration is invalid or incomplete.
    """

class NotSupportedError(PluginError):
    """
    Certbot Plugin function not supported error.
    
    Raised when attempting to use unsupported plugin functionality.
    """

class NoInstallationError(PluginError):
    """
    Certbot No Installation error.
    
    Raised when installer plugin cannot find supported software installation.
    """

class PluginStorageError(PluginError):
    """
    Certbot Plugin Storage error.
    
    Raised when plugin storage operations fail.
    """

class PluginEnhancementAlreadyPresent(Error):
    """
    Enhancement was already set.
    
    Raised when trying to apply an enhancement that's already configured.
    """

class StandaloneBindError(Error):
    """
    Standalone plugin bind error.
    
    Raised when standalone authenticator cannot bind to required ports.
    """

Usage examples:

from certbot import errors

class MyPlugin:
    def deploy_cert(self, domain, cert_path, key_path, chain_path, fullchain_path):
        try:
            # Deploy certificate logic
            self._update_server_config(domain, cert_path, key_path)
        except FileNotFoundError:
            raise errors.NoInstallationError(
                f"Server configuration not found for {domain}"
            )
        except PermissionError:
            raise errors.PluginError(
                "Insufficient permissions to update server configuration"
            )
    
    def enhance(self, domain, enhancement, options=None):
        if enhancement not in self.supported_enhancements():
            raise errors.NotSupportedError(
                f"Enhancement '{enhancement}' is not supported"
            )
        
        if self._enhancement_exists(domain, enhancement):
            raise errors.PluginEnhancementAlreadyPresent(
                f"Enhancement '{enhancement}' already configured for {domain}"
            )

Certificate Storage Errors

Errors related to certificate storage and management.

class CertStorageError(Error):
    """
    Generic certificate storage error.
    
    Raised when certificate storage operations fail.
    """

Usage example:

from certbot import errors

try:
    # Save certificate to storage
    cert_storage.save(domain, cert_data)
except errors.CertStorageError as e:
    print(f"Failed to store certificate: {e}")

Error Handling Patterns

Try-Catch Patterns

Common patterns for handling Certbot errors:

from certbot import errors

# Handle specific plugin errors
try:
    plugin.deploy_cert(domain, cert_path, key_path, chain_path, fullchain_path)
except errors.NoInstallationError:
    print("Web server not found - manual configuration required")
except errors.MisconfigurationError as e:
    print(f"Configuration error: {e}")
except errors.PluginError as e:
    print(f"Plugin error: {e}")

# Handle challenge failures
try:
    responses = authenticator.perform(challenges)
except errors.FailedChallenges as e:
    for achall in e.failed_achalls:
        if achall.error:
            print(f"Challenge failed for {achall.domain}: {achall.error}")
except errors.AuthorizationError:
    print("Authorization process failed")

# Handle account operations
try:
    account = account_storage.load(account_id)
except errors.AccountNotFound:
    print("Account not found - creating new account")
    account = account_storage.create_new_account()
except errors.AccountStorageError as e:
    print(f"Account storage error: {e}")

Error Context Information

Many Certbot errors include additional context information:

# FailedChallenges provides detailed failure information
try:
    authenticator.perform(challenges)
except errors.FailedChallenges as e:
    for achall in e.failed_achalls:
        print(f"Failed challenge:")
        print(f"  Domain: {achall.domain}")
        print(f"  Challenge type: {achall.typ}")
        print(f"  Error: {achall.error}")
        print(f"  Status: {achall.status}")

# Plugin errors often include configuration details
try:
    plugin.config_test()
except errors.MisconfigurationError as e:
    print(f"Configuration test failed: {e}")
    # Error message includes specific configuration issues

Custom Error Handling

When developing plugins, create informative error messages:

from certbot import errors

class MyAuthenticator:
    def perform(self, achalls):
        for achall in achalls:
            try:
                self._create_challenge_response(achall)
            except ConnectionError:
                raise errors.PluginError(
                    f"Cannot connect to DNS provider API for domain {achall.domain}. "
                    f"Check network connectivity and API credentials."
                )
            except ValueError as e:
                raise errors.MisconfigurationError(
                    f"Invalid configuration for domain {achall.domain}: {e}"
                )

Install with Tessl CLI