dls-dodal 1.32.0__tar.gz → 1.34.1__tar.gz

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/.copier-answers.yml

@@ -1,9 +1,11 @@
 # Changes here will be overwritten by Copier
-_commit: 2.2.0
+_commit: 2.5.0
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: dominic.oram@diamond.ac.uk
 author_name: Dominic Oram
+component_lifecycle: production
 component_owner: group:data-acquisition
+component_type: library
 description: Ophyd devices and other utils that could be used across DLS beamlines
 distribution_name: dls-dodal
 docker: false

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/.github/CONTRIBUTING.md

@@ -24,4 +24,4 @@ It is recommended that developers use a [vscode devcontainer](https://code.visua
 
 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.2.0/how-to.html).
+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.5.0/how-to.html).

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/.github/pages/make_switcher.py

@@ -1,3 +1,5 @@
+"""Make switcher.json to allow docs to switch between different versions."""
+
 import json
 import logging
 from argparse import ArgumentParser
@@ -6,6 +8,7 @@ from subprocess import CalledProcessError, check_output
 
 
 def report_output(stdout: bytes, label: str) -> list[str]:
+    """Print and return something received frm stdout."""
     ret = stdout.decode().strip().split("\n")
     print(f"{label}: {ret}")
     return ret
@@ -52,14 +55,12 @@ def get_versions(ref: str, add: str | None) -> list[str]:
     return versions
 
 
-def write_json(path: Path, repository: str, versions: str):
+def write_json(path: Path, repository: str, versions: list[str]):
+    """Write the JSON switcher to path."""
     org, repo_name = repository.split("/")
-    pages_url = f"https://{org}.github.io"
-    if repo_name != f"{org}.github.io":
-        # Only add the repo name if it isn't the source for the org pages site
-        pages_url += f"/{repo_name}"
     struct = [
-        {"version": version, "url": f"{pages_url}/{version}/"} for version in versions
+        {"version": version, "url": f"https://{org}.github.io/{repo_name}/{version}/"}
+        for version in versions
     ]
     text = json.dumps(struct, indent=2)
     print(f"JSON switcher:\n{text}")
@@ -67,6 +68,7 @@ def write_json(path: Path, repository: str, versions: str):
 
 
 def main(args=None):
+    """Parse args and write switcher."""
     parser = ArgumentParser(
         description="Make a versions.json file from gh-pages directories"
     )

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/.github/workflows/_pypi.yml

@@ -15,3 +15,5 @@ jobs:
 
       - name: Publish to PyPI using trusted publishing
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: false

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/.github/workflows/_release.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Create GitHub Release
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191 # v2.0.8
+        uses: softprops/action-gh-release@e7a8f85e1c67a31e6ed99a94b41bd0b71bbee6b8 # v2.0.9
         with:
           prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
           files: "*"

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
     strategy:
       matrix:
         runs-on: ["ubuntu-latest"] # can add windows-latest, macos-latest
-        python-version: ["3.10", "3.11"] # add 3.12 when p4p #145 is fixed
+        python-version: ["3.10", "3.11", "3.12"]
         include:
           # Include one that runs in the dev environment
           - runs-on: "ubuntu-latest"

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/.gitignore

@@ -57,6 +57,7 @@ tmp/
 # Sphinx documentation
 docs/_build/
 docs/reference/generated/
+docs/_api
 
 # PyBuilder
 target/

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/Dockerfile

@@ -1,7 +1,7 @@
 # The devcontainer should use the developer target and run as root with podman
 # or docker with user namespaces.
 ARG PYTHON_VERSION=3.11
-FROM python:${PYTHON_VERSION} as developer
+FROM python:${PYTHON_VERSION} AS developer
 
 # Add any system dependencies for the developer/build environment here
 RUN apt-get update && apt-get install -y --no-install-recommends \

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dls-dodal
-Version: 1.32.0
+Version: 1.34.1
 Summary: Ophyd devices and other utils that could be used across DLS beamlines
 Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>
 License:                                  Apache License
@@ -216,7 +216,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: ophyd
-Requires-Dist: ophyd-async<0.7,>=0.6
+Requires-Dist: ophyd-async<0.8,>=0.7.0a1
 Requires-Dist: bluesky
 Requires-Dist: pyepics
 Requires-Dist: dataclasses-json
@@ -263,7 +263,7 @@ Requires-Dist: types-aiofiles; extra == "dev"
 [![CI](https://github.com/DiamondLightSource/dodal/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/dodal/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/DiamondLightSource/dodal/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/dodal)
 [![PyPI](https://img.shields.io/pypi/v/dls-dodal.svg)](https://pypi.org/project/dls-dodal)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
 # dodal
 

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/README.md

@@ -1,7 +1,7 @@
 [![CI](https://github.com/DiamondLightSource/dodal/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/dodal/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/DiamondLightSource/dodal/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/dodal)
 [![PyPI](https://img.shields.io/pypi/v/dls-dodal.svg)](https://pypi.org/project/dls-dodal)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
 # dodal
 

dls_dodal-1.34.1/docs/_api.rst

@@ -0,0 +1,16 @@
+:orphan:
+
+..
+   This page is not included in the TOC tree, but must exist so that the
+   autosummary pages are generated for dodal and all its
+   subpackages
+
+API
+===
+
+.. autosummary::
+    :toctree: _api
+    :template: custom-module-template.rst
+    :recursive:
+
+    dodal

dls_dodal-1.34.1/docs/_templates/custom-module-template.rst

@@ -0,0 +1,37 @@
+{{ ('``' + fullname + '``') | underline }}
+
+{%- set filtered_members = [] %}
+{%- for item in members %}
+    {%- if item in functions + classes + exceptions + attributes %}
+        {% set _ = filtered_members.append(item) %}
+    {%- endif %}
+{%- endfor %}
+
+.. automodule:: {{ fullname }}
+    :members:
+
+    {% block modules %}
+    {% if modules %}
+    .. rubric:: Submodules
+
+    .. autosummary::
+        :toctree:
+        :template: custom-module-template.rst
+        :recursive:
+    {% for item in modules %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block members %}
+    {% if filtered_members %}
+    .. rubric:: Members
+
+    .. autosummary::
+        :nosignatures:
+    {% for item in filtered_members %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/docs/conf.py

@@ -1,8 +1,9 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
 
 import sys
 from inspect import isclass
@@ -33,6 +34,7 @@ else:
 extensions = [
     # Use this for generating API docs
     "sphinx.ext.autodoc",
+    # and making summary tables at the top of API docs
     "sphinx.ext.autosummary",
     # This can parse google style docstrings
     "sphinx.ext.napoleon",
@@ -91,6 +93,12 @@ autodoc_preserve_defaults = True
 autosummary_generate = True
 autosummary_imported_members = False
 
+# Document only what is in __all__
+autosummary_ignore_module_all = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
 # Output graphviz directive produced images in a scalable format
 graphviz_output_format = "svg"
 

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/docs/how-to/create-beamline.rst

@@ -11,7 +11,7 @@ Each beamline should have its own file in the ``doodal.beamlines`` folder, in wh
 beamline are instantiated. The file should be named after the colloquial name for the beamline. For example:
 
 * ``i03.py``
-* ``i04_1.py``
+* ``i20_1.py``
 * ``vmxi.py``
 
 Beamline modules (in ``dodal.beamlines``) are code-as-configuration. They define the set of devices and common device

dls_dodal-1.34.1/docs/how-to/write-tests.md

@@ -0,0 +1,8 @@
+# Writing Tests in This Python Project
+
+Testing is essential to maintain the integrity and reliability of the codebase. Follow the guidelines below to write tests for this project effectively.
+
+## Test Organization
+
+- **Unit Tests**: Place unit tests for individual components in the `tests` directory, but take care to mirror the file structure of the `src` folder with the corresponding code files. Use the `test_*.py` naming convention for test files.
+- **System Tests**: Tests that interact with DLS infrastructure, network, and filesystem should be placed in the top-level `systems_test` folder. This separation ensures that these tests are easily identifiable and can be run independently from unit tests.

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/docs/reference/device-standards.rst

@@ -21,6 +21,17 @@ should think about where to place them in the following order:
 
 This is in an effort to avoid duplication across facilities/beamlines. 
 
+Device Best Practices
+----------------------------
+
+Ophyd-async directory contains a flowchart_ for a simplified decision tree about what interfaces
+should a given device implement. In addition to this the following guidelines are strongly recommended:
+
+#. Devices should contain only the PV suffixes that are generic for any instance of the device. See `PV Suffixes`_
+#. Anything in a device that is expected to be set externally should be a signal. See `Use of signals`_
+#. Devices should not hold state, when they are read they should read the hardware. See `Holding State`_
+
+
 PV Suffixes
 -----------
 
@@ -86,16 +97,78 @@ Instead you should make a soft signal:
     
     class MyDevice(Device):
         def __init__(self):
-             self.param = create_soft_signal(str, "", self.name)
+             self.param = soft_signal_rw(str)
     
     my_device = MyDevice()
     def my_plan():
         yield from bps.mv(my_device.param, "new_value")
 
-Ophyd Devices best practices
-----------------------------
 
-Ophyd-async directory contains a flowchart_ for a simplified decision tree about what interfaces
-should a given device implement.
+Holding State
+-------------
+
+Devices should avoid holding state as much as possible. Ophyd devices are mostly trying to reflect the state of hardware and so when the device is read that hardware should be read.
+
+If the device holds the state itself it is likely to not reflect the real hardware if:
+* The device has just been initialised
+* The hardware has changed independently e.g. via EPICS directly
+* The hardware has failed to do what the device expected
+
+For example, if I have a device that I would like to treat as moving in/out based on an underlying axis then it would be incorrect to implement it like this:
+
+.. code-block:: python
+
+    class InOut(Enum):
+        IN = 0
+        OUT = 0
+
+    class MyDevice(Device):
+        def __init__(self):
+            self.underlying_motor = Motor("MOTOR")
+            with self.add_children_as_readables():
+                self.in_out, self._in_out_setter = soft_signal_r_and_setter(InOut)
+                
+
+        @AsyncStatus.wrap
+        async def set(self, value: InOut):
+            if value == InOut.IN:
+                await self.underlying_motor.set(100)
+            else:
+                await self.underlying_motor.set(0)
+            self._in_out_setter(value)
+
+While this may appear to work fine during normal operation the state of in_out is only ever updated if the ophyd device is set. It is incorrect to assume that underlying_motor only changes
+based on this and so this has the issues listed above. Instead you should make sure to update in_out whenever the device is read e.g.
+
+.. code-block:: python
+
+    class InOut(Enum):
+        IN = 0
+        OUT = 0
+
+    class MyDevice(Device):
+        def __init__(self):
+            self.underlying_motor = Motor("MOTOR")
+            with self.add_children_as_readables():
+                self.in_out = create_hardware_backed_soft_signal(InOut, self._get_in_out_from_hardware)
+                
+        async def _get_in_out_from_hardware(self):
+            current_position = await self.underlying_motor.get_value()
+            if isclose(current_position, 0):
+                return InOut.IN
+            elif isclose(current_position, 100):
+                return InOut.OUT
+            else:
+                raise ValueError()
+
+
+        @AsyncStatus.wrap
+        async def set(self, value: InOut):
+            if value == InOut.IN:
+                await self.underlying_motor.set(100)
+            else:
+                await self.underlying_motor.set(0)
+
+This will be simplified by https://github.com/bluesky/ophyd-async/issues/525
 
 .. _flowchart: https://blueskyproject.io/ophyd-async/main/how-to/choose-interfaces-for-devices.html

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/docs/reference/standards.rst

@@ -29,7 +29,7 @@ Supported Python Versions
 As a standard for the python versions to support, we should be matching the deprecation policy at 
 https://numpy.org/neps/nep-0029-deprecation_policy.html.
 
-Currently supported versions are: 3.10, 3.11.
+Currently supported versions are: 3.10, 3.11, 3.12. (As of the last edit of this document.)
 
 .. _documentation_standards:
 

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/docs/reference.md

@@ -6,7 +6,7 @@ Technical reference material including APIs and release notes.
 :maxdepth: 1
 :glob:
 
-reference/*
+API <_api/dodal>
 genindex
 Release Notes <https://github.com/DiamondLightSource/dodal/releases>
 ```

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/pull_request_template.md

@@ -6,6 +6,6 @@ Fixes #ISSUE
 
 ### Checks for reviewer
 - [ ] Would the PR title make sense to a scientist on a set of release notes
-- [ ] If a new device has been added does it follow the [standards](https://github.com/DiamondLightSource/dodal/wiki/Device-Standards)
+- [ ] If a new device has been added does it follow the [standards](https://diamondlightsource.github.io/dodal/main/reference/device-standards.html)
 - [ ] If changing the API for a pre-existing device, ensure that any beamlines using this device have updated their Bluesky plans accordingly
 - [ ] Have the connection tests for the relevant beamline(s) been run via `dodal connect ${BEAMLINE}`

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/pyproject.toml

@@ -15,7 +15,7 @@ description = "Ophyd devices and other utils that could be used across DLS beaml
 dependencies = [
     "click",
     "ophyd",
-    "ophyd-async>=0.6,<0.7",
+    "ophyd-async>=0.7.0a1,<0.8",
     "bluesky",
     "pyepics",
     "dataclasses-json",
@@ -24,10 +24,10 @@ dependencies = [
     "requests",
     "graypy",
     "pydantic>=2.0",
-    "opencv-python-headless", # For pin-tip detection.
-    "aioca",                  # Required for CA support with ophyd-async.
-    "p4p",                    # Required for PVA support with ophyd-async.
-    "numpy<2.0",              # Unpin when https://github.com/bluesky/ophyd-async/issues/387 resolved
+    "opencv-python-headless",    # For pin-tip detection.
+    "aioca",                     # Required for CA support with ophyd-async.
+    "p4p",                       # Required for PVA support with ophyd-async.
+    "numpy<2.0",                 # Unpin when https://github.com/bluesky/ophyd-async/issues/387 resolved
     "aiofiles",
     "aiohttp",
     "redis",
@@ -91,6 +91,7 @@ dodal = ["*.txt"]
 version_file = "src/dodal/_version.py"
 
 [tool.pyright]
+typeCheckingMode = "standard"
 reportMissingImports = false # Ignore missing stubs in imported modules
 
 [tool.pytest.ini_options]
@@ -115,7 +116,7 @@ filterwarnings = [
     "ignore::DeprecationWarning:wheel",
 ]
 # Doctest python code in docs, python code in src docstrings, test functions in tests
-testpaths = "docs src tests"
+testpaths = "docs src tests system_tests"
 
 [tool.coverage.report]
 exclude_also = [
@@ -176,3 +177,4 @@ lint.select = [
 # See https://github.com/DiamondLightSource/python-copier-template/issues/154
 # Remove this line to forbid private member access in tests
 "tests/**/*" = ["SLF001"]
+"system_tests/**/*" = ["SLF001"]

{dls_dodal-1.32.0 → dls_dodal-1.34.1}/src/dls_dodal.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dls-dodal
-Version: 1.32.0
+Version: 1.34.1
 Summary: Ophyd devices and other utils that could be used across DLS beamlines
 Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>
 License:                                  Apache License
@@ -216,7 +216,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: ophyd
-Requires-Dist: ophyd-async<0.7,>=0.6
+Requires-Dist: ophyd-async<0.8,>=0.7.0a1
 Requires-Dist: bluesky
 Requires-Dist: pyepics
 Requires-Dist: dataclasses-json
@@ -263,7 +263,7 @@ Requires-Dist: types-aiofiles; extra == "dev"
 [![CI](https://github.com/DiamondLightSource/dodal/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/dodal/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/DiamondLightSource/dodal/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/dodal)
 [![PyPI](https://img.shields.io/pypi/v/dls-dodal.svg)](https://pypi.org/project/dls-dodal)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
 # dodal