0
# Configuration and Authentication\n\nConfiguration and authentication operations enable setting up Archive.org credentials, managing configuration files, and retrieving user information for programmatic access to the Internet Archive.\n\n## Capabilities\n\n### Configuration Setup\n\nConfigure the Internet Archive library with user credentials and settings.\n\n```python { .api }\ndef configure(username=\"\", password=\"\", config_file=\"\", host=\"archive.org\"):\n    \"\"\"\n    Configure internetarchive with Archive.org credentials.\n    \n    Args:\n        username (str): Archive.org username or email address\n        password (str): Archive.org password\n        config_file (str): Path to configuration file (default: ~/.config/internetarchive/ia.ini)\n        host (str): Archive.org host (default: 'archive.org')\n        \n    Returns:\n        str: Path to the configuration file that was written\n        \n    Raises:\n        AuthenticationError: If credentials are invalid\n        IOError: If configuration file cannot be written\n        \n    Note:\n        This function will prompt for username/password if not provided.\n        The configuration is saved for future use by the library.\n    \"\"\"\n```\n\n### User Information Retrieval\n\nRetrieve user information using IA-S3 access keys.\n\n```python { .api }\ndef get_username(access_key, secret_key):\n    \"\"\"\n    Get Archive.org username from IA-S3 key pair.\n    \n    Args:\n        access_key (str): IA-S3 access key\n        secret_key (str): IA-S3 secret key\n        \n    Returns:\n        str: Archive.org username associated with the keys\n        \n    Raises:\n        AuthenticationError: If keys are invalid or expired\n        requests.RequestException: If API request fails\n    \"\"\"\n\ndef get_user_info(access_key, secret_key):\n    \"\"\"\n    Get detailed user information from IA-S3 key pair.\n    \n    Args:\n        access_key (str): IA-S3 access key  \n        secret_key (str): IA-S3 secret key\n        \n    Returns:\n        dict: User information dictionary with keys:\n            - 'username': Archive.org username\n            - 'email': User email address\n            - 'itemname': User's item identifier\n            - 'privileges': List of user privileges\n            - 'verified': Email verification status\n            \n    Raises:\n        AuthenticationError: If keys are invalid or expired\n        requests.RequestException: If API request fails\n    \"\"\"\n```\n\n### Configuration Management\n\nLow-level configuration file management functions.\n\n```python { .api }\n# From internetarchive.config module\ndef get_config(config=None, config_file=None):\n    \"\"\"\n    Get configuration dictionary from file or provided config.\n    \n    Args:\n        config (dict, optional): Configuration dictionary to use\n        config_file (str, optional): Path to configuration file\n        \n    Returns:\n        dict: Configuration dictionary with sections:\n            - 's3': IA-S3 authentication settings\n            - 'general': General library settings\n            - 'cookies': Archive.org cookies for authentication\n    \"\"\"\n\ndef parse_config_file(config_file=None):\n    \"\"\"\n    Parse configuration file and return config dictionary.\n    \n    Args:\n        config_file (str, optional): Path to config file\n        \n    Returns:\n        dict: Parsed configuration\n    \"\"\"\n\ndef write_config_file(auth_config, config_file=None):\n    \"\"\"\n    Write authentication configuration to file.\n    \n    Args:\n        auth_config (dict): Authentication configuration\n        config_file (str, optional): Path to config file\n    \"\"\"\n\ndef get_auth_config(email, password, host=\"archive.org\"):\n    \"\"\"\n    Get authentication configuration from credentials.\n    \n    Args:\n        email (str): Archive.org email/username\n        password (str): Archive.org password\n        host (str): Archive.org host\n        \n    Returns:\n        dict: Authentication configuration dictionary\n    \"\"\"\n```\n\n### Authentication Classes\n\nInternal authentication handling classes.\n\n```python { .api }\n# From internetarchive.auth module (used internally)\nclass S3Auth:\n    \"\"\"\n    S3 authentication handler for IA-S3 API requests.\n    \"\"\"\n    \n    def __init__(self, access_key, secret_key):\n        \"\"\"\n        Initialize S3 authentication.\n        \n        Args:\n            access_key (str): IA-S3 access key\n            secret_key (str): IA-S3 secret key\n        \"\"\"\n\nclass S3PostAuth:\n    \"\"\"\n    S3 POST authentication handler for multipart uploads.\n    \"\"\"\n    \n    def __init__(self, access_key, secret_key):\n        \"\"\"\n        Initialize S3 POST authentication.\n        \n        Args:\n            access_key (str): IA-S3 access key\n            secret_key (str): IA-S3 secret key\n        \"\"\"\n```\n\n### Session Authentication\n\nAuthentication properties and methods available through ArchiveSession.\n\n```python { .api }\nclass ArchiveSession:\n    @property\n    def user_email(self):\n        \"\"\"str: Email of logged-in user (if authenticated).\"\"\"\n        \n    @property\n    def access_key(self):\n        \"\"\"str: IA-S3 access key (if configured).\"\"\"\n        \n    @property\n    def secret_key(self):\n        \"\"\"str: IA-S3 secret key (if configured).\"\"\"\n        \n    def whoami(self):\n        \"\"\"\n        Get the email address of the logged-in user.\n        \n        Returns:\n            str: User email address, or empty string if not authenticated\n        \"\"\"\n```\n\n## Configuration File Format\n\nThe Internet Archive library uses INI-format configuration files with the following structure:\n\n```ini\n[general]\nsecure = true\nhost = archive.org\n\n[s3]\naccess = your-access-key\nsecret = your-secret-key\n\n[cookies]\nlogged-in-user = username\nlogged-in-sig = signature\n```\n\n## Authentication Methods\n\n### IA-S3 Keys (Recommended)\n\nIA-S3 keys provide programmatic access without exposing your Archive.org password:\n\n```python\n# Configure with IA-S3 keys\nconfig = {\n    's3': {\n        'access': 'your-access-key',\n        'secret': 'your-secret-key'\n    }\n}\nsession = internetarchive.get_session(config=config)\n```\n\n### Cookie Authentication\n\nUse Archive.org cookies for authentication:\n\n```python\n# Configure with cookies\nconfig = {\n    'cookies': {\n        'logged-in-user': 'username',\n        'logged-in-sig': 'signature'\n    }\n}\nsession = internetarchive.get_session(config=config)\n```\n\n## Usage Examples\n\n### Initial Configuration\n\n```python\nimport internetarchive\n\n# Interactive configuration (will prompt for credentials)\nconfig_file = internetarchive.configure()\nprint(f\"Configuration saved to: {config_file}\")\n\n# Non-interactive configuration\nconfig_file = internetarchive.configure(\n    username='your-email@example.com',\n    password='your-password'\n)\n```\n\n### Using Configuration Files\n\n```python\nimport internetarchive\n\n# Use default configuration file\nsession = internetarchive.get_session()\n\n# Use specific configuration file\nsession = internetarchive.get_session(config_file='/path/to/ia.ini')\n\n# Override configuration\ncustom_config = {\n    's3': {\n        'access': 'custom-access-key',\n        'secret': 'custom-secret-key'\n    },\n    'general': {\n        'secure': True,\n        'host': 'archive.org'\n    }\n}\nsession = internetarchive.get_session(config=custom_config)\n```\n\n### Checking Authentication Status\n\n```python\nimport internetarchive\n\n# Create session and check authentication\nsession = internetarchive.get_session()\n\nif session.user_email:\n    print(f\"Authenticated as: {session.user_email}\")\n    print(f\"Access key: {session.access_key[:10]}...\")\nelse:\n    print(\"Not authenticated\")\n\n# Get detailed user info if using IA-S3 keys\nif session.access_key and session.secret_key:\n    try:\n        user_info = internetarchive.get_user_info(\n            session.access_key, \n            session.secret_key\n        )\n        print(f\"User info: {user_info}\")\n    except Exception as e:\n        print(f\"Could not retrieve user info: {e}\")\n```\n\n### Multiple Authentication Configurations\n\n```python\nimport internetarchive\n\n# Different configurations for different operations\nread_only_config = {\n    # No authentication needed for public items\n    'general': {'secure': True}\n}\n\nwrite_config = {\n    's3': {\n        'access': 'write-access-key',\n        'secret': 'write-secret-key'\n    }\n}\n\n# Use read-only for downloading\nread_session = internetarchive.get_session(config=read_only_config)\nitem = read_session.get_item('public-item')\nitem.download()\n\n# Use authenticated session for uploading\nwrite_session = internetarchive.get_session(config=write_config)\nwrite_session.get_item('my-item').upload(['file.txt'])\n```\n\n### Environment-Based Configuration\n\n```python\nimport internetarchive\nimport os\n\n# Configuration from environment variables\nconfig = {}\n\nif os.getenv('IA_ACCESS_KEY') and os.getenv('IA_SECRET_KEY'):\n    config['s3'] = {\n        'access': os.getenv('IA_ACCESS_KEY'),\n        'secret': os.getenv('IA_SECRET_KEY')\n    }\n\n# Use environment config if available, otherwise default\nsession = internetarchive.get_session(config=config if config else None)\n\nif session.user_email:\n    print(f\"Using credentials for: {session.user_email}\")\nelse:\n    print(\"Using anonymous access\")\n```\n\n### Credential Validation\n\n```python\nimport internetarchive\n\ndef validate_credentials(access_key, secret_key):\n    \"\"\"Validate IA-S3 credentials.\"\"\"\n    try:\n        username = internetarchive.get_username(access_key, secret_key)\n        user_info = internetarchive.get_user_info(access_key, secret_key)\n        \n        print(f\"Credentials valid for user: {username}\")\n        print(f\"Email: {user_info.get('email')}\")\n        print(f\"Verified: {user_info.get('verified')}\")\n        print(f\"Privileges: {user_info.get('privileges', [])}\")\n        \n        return True\n    except Exception as e:\n        print(f\"Credential validation failed: {e}\")\n        return False\n\n# Test credentials\nif validate_credentials('your-access-key', 'your-secret-key'):\n    print(\"Credentials are valid\")\nelse:\n    print(\"Invalid credentials\")\n```\n\n### Configuration Management\n\n```python\nimport internetarchive\nfrom internetarchive import config as ia_config\n\n# Get current configuration\ncurrent_config = ia_config.get_config()\nprint(f\"Current config: {current_config}\")\n\n# Create new authentication config\nauth_config = ia_config.get_auth_config(\n    'your-email@example.com',\n    'your-password'\n)\n\n# Write to specific config file\nia_config.write_config_file(auth_config, '/tmp/test_config.ini')\n\n# Load from specific config file\ntest_config = ia_config.get_config(config_file='/tmp/test_config.ini')\nsession = internetarchive.get_session(config=test_config)\n```"}]