How borisbabic/browser_cookie3 works
Project type and purpose
• This is an open-source Python library & CLI tool (“browser_cookie3”) that exposes functions (and a command‐line interface) to load cookies from various web browsers into a Python http.cookiejar.CookieJar.
File structure
• Top level:
• .github/workflows/* → CI for testing on Linux & Windows
• setup.py, MANIFEST.in, release.nix → packaging & deployment
• README(.md), LICENSE, CHANGELOG.md
• Core package:
• browser_cookie3/__init__.py → public API & factory functions (chrome(), firefox(), load(), etc.)
• browser_cookie3/__main__.py → CLI entrypoint (console script “browser-cookie”)
• Tests: tests/ and tests/utils/ → unit tests for each browser loader, path-finding, driver/version detection, user-agent helpers
README for additional insights
• Lists supported browsers & platforms
• Describes two usage patterns:
a) Python API: import browser_cookie3; cj = browser_cookie3.chrome()
b) CLI: browser-cookie --chrome domain name
Main components & interactions
a. Components:
• Client (Python script or CLI)
• CLI wrapper (browser_cookie3.__main__)
• Core Library (browser_cookie3 package)
– Browser-specific loader modules (ChromeLoader, FirefoxLoader, etc.)
– Profile & path discovery logic (cross-platform)
– Decryption helper (e.g., Windows CryptUnprotectData, macOS keychain, Linux decryption)
– SQLite/TXT parser
– CookieJar builder
• External dependencies:
– File System (browser cookie store files)
– OS-specific encryption APIs
– Python stdlib sqlite3, http.cookiejar
• Consumer HTTP client (requests or urllib2)
b. Relationships & data flow:
1. User invokes Python API or CLI.
2. CLI → calls Core Library .load() or browser-specific function.
3. Library → discovers cookie file path(s) via path-finder.
4. Library → if encrypted, calls decryption helper.
5. Library → opens SQLite DB or TXT, queries cookie table or parses text.
6. Library → populates CookieJar object.
7. Library → returns CookieJar to Client.
8. Client → HTTP client uses CookieJar to attach cookies to outgoing requests.
c. Architectural patterns / design principles:
• Strategy pattern: one loader per browser, all implement a common interface
• Factory functions: chrome(), firefox(), load() select appropriate strategy
• Single responsibility: separate modules for path discovery, decryption, DB parsing
• Cross-platform abstraction: OS-branching inside path/discovery and decryption layers
d. Key technologies & libraries:
• Python 3.x
• sqlite3 (built-in)
• http.cookiejar
• platform & os modules (path discovery)
• ctypes / win32crypt (Windows decryption)
• keyring or subprocess to call macOS keychain
• tab-delimited TXT parser for W3m/Lynx
Essential elements to capture
• Labels for each component & module
• Library core vs. browser-specific strategies
• Data stores vs. code modules
• OS APIs vs. application code