Merge branch 'main' into replace-skeleton-reference

.github/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contribute to the project
+
+Contributions and issues are most welcome! All issues and pull requests are
+handled through [GitHub](https://github.com/DiamondLightSource/blueapi/issues). Also, please check for any existing issues before
+filing a new one. If you have a great idea but it involves big changes, please
+file a ticket before making a pull request! We want to make sure you don't spend
+your time coding something that might not fit the scope of the project.
+
+## Issue or Discussion?
+
+Github also offers [discussions](https://github.com/DiamondLightSource/blueapi/discussions) as a place to ask questions and share ideas. If
+your issue is open ended and it is not obvious when it can be "closed", please
+raise it as a discussion instead.
+
+## Code Coverage
+
+While 100% code coverage does not make a library bug-free, it significantly
+reduces the number of easily caught bugs! Please make sure coverage remains the
+same or is improved by a pull request!
+
+## Developer Information
+
+It is recommended that developers use a [vscode devcontainer](https://code.visualstudio.com/docs/devcontainers/containers). This repository contains configuration to set up a containerized development environment that suits its own needs.
+
+This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
+
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/2.0.1/how-to.html).

.github/pages/make_switcher.py

@@ -3,28 +3,28 @@
 from argparse import ArgumentParser
 from pathlib import Path
 from subprocess import CalledProcessError, check_output
-from typing import List, Optional
+from typing import Optional
 
 
-def report_output(stdout: bytes, label: str) -> List[str]:
+def report_output(stdout: bytes, label: str) -> list[str]:
     ret = stdout.decode().strip().split("\n")
     print(f"{label}: {ret}")
     return ret
 
 
-def get_branch_contents(ref: str) -> List[str]:
+def get_branch_contents(ref: str) -> list[str]:
     """Get the list of directories in a branch."""
     stdout = check_output(["git", "ls-tree", "-d", "--name-only", ref])
     return report_output(stdout, "Branch contents")
 
 
-def get_sorted_tags_list() -> List[str]:
+def get_sorted_tags_list() -> list[str]:
     """Get a list of sorted tags in descending order from the repository."""
     stdout = check_output(["git", "tag", "-l", "--sort=-v:refname"])
     return report_output(stdout, "Tags list")
 
 
-def get_versions(ref: str, add: Optional[str]) -> List[str]:
+def get_versions(ref: str, add: Optional[str]) -> list[str]:
     """Generate the file containing the list of all GitHub Pages builds."""
     # Get the directories (i.e. builds) from the GitHub Pages branch
     try:
@@ -41,7 +41,7 @@ def get_versions(ref: str, add: Optional[str]) -> List[str]:
     tags = get_sorted_tags_list()
 
     # Make the sorted versions list from main branches and tags
-    versions: List[str] = []
+    versions: list[str] = []
     for version in ["master", "main"] + tags:
         if version in builds:
             versions.append(version)

README.md

@@ -0,0 +1,43 @@
+[![CI](https://github.com/DiamondLightSource/blueapi/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/blueapi/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/DiamondLightSource/blueapi/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/blueapi)
+[![PyPI](https://img.shields.io/pypi/v/blueapi.svg)](https://pypi.org/project/blueapi)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+# blueapi
+
+Lightweight bluesky-as-a-service wrapper application. Also usable as a library.
+
+Source          | <https://github.com/DiamondLightSource/blueapi>
+:---:           | :---:
+PyPI            | `pip install blueapi`
+Docker          | `docker run ghcr.io/diamondlightsource/blueapi:latest`
+Documentation   | <https://diamondlightsource.github.io/blueapi>
+Releases        | <https://github.com/DiamondLightSource/blueapi/releases>
+
+This module wraps [bluesky](https://blueskyproject.io/bluesky) plans and devices
+inside a server and exposes endpoints to send commands/receive data. Useful for
+installation at labs where multiple people may control equipment, possibly from
+remote locations.
+
+![concept][]
+
+The main premise of blueapi is to minimize the boilerplate required to get plans
+and devices up and running by generating an API for your lab out of
+type-annotated plans. For example, take the following plan:
+
+```python
+    import bluesky.plans as bp
+    from blueapi.core import MsgGenerator
+
+    def my_plan(foo: str, bar: int) -> MsgGenerator:
+        yield from bp.scan(...)
+```
+
+Blueapi's job is to detect this plan and automatically add it to the lab's API
+so it can be invoked easily with a few REST calls. 
+
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+See https://diamondlightsource.github.io/blueapi for more detailed documentation.
+
+[concept]: https://raw.githubusercontent.com/DiamondLightSource/blueapi/main/docs/images/blueapi.png

docs/how-to/contribute.md

@@ -0,0 +1,2 @@
+```{include} ../../.github/CONTRIBUTING.md
+```

docs/index.md

@@ -2,11 +2,11 @@
 html_theme.sidebar_secondary.remove: true
 ---
 
-```{include} ../README.rst
-:relative-images:
-:end-before: and will be replaced
+```{include} ../README.md
+:end-before: <!-- README only content
 ```
 
+[concept]: images/blueapi.png
 
 How the documentation is structured
 -----------------------------------

pyproject.toml

@@ -26,13 +26,12 @@ dependencies = [
     "fastapi[all]<0.99",
     "uvicorn",
     "requests",
-    "dls-bluesky-core", #requires ophyd-async
+    "dls-bluesky-core",  #requires ophyd-async
     "dls-dodal",
-    "typing_extensions<4.6",
 ]
 dynamic = ["version"]
 license.file = "LICENSE"
-readme = "README.rst"
+readme = "README.md"
 requires-python = ">=3.9"
 
 [project.optional-dependencies]
@@ -135,9 +134,13 @@ lint.select = [
     "F",  # pyflakes rules - https://docs.astral.sh/ruff/rules/#pyflakes-f
     "W",  # pycodestyle warnings - https://docs.astral.sh/ruff/rules/#warning-w
     "I",  # isort - https://docs.astral.sh/ruff/rules/#isort-i
-    #"UP", # pyupgrade - https://docs.astral.sh/ruff/rules/#pyupgrade-up
+    "UP", # pyupgrade - https://docs.astral.sh/ruff/rules/#pyupgrade-up
 ]
 
 [tool.ruff.lint.flake8-bugbear]
-extend-immutable-calls = ["fastapi.Depends", "fastapi.Body", "fastapi.Task", "dls_bluesky_core.core.inject"]
-
+extend-immutable-calls = [
+    "fastapi.Depends",
+    "fastapi.Body",
+    "fastapi.Task",
+    "dls_bluesky_core.core.inject",
+]

src/blueapi/cli/cli.py

@@ -4,7 +4,7 @@
 from functools import wraps
 from pathlib import Path
 from pprint import pprint
-from typing import Optional, Tuple, Union
+from typing import Optional, Union
 
 import click
 from requests.exceptions import ConnectionError
@@ -34,7 +34,7 @@
     "-c", "--config", type=Path, help="Path to configuration YAML file", multiple=True
 )
 @click.pass_context
-def main(ctx: click.Context, config: Union[Optional[Path], Tuple[Path, ...]]) -> None:
+def main(ctx: click.Context, config: Union[Optional[Path], tuple[Path, ...]]) -> None:
     # if no command is supplied, run with the options passed
 
     config_loader = ConfigLoader(ApplicationConfig)

src/blueapi/cli/rest.py

@@ -1,4 +1,5 @@
-from typing import Any, Callable, Literal, Mapping, Optional, Type, TypeVar
+from collections.abc import Mapping
+from typing import Any, Callable, Literal, Optional, TypeVar
 
 import requests
 from pydantic import parse_obj_as
@@ -98,7 +99,7 @@ def cancel_current_task(
     def _request_and_deserialize(
         self,
         suffix: str,
-        target_type: Type[T],
+        target_type: type[T],
         data: Optional[Mapping[str, Any]] = None,
         method="GET",
         raise_if: Callable[[requests.Response], bool] = _is_exception,

src/blueapi/cli/updates.py

@@ -1,5 +1,6 @@
 import itertools
-from typing import Dict, Mapping, Optional, Union
+from collections.abc import Mapping
+from typing import Optional, Union
 
 from tqdm import tqdm
 
@@ -9,7 +10,7 @@
 
 
 class ProgressBarRenderer:
-    _bars: Dict[str, tqdm]
+    _bars: dict[str, tqdm]
     _count: itertools.count
 
     def __init__(self) -> None:

src/blueapi/config.py

@@ -1,7 +1,8 @@
 import os
+from collections.abc import Mapping
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, Generic, Literal, Mapping, Optional, Type, TypeVar, Union
+from typing import Any, Generic, Literal, Optional, TypeVar, Union
 
 import yaml
 from pydantic import BaseModel, Field, ValidationError, parse_obj_as, validator
@@ -124,10 +125,10 @@ class ConfigLoader(Generic[C]):
     of default values, dictionaries, YAML/JSON files etc.
     """
 
-    _schema: Type[C]
-    _values: Dict[str, Any]
+    _schema: type[C]
+    _values: dict[str, Any]
 
-    def __init__(self, schema: Type[C]) -> None:
+    def __init__(self, schema: type[C]) -> None:
         self._schema = schema
         self._values = {}
 
@@ -142,7 +143,7 @@ def use_values(self, values: Mapping[str, Any]) -> None:
                                         if defaults provided.
         """
 
-        def recursively_update_map(old: Dict[str, Any], new: Mapping[str, Any]) -> None:
+        def recursively_update_map(old: dict[str, Any], new: Mapping[str, Any]) -> None:
             for key in new:
                 if (
                     key in old