refactor(examples): reorganize Python examples into categorized subdirectories by yingjunwu · Pull Request #223 · boxlite-ai/boxlite

yingjunwu · 2026-02-09T22:31:23Z

Summary

Reorganize 32 flat Python example files into 7 numbered subdirectories (01_getting_started through 07_advanced) with verb-prefixed filenames for easier navigation
Extract shared setup_logging() into _helpers.py (with standalone fallback) to eliminate duplication across 8+ files
Merge cp_example.py + cp_tmpfs_workaround_example.py into a single copy_files.py; delete 3 redundant files (skillbox.py, two cp_tmpfs variants)
Rewrite examples/python/README.md as a category index table; add per-directory READMEs
Update all documentation references in sdks/python/README.md, docs/guides/README.md, docs/getting-started/quickstart-python.md, CLAUDE.md, and sub-example READMEs
Fix broken browserbox_example.py links across 4 documentation files (file never existed; now points to automate_with_playwright.py)

New Structure

examples/python/
  _helpers.py
  README.md
  01_getting_started/   # SimpleBox, CodeBox, sync variants, list boxes
  02_features/          # CMD/user, ports, file copy, registries, OCI bundles
  03_lifecycle/         # Stop/restart, detach, shutdown, cross-process
  04_interactive/       # Interactive shell, Claude Code install
  05_browser_desktop/   # Playwright, Puppeteer, desktop automation
  06_ai_agents/         # LLM-driven, SkillBox, Claude chat, Starbucks, OpenClaw
  07_advanced/          # Native API, FUSE, multi-agent, AI pipeline

Test plan

All 33 Python files pass py_compile syntax check
_helpers.py import resolves correctly from all 7 subdirectories
All markdown links in 11 READMEs + 3 doc files point to existing files
Zero stale old-path references remain in documentation
Spot-check: python examples/python/01_getting_started/run_simplebox.py runs from new path

🤖 Generated with Claude Code

…rectories Flat 32-file layout was hard to navigate for new users. Reorganize into 7 numbered subdirectories (01_getting_started through 07_advanced) with verb-prefixed filenames, shared _helpers.py, per-directory READMEs, and updated documentation links across the repo. - Move 35 files via git mv into categorized subdirectories - Merge cp_example + cp_tmpfs_workaround into copy_files.py - Delete 3 redundant files (skillbox.py, 2x cp_tmpfs workarounds) - Extract shared setup_logging() into _helpers.py with fallback - Rewrite examples/python/README.md as category index - Update all doc references (sdks/python, docs/guides, quickstart, CLAUDE.md) - Fix broken browserbox_example.py links across 4 documentation files Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot

Pull request overview

This PR refactors the BoxLite Python examples by reorganizing them into numbered, categorized subdirectories, deduplicating shared utilities, and updating documentation to point to the new paths.

Changes:

Reorganize Python examples into examples/python/01_getting_started through 07_advanced and rename scripts with verb-first filenames.
Add shared example utilities in examples/python/_helpers.py and update examples to use it with a standalone fallback.
Update docs/READMEs across the repo to reference the new example locations; remove/merge redundant legacy example scripts.

Reviewed changes

Copilot reviewed 30 out of 52 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
sdks/python/README.md	Updates the examples gallery links/names to the new categorized structure.
examples/python/sync_cp_tmpfs_workaround_example.py	Removes a redundant legacy example (superseded by new copy example).
examples/python/skillbox.py	Removes a legacy SkillBox example (replaced by categorized version).
examples/python/cp_tmpfs_workaround_example.py	Removes a legacy tmpfs workaround example (merged into new copy example).
examples/python/cp_example.py	Removes a legacy copy example (merged into new copy example).
examples/python/_helpers.py	Adds shared `setup_logging()` helper for examples.
examples/python/README.md	Rewrites top-level examples README as a categorized index and quickstart.
examples/python/07_advanced/use_native_api_sync.py	Updates sync native API example header to reference the async version.
examples/python/07_advanced/use_native_api.py	Adds a comprehensive async native API example.
examples/python/07_advanced/multi_agent/host.py	Adds multi-agent orchestration host example under advanced category.
examples/python/07_advanced/multi_agent/agent_sender.py	Adds standalone sender agent script for orchestration demos.
examples/python/07_advanced/multi_agent/agent_receiver.py	Adds standalone receiver agent script for orchestration demos.
examples/python/07_advanced/multi_agent/README.md	Updates run instructions to new advanced path.
examples/python/07_advanced/fuse/run_fuse_demo.sh	Adds FUSE demo runner script for inside-box execution.
examples/python/07_advanced/fuse/hellofs.py	Adds minimal FUSE filesystem implementation for the demo.
examples/python/07_advanced/fuse/fuse_example.py	Adds Python driver script to run the FUSE demo in a box.
examples/python/07_advanced/ai_pipeline/host.py	Adds AI pipeline orchestration host example under advanced category.
examples/python/07_advanced/ai_pipeline/README.md	Updates run instructions and related-links to new paths.
examples/python/07_advanced/README.md	Adds advanced category README indexing advanced examples.
examples/python/06_ai_agents/use_skillbox.py	Adds SkillBox example in AI agents category.
examples/python/06_ai_agents/run_openclaw.py	Adds OpenClaw gateway example in AI agents category.
examples/python/06_ai_agents/order_starbucks.py	Adds a browser-ordering demo example using SkillBox GUI monitoring.
examples/python/06_ai_agents/drive_box_with_llm.py	Adds an LLM-driven sandbox exploration example using tool calls.
examples/python/06_ai_agents/chat_with_claude.py	Refactors logging setup to use shared helper with fallback.
examples/python/06_ai_agents/README.md	Adds AI agents category README indexing agent-focused examples.
examples/python/05_browser_desktop/automate_with_puppeteer.py	Adds BrowserBox automation example using pyppeteer.
examples/python/05_browser_desktop/automate_with_playwright.py	Adds BrowserBox automation example using Playwright.
examples/python/05_browser_desktop/automate_desktop.py	Refactors logging setup to use shared helper with fallback.
examples/python/05_browser_desktop/README.md	Adds browser/desktop category README indexing automation examples.
examples/python/04_interactive/run_interactive_shell.py	Refactors logging setup to use shared helper with fallback.
examples/python/04_interactive/install_claude_interactively.py	Refactors logging setup to use shared helper with fallback.
examples/python/04_interactive/README.md	Adds interactive category README indexing interactive examples.
examples/python/03_lifecycle/shutdown_runtime.py	Adds runtime shutdown lifecycle example.
examples/python/03_lifecycle/share_across_processes.py	Adds cross-process lifecycle example using non-singleton runtime.
examples/python/03_lifecycle/manage_lifecycle.py	Adds expanded lifecycle management example suite.
examples/python/03_lifecycle/detach_and_reattach.py	Adds detach/reattach option demonstration.
examples/python/03_lifecycle/README.md	Adds lifecycle category README indexing lifecycle examples.
examples/python/02_features/use_local_oci_bundle.py	Adds local OCI bundle usage example.
examples/python/02_features/use_custom_registry.py	Refactors logging setup to use shared helper with fallback.
examples/python/02_features/set_cmd_and_user.py	Refactors logging setup to use shared helper with fallback.
examples/python/02_features/forward_ports.py	Adds port forwarding verification example.
examples/python/02_features/copy_files.py	Adds merged copy example including tmpfs workaround (tar via stdin).
examples/python/02_features/README.md	Adds features category README indexing feature-focused examples.
examples/python/01_getting_started/run_simplebox_sync.py	Refactors logging setup to use shared helper with fallback.
examples/python/01_getting_started/run_simplebox.py	Refactors logging setup to use shared helper with fallback.
examples/python/01_getting_started/run_codebox_sync.py	Updates sync CodeBox header to reference the async version.
examples/python/01_getting_started/run_codebox.py	Adds new CodeBox getting-started example.
examples/python/01_getting_started/list_boxes.py	Adds getting-started example to list runtime boxes.
examples/python/01_getting_started/README.md	Adds getting-started category README indexing core examples.
docs/guides/README.md	Updates guide references to new example filenames/paths.
docs/getting-started/quickstart-python.md	Updates quickstart commands and example overview to new structure.
CLAUDE.md	Updates repository layout description to reflect new examples organization.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-09T22:40:08Z

examples/python/05_browser_desktop/README.md

+| File | Description |
+|------|-------------|
+| `automate_with_playwright.py` | Chromium automation via Playwright (CDP) |
+| `automate_with_puppeteer.py` | Chromium automation via Puppeteer (Node.js) |


The README claims automate_with_puppeteer.py is a Node.js Puppeteer example, but the script is Python and uses pyppeteer. Update the description to avoid confusing users about runtime/dependencies.

Suggested change

| `automate_with_puppeteer.py` | Chromium automation via Puppeteer (Node.js) |

| `automate_with_puppeteer.py` | Chromium automation via Pyppeteer (Python) |

Copilot · 2026-02-09T22:40:09Z

examples/python/02_features/copy_files.py

+"""
+Copy files into and out of a box (docker-like cp).
+


Most other example scripts in this directory start with a shebang (#!/usr/bin/env python3) so they can be run directly. Consider adding one here for consistency and easier copy/paste execution.

- Fix automate_with_puppeteer.py description: Pyppeteer (Python), not Puppeteer (Node.js) - Add missing shebang to copy_files.py for consistency Co-Authored-By: Claude Opus 4.6 <[email protected]>

DorianZheng · 2026-02-13T01:39:38Z

examples/python/cp_example.py

seems this example is deleted by acidentally

Not accidental — this was intentionally merged into 02_features/copy_files.py (Example 1: native copy_in/copy_out API). The new file preserves the exact same round-trip logic.

DorianZheng · 2026-02-13T01:39:45Z

examples/python/cp_tmpfs_workaround_example.py

Also intentionally merged into 02_features/copy_files.py (Example 2: tmpfs workaround). The make_tar() helper, the problem demonstration, and the tar-pipe workaround are all preserved, including the moby/moby#22020 reference.

DorianZheng · 2026-02-13T01:39:53Z

examples/python/skillbox.py

Intentional. There were two skillbox example files: skillbox.py (simpler, 3 calls) and skillbox_example.py (comprehensive, 6 sub-examples). The comprehensive version was kept and renamed to 06_ai_agents/use_skillbox.py. It's a strict superset — covers the same APIs (skill listing, multi-turn, skill usage) with more depth.

DorianZheng · 2026-02-13T01:39:58Z

examples/python/sync_cp_tmpfs_workaround_example.py

Good catch — the sync variant was originally missing from copy_files.py (only the async version was merged). Just pushed f1367fe which restores it as Example 3 in copy_files.py, with a graceful ImportError fallback for users without boxlite[sync].

The sync variant from sync_cp_tmpfs_workaround_example.py was lost during the merge into copy_files.py. Add it back as Example 3 with a graceful ImportError fallback for users without boxlite[sync]. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot

Pull request overview

Copilot reviewed 30 out of 52 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

examples/python/07_advanced/multi_agent/README.md:65

This example imports boxlite.orchestration.BoxRuntime, which is gated behind the optional orchestration extra (depends on cloudpickle). Consider adding a short prereq like pip install 'boxlite[orchestration]' so the example runs for users who only installed the core package.
examples/python/07_advanced/ai_pipeline/README.md:47
This README’s run instructions assume BoxRuntime is importable, but boxlite.orchestration requires the optional orchestration extra (cloudpickle). Add a prereq like pip install 'boxlite[orchestration]' so users don’t hit ImportError.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings February 9, 2026 22:31

Copilot started reviewing on behalf of yingjunwu February 9, 2026 22:31 View session

Copilot AI reviewed Feb 9, 2026

View reviewed changes

fix(examples): address PR review feedback

a85662f

- Fix automate_with_puppeteer.py description: Pyppeteer (Python), not Puppeteer (Node.js) - Add missing shebang to copy_files.py for consistency Co-Authored-By: Claude Opus 4.6 <[email protected]>

DorianZheng reviewed Feb 13, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings February 13, 2026 02:00

DorianZheng approved these changes Feb 13, 2026

View reviewed changes

Copilot started reviewing on behalf of yingjunwu February 13, 2026 02:00 View session

DorianZheng merged commit a6d4537 into main Feb 13, 2026
22 of 23 checks passed

DorianZheng deleted the refactor/reorganize-python-examples branch February 13, 2026 02:00

Copilot AI reviewed Feb 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(examples): reorganize Python examples into categorized subdirectories#223

refactor(examples): reorganize Python examples into categorized subdirectories#223
DorianZheng merged 3 commits intomainfrom
refactor/reorganize-python-examples

yingjunwu commented Feb 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 9, 2026

Uh oh!

Copilot AI Feb 9, 2026

Uh oh!

DorianZheng Feb 13, 2026

Uh oh!

yingjunwu Feb 13, 2026

Uh oh!

DorianZheng Feb 13, 2026

Uh oh!

yingjunwu Feb 13, 2026

Uh oh!

DorianZheng Feb 13, 2026

Uh oh!

yingjunwu Feb 13, 2026

Uh oh!

DorianZheng Feb 13, 2026

Uh oh!

yingjunwu Feb 13, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	\| `automate_with_puppeteer.py` \| Chromium automation via Puppeteer (Node.js) \|
	\| `automate_with_puppeteer.py` \| Chromium automation via Pyppeteer (Python) \|

Conversation

yingjunwu commented Feb 9, 2026

Summary

New Structure

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants