Merge pull request #1 from ISISComputingGroup/make_package

Make package

.github/workflows/documentation.yml

@@ -0,0 +1,8 @@
+name: sphinx
+
+on: [push, pull_request, workflow_call]
+
+jobs:
+  call_sphinx_builder:
+    uses: ISISComputingGroup/reusable-workflows/.github/workflows/sphinx.yml@main
+    secrets: inherit

.github/workflows/lint_and_test.yml

@@ -0,0 +1,45 @@
+env:
+  PYTHONUNBUFFERED: "TRUE"
+name: test
+on: [pull_request, workflow_call]
+jobs:
+  lint:
+    uses: ISISComputingGroup/reusable-workflows/.github/workflows/linters.yml@main
+    with:
+      compare-branch: origin/main
+      python-ver: '3.11'
+  unit-tests:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: ["ubuntu-latest", "windows-latest"]
+        version: ['3.11']
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.version }}
+      - name: Install base requirements
+        run: pip install -e .
+      - name: Verify package is importable
+        run: |
+          python -c "from genie_python.genie_startup import *"
+          python -c "from genie_python import genie as g"
+      - name: Install dev requirements
+        run: pip install -e .[dev]
+      - name: Run unit tests
+        run: python -m pytest
+  results:
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    name: Final Results
+    needs: [lint, unit-tests]
+    steps:
+    - run: exit 1
+      # see https://stackoverflow.com/a/67532120/4907315
+      if: >-
+          ${{
+               contains(needs.*.result, 'failure')
+            || contains(needs.*.result, 'cancelled')
+          }}

.github/workflows/release.yml

@@ -0,0 +1,92 @@
+name: Publish Python distribution to PyPI
+on: push
+jobs:
+  lint-and-test:
+    if: github.ref_type == 'tag'
+    name: Run lint & tests
+    uses: ./.github/workflows/lint_and_test.yml
+  build:
+    needs: lint-and-test
+    if: github.ref_type == 'tag'
+    name: build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+  publish-to-pypi:
+    name: >-
+      Publish Python distribution to PyPI
+    if: github.ref_type == 'tag'
+    needs: [lint-and-test, build]
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/p/genie_python
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+  github-release:
+    name: >-
+      Sign the Python distribution with Sigstore
+      and upload them to GitHub Release
+    needs: [lint-and-test, build, publish-to-pypi]
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Sign the dists with Sigstore
+      uses: sigstore/[email protected]
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        '${{ github.ref_name }}'
+        --repo '${{ github.repository }}'
+        --notes ""
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      # Upload to GitHub Release using the `gh` CLI.
+      # `dist/` contains the built packages, and the
+      # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        '${{ github.ref_name }}' dist/**
+        --repo '${{ github.repository }}'

.gitignore

@@ -160,3 +160,5 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
+
+_build/

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, ISIS Experiment Controls Computing
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/conf.py → doc/conf.py

@@ -20,7 +20,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath("../Lib/site-packages/genie_python/"))
+sys.path.insert(0, os.path.abspath("../src/genie_python/"))
 
 # -- General configuration ------------------------------------------------
 

pyproject.toml

@@ -0,0 +1,126 @@
+[build-system]
+requires = ["setuptools", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "genie_python"
+dynamic = ["version"]
+description = "Instrument control & scripting for the ISIS Neutron & Muon source"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {file = "LICENSE"}
+
+authors = [
+  {name = "ISIS Experiment Controls", email = "[email protected]" }
+]
+maintainers = [
+  {name = "ISIS Experiment Controls", email = "[email protected]" }
+]
+
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: BSD License",
+  "Programming Language :: Python :: 3.11",
+]
+
+dependencies = [
+  # EPICS Channel access lib
+  "CaChannel",
+  # Caffi provides some EPICS CA definitions if CaChannel is falling back to using caffi backend
+  # (not used if CaChannel._ca is available)
+  "caffi",
+  # Send log messages to graylog
+  "graypy",
+  # genie_python will install ipython completers
+  "ipython",
+  # Getting user details from database
+  "mysql-connector-python",
+  # Array support for CA calls
+  "numpy",
+  # EPICS PV access lib
+  "p4p",
+  # Used to find process by name to kill it
+  "psutil",
+  # For linting user scripts on g.load_script()
+  "pylint",
+  # For type-checking user scripts on g.load_script()
+  "pyright",
+  # For setting windows job-object flags
+  "pywin32;platform_system=='Windows'",
+]
+
+[project.optional-dependencies]
+
+# Make plotting an optional dependency as:
+# - It fixes a *specific* matplotlib version
+# - It depends on a couple of heavyweight libs (py4j and tornado) that aren't necessary otherwise
+plot = [
+  # When updating, check plotting works in GUI. Must keep pinned to a specific, tested version.
+  "matplotlib==3.9.2",
+  # Python <-> Java communication, to spawn matplotlib plots in GUI
+  "py4j",
+  # Tornado webserver used by custom backend
+  "tornado",
+]
+
+doc = [
+  "sphinx",
+  "sphinx_rtd_theme",
+  "myst_parser",
+  "sphinx-autobuild",
+]
+
+dev = [
+  "genie_python[plot,doc]",
+  "mock",
+  "parameterized",
+  "pyhamcrest",
+  "pytest",
+  "pytest-cov",
+  "ruff>=0.6",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/isiscomputinggroup/genie"
+"Bug Reports" = "https://github.com/isiscomputinggroup/genie/issues"
+"Source" = "https://github.com/isiscomputinggroup/genie"
+
+[tool.pytest.ini_options]
+testpaths = "tests"
+addopts = "--cov --cov-report=html -vv"
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "if typing.TYPE_CHECKING:",
+  "@abstractmethod",
+]
+
+[tool.coverage.html]
+directory = "coverage_html_report"
+
+[tool.pyright]
+include = ["src", "tests"]
+reportConstantRedefinition = true
+reportDeprecated = true
+reportInconsistentConstructor = true
+reportMissingParameterType = true
+reportMissingTypeArgument = true
+reportUnnecessaryCast = true
+reportUnnecessaryComparison = true
+reportUnnecessaryContains = true
+reportUnnecessaryIsInstance = true
+reportUntypedBaseClass = true
+reportUntypedClassDecorator = true
+reportUntypedFunctionDecorator = true
+
+[tool.setuptools_scm]
+
+[tool.build_sphinx]

ruff.toml

@@ -1,32 +1,8 @@
 # Exclude a variety of commonly ignored directories.
 exclude = [
-    ".bzr",
-    ".direnv",
-    ".eggs",
-    ".git",
-    ".git-rewrite",
-    ".hg",
-    ".ipynb_checkpoints",
-    ".mypy_cache",
-    ".nox",
-    ".pants.d",
-    ".pyenv",
-    ".pytest_cache",
-    ".pytype",
-    ".ruff_cache",
-    ".svn",
-    ".tox",
-    ".venv",
-    ".vscode",
-    "__pypackages__",
-    "_build",
-    "buck-out",
-    "build",
-    "dist",
-    "node_modules",
-    "venv",
-    "uk.ac.stfc.isis.ibex.opis",
+    ".pyi",
     "snmp-mibs",
+    "tests/test_scripts",
 ]
 
 # Set the maximum line length to 100.
@@ -52,7 +28,7 @@ ignore = [
     "ANN401", # explicit ANY type is allowed
 ]
 [lint.per-file-ignores]
-"{**/tests/**,/tests/**,**/*tests.py,tests/**,*tests.py,*test.py,**/*test.py,common_tests/**,**/test_modules**}" = [
+"tests/*" = [
     "N802",
     "D100",
     "D101",
@@ -64,9 +40,3 @@ ignore = [
 [lint.pydocstyle]
 # Use Google-style docstrings.
 convention = "google"
-
-[format]
-quote-style = "double"
-indent-style = "space"
-docstring-code-format = true
-line-ending = "auto"