Andrew/refactor

.github/workflows/publish_testpypi.yml

@@ -28,7 +28,7 @@ jobs:
       # don't modify sync file! messes up version!
       - run: uv sync --all-extras --frozen # does order matter?
       - run: uv build
-      - run: uv run --no-sync choreo_get_browser -v --i ${{ matrix.chrome_v }}
+      - run: uv run --no-sync choreo_get_chrome -v --i ${{ matrix.chrome_v }}
       - name: Reinstall from wheel
         run: >
           uv pip install dist/choreographer-$(uv

.github/workflows/test.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Install choreographer
         run:  uv sync --all-extras
       - name: Install google-chrome-for-testing
-        run: uv run choreo_get_browser
+        run: uv run choreo_get_chrome
       - name: Diagnose
         run:  uv run choreo_diagnose --no-run
         timeout-minutes: 1

choreographer/README.txt

@@ -0,0 +1,10 @@
+These READMEs (in directories) are development notes, think of them as additions
+to the package-level docstrings (the one at the top of each __init__.py).
+
+
+The browsers are the main entrypoint for the user. They:
+
+1. Manage the actual browser process (start/stop/kill).
+2. Integrate the different resources: (see _channels/, _brokers/, _browsers/).
+3. Is a list of `Tab`s, `Session`s, and `Target`s.
+4. Provides a basic API.

choreographer/__init__.py

@@ -1,24 +1,63 @@
-"""choreographer is a browser controller for python."""
+"""
+choreographer is a browser controller for python.
 
-import choreographer._devtools_protocol_layer as protocol
+choreographer is natively async, so while there are two main entrypoints:
+classes `Browser` and `BrowserSync`, the sync version is very limited, functioning
+as a building block.
 
-from ._browser import Browser, BrowserClosedError, browser_which, get_browser_path
-from ._cli_utils import get_browser, get_browser_sync
-from ._pipe import BlockWarning, PipeClosedError
-from ._system_utils._tempfile import TempDirectory, TempDirWarning
-from ._tab import Tab
+See the main README for a quickstart.
+"""
 
-__all__ = [
-    "BlockWarning",
-    "Browser",
+from ._browsers import (  # noqa: F401 unused import
+    BrowserClosedError,
+    BrowserFailedError,
+    Chromium,
+)
+from ._channels import BlockWarning, ChannelClosedError  # noqa: F401 unused import
+from ._cli_utils import get_chrome, get_chrome_sync  # noqa: F401 unused import
+from ._sys_utils import (  # noqa: F401 unused import
+    TmpDirectory,
+    TmpDirWarning,
+    browser_which,
+    get_browser_path,
+)
+from .browser_sync import (  # noqa: F401 unused import
+    BrowserSync,
+    SessionSync,
+    TabSync,
+    TargetSync,
+)
+
+_sync_api = [
+    "BrowserSync",
+    "SessionSync",
+    "TabSync",
+    "TargetSync",
+]
+
+_browser_impls = [
+    "Chromium",
+]
+
+_errors = [
     "BrowserClosedError",
-    "PipeClosedError",
-    "Tab",
-    "TempDirWarning",
-    "TempDirectory",
+    "BrowserFailedError",
+    "ChannelClosedError",
+    "BlockWarning",
+    "TmpDirWarning",
+]
+
+_utils = [
+    "get_chrome",
+    "get_chrome_sync",
+    "TmpDirectory",
     "browser_which",
-    "get_browser",
     "get_browser_path",
-    "get_browser_sync",
-    "protocol",
+]
+
+__all__ = [  # noqa: PLE0604 non-string in all
+    *_sync_api,
+    *_browser_impls,
+    *_errors,
+    *_utils,
 ]

choreographer/_brokers/README.txt

@@ -0,0 +1,13 @@
+Brokers will handle all events and promises, if there are any.
+
+For example, the _sync.py broker only gives us the option of
+starting a thread to dump all events. Writing a broker without
+a concurrent structure would be fruitless- it would block and break.
+
+
+The _async.py broker is much more complex, and will allow users to subscribe
+to events, will fulfill processes when receiving responses from the browser
+addressed to the user's commands, and generally absorbs all browser communication.
+
+Brokers do not have a standard interface, they are usually 1-1 matched with a particular
+`class Browser*` implementation.

choreographer/_brokers/__init__.py

@@ -0,0 +1,5 @@
+from ._sync import BrokerSync
+
+__all__ = [
+    "BrokerSync",
+]

choreographer/_brokers/_sync.py

@@ -0,0 +1,38 @@
+import json
+from threading import Thread
+
+import logistro
+
+from choreographer import protocol
+from choreographer._channels import ChannelClosedError
+
+logger = logistro.getLogger(__name__)
+
+
+class BrokerSync:
+    def __init__(self, browser, channel):
+        self.browser = browser
+        self.channel = channel
+
+    # This is the broker
+    def run_output_thread(self, **kwargs):
+        def run_print():
+            try:
+                while True:
+                    responses = self.channel.read_jsons()
+                    for response in responses:
+                        print(json.dumps(response, indent=4), **kwargs)
+            except ChannelClosedError:
+                print("ChannelClosedError caught.", **kwargs)
+
+        logger.info("Starting thread to dump output to stdout.")
+        Thread(target=run_print).start()
+
+    def send_json(self, obj):
+        protocol.verify_params(obj)
+        key = protocol.calculate_message_key(obj)
+        self.channel.write_json(obj)
+        return key
+
+    def clean(self):
+        pass