Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ jobs:
if: github.ref != 'refs/heads/main'
uses: ./.github/workflows/_tox.yml
with:
tox: pre-commit,type-checking
tox: pre-commit,type-checking,import-linter

test:
if: github.ref != 'refs/heads/main'
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Lightweight bluesky-as-a-service wrapper application. Also usable as a library.
What | Where
:---: | :---:
Source | <https://github.com/DiamondLightSource/blueapi>
PyPI | `pip install blueapi[server]` (server) / `pip install blueapi` (client only)
PyPI | `pip install blueapi[server]` (server) / `pip install blueapi[client]` (client)
Docker | `docker run ghcr.io/diamondlightsource/blueapi:latest`
Documentation | <https://diamondlightsource.github.io/blueapi>
Releases | <https://github.com/DiamondLightSource/blueapi/releases>
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ option to the `controller` subcommand to 'full', you would need to set the
environment variable `BLUEAPI_CONTROLLER_OUTPUT=full`.

```{eval-rst}
.. click:: blueapi.cli:main
.. click:: blueapi.__main__:main
:prog: blueapi
:show-nested:
```
6 changes: 4 additions & 2 deletions docs/tutorials/1. installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,10 @@ from GitHub:
python3 -m pip install "blueapi[server] @ git+https://github.com/DiamondLightSource/blueapi.git"
```

The `server` extra is only needed to run the worker (`blueapi serve`). For the client
and `blueapi controller` commands, `pip install blueapi` is enough.
The `server` extra is needed to run the worker (`blueapi serve`, `setup-scratch`
and `schema`). To only talk to a running worker (`blueapi controller`, `login`,
`logout` and `BlueapiClient`), `pip install blueapi[client]` is enough. Install
`blueapi[server,client]` for both.

The library should now be installed and the commandline interface on your path.
You can check the version that has been installed by typing:
Expand Down
2 changes: 1 addition & 1 deletion docs/tutorials/7. scripting-plans.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ This will be one of `WorkerEvent`, `ProgressEvent` or `DataEvent`.
An example that prints data for each point could be something like

```python
from blueapi.core.bluesky_types import DataEvent
from blueapi.model.event import DataEvent

def feedback(evt):
match evt:
Expand Down
109 changes: 94 additions & 15 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -14,34 +14,31 @@ classifiers = [
]
description = "Lightweight bluesky-as-a-service wrapper application. Also usable as a library."
dependencies = [
"bluesky[plotting]>=1.14.0", # plotting includes matplotlib, required for BestEffortCallback in run plans
"ophyd-async>=0.13.5",
"bluesky[plotting]>=1.14.0", # plotting includes matplotlib, required for BestEffortCallback in the CLI's run command
"pydantic>=2.0",
"pydantic-settings",
"stomp-py",
"PyYAML>=6.0.2",
"click>=8.2.0",
"requests",
"GitPython>=3.1.58", #security base min https://github.com/advisories/GHSA-4gmw-gg2m-w46p - used by the server's /python_environment endpoint and the CLI's scratch setup
"event-model==1.24.0", # https://github.com/DiamondLightSource/blueapi/issues/684
"bluesky-stomp>=0.1.6",
"opentelemetry-distro>=0.48b0",
"observability-utils>=0.1.4",
"pyjwt[crypto]",
"websockets",
"tqdm",
"packaging",
]
dynamic = ["version"]
license.file = "LICENSE"
readme = "README.md"
requires-python = ">=3.11"

[project.optional-dependencies]
# Needed to talk to a running worker: `blueapi controller`, `login`, `logout` and BlueapiClient.
client = ["websockets", "tqdm", "packaging"]

demo = ["dls-dodal>=3.0.2", "ophyd-async[sim]"]
# Only needed to run `blueapi serve` (the FastAPI worker service).
# Needed to run the worker service: `blueapi serve`, `setup-scratch` and `schema`.
server = [
"opentelemetry-distro>=0.48b0",
"ophyd-async>=0.13.5",
"event-model==1.24.0", # https://github.com/DiamondLightSource/blueapi/issues/684
"GitPython>=3.1.58", #security base min https://github.com/advisories/GHSA-4gmw-gg2m-w46p - used by the /python_environment endpoint and scratch setup
"fastapi>=0.112.0",
"uvicorn>=0.52.1",
"aiohttp>=3.13.5",
Expand All @@ -54,9 +51,10 @@ server = [

[dependency-groups]
dev = [
"blueapi[server]",
"blueapi[server,client]",
"ophyd_async[sim]",
"copier",
"import-linter",
"dls-dodal>=3.0.2",
"myst-parser",
"prek",
Expand Down Expand Up @@ -97,7 +95,7 @@ client-system-test = [
]

[project.scripts]
blueapi = "blueapi.cli:main"
blueapi = "blueapi.__main__:main"

[project.urls]
GitHub = "https://github.com/DiamondLightSource/blueapi"
Expand All @@ -113,6 +111,81 @@ required-version = ">=0.13.5"
[tool.setuptools_scm]
version_file = "src/blueapi/_version.py"

[tool.importlinter]
root_package = "blueapi"
include_external_packages = true
exclude_type_checking_imports = true

[[tool.importlinter.contracts]]
name = "Client does not depend on the server or its dependencies"
type = "forbidden"
source_modules = ["blueapi.client", "blueapi.cli"]
forbidden_modules = [
"blueapi.core",
"blueapi.worker",
"blueapi.tutorial",
"blueapi.utils.path_provider",
"blueapi.service.authentication",
"blueapi.service.authorization",
"blueapi.service.cli",
"blueapi.service.environment",
"blueapi.service.interface",
"blueapi.service.main",
"blueapi.service.middleware",
"blueapi.service.numtracker",
"blueapi.service.openapi",
"blueapi.service.runner",
"blueapi.service.scratch",
# server extra
"aioca",
"aiohttp",
"dodal",
"event_model",
"fastapi",
"git",
"graypy",
"httpx",
"ophyd",
"ophyd_async",
"starlette",
"tiled",
"uvicorn",
]
ignore_imports = [
# DeviceModel.from_device is only called by the server
"blueapi.service.model -> blueapi.core.bluesky_types",
"blueapi.service.model -> blueapi.core.context",
# Optional: graylog handler is only imported if graylog is configured
"blueapi.log -> graypy",
]

[[tool.importlinter.contracts]]
name = "Server does not depend on the client"
type = "forbidden"
source_modules = [
"blueapi.config",
"blueapi.core",
"blueapi.log",
"blueapi.model",
"blueapi.service",
"blueapi.tutorial",
"blueapi.utils",
"blueapi.worker",
]
forbidden_modules = [
"blueapi.client",
"blueapi.cli",
# client extra
"packaging",
"tqdm",
"websockets",
]
ignore_imports = [
# Backwards compatible aliases, to be removed May 2027
"blueapi.service -> blueapi.client.session",
"blueapi.service.authentication -> blueapi.client.session",
]

[tool.pyright]
typeCheckingMode = "standard"
reportMissingImports = false # Ignore missing stubs in imported modules
Expand All @@ -136,7 +209,7 @@ source = ["src", "**/site-packages/"]
[tool.tox]
skipsdist = true
# envs to runs automatically with tox -p
env_list = ["pre-commit", "type-checking", "tests", "docs"]
env_list = ["pre-commit", "type-checking", "import-linter", "tests", "docs"]

[tool.tox.env_run_base]
# Pass all environment variables to the test environments
Expand Down Expand Up @@ -171,6 +244,10 @@ commands = [
],
]

[tool.tox.env.import-linter]
description = "Check the client and server only import what they are allowed to"
commands = [["lint-imports"]]

[tool.tox.env.tests]
description = "Run unit tests with coverage"
commands = [
Expand All @@ -190,14 +267,16 @@ commands = [
]

[tool.tox.env.client-system-test]
description = "Run client system tests with blueapi only, no server dependencies"
description = "Run client system tests with blueapi[client] only, no server dependencies"
commands = [
[
"uv",
"run",
"--isolated", # uv run leaves extra packages in place, so don't reuse the dev venv
"--locked",
"--no-default-groups",
"--extra",
"client",
"--group",
"client-system-test",
"pytest",
Expand Down
134 changes: 133 additions & 1 deletion src/blueapi/__main__.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,136 @@
from .cli.cli import main
"""The blueapi command: shared options, plus the client and the server commands.

Client and server do not import each other, this is the one place they are put together
"""

import json
import os
import stat
import textwrap
from pathlib import Path

import click
from click.exceptions import ClickException

from blueapi import __version__, config
from blueapi.config import ApplicationConfig, ConfigLoader
from blueapi.log import set_up_logging
from blueapi.service.cli import SERVER_COMMANDS


@click.group(
invoke_without_command=True, context_settings={"auto_envvar_prefix": "BLUEAPI"}
)
@click.version_option(version=__version__, prog_name="blueapi")
@click.option(
"-h",
"--host",
type=str,
help=textwrap.dedent(
"""
Hostname for the blueapi instance to use

Value should be the full URL including scheme (and port if non-default),
eg `--host http://localhost:8000`
"""
),
)
@click.option(
"-c", "--config", type=Path, help="Path to configuration YAML file", multiple=True
)
@click.option(
"-v",
"--verbose",
"log_level",
flag_value="DEBUG",
help="Include DEBUG level logging output",
)
@click.option(
"-q",
"--quiet",
"log_level",
flag_value="ERROR",
help="Reduce logging noise to only show errors",
)
@click.pass_context
def main(
ctx: click.Context,
config: tuple[Path, ...],
host: str | None = None,
log_level: str | None = None,
) -> None:
# if no command is supplied, run with the options passed

# Set umask to DLS standard
os.umask(stat.S_IWOTH)

config_loader = ConfigLoader(ApplicationConfig)
try:
config_loader.use_values_from_yaml(*config)
except FileNotFoundError as fnfe:
raise ClickException(f"Config file not found: {fnfe.filename}") from fnfe
if host:
config_loader.use_values({"api": {"url": host}})
if log_level:
config_loader.use_values({"logging": {"level": log_level}})

loaded_config: ApplicationConfig = config_loader.load()

set_up_logging(loaded_config.logging)

ctx.ensure_object(dict)
ctx.obj["config"] = loaded_config

if ctx.invoked_subcommand is None:
print("Please invoke subcommand!")


@click.option(
"-o", "--output", type=Path, help="Path to file to save the config schema"
)
@click.option(
"-u",
"--update",
type=bool,
is_flag=True,
help="[Development only] update the config schema in the documentation",
)
@main.command(name="config-schema")
def config_schema(output: Path | None = None, update: bool = False) -> None:
from blueapi.config import generate_config_schema

schema = generate_config_schema()
if update:
output = config.CONFIG_SCHEMA_LOCATION
if output is not None:
with output.open("w") as stream:
json.dump(schema, stream, indent=4)
stream.write("\n")
else:
print(json.dumps(schema))


def _needs_client_extra(name: str, missing: str | None) -> click.Command:
@click.command(name, context_settings={"ignore_unknown_options": True})
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
def command(args: tuple[str, ...]) -> None:
raise ClickException(
f"{missing} is not installed, it is needed to run the client. "
"Install it with: pip install blueapi[client]"
)

return command


try:
from blueapi.cli.cli import CLIENT_COMMANDS
except ModuleNotFoundError as e:
CLIENT_COMMANDS = [
_needs_client_extra(name, e.name) for name in ("controller", "login", "logout")
]

for command in [*CLIENT_COMMANDS, *SERVER_COMMANDS]:
main.add_command(command)

# test with: python -m blueapi
if __name__ == "__main__":
Expand Down
3 changes: 0 additions & 3 deletions src/blueapi/cli/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +0,0 @@
from .cli import main

__all__ = ["main"]
4 changes: 0 additions & 4 deletions src/blueapi/cli/__main__.py

This file was deleted.

Loading
Loading