Add an optional xrootd extra and use it in CI (#117)

* Add optional xrootd extra

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix Ruff failure in package test

* Restore xrootd server in CI

* Require XRootD 6 in CI

* Relax CI xrootd server requirement

* Avoid pip xrootd in CI test jobs

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: lobis

.github/CONTRIBUTING.md

@@ -32,7 +32,7 @@ You can set up a development environment by running:
 ```bash
 python3 -m venv .venv
 source ./.venv/bin/activate
-pip install -v -e .[dev]
+pip install -v -e .[dev,xrootd]
 ```
 
 If you have the
@@ -41,7 +41,7 @@ can instead do:
 
 ```bash
 py -m venv .venv
-py -m install -v -e .[dev]
+py -m install -v -e .[dev,xrootd]
 ```
 
 # Post setup

.github/workflows/ci.yml

@@ -48,11 +48,10 @@ jobs:
           python-version: ${{ matrix.python-version }}
           miniforge-version: latest
           activate-environment: fsspec
-      - name: Install build environment
-        run: |
-          mamba install -c conda-forge "xrootd>=5.4.3"
+      - name: Install XRootD server
+        run: mamba install -c conda-forge xrootd
       - name: Install package
-        run: python -m pip install .[test]
+        run: python -m pip install ".[test]"
       - name: Test package
         run: |
           python -m pytest -vv tests --reruns 3 --reruns-delay 5 --only-rerun "(?i)OSError|FileNotFoundError|timeout|expired|connection|socket"
@@ -64,8 +63,8 @@ jobs:
           git clone https://github.com/scikit-hep/uproot5.git uproot
           git -C uproot checkout tags/v${UPROOT_VERSION}
           (cd uproot && python -m pip install . --group test)
-          # Install xrootd-fsspec again because it may have been overwritten by uproot
-          python -m pip install .[test]
+          # Reinstall fsspec-xrootd after uproot without replacing the conda xrootd runtime.
+          python -m pip install ".[test]"
           python -m pytest -vv -k "xrootd" uproot/tests --reruns 10 --reruns-delay 30 --only-rerun "(?i)OSError|FileNotFoundError|timeout|expired|connection|socket"
 
   pass:

.github/workflows/docs.yml

@@ -10,9 +10,6 @@ jobs:
   docs:
     name: Build and deploy docs
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        shell: bash -l {0}
 
     steps:
       - uses: actions/checkout@v6
@@ -23,17 +20,8 @@ jobs:
         with:
           python-version: "3.14"
 
-      - name: Set up Conda
-        uses: conda-incubator/setup-miniconda@v3
-        with:
-          python-version: "3.14"
-          miniforge-version: latest
-          activate-environment: fsspec
-      - name: Install build environment
-        run: |
-          mamba install -c conda-forge "xrootd>=5.4.3"
       - name: Install package
-        run: python -m pip install -e .[docs]
+        run: python -m pip install -e ".[docs,xrootd]"
 
       - name: Build documentation
         run: |

README.md

@@ -5,17 +5,17 @@ An XRootD implementation for fsspec.
 ## Install
 
 ```bash
-pip install fsspec-xrootd
+pip install "fsspec-xrootd[xrootd]"
 ```
 
 Supports Python 3.9 and newer.
 
 ## Purpose
 
 To allow fsspec to use XRootD accessible storage systems. Install fsspec-xrootd
-alongside fsspec and have easy access to files stored on XRootD servers. Once
-installed, fsspec will be able to work with urls with the 'root' protocol. Only
-tested with Linux at this time.
+with the optional `xrootd` extra alongside fsspec and have easy access to files
+stored on XRootD servers. Once installed, fsspec will be able to work with urls
+with the 'root' protocol. Only tested with Linux at this time.
 
 ## Documentation
 

docs/index.rst

@@ -9,12 +9,15 @@ Install
 
 .. code:: bash
 
-    pip install fsspec-xrootd
+    pip install "fsspec-xrootd[xrootd]"
 
 Purpose
 -------
 
-To allow fsspec to use XRootD accessible storage systems. Install fsspec-xrootd alongside fsspec and have easy access to files stored on XRootD serevrs. Once installed, fsspec will be able to work with urls with the 'root' protocol. Only tested with Linux at this time.
+To allow fsspec to use XRootD accessible storage systems. Install
+``fsspec-xrootd[xrootd]`` alongside fsspec and have easy access to files stored
+on XRootD servers. Once installed, fsspec will be able to work with urls with
+the ``root`` protocol. Only tested with Linux at this time.
 
 .. toctree::
    :maxdepth: 3

noxfile.py

@@ -24,7 +24,7 @@ def tests(session: nox.Session) -> None:
     """
     Run the unit and regular tests.
     """
-    session.install(".[test]")
+    session.install(".[test,xrootd]")
     session.run("pytest", *session.posargs)
 
 
@@ -34,7 +34,7 @@ def docs(session: nox.Session) -> None:
     Build the docs. Pass "serve" to serve.
     """
 
-    session.install(".[docs]")
+    session.install(".[docs,xrootd]")
     session.chdir("docs")
     session.run("sphinx-build", "-M", "html", ".", "_build")
 

pyproject.toml

@@ -50,6 +50,7 @@ docs = [
     "sphinx-copybutton",
 ]
 test = ["pytest>=6", "pytest-rerunfailures", "pytest-timeout"]
+xrootd = ["xrootd>=6.0.0"]
 
 [tool.setuptools]
 include-package-data = true

src/fsspec_xrootd/__init__.py

@@ -7,7 +7,32 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Any
+
 from ._version import version as __version__
-from .xrootd import XRootDFile, XRootDFileSystem
+
+if TYPE_CHECKING:
+    from .xrootd import XRootDFile, XRootDFileSystem
 
 __all__ = ("__version__", "XRootDFileSystem", "XRootDFile")
+
+
+def __getattr__(name: str) -> Any:
+    if name not in {"XRootDFile", "XRootDFileSystem"}:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    try:
+        from .xrootd import XRootDFile, XRootDFileSystem
+    except ModuleNotFoundError as exc:
+        if exc.name == "XRootD":
+            raise ModuleNotFoundError(
+                "The 'xrootd' package is required to use fsspec-xrootd. "
+                'Install it with `pip install "fsspec-xrootd[xrootd]"`.'
+            ) from exc
+        raise
+
+    globals().update({
+        "XRootDFile": XRootDFile,
+        "XRootDFileSystem": XRootDFileSystem,
+    })
+    return globals()[name]

tests/conftest.py

@@ -35,6 +35,8 @@ def localserver(tmpdir_factory):
         fout.write("all.export /Folder\n")
         fout.write(f"oss.localroot {srvdir}\n")
     xrdexe = shutil.which("xrootd")
+    if xrdexe is None:
+        pytest.skip("xrootd executable is required for basic I/O integration tests")
     proc = subprocess.Popen([xrdexe, "-p", str(XROOTD_PORT), "-c", cfgfile])
     time.sleep(2)  # give it some startup
     yield "root://localhost//Folder", tempPath

tests/test_package.py

@@ -1,7 +1,32 @@
 from __future__ import annotations
 
+import builtins
+import importlib
+import sys
+
+import pytest
+
 import fsspec_xrootd as m
 
 
 def test_version():
     assert m.__version__
+
+
+def test_import_without_xrootd(monkeypatch):
+    original_import = builtins.__import__
+
+    def raising_import(name, *args, **kwargs):
+        if name == "XRootD":
+            raise ModuleNotFoundError("No module named 'XRootD'", name="XRootD")
+        return original_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", raising_import)
+    for module_name in ("fsspec_xrootd", "fsspec_xrootd.xrootd", "XRootD"):
+        sys.modules.pop(module_name, None)
+
+    module = importlib.import_module("fsspec_xrootd")
+
+    assert module.__version__
+    with pytest.raises(ModuleNotFoundError, match="Install it with"):
+        _ = module.XRootDFileSystem