ombrabrowser 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,85 @@
1
+ """Ombra Python SDK — Stealth Chromium launcher and CDP bridge for Playwright.
2
+
3
+ Usage:
4
+ from ombrabrowser import launch
5
+
6
+ browser = launch()
7
+ page = browser.new_page()
8
+ page.goto("https://example.com")
9
+ print(page.title())
10
+ browser.close()
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from ._version import (
16
+ CONTRACT_VERSION,
17
+ DEFAULT_ENGINE_VERSION,
18
+ SUPPORTED_CONTRACT_RANGE,
19
+ SUPPORTED_ENGINE_RANGE,
20
+ SUPPORTED_PLAYWRIGHT_RANGE,
21
+ __version__,
22
+ )
23
+ from .binary import binary_info, clear_cache, ensure_binary
24
+ from .errors import (
25
+ BinaryNotFoundError,
26
+ CDPConnectError,
27
+ ChecksumMismatchError,
28
+ DownloadFailedError,
29
+ EngineCrashedError,
30
+ EngineExitedError,
31
+ InvalidOptionError,
32
+ LaunchTimeoutError,
33
+ LicenseError,
34
+ OmbraError,
35
+ PlaywrightNotInstalledError,
36
+ ProfileBusyError,
37
+ ProxyError,
38
+ UnsupportedEngineError,
39
+ UnsupportedPlatformError,
40
+ )
41
+ from .launcher import (
42
+ build_launch_options,
43
+ last_launch_info,
44
+ launch,
45
+ launch_async,
46
+ launch_context,
47
+ launch_context_async,
48
+ launch_persistent_context,
49
+ launch_persistent_context_async,
50
+ )
51
+
52
+ __all__ = [
53
+ "__version__",
54
+ "CONTRACT_VERSION",
55
+ "DEFAULT_ENGINE_VERSION",
56
+ "SUPPORTED_CONTRACT_RANGE",
57
+ "SUPPORTED_ENGINE_RANGE",
58
+ "SUPPORTED_PLAYWRIGHT_RANGE",
59
+ "launch",
60
+ "launch_async",
61
+ "launch_context",
62
+ "launch_context_async",
63
+ "launch_persistent_context",
64
+ "launch_persistent_context_async",
65
+ "build_launch_options",
66
+ "last_launch_info",
67
+ "binary_info",
68
+ "ensure_binary",
69
+ "clear_cache",
70
+ "OmbraError",
71
+ "InvalidOptionError",
72
+ "BinaryNotFoundError",
73
+ "DownloadFailedError",
74
+ "ChecksumMismatchError",
75
+ "UnsupportedPlatformError",
76
+ "UnsupportedEngineError",
77
+ "LicenseError",
78
+ "ProxyError",
79
+ "ProfileBusyError",
80
+ "LaunchTimeoutError",
81
+ "CDPConnectError",
82
+ "EngineExitedError",
83
+ "EngineCrashedError",
84
+ "PlaywrightNotInstalledError",
85
+ ]
@@ -0,0 +1,290 @@
1
+ """CLI for managing the Ombra stealth Chromium binary and license key.
2
+
3
+ Usage:
4
+ python -m ombrabrowser install # Download and verify the engine binary
5
+ python -m ombrabrowser info # Environment, binary, and dependency diagnostics
6
+ python -m ombrabrowser doctor # Alias for info
7
+ python -m ombrabrowser update # Check for and install a newer engine build
8
+ python -m ombrabrowser clear-cache # Remove SDK-managed engine binaries (keeps profiles)
9
+ python -m ombrabrowser login [KEY] # Save license key to ~/.ombra/license.key (0600)
10
+ python -m ombrabrowser logout # Remove saved ~/.ombra/license.key
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import getpass
17
+ import importlib.util
18
+ import json
19
+ import os
20
+ import platform
21
+ import secrets
22
+ import subprocess
23
+ import sys
24
+ from pathlib import Path
25
+
26
+ from ._version import CONTRACT_VERSION, SUPPORTED_ENGINE_RANGE, __version__
27
+ from .binary import binary_info, clear_cache, ensure_binary, resolve_binary
28
+ from .config import (
29
+ _normalize_license_key,
30
+ get_cache_dir,
31
+ get_platform_tag,
32
+ resolve_license_key,
33
+ )
34
+ from .errors import redact_secrets
35
+
36
+
37
+ def _module_available(module_name: str) -> bool:
38
+ try:
39
+ return importlib.util.find_spec(module_name) is not None
40
+ except (ImportError, ValueError):
41
+ return False
42
+
43
+
44
+ def _probe_binary_runs(binary_path: str) -> dict[str, object]:
45
+ if platform.system() == "Windows":
46
+ return {"tested": False, "reason": "skipped on Windows (--version spawns browser)"}
47
+ try:
48
+ res = subprocess.run(
49
+ [binary_path, "--version"],
50
+ capture_output=True,
51
+ text=True,
52
+ timeout=10,
53
+ )
54
+ if res.returncode == 0:
55
+ return {"tested": True, "ok": True, "version": res.stdout.strip()}
56
+ return {
57
+ "tested": True,
58
+ "ok": False,
59
+ "error": (res.stderr or res.stdout).strip(),
60
+ }
61
+ except (OSError, subprocess.SubprocessError) as exc:
62
+ return {"tested": True, "ok": False, "error": str(exc)}
63
+
64
+
65
+ def _collect_diagnostics(*, quick: bool = False, proxy: str | None = None) -> dict[str, object]:
66
+ info = binary_info()
67
+ _, key_source = resolve_license_key()
68
+
69
+ if quick or not info.get("installed") or not info.get("path"):
70
+ launch_check: dict[str, object] = {
71
+ "tested": False,
72
+ "reason": "skipped (--quick)" if quick else "binary not installed",
73
+ }
74
+ else:
75
+ launch_check = _probe_binary_runs(str(info["path"]))
76
+
77
+ from .geoip import GEOIP_DB_FILENAME, get_geoip_dir, geoip_available
78
+
79
+ geoip_db = get_geoip_dir() / GEOIP_DB_FILENAME
80
+ geoip_diag: dict[str, object] = {
81
+ "db_present": geoip_db.exists(),
82
+ "path": str(geoip_db),
83
+ }
84
+ if proxy:
85
+ from .proxy import parse_proxy
86
+
87
+ try:
88
+ parsed = parse_proxy(proxy)
89
+ from .geoip import resolve_proxy_geo_with_ip
90
+
91
+ tz, loc, exit_ip = resolve_proxy_geo_with_ip(
92
+ parsed.upstream_url_for_geoip() if parsed else None
93
+ )
94
+ geoip_diag["resolved"] = {
95
+ "exit_ip": exit_ip,
96
+ "timezone": tz,
97
+ "locale": loc,
98
+ }
99
+ except Exception as exc:
100
+ geoip_diag["resolved"] = {"error": redact_secrets(str(exc))}
101
+
102
+ return {
103
+ "sdk": {
104
+ "version": __version__,
105
+ "contract": CONTRACT_VERSION,
106
+ "supported_engine": SUPPORTED_ENGINE_RANGE,
107
+ "python": sys.version.split()[0],
108
+ "os": platform.system(),
109
+ "arch": platform.machine(),
110
+ "platform": get_platform_tag(),
111
+ "cache_dir": str(get_cache_dir()),
112
+ },
113
+ "binary": info,
114
+ "launch_check": launch_check,
115
+ "license": {
116
+ "configured": key_source != "none",
117
+ "source": key_source,
118
+ },
119
+ "geoip": geoip_diag,
120
+ "modules": {
121
+ "playwright": _module_available("playwright.sync_api"),
122
+ "httpx": _module_available("httpx"),
123
+ "cryptography": _module_available("cryptography"),
124
+ "geoip2": geoip_available(),
125
+ },
126
+ }
127
+
128
+
129
+ def _print_diagnostics(diag: dict[str, object]) -> None:
130
+ sdk = diag["sdk"]
131
+ binary = diag["binary"]
132
+ launch_check = diag["launch_check"]
133
+ lic = diag["license"]
134
+ geoip = diag["geoip"]
135
+ modules = diag["modules"]
136
+ assert isinstance(sdk, dict)
137
+ assert isinstance(binary, dict)
138
+ assert isinstance(launch_check, dict)
139
+ assert isinstance(lic, dict)
140
+ assert isinstance(geoip, dict)
141
+ assert isinstance(modules, dict)
142
+
143
+ print("Ombra SDK diagnostics")
144
+ print(f"SDK: {sdk['version']} (contract {sdk['contract']}, engine {sdk['supported_engine']})")
145
+ print(f"Python: {sdk['python']}")
146
+ print(f"Platform: {sdk['platform']} ({sdk['os']} {sdk['arch']})")
147
+ print(f"Cache dir: {sdk['cache_dir']}")
148
+ print(f"Binary: {binary['path'] or '(not installed)'}")
149
+ print(f"Version: {binary['version']} (source={binary['source']}, installed={binary['installed']})")
150
+ print(f"SHA-256: {binary['sha256'] or '(none)'}")
151
+ if launch_check.get("tested"):
152
+ status = f"ok ({launch_check.get('version')})" if launch_check.get("ok") else f"failed ({launch_check.get('error')})"
153
+ print(f"Check: {status}")
154
+ else:
155
+ print(f"Check: {launch_check.get('reason')}")
156
+ print(f"License: {'configured' if lic['configured'] else 'not set'} (source={lic['source']})")
157
+ print(f"GeoIP DB: {'present' if geoip['db_present'] else 'absent'}")
158
+ if "resolved" in geoip:
159
+ res = geoip["resolved"]
160
+ assert isinstance(res, dict)
161
+ if "error" in res:
162
+ print(f"GeoIP res: error ({res['error']})")
163
+ else:
164
+ print(f"GeoIP res: exit_ip={res.get('exit_ip')}, tz={res.get('timezone')}, locale={res.get('locale')}")
165
+ print("Modules:")
166
+ for name, ok in modules.items():
167
+ print(f" {name}: {'ok' if ok else 'missing'}")
168
+
169
+
170
+ def _cmd_install(args: argparse.Namespace) -> None:
171
+ path = ensure_binary(version=args.version, release_channel=args.channel)
172
+ print(path)
173
+
174
+
175
+ def _cmd_info(args: argparse.Namespace) -> None:
176
+ diag = _collect_diagnostics(quick=args.quick, proxy=args.proxy)
177
+ if args.json:
178
+ print(json.dumps(diag, indent=2))
179
+ else:
180
+ _print_diagnostics(diag)
181
+
182
+
183
+ def _cmd_update(args: argparse.Namespace) -> None:
184
+ resolved = resolve_binary(
185
+ download=True,
186
+ release_channel=args.channel,
187
+ force_update_check=True,
188
+ )
189
+ print(f"Engine ready: {resolved.version} ({resolved.path})")
190
+
191
+
192
+ def _cmd_clear_cache(_args: argparse.Namespace) -> None:
193
+ clear_cache()
194
+ print("Cleared SDK-managed engine cache (profiles preserved).")
195
+
196
+
197
+ def _write_key_file(path: Path, key: str) -> None:
198
+ path.parent.mkdir(parents=True, exist_ok=True)
199
+ if os.name != "nt":
200
+ os.chmod(path.parent, 0o700)
201
+ tmp = path.with_name(f"{path.name}.{secrets.token_hex(6)}.tmp")
202
+ fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
203
+ try:
204
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
205
+ fh.write(key + "\n")
206
+ fh.flush()
207
+ os.fsync(fh.fileno())
208
+ os.replace(tmp, path)
209
+ finally:
210
+ tmp.unlink(missing_ok=True)
211
+
212
+
213
+ def _cmd_login(args: argparse.Namespace) -> None:
214
+ raw_key = args.key
215
+ if not raw_key:
216
+ if not sys.stdin.isatty():
217
+ print("Usage: ombra login <license-key>", file=sys.stderr)
218
+ sys.exit(2)
219
+ raw_key = getpass.getpass("Enter Ombra license key: ")
220
+ cleaned = _normalize_license_key(raw_key)
221
+ key_path = get_cache_dir() / "license.key"
222
+ _write_key_file(key_path, cleaned)
223
+ print(f"Saved license key to {key_path}")
224
+
225
+
226
+ def _cmd_logout(_args: argparse.Namespace) -> None:
227
+ key_path = get_cache_dir() / "license.key"
228
+ if key_path.exists():
229
+ key_path.unlink()
230
+ print(f"Removed {key_path}")
231
+ else:
232
+ print("No saved license key found.")
233
+
234
+
235
+ def build_parser() -> argparse.ArgumentParser:
236
+ parser = argparse.ArgumentParser(
237
+ prog="ombrabrowser",
238
+ description="Manage the Ombra stealth Chromium binary and SDK configuration.",
239
+ )
240
+ sub = parser.add_subparsers(dest="command")
241
+
242
+ install_p = sub.add_parser("install", help="Resolve/download and verify the Ombra engine")
243
+ install_p.add_argument("--version", default=None, help="Pin an engine version")
244
+ install_p.add_argument("--channel", default=None, help="Release channel (stable|beta)")
245
+
246
+ for name, help_text in (("info", "Diagnostics report"), ("doctor", "Alias for info")):
247
+ p = sub.add_parser(name, help=help_text)
248
+ p.add_argument("--quick", action="store_true", help="Skip spawning binary --version check")
249
+ p.add_argument("--json", action="store_true", help="Output diagnostics as JSON")
250
+ p.add_argument("--proxy", default=None, help="Test GeoIP exit resolution through proxy")
251
+
252
+ update_p = sub.add_parser("update", help="Check for and install the latest engine build")
253
+ update_p.add_argument("--channel", default=None, help="Release channel (stable|beta)")
254
+
255
+ sub.add_parser("clear-cache", help="Remove SDK-managed binaries (keeps profiles)")
256
+
257
+ login_p = sub.add_parser("login", help="Save an Ombra license key to ~/.ombra/license.key")
258
+ login_p.add_argument("key", nargs="?", default=None, help="License key (omit to prompt securely)")
259
+ sub.add_parser("logout", help="Remove saved ~/.ombra/license.key")
260
+
261
+ return parser
262
+
263
+
264
+ def main(argv: list[str] | None = None) -> None:
265
+ parser = build_parser()
266
+ args = parser.parse_args(argv)
267
+ if not args.command:
268
+ parser.print_help()
269
+ sys.exit(2)
270
+
271
+ handlers = {
272
+ "install": _cmd_install,
273
+ "info": _cmd_info,
274
+ "doctor": _cmd_info,
275
+ "update": _cmd_update,
276
+ "clear-cache": _cmd_clear_cache,
277
+ "login": _cmd_login,
278
+ "logout": _cmd_logout,
279
+ }
280
+ try:
281
+ handlers[args.command](args)
282
+ except KeyboardInterrupt:
283
+ sys.exit(130)
284
+ except Exception as exc:
285
+ print(f"Error: {redact_secrets(str(exc))}", file=sys.stderr)
286
+ sys.exit(1)
287
+
288
+
289
+ if __name__ == "__main__":
290
+ main()
@@ -0,0 +1,15 @@
1
+ """Version and compatibility declarations for the Ombra Python SDK."""
2
+
3
+ from __future__ import annotations
4
+
5
+ __version__ = "0.1.0"
6
+
7
+ CONTRACT_VERSION = "0.1.0"
8
+ SUPPORTED_CONTRACT_RANGE = ">=0.1,<0.2"
9
+
10
+ DEFAULT_ENGINE_VERSION = "151.0.7922.108"
11
+ SUPPORTED_ENGINE_RANGE = ">=151.0.7922.108,<152"
12
+ SUPPORTED_ENGINE_MIN_CHROMIUM = (151, 0, 7922, 108)
13
+ SUPPORTED_ENGINE_MAX_MAJOR = 152 # exclusive
14
+
15
+ SUPPORTED_PLAYWRIGHT_RANGE = ">=1.48,<2.0"