From fac2591b45283654824832d27595a587d351b3b3 Mon Sep 17 00:00:00 2001 From: Jean Mainguy Date: Mon, 21 Sep 2026 16:29:10 +0200 Subject: [PATCH 1/5] Add a GitHub Actions workflow to build and publish PANORAMA releases to PyPI. (#60) ## Description Add a GitHub Actions workflow to build and publish PANORAMA releases to PyPI. The `panorama` name is already taken on PyPI, so the package cannot be published under this name. We therefore use `panorama-sys`, reflecting PANORAMA's main feature: system detection. The panorama-sys projects have already been created on both PyPI and TestPyPI. ## What changed * Added a GitHub Actions workflow to build and publish the package to PyPI. * Added optional manual publishing through `workflow_dispatch`: * Publish to TestPyPI for testing. * Publish to PyPI when needed. * Releases are automatically published to PyPI when a GitHub release is created. Fixed how version is retrieved: use `distribution("panorama-sys").version` instead of `distribution("panorama").version`. This was call in main and in utils. Refactor in a utils function `get_panorama_version` to hold only once the logic. ## Testing The workflow can be tested manually using `workflow_dispatch` and selecting the appropriate publishing option. ## Documentation Documentation and README updates will be handled in a second PR, once PANORAMA is available on PyPI. This should make it easier to update the installation instructions with the actual PyPI package. ## Additional notes The workflow uses PyPI's trusted publishing mechanism, so no PyPI API token is required. --- .github/workflows/python-publish.yml | 99 ++++++++++++++++++++++++++++ panorama/main.py | 4 +- panorama/utils.py | 11 +++- pyproject.toml | 2 +- 4 files changed, 112 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/python-publish.yml diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml new file mode 100644 index 0000000..806cf59 --- /dev/null +++ b/.github/workflows/python-publish.yml @@ -0,0 +1,99 @@ +# Publish PANORAMA to PyPI +# +# - On a GitHub release: automatically publish to PyPI +# - Manually: optionally publish to TestPyPI and/or PyPI + +name: Publish Python Package + +on: + release: + types: [released] + + workflow_dispatch: + inputs: + publish_test: + description: "Publish to TestPyPI" + required: true + type: boolean + default: false + publish_to_pypi: + description: "Publish to PyPI" + required: true + type: boolean + default: false + +permissions: + contents: read + +jobs: + release-build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.x" + + - name: Build release distributions + run: | + python -m pip install --upgrade build + python -m build + + - name: Upload distributions + uses: actions/upload-artifact@v4 + with: + name: release-dists + path: dist/ + + pypi-publish-test: + runs-on: ubuntu-latest + needs: release-build + if: github.event_name == 'workflow_dispatch' && inputs.publish_test == true + + permissions: + id-token: write + + environment: + name: testpypi + url: https://test.pypi.org/project/panorama-sys/ + steps: + - name: Retrieve release distributions + uses: actions/download-artifact@v4 + with: + name: release-dists + path: dist/ + + - name: Publish to TestPyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + repository-url: https://test.pypi.org/legacy/ + + pypi-publish: + runs-on: ubuntu-latest + needs: release-build + + if: >- + (github.event_name == 'release' && github.event.action == 'released') || + (github.event_name == 'workflow_dispatch' && inputs.publish_to_pypi == true) + + permissions: + id-token: write + + environment: + name: pypi + url: https://pypi.org/project/panorama-sys/ + + steps: + - name: Retrieve release distributions + uses: actions/download-artifact@v4 + with: + name: release-dists + path: dist/ + + - name: Publish to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + diff --git a/panorama/main.py b/panorama/main.py index 6a38fa8..f0c9cdf 100644 --- a/panorama/main.py +++ b/panorama/main.py @@ -23,7 +23,6 @@ ) import argparse -from importlib.metadata import distribution from panorama.alignment.align import launch as align_launcher from panorama.alignment.align import subparser as align_subparser @@ -52,12 +51,13 @@ from panorama.utils import ( RawTextArgumentDefaultsHelpFormatter, add_common_arguments, + get_panorama_version, set_verbosity_level, ) from panorama.workflow.pansystems import launch as pansystems_launcher from panorama.workflow.pansystems import subparser as pansystems_subparser -version = distribution("panorama").version +version = get_panorama_version() opening = r""" ____ ___ _ __ ____ ____ ___ __ ___ ___ / __ \ / | / | / / / __ \ / __ \ / | / |/ / / | diff --git a/panorama/utils.py b/panorama/utils.py index 9a2a3e7..e256820 100644 --- a/panorama/utils.py +++ b/panorama/utils.py @@ -122,7 +122,16 @@ def set_verbosity_level(args: argparse.Namespace) -> None: # log is written in a files. basic condif uses filename logging.basicConfig(filename=args.log, level=level, format=str_format, datefmt=datefmt) logging.getLogger("PANORAMA").debug("Command: " + " ".join([arg for arg in sys.argv])) - logging.getLogger("PANORAMA").debug(f"PANORAMA version: {distribution('panorama').version}") + logging.getLogger("PANORAMA").debug(f"PANORAMA version: {get_panorama_version()}") + + +def get_panorama_version() -> str: + """ + Get the version of the panorama package. + + :return: The version of the panorama package. + """ + return distribution("panorama-sys").version # File managing system diff --git a/pyproject.toml b/pyproject.toml index 09a6e4e..f79db77 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ requires = ["setuptools"] build-backend = "setuptools.build_meta" [project] -name = "PANORAMA" +name = "panorama-sys" authors = [ { name = "Jérôme Arnoux", email = "arnoux.jeromepj@gmail.com" }, From 55f5ec0d7cb4dfc21737877fed796db1595bb342 Mon Sep 17 00:00:00 2001 From: JeanMainguy Date: Wed, 23 Sep 2026 15:34:21 +0200 Subject: [PATCH 2/5] update doc with pipy info --- README.md | 31 ++++++++++++++++++++----------- docs/user/install.md | 15 ++++++++++++++- 2 files changed, 34 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index a0c67d8..b2c3dbe 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ [![GitHub issues](https://img.shields.io/github/issues/labgem/panorama.svg?style=flat-square&maxAge=600)](https://github.com/labgem/panorama/issues) [![Docs](https://img.shields.io/readthedocs/panorama/latest?style=flat-square&maxAge=600)](https://panorama.readthedocs.io) [![Downloads](https://anaconda.org/bioconda/panorama/badges/downloads.svg)](https://bioconda.github.io/recipes/panorama/README.html#download-stats) +[![PyPI version](https://badge.fury.io/py/panorama-sys.svg?cache-control=no-cache)](https://pypi.org/project/panorama-sys/) [![Paper](https://img.shields.io/badge/paper-PLOS%20Computational%20Biology-teal.svg?style=flat-square&maxAge=3600)](https://doi.org/10.1371/journal.pcbi.1013856) [![Citations](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fbadge.dimensions.ai%2Fdetails%2Fdoi%2F10.1371%2Fjournal.pcbi.1013856&search=%3Cdiv%20class%3D%22count%22%3E(%5Cd*)%3C%2Fdiv%3E&replace=%241&style=flat-square&label=citations&cacheSeconds=3600)](https://badge.dimensions.ai/details/doi/10.1371/journal.pcbi.1013856) @@ -23,20 +24,28 @@ software suite. It is designed to perform pangenome comparison at high-throughtu # Quick Installation -PANORAMA is easily installed with [conda](https://docs.conda.io/projects/conda/en/latest/index.html) and -[pip](https://pip.pypa.io/en/stable/). Follow the next step to install panorama. +The recommended installation method is via [Conda](https://docs.conda.io/projects/conda/en/latest/index.html) from the [Bioconda](https://bioconda.github.io/) channel. +A PyPI installation is also available as an alternative when you prefer `pip`. + +## Install with Bioconda ```shell -# 1. Clone the Repository -git clone https://github.com/labgem/PANORAMA.git -cd PANORAMA - -# 2. Create and Configure the Conda Environment -conda create -n panorama -conda config --add channels bioconda -conda config --add channels conda-forge +conda create -n panorama -c conda-forge -c bioconda panorama conda activate panorama -conda env update --file panorama.yml +panorama --version +``` + +## Install with PyPI + +The package published on PyPI is named `panorama-sys`. + +```shell +pip install panorama-sys +panorama --version +``` + +```{warning} +The PyPI release only includes the Python package and Python dependencies. Non-Python system requirements such as MMSeqs2 and geckodriver must be installed separately before using the full feature set. ``` [//]: # (You can find more information on the installation [here](link_read_the_doc)) diff --git a/docs/user/install.md b/docs/user/install.md index c9baf3d..b11ff4a 100644 --- a/docs/user/install.md +++ b/docs/user/install.md @@ -37,10 +37,23 @@ To use a specific python version: conda create -n panorama -c conda-forge -c bioconda panorama python=X.X ``` ---- +### Installation via PyPI + +An alternative install option is the PyPI package, named `panorama-sys`. + +```shell +pip install panorama-sys +panorama --version +``` + +```{warning} +The PyPI package includes only the Python package and Python dependencies. It does not ship non-Python system requirements, such as MMSeqs2, geckodriver, or other OS-level tools that PANORAMA may need. Install those separately with your system package manager or Conda before using the full feature set. +``` ### Installing from source code (GitHub) +This installation method is intended for developers or advanced users. For normal users, we recommend the Bioconda package or the PyPI package. + (with_conda_env)= #### Within a Conda environment From abeec9ec575d13c0c36d5cdbfd24c2fa5b1c4331 Mon Sep 17 00:00:00 2001 From: JeanMainguy Date: Mon, 5 Oct 2026 15:02:26 +0200 Subject: [PATCH 3/5] update install doc --- README.md | 12 +++++------- docs/user/install.md | 5 ++--- 2 files changed, 7 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index b2c3dbe..0ebaa17 100644 --- a/README.md +++ b/README.md @@ -44,9 +44,8 @@ pip install panorama-sys panorama --version ``` -```{warning} -The PyPI release only includes the Python package and Python dependencies. Non-Python system requirements such as MMSeqs2 and geckodriver must be installed separately before using the full feature set. -``` +> [!WARNING] +> The PyPI release only includes the Python package and Python dependencies. Non-Python system requirements such as MMSeqs2 and geckodriver must be installed separately before using the full feature set. Please refer to [Install PANORAMA dependencies](#install-panorama-dependencies) for the required external dependencies. [//]: # (You can find more information on the installation [here](link_read_the_doc)) @@ -66,10 +65,9 @@ In the following we will name this file *pangenomes.tsv* | ... | ... | | PangenomeX | path/to/pangenomeX | -```{note} -We recommend using an absolute path in this file to avoid errors. -You can use the path from your current directory or the path from the input file as a relative path to find pangenomes -``` +> [!NOTE] +> We recommend using an absolute path in this file to avoid errors. +> You can use the path from your current directory or the path from the input file as a relative path to find pangenomes. ## Biological systems detection diff --git a/docs/user/install.md b/docs/user/install.md index b11ff4a..662d6d5 100644 --- a/docs/user/install.md +++ b/docs/user/install.md @@ -46,9 +46,8 @@ pip install panorama-sys panorama --version ``` -```{warning} -The PyPI package includes only the Python package and Python dependencies. It does not ship non-Python system requirements, such as MMSeqs2, geckodriver, or other OS-level tools that PANORAMA may need. Install those separately with your system package manager or Conda before using the full feature set. -``` +> [!WARNING] +> The PyPI package includes only the Python package and Python dependencies. It does not ship non-Python system requirements, such as MMSeqs2, geckodriver, or other OS-level tools that PANORAMA may need. Install those separately with your system package manager or Conda before using the full feature set. See [Install PANORAMA dependencies](#install-panorama-dependencies) for the required setup. ### Installing from source code (GitHub) From d6898b1705989c77cdb5a3b491d2eb32fd4ee368 Mon Sep 17 00:00:00 2001 From: JeanMainguy Date: Mon, 5 Oct 2026 15:07:30 +0200 Subject: [PATCH 4/5] fix link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0ebaa17..f8f77ff 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ panorama --version ``` > [!WARNING] -> The PyPI release only includes the Python package and Python dependencies. Non-Python system requirements such as MMSeqs2 and geckodriver must be installed separately before using the full feature set. Please refer to [Install PANORAMA dependencies](#install-panorama-dependencies) for the required external dependencies. +> The PyPI release only includes the Python package and Python dependencies. Non-Python system requirements such as MMSeqs2 and geckodriver must be installed separately before using the full feature set. Please refer to the [installation documentation](https://panorama.readthedocs.io/latest/user/install.html#install-panorama-dependencies) for the required external dependencies. [//]: # (You can find more information on the installation [here](link_read_the_doc)) From 63893b9edf436f48ac2f23e97d48c2e11e0c1fc6 Mon Sep 17 00:00:00 2001 From: JeanMainguy Date: Mon, 5 Oct 2026 15:12:40 +0200 Subject: [PATCH 5/5] fix watning in install doc --- docs/user/install.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/user/install.md b/docs/user/install.md index 662d6d5..b72c235 100644 --- a/docs/user/install.md +++ b/docs/user/install.md @@ -46,8 +46,9 @@ pip install panorama-sys panorama --version ``` -> [!WARNING] -> The PyPI package includes only the Python package and Python dependencies. It does not ship non-Python system requirements, such as MMSeqs2, geckodriver, or other OS-level tools that PANORAMA may need. Install those separately with your system package manager or Conda before using the full feature set. See [Install PANORAMA dependencies](#install-panorama-dependencies) for the required setup. +```{warning} +The PyPI package includes only the Python package and Python dependencies. It does not ship non-Python system requirements, such as MMSeqs2 and geckodriver. Install those separately with your system package manager or Conda before using the full feature set. See [Install PANORAMA dependencies](#install-panorama-dependencies) for the required setup. +``` ### Installing from source code (GitHub)