Skip to content

Commit

Permalink
Fizxmike readme patch plus release action (#30)
Browse files Browse the repository at this point in the history 
Clarifying and simplifying quick start. Added direct links to Jupyter Notebooks. Added tooling recommendations.

Added workflow to build, upload to (test) pypi then create release.

Bumped version num, added pywin32 dependency
  • Loading branch information
@fizxmike
fizxmike authored Jul 20, 2024
1 parent 60cee56 commit 9668514
Show file tree
Hide file tree
Showing 4 changed files with 135 additions and 19 deletions.
52 changes: 52 additions & 0 deletions .github/workflows/release-test.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
name: Release
on:
pull_request:
# push:
# tags:
# - 'v[0-9]+.[0-9]+.[0-9]+' # like v1.0.0
jobs:
build-dist:
name: Package PyESAPI and Release
runs-on: windows-latest
steps:
- name: Checkout repo
uses: actions/checkout@v4
- name: Update pip
run: py -m pip install --upgrade pip
- name: Build package
run: |
py -m pip install --upgrade build
py -m build
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: dist
path: dist
- name: Create Release
uses: softprops/action-gh-release@v2
with:
name: PyESAPI ${{ github.ref_name }}
token: ${{ secrets.GITHUB_TOKEN }}
draft: true
files: dist/*
body: |
This is the official `${{ github.ref_name }}` release of the PyESAPI for use on Eclipse TBOX or VIC environment for Eclipse versions 15.1 and up.
pypi-publish:
name: Upload release to PyPI
runs-on: ubuntu-latest
needs: build-dist
environment:
name: pypi
url: https://test.pypi.org/p/PyESAPI
permissions:
id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
steps:
- name: Download All Artifacts
uses: actions/download-artifact@v4
with:
name: dist
path: dist
- name: Publish package distributions to TestPyPI
uses: pypa/gh-action-pypi-publish@release/v1
with:
repository-url: https://test.pypi.org/legacy/
49 changes: 49 additions & 0 deletions .github/workflows/release.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
name: Release
on:
push:
tags:
- 'v[0-9]+.[0-9]+.[0-9]+' # like v1.0.0
jobs:
build-dist:
name: Package PyESAPI and Release
runs-on: windows-latest
steps:
- name: Checkout repo
uses: actions/checkout@v4
- name: Update pip
run: py -m pip install --upgrade pip
- name: Build package
run: |
py -m pip install --upgrade build
py -m build
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: dist
path: dist
- name: Create Release
uses: softprops/action-gh-release@v2
with:
name: PyESAPI ${{ github.ref_name }}
token: ${{ secrets.GITHUB_TOKEN }}
draft: true
files: dist/*
body: |
This is the official `${{ github.ref_name }}` release of the PyESAPI for use on Eclipse TBOX or VIC environment for Eclipse versions 15.1 and up.
pypi-publish:
name: Upload release to PyPI
runs-on: ubuntu-latest
needs: build-dist
environment:
name: pypi
url: https://pypi.org/p/pyesapi
permissions:
id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
steps:
- name: Download All Artifacts
uses: actions/download-artifact@v4
with:
name: dist
path: dist
- name: Publish package distributions to TestPyPI
uses: pypa/gh-action-pypi-publish@release/v1
42 changes: 27 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,47 @@
# PyESAPI
"Pie-Sappy" for research use only.
"Pi-e-Sappy" for research use only.

A passion project to help accelerate breakthroughs in medical physics research by bringing the power of Python into the Varian API ecosystem.
PyESAPI combined with Jupyter Notebook gives you a "command line to Eclipse" allowing you to rapidly prototype you ESAPI scripts or research ideas.

## Quickstart (updated June 16th 2023)
## Quick Start (updated July 17th 2024)

* Access your Eclipse 15.5 (or later) TBOX desktop
* Install Python 3.10 or higher from: https://www.python.org/downloads/
* Optionally install google chrome or chromium browser (for better Jupyter Notebook experience) and set it as your default browser
* Install Python 3.10 or later from: https://www.python.org/downloads/
* Be sure to check the option to "add python.exe to PATH" (unless you are already managing multiple versions of Python)
* Note: If you use an older version of Python, your milage may vary.
* Launch "Command Prompt" by searching in Windows menu
* Navigate to a directory where you would like to store your first PyEsapi project using the `cd` command
* (optional) Create and activate a python virtual environment in this location using `python -m venv venv`
* Navigate to a directory where you would like to store your first PyESAPI project using the `cd` command
* In the prompt, execute the commands:
* `pip install https://api.github.com/repos/VarianAPIs/PyESAPI/tarball`
* `pip install jupyter`
* This
* Then execute the command `jupyter notebook`
* Create a new notebook and see below for examples (be sure not to select "root" kernel).
* Create a new notebook and see below for examples (if you are using a python virtual be sure not to select "root" kernel).

## Examples
* [Developer Workshop 2018](examples/DeveloperWorkshop2018/README.md)
### Jupyter Notebooks (from Developer Workshop 2018)
* [Getting Started](http://nbviewer.jupyter.org/github/VarianAPIs/PyESAPI/blob/master/examples/DeveloperWorkshop2018/GettingStarted.ipynb)
* [Data Mining](http://nbviewer.jupyter.org/github/VarianAPIs/PyESAPI/blob/master/examples/DeveloperWorkshop2018/DataMining.ipynb)
* [10xResearch](http://nbviewer.jupyter.org/github/VarianAPIs/PyESAPI/blob/master/examples/DeveloperWorkshop2018/10xResearch.ipynb)
* Stand-alone python script: [standalone.py](examples/standalone.py)

## Known issues
PyESAPI is not compatible with vscode-jupyter plugin which uses multithreading. ESAPI only allows for single-thread access to objects and functions.

## Upgrading
* Inside your project directory, execute `pip install https://api.github.com/repos/VarianAPIs/PyESAPI/tarball --upgrade`
* This will check and upgrade PyESAPI if a newer version is available

# Development
For those wishing to contribute to PyESAPI
## Recommended tooling:
Now that you've had a chance to explore the capabilities of PyESAPI, it's time to get more organized. Below are some recommendations on platforms and software to develop with.
* Varian Innovation Center Eclipse environment (or local TBOX)
* VisualStudio Code (lightweight IDE)
* Google Chrome or Microsoft Edge set as default browser (for better Jupyter Notebook experience)
* Git or GitHub Desktop (code repository and open source collaboration)

# Development Notes
For those wishing to contribute to PyESAPI or use PyESAPI with pre-released local builds of Eclipse.

## Custom ESAPI DLL path
Set custom ESAPI_PATH (to DLLs) before import (bypasses production directory path search)
Expand All @@ -37,13 +52,10 @@ import pyesapi
# ...
```

## Stub Gen
To create lintable code and enable code completion (in Visual Studio Code at least) we generate python stubs for ESAPI libs...
## Stub Gen (experimental/under construction)
To create lintable code and enable code completion (in Visual Studio Code at least) we can generate python stubs for ESAPI libs using IronPython...
1. [Download](https://ironpython.net/download/) and install IronPython (2.7.9 tested to work) in default location (C:\Program Files\IronPython 2.7\ipy.exe).
1. Load ironpython-stubs submodule `git submodule update --init` (ironstubs)
1. Move to stubgen folder `cd stubgen`
1. Execute script `stubgen.ps1` (if you hit a Pdb prompt, type continue)
1. Commit updates to stubs folder

## TODOs

11 changes: 7 additions & 4 deletions setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,19 @@

setup(
name='pyesapi',
version='0.2.3',
description='Python interface to Eclipse Scripting API',
author='Michael Folkerts, Varian Medical Systems',
version='0.2.4',
description='A customized Python interface to Eclipse Scripting API',
long_description='Leverages the pythonnet project to interface with dotnet CLI to launch a stand-alone instance of ESAPI runtime. Helper functions and classes have been added to return numpy arrays and manage collections (of IEnumerable).',
author='Michael M. Folkerts',
url='https://github.com/VarianAPIs/PyESAPI',
author_email='Michael.Folkerts@varian.com',
license='MIT',
packages=find_packages(),
python_requires=">=3.7, <4", # see up to date active releases here: https://www.python.org/downloads/
install_requires=[
'numpy',
'scipy',
'pythonnet', # v2.3.0 tested to work with python 3.6
'pythonnet',
'pynetdicom'
],
)

0 comments on commit 9668514

Please sign in to comment.