/kb-python-development

name: kb-python-development
description: "Reference data, not a reviewer. Python and wxPython development: packaging (PyInstaller/Nuitka), testing, desktop accessibility APIs, cross-platform paths, and framework patterns."
license: MIT
disable-model-invocation: true
user-invocable: false
metadata:
  tier: reference
  domain: cross-cutting
  output: none
  effort: low
  title: Python Development

Python Development Skill

Reference data for the Developer Hub, Python Specialist, and wxPython Specialist agents.

Python Version Quick Reference

Each version, with its key features and end of support (python.org, October 2026). 3.10 reached end of life on 1 October 2026.

| Version | Key Features | EOL | |---|---|---| | 3.10 | `match/case`, `X \| Y` unions, `ParamSpec` | Oct 2026 (end of life) | | 3.11 | Exception groups, `Self` type, `tomllib`, faster CPython | Oct 2027 | | 3.12 | Type parameter syntax `def f[T]()`, `@override`, f-string nesting | Oct 2028 | | 3.13 | Experimental free-threaded mode, improved error messages | Oct 2029 | | 3.14 | Template strings (PEP 750), deferred evaluation of annotations (PEP 649), `compression.zstd` (PEP 784) | Oct 2030 | | 3.15 | Explicit lazy imports (PEP 810), `frozendict` (PEP 814), UTF-8 default encoding (PEP 686) | Oct 2031 |

pyproject.toml Skeleton

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-app"
version = "1.0.0"
requires-python = ">=3.11"
dependencies = []

[project.optional-dependencies]
dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.11"]

[project.scripts]
myapp = "my_app.__main__:main"

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra --strict-markers"

[tool.ruff]
target-version = "py311"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "TC"]  # flake8-type-checking is "TC" since ruff 0.8 (was "TCH")

[tool.mypy]
python_version = "3.11"
strict = true

PyInstaller Quick Reference

One-File Mode

exe = EXE(pyz, a.scripts, a.binaries, a.zipfiles, a.datas,
          name='MyApp', console=False, icon='icon.ico')

One-Folder Mode

exe = EXE(pyz, a.scripts, exclude_binaries=True,
          name='MyApp', console=False, icon='icon.ico')
coll = COLLECT(exe, a.binaries, a.zipfiles, a.datas, name='MyApp')

Common Hidden Imports

• `pkg_resources.extern`
• `accessible_output2` (for a11y desktop apps)
• `keyring.backends` (for credential storage)
• `platformdirs`
• `httpx._transports` / `httpcore._backends`
• `encodings` (always needed)

wxPython Quick Reference

Sizer Cheat Sheet

Each sizer, with when to use.

| Sizer | When to Use | |---|---| | `wx.BoxSizer(wx.VERTICAL)` | Stack items top-to-bottom | | `wx.BoxSizer(wx.HORIZONTAL)` | Lay items left-to-right | | `wx.GridBagSizer(vgap, hgap)` | Form layouts with labels + controls | | `wx.FlexGridSizer(rows, cols, vgap, hgap)` | Even grid layouts | | `wx.WrapSizer` | Flow layout that wraps | | `wx.StaticBoxSizer(wx.VERTICAL, parent, "Label")` | Grouped controls with border |

Thread-Safe GUI Updates

# From worker thread:
wx.CallAfter(self.update_status, "Done")
wx.PostEvent(self, CustomEvent(data=result))

# NEVER do this from a worker thread:
self.status_bar.SetStatusText("Done")  # CRASH or CORRUPTION

Standard IDs

Each standard ID, with its ID and purpose.

| ID | Purpose | |---|---| | `wx.ID_OK` | OK button | | `wx.ID_CANCEL` | Cancel button | | `wx.ID_SAVE` | Save action | | `wx.ID_OPEN` | Open action | | `wx.ID_EXIT` | Exit / Quit | | `wx.ID_HELP` | Help action | | `wx.ID_NEW` | New document | | `wx.ID_UNDO` / `wx.ID_REDO` | Undo / Redo |

Event Types

Each event, with its trigger.

| Event | Trigger | |---|---| | `wx.EVT_BUTTON` | Button click | | `wx.EVT_MENU` | Menu item selected | | `wx.EVT_CLOSE` | Window close requested | | `wx.EVT_SIZE` | Window resized | | `wx.EVT_TIMER` | Timer fired | | `wx.EVT_TEXT` | Text control content changed | | `wx.EVT_LIST_ITEM_SELECTED` | List item selected | | `wx.EVT_TREE_SEL_CHANGED` | Tree selection changed | | `wx.EVT_UPDATE_UI` | UI state update check |

Common Pitfalls

Python

• **Mutable default arguments:** `def f(items=[])` shares the list across calls. Use `None` and create inside.
• **Late binding closures:** `lambda: x` in a loop captures the variable, not the value. Use `lambda x=x: x`.
• **Circular imports:** Move imports inside functions, use `TYPE_CHECKING` block, or restructure modules.
• **`field()` outside dataclass:** `field()` is only valid inside `@dataclass` classes. Use plain type annotations elsewhere.
• **`is` vs `==`:** `is` checks identity, `==` checks equality. Use `is` only for `None`, `True`, `False`.
• **String concatenation in loops:** Use `"".join()` or `io.StringIO` instead.

wxPython

• **GUI from worker thread:** Always use `wx.CallAfter()` or `wx.PostEvent()`.
• **Missing `event.Skip()`:** Other handlers won't fire. Call `event.Skip()` unless you intentionally consume the event.
• **Timer not stopped:** Stop timers in `EVT_CLOSE` handler to prevent callbacks after destruction.
• **AUI not uninitialized:** Call `_mgr.UnInit()` in close handler.
• **Dialog not destroyed:** Use context managers (`with MyDialog(...) as dlg:`) for automatic cleanup.
• **Wrong parent for sizer items:** All controls in a sizer must have the same parent panel.
• **Absolute positioning:** Never use `SetPosition()` or `SetSize()` for layout. Always use sizers.

Cross-Platform Paths

from platformdirs import user_config_dir, user_data_dir, user_cache_dir

config = user_config_dir("MyApp", "MyCompany")  # %APPDATA% / ~/Library/... / ~/.config/
data = user_data_dir("MyApp", "MyCompany")
cache = user_cache_dir("MyApp", "MyCompany")

Testing Quick Reference

# Run all tests
pytest

# Run specific test file
pytest tests/test_queue.py

# Run specific test
pytest tests/test_queue.py::test_submit_job -v

# With cover