{"id":50766331,"url":"https://github.com/stu-speed/xppython3-headless-dev","last_synced_at":"2026-06-28T18:00:35.810Z","repository":{"id":336400021,"uuid":"1147363168","full_name":"stu-speed/xppython3-headless-dev","owner":"stu-speed","description":"Headless development environment for XPPython3","archived":false,"fork":false,"pushed_at":"2026-06-19T23:00:27.000Z","size":605,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T01:03:02.021Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stu-speed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-01T16:24:44.000Z","updated_at":"2026-06-19T23:00:31.000Z","dependencies_parsed_at":"2026-06-20T01:00:31.298Z","dependency_job_id":null,"html_url":"https://github.com/stu-speed/xppython3-headless-dev","commit_stats":null,"previous_names":["stu-speed/xppython3-headless-dev"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/stu-speed/xppython3-headless-dev","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stu-speed%2Fxppython3-headless-dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stu-speed%2Fxppython3-headless-dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stu-speed%2Fxppython3-headless-dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stu-speed%2Fxppython3-headless-dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stu-speed","download_url":"https://codeload.github.com/stu-speed/xppython3-headless-dev/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stu-speed%2Fxppython3-headless-dev/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34898568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-11T14:01:24.521Z","updated_at":"2026-06-28T18:00:35.804Z","avatar_url":"https://github.com/stu-speed.png","language":"Python","funding_links":[],"categories":["Other Software Librares"],"sub_categories":["Python Language Plugin and Scripts"],"readme":"# 📘 xppython3-headless-dev\n### IDE and AI friendly workflow • Sim‑less execution and debugging • Live X‑Plane DataRef injection\n\nA structured development environment for building and debugging XPPython3 plugins natively in\nan IDE (PyCharm) through runtime emulation of the XPPython3 API.\n\nXPPython3 is ideal for AI assisted coding of X‑Plane plugins. The Python syntax is highly compatible with LLM models\nas well as having a large validated public code base for training.\n\nThis project provides:\n\n• A X‑Plane‑compatible plugin folder structure  \n• Sim‑less execution and debugging of plugins with a runner that simulates the full plugin lifecycle  \n• Live X‑Plane DataRef streaming through a bridge plugin  \n• A complete XPWidget + XPLMGraphics emulation layer (DearPyGui‑backed)  \n• Auto‑created, managed, and bridged DataRefs  \n• Stubs and .pyi files for strong datatyping and code introspection  \n• A simless multi‑plugin environment for integration testing  \n\nThe goal is fast, maintainable plugin development with behavior identical inside and outside X‑Plane.\n\n---------------------------------------------------------------------\n\n# 🚀 Installation\n\nFollow these steps to set up a fully functional sim‑less XPPython3 development environment.\n\n1. Copy this package into your IDE project directory  \n   Place the entire xppython3-headless-dev folder inside your IDE project root.\n\n   Example:\n   my-project/\n       xppython3-headless-dev/\n       your-other-code/\n\n2. Copy the real XPPython3 package into the project\n   Download or extract the official XPPython3 distribution and place the entire XPPython3 folder into:\n   xppython3-headless-dev/Resources/plugins/PythonPlugins/XPPython3/\n\n   This provides xp.pyi, xp_types.pyi, and all official API signatures for IDE autocompletion.\n   \n   This provides plugins access to package modules (utils)\n\n4. Develop plugins inside the headless-dev plugins directory  \n   All plugin modules must be placed in:\n   xppython3-headless-dev/Resources/plugins/PythonPlugins\n\n   The simless runner loads plugins directly from this directory and executes their full lifecycle.\n\n5. (Optional) Install Poetry for dependency management  \n   If you want a reproducible environment:\n   pip install --user poetry\n   poetry install\n   poetry shell\n\n---------------------------------------------------------------------\n\n# 📁 Directory Structure\n```\nxppython3-headless-dev/                      # Runner treats as X=plane root dir\n│\n├── Resources/                               # Mirrors X-plane dir\n│   └── plugins/                             # X‑Plane plugins dir\n│       ├── XPPython3/                       # *** Copy complete package ***                      \n│       │   └── ...\n│       │\n│       └── PythonPlugins/                   # ALL XPPython3 plugins live here\n│           ├── PI_sshd_dataref_bridge.py    # This bridge server must be installed in X-plane\n│           ├── PI_sshd_ota.py               # Example plugin with managed DataRefs\n│           ├── PI_sshd_dev_ota_gui.py       # Example XPWidget GUI plugin\n│           │\n│           ├── sshd_extlibs/                # Shared modules\n│           │   ├── ss_serial_device.py\n│           │   └── ...\n│           │\n│           └── sshd_extensions/             # Shared plugin architecture (production)\n│               ├── datarefs.py              # Managed DataRefs (maybe should use EasyDataRefs)\n│               ├── bridge_protocol.py       # Bridge datarefs to X-Plane\n│               └── ...\n│\n├── Output/                                  # Mirrors X‑Plane dir\n│   └── real weather/                        # NOAA expects this directory to exist\n│\n├── simless/                                 # Sim‑less execution harness (development‑only)\n│   │\n│   ├── __init__.py                          # Bootstraps paths expected by plugins\n│   ├── run_oat_control.py                   # example run script for plugins\n│   ├── DataRefCache.txt                     # Cached DataRefs from bridge to work offline\n│   │\n│   └── libs/\n│       ├── fake_xp.py                       # FakeXP: public xp.* API façade\n│       ├── fake_xp.pyi                      # Typing surface for FakeXP API\n│       ├── plugin_runner.py                 # Runs full lifecycles for plugins\n│       ├── plugin_loader.py                 # Load plugin compatible environment\n│       ├── xppython3_runtime.py             # Monkey-patch xp.* API methods with fake emulators\n│       ├── fake_xp_widget.py                # XPWidget emulation (DearPyGui-backed)\n│       ├── fake_xp_graphics.py              # XPLMDisplay/XPLMGraphics simulation\n│       ├── fake_xp_dataref.py               # DataRef engine (managed + inferred + bridged)\n│       ├── fake_xp_utilities.py             # Commands, menus, misc XPLM shims\n│       └── fake_xp_input.py                 # mouse / keyboard\n│\n├── tests/                                   # Unit tests for FakeXP + plugin lifecycle\n│\n└── pyproject.toml                           # Poetry package management\n```\n---------------------------------------------------------------------\n\n# 🧩 IDE (PyCharm) Development Workflow\n\nDevelopment workflow features:\n\n• Strong datatyping and code inspection with xp.pyi and xp_interface.pyi  \n• Structured to generate and validate AI‑generated code  \n• Debug plugins in the IDE debugger using a simless runner  \n• Run with live X‑Plane DataRefs through a dataref bridge  \n\nSee [PYCHARM_CONFIGURATION.md](docs/PYCHARM_CONFIGURATION.md) for full setup instructions.\n\nSee [DEVELOPER_NOTES.md](docs/DEVELOPER_NOTES.md) for special considerations for running Python in X‑Plane.\n\nSee [AI_CODING_GUIDE.md](docs/AI_CODING_GUIDE.md) for generating AI code within this project structure.\n\nSee [GUI_EMULATION.md](docs/GUI_EMULATION.md) for special considerations for GUI usage.\n\n---------------------------------------------------------------------\n\n# ▶️ Minimal Sim‑less Runner\n\nA simple runner script is all that’s needed to execute plugins outside X‑Plane.\n\n```python\nfrom simless.libs.fake_xp import FakeXP\n\ndef run_gui_sample() -\u003e None:\n    # log to terminal instead of log files for IDE debugging\n    xp = FakeXP(terminal_logging=True)\n\n    plugins = [\n        \"PI_sshd_gui_sample\",\n    ]\n\n    xp.simless_runner.run_plugin_lifecycle(plugins)\n\nif __name__ == \"__main__\":\n    run_gui_sample()\n```\n\nThis runner:\n\n• Boots FakeXP which emulates the X‑Plane xp module  \n• Loads any number of plugins that will share the same DataRef namespace  \n• Executes the full lifecycle (start/enable/flight_loop/disable/stop)  \n• Runs in GUI or headless mode\n\n---------------------------------------------------------------------\n\n# 🔌 Bridged DataRefs (Live X‑Plane integration)\n\nBridged DataRefs allow a sim‑less FakeXP environment to mirror live X‑Plane DataRefs in real time.\nThe live DataRefs can be cached to a file to allow for subsequent offline debugging sessions\nwith properly shaped data.\n\n**The PI_sshd_dataref_bridge.py plugin must be installed in X-Plane**\n\nThis enables:\n\n• Running plugins in an IDE while X‑Plane is running  \n• Injecting real simulator values into FakeXP  \n• Debugging plugin logic against live aircraft state  \n• Debugging plugin logic against cached plausible data\n• Seamless transition between sim‑less and in‑sim execution  \n\nSee [BRIDGED_DATAREFS](docs/DATAREF_MODEL.md#bridge-enabled-datarefs) for full details.\n\nKey properties:\n\n• Bridged DataRefs are non‑blocking  \n• Fake values are always available  \n• Authority is established explicitly by X‑Plane  \n• Type and value become authoritative together  \n• Disconnects safely revert DataRefs to dummy state  \n\nBridged DataRefs integrate transparently with:\n\n• Managed DataRefs  \n• Auto‑created DataRefs  \n• The standard xp.* API  \n\nNo plugin code changes are required.\n\n---------------------------------------------------------------------\n\n# 🔍 DataRef Viewer (Plugin Menu Tool)\n\nA lightweight in‑sim DataRef Viewer is included for debugging.  \nIt appears under:\n\nPlugins → FakeXP → Dataref Viewer\n\nThe viewer automatically catalogs **all DataRefs used by the plugin**, including:\n\nFeatures:\n\n• Search and filter  \n• Real‑time updates when bridged to X‑Plane  \n• Safe fallback to cached values when offline  \n\n---------------------------------------------------------------------\n\n# 🧩 Managed DataRefs (extension)\n\nManaged DataRefs provide:\n\n• Automatic waiting for required DataRefs during startup  \n• Defaults used until X‑Plane provides real values  \n• Automatic handle and metadata retrieval  \n• Unified, type‑safe get/set access\n\nManaged DataRefs define the plugin’s contract with X‑Plane and are production‑safe.\n\nSee [DATAREF_MODEL.md](docs/DATAREF_MODEL.md) for full details.\n\n---------------------------------------------------------------------\n\n# 🚀 Deployment to X‑Plane\n\nCopy plugin contents into:\n\nX‑Plane 12/Resources/plugins/PythonPlugins/\n\nExample:\n\nPI_sshd_ota.py  \nextensions/  \nextlibs/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstu-speed%2Fxppython3-headless-dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstu-speed%2Fxppython3-headless-dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstu-speed%2Fxppython3-headless-dev/lists"}