BCS (Beamline Control System) Python Package

A Python wrapper for dynamically generated API clients that connect to the LabVIEW Beamline Control System.

Overview

This package wraps a lower-level legacy system that dynamically generates API client code for the beamline control system. The actual client implementation is managed externally in the src/clients directory, while this package provides:

• Type stub generation for static analysis
• PEP 561 type information support
• Remote type checking without runtime dependencies

Installation

# Install the package with development dependencies
uv pip install -e ".[dev]"

# Or using uv
uv sync

Usage

from bcs.clients import BCSz

# Use the client to connect to the beamline control system
client = BCSz()

Type Stubs and Type Checking

For Remote Type Checking

Remote systems can import type information without requiring the actual LabVIEW client implementation:

# This will work on systems without LabVIEW installed
from bcs import clients  # Type information is available via .pyi stubs

PEP 561 Compliance

The package includes a py.typed marker file (PEP 561) that signals to type checkers that this package supports inline type hints.

Updating BCS Clients

When the dynamically generated BCS clients in src/clients are updated:

1. Regenerate Type Stubs

After updating the client code, regenerate the type stub files using the provided script:

# Using uv (recommended)
uv run scripts/generate_stubs.py

# Or using Python directly
python scripts/generate_stubs.py

This script uses Pyright to analyze the updated client code and generate corresponding .pyi stub files.

2. Rebuild the Package

# Clean previous builds
rm -r build/ dist/ *.egg-info/

# Rebuild with updated stubs
pip install -e ".[dev]"

3. Test Type Checking

Verify that type stubs are correctly generated by running Pyright:

# Check for type errors
pyright src/

# Or using uv
uv run pyright src/

4. Commit Changes

git add src/__init__.pyi src/py.typed
git commit -m "Update type stubs for BCS client changes"

Development

Directory Structure

bcs-install/
├── src/
│   ├── clients/          # External client implementation (managed elsewhere)
│   ├── __init__.py       # Package initialization
│   ├── __init__.pyi      # Type stubs (auto-generated)
│   └── py.typed          # PEP 561 marker
├── scripts/
│   └── generate_stubs.py # Stub generation script
└── pyproject.toml        # Project configuration

Running Type Checks

# Check entire project
pyright

# Or specific directory
pyright src/

Script Format

The generate_stubs.py script uses uv's script format with inline dependencies, allowing it to be run standalone with automatic dependency installation:

uv run scripts/generate_stubs.py

Type Checking with Remote Systems

For systems that need to import BCS types without the LabVIEW implementation:

1. The .pyi stub files in src/__init__.pyi provide type information
2. The py.typed marker file indicates PEP 561 compliance
3. Type checkers (mypy, Pyright, etc.) can use these stubs without runtime dependencies

Troubleshooting

Stub Generation Fails

If stub generation fails:

1. Ensure Pyright is installed: pip install pyright>=1.1.300
2. Check that the client code in src/clients is syntactically valid
3. Review Pyright output for specific errors: pyright --verbose

Type Checking Errors

If you see type errors after updating clients:

1. Regenerate stubs: uv run scripts/generate_stubs.py
2. Rebuild the package: pip install -e ".[dev]"
3. Run type checks: pyright src/

Contributing

When contributing changes to the client wrapper:

• Do not modify files in src/clients/ directly (this is managed externally)
• Update type stubs when client interfaces change
• Run type checks before submitting pull requests

License

[Add your license here]