Adopt python-copier-template 5.5.0

.copier-answers.yml

@@ -0,0 +1,19 @@
+# Changes here will be overwritten by Copier
+_commit: 5.5.0
+_src_path: https://github.com/DiamondLightSource/python-copier-template.git
+author_email: Michael.Abbott@diamond.ac.uk
+author_name: Michael Abbott
+component_lifecycle: production
+component_owner: group:default/accelerator-controls
+component_type: library
+description: Embed an EPICS IOC in a Python process
+distribution_name: softioc
+docker: false
+docs_type: sphinx
+git_platform: github.com
+github_org: DiamondLightSource
+package_name: softioc
+pypi: true
+repo_name: pythonSoftIOC
+strict_typing: false
+type_checker: pyright

.devcontainer/devcontainer.json

@@ -0,0 +1,72 @@
+// For format details, see https://containers.dev/implementors/json_reference/
+{
+    "name": "Python 3 Developer Container",
+    "build": {
+        "dockerfile": "../Dockerfile",
+        "target": "developer"
+    },
+    "remoteEnv": {
+        // Allow X11 apps to run inside the container
+        "DISPLAY": "${localEnv:DISPLAY}",
+        // Put things that allow it in the persistent cache
+        "PRE_COMMIT_HOME": "/cache/pre-commit",
+        "UV_CACHE_DIR": "/cache/uv",
+        "UV_PYTHON_CACHE_DIR": "/cache/uv-python",
+        // Make a venv that is specific for this workspace path as the cache is shared
+        "UV_PROJECT_ENVIRONMENT": "/cache/venv-for${localWorkspaceFolder}",
+        // Do the equivalent of "activate" the venv so we don't have to "uv run" everything
+        "VIRTUAL_ENV": "/cache/venv-for${localWorkspaceFolder}",
+        "PATH": "/cache/venv-for${localWorkspaceFolder}/bin:${containerEnv:PATH}"
+    },
+    "customizations": {
+        "vscode": {
+            // Set *default* container specific settings.json values on container create.
+            "settings": {
+                // Use the container's python by default
+                "python.defaultInterpreterPath": "/cache/venv-for${localWorkspaceFolder}/bin/python",
+                // Don't activate the venv as it is already in the PATH
+                "python.terminal.activateEnvInCurrentTerminal": false,
+                "python.terminal.activateEnvironment": false,
+                // Workaround to prevent garbled python REPL in the terminal
+                // https://github.com/microsoft/vscode-python/issues/25505
+                "python.terminal.shellIntegration.enabled": false
+            },
+            // Add the IDs of extensions you want installed when the container is created.
+            "extensions": [
+                "ms-python.python",
+                "github.vscode-github-actions",
+                "tamasfe.even-better-toml",
+                "redhat.vscode-yaml",
+                "ryanluker.vscode-coverage-gutters",
+                "charliermarsh.ruff",
+                "ms-azuretools.vscode-docker"
+            ]
+        }
+    },
+    // Create the config folder for the bash-config feature and uv cache
+    "initializeCommand": "mkdir -p ${localEnv:HOME}/.config/terminal-config",
+    "runArgs": [
+        // Allow the container to access the host X11 display and EPICS CA
+        "--net=host",
+        // Make sure SELinux does not disable with access to host filesystems like tmp
+        "--security-opt=label=disable"
+    ],
+    "mounts": [
+        // Mount in the user terminal config folder so it can be edited
+        {
+            "source": "${localEnv:HOME}/.config/terminal-config",
+            "target": "/user-terminal-config",
+            "type": "bind"
+        },
+        // Keep a persistent cross container cache for uv, pre-commit, and the venvs
+        {
+            "source": "devcontainer-shared-cache",
+            "target": "/cache",
+            "type": "volume"
+        }
+    ],
+    // Mount the parent as /workspaces so we can pip install peers as editable
+    "workspaceMount": "source=${localWorkspaceFolder}/..,target=/workspaces,type=bind",
+    // After the container is created, recreate the venv then make pre-commit first run faster
+    "postCreateCommand": "uv venv --clear && uv sync && pre-commit install --install-hooks"
+}

.github/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+# Contribute to the project
+
+Contributions and issues are most welcome! All issues and pull requests are
+handled through [GitHub](https://github.com/DiamondLightSource/pythonSoftIOC/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/pythonSoftIOC/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.
+
+## 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/5.5.0/how-to.html).
+
+## Running the tests
+
+The iocStats sources are a git submodule that is needed to build the
+extension, so clone with `--recurse-submodules`. To get the source code and
+run the unit tests, run:
+
+```
+git clone --recurse-submodules https://github.com/DiamondLightSource/pythonSoftIOC.git
+cd pythonSoftIOC
+uv sync
+uv run tox -e tests
+```
+
+`uv sync` builds the extension and installs it, with the `dev` dependency
+group, into a virtual environment. `uv run tox -p` runs the tests, lint, type
+checking and docs build in parallel.
+
+## Updating Dependencies
+
+pythonSoftIOC has a variety of types of dependencies, from Python modules to
+C files and built libraries. If it is necessary to update any of them, the
+safest way to do that is:
+
+```
+# Ensure all changes are committed/saved/backed up
+git clean -fdX
+# Update dependencies in pyproject.toml / setup.py
+uv lock --upgrade
+uv sync
+```
+
+### The epicscorelibs build pin
+
+The extension is built against epicscorelibs, and the epicscorelibs
+dependency of the built package is pinned to the ABI of the version it was
+built against.
+
+- Released wheels and sdists (built by cibuildwheel or pip) use the
+  epicscorelibs floor in `[build-system] requires` in `pyproject.toml`, so they
+  always build against the newest epicscorelibs. They need no edit.
+- `uv.lock` and the development environment use the epicscorelibs version
+  pinned by `build-constraint-dependencies` in the `[tool.uv]` section of
+  `pyproject.toml`. That pin is the only one to change: edit it, then run
+  `uv lock --upgrade-package epicscorelibs` and `uv sync`. Renovate does not
+  bump it.
+
+## Code Styling
+
+The code in this repository conforms to standards set by the following tools:
+
+- [ruff](https://docs.astral.sh/ruff/) for style checks
+- [pyright](https://microsoft.github.io/pyright/) for type checks
+
+These are run by `uv run tox -e pre-commit,type-checking` and also
+automatically at check in. Please read the tool documentation for details
+on how to fix the errors it reports.
+
+## Documentation
+
+Documentation is contained in the `docs` directory and extracted from
+docstrings of the API.
+
+Docs follow the underlining convention:
+
+```
+Heading 1 (page title)
+=======================
+
+Heading 2
+---------
+
+Heading 3
+~~~~~~~~~
+```
+
+You can build the docs from the project directory by running:
+
+```
+uv run tox -e docs
+firefox build/html/index.html
+```
+
+## Release Process
+
+To make a new release, please follow this checklist:
+
+- Choose a new PEP440 compliant release number
+- Git tag the version
+- Push to github and the actions will make a release on pypi
+- Push to internal gitlab but do not release from there
+- Run `dls-py3 download-one-dependency softioc <release>`
+- Run `uv export --frozen --no-dev --all-extras --no-hashes --no-emit-project > /dls_sw/work/python3/RHEL7-x86_64/distributions/softioc-<release>.requirements.txt`
+- Run `dls-release.py -a python3ext softioc <release>`
+
+Release notes are generated in GitHub Releases from the titles of the merged
+pull requests; edit them there to add anything else, such as breaking changes.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug Report
+about: The template to use for reporting bugs and usability issues
+title: " "
+labels: 'bug'
+assignees: ''
+
+---
+
+Describe the bug, including a clear and concise description of the expected behaviour, the actual behavior and the context in which you encountered it (ideally include details of your environment).
+
+## Steps To Reproduce
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+
+## Acceptance Criteria
+- Specific criteria that will be used to judge if the issue is fixed

.github/ISSUE_TEMPLATE/issue.md

@@ -0,0 +1,13 @@
+---
+name: Issue
+about: The standard template to use for feature requests, design discussions and tasks
+title: " "
+labels: ''
+assignees: ''
+
+---
+
+A brief description of the issue, including specific stakeholders and the business case where appropriate
+
+## Acceptance Criteria
+- Specific criteria that will be used to judge if the issue is fixed

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,8 @@
+Fixes #ISSUE
+
+### Instructions to reviewer on how to test:
+1. Do thing x
+2. Confirm thing y happens
+
+### Checks for reviewer
+- [ ] Would the PR title make sense to a user on a set of release notes

.github/pages/make_switcher.py

@@ -0,0 +1,96 @@
+"""Make switcher.json to allow docs to switch between different versions."""
+
+import json
+import logging
+from argparse import ArgumentParser
+from pathlib import Path
+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
+
+
+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]:
+    """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: str | None) -> 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:
+        builds = set(get_branch_contents(ref))
+    except CalledProcessError:
+        builds = set()
+        logging.warning(f"Cannot get {ref} contents")
+
+    # Add and remove from the list of builds
+    if add:
+        builds.add(add)
+
+    # Get a sorted list of tags
+    tags = get_sorted_tags_list()
+
+    # Make the sorted versions list from main branches and tags
+    versions: list[str] = []
+    for version in ["master", "main"] + tags:
+        if version in builds:
+            versions.append(version)
+            builds.remove(version)
+
+    # Add in anything that is left to the bottom
+    versions += sorted(builds)
+    print(f"Sorted versions: {versions}")
+    return versions
+
+
+def write_json(path: Path, repository: str, versions: list[str]):
+    """Write the JSON switcher to path."""
+    org, repo_name = repository.split("/")
+    struct = [
+        {"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}")
+    path.write_text(text, encoding="utf-8")
+
+
+def main(args=None):
+    """Parse args and write switcher."""
+    parser = ArgumentParser(
+        description="Make a versions.json file from gh-pages directories"
+    )
+    parser.add_argument(
+        "--add",
+        help="Add this directory to the list of existing directories",
+    )
+    parser.add_argument(
+        "repository",
+        help="The GitHub org and repository name: ORG/REPO",
+    )
+    parser.add_argument(
+        "output",
+        type=Path,
+        help="Path of write switcher.json to",
+    )
+    args = parser.parse_args(args)
+
+    # Write the versions file
+    versions = get_versions("origin/gh-pages", args.add)
+    write_json(args.output, args.repository, versions)
+
+
+if __name__ == "__main__":
+    main()