Merge pull request #17 from ssl-hep/main

Update branch from main

Author: ArturU043

.github/workflows/pypi.yml

@@ -0,0 +1,127 @@
+name: Publish package to PyPi
+
+on:
+  release:
+    types: [released, prereleased]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Install python-build and twine
+      run: |
+        uv pip install --system build twine
+        uv pip list --system
+
+    - name: Set env
+      run: echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV
+
+    - name: Update Version
+      run: |
+        sed -i 's/^version\s*=\s*".*"/version = "${{ env.RELEASE_VERSION }}"/' pyproject.toml
+        sed -i '/__version__/ s/__version__\s*=.*/__version__ = "${{ env.RELEASE_VERSION }}"/' servicex_analysis_utils/__init__.py
+
+
+    - name: Build a sdist and wheel
+      run: |
+        python -m build .
+
+    - name: Check dist
+      run: twine check --strict dist/*
+
+    - name: List contents of sdist
+      run: python -m tarfile --list dist/servicex_analysis_utils-*.tar.gz
+
+    - name: List contents of wheel
+      run: python -m zipfile --list dist/servicex_analysis_utils-*.whl
+
+    - name: Upload an artifact of dist
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist-gha-artifact
+        path: dist
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest  
+
+    permissions:
+      id-token: write  # required to push with trusted-pypi-token
+    
+    steps:
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Download artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: dist-gha-artifact
+        path: dist
+
+    - name: Publish distribution 
+      uses: pypa/gh-action-pypi-publish@v1.12.3
+      with:
+        print-hash: true
+  
+  commit-version-bump:
+    needs: 
+      - build 
+      - publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # required to push with GITHUB_TOKEN
+
+    steps:
+    - name: Checkout main branch
+      uses: actions/checkout@v4
+      with:
+        ref: main 
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Set env
+      run: echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV
+
+    - name: Update version to commit
+      run: |
+        sed -i 's/^version\s*=\s*".*"/version = "${{ env.RELEASE_VERSION }}"/' pyproject.toml
+        sed -i '/__version__/ s/__version__\s*=.*/__version__ = "${{ env.RELEASE_VERSION }}"/' servicex_analysis_utils/__init__.py
+
+
+    - name: Commit version change
+      run: |
+        git config --local user.name "github-actions[bot]"
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git add ./pyproject.toml servicex_analysis_utils/__init__.py
+
+        # Check if there are changes to commit
+        if ! git diff --cached --quiet; then
+          echo "Changes detected, committing..."
+          git commit -m "Update version to ${{ env.RELEASE_VERSION }}" --no-verify
+        else
+          echo "No changes to commit"
+        fi
+
+    - name: Push commit to main
+      # GITHUB_TOKEN is automatically provided
+      run: |
+        git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+        git push origin main

.readthedocs.yml

@@ -0,0 +1,33 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+#   # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  builder: html
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

@@ -1,12 +1,15 @@
 # ServiceX analysis utils
-This repository provides analysis tools to be used with the [ServiceX Client](https://github.com/ssl-hep/ServiceX_frontend/tree/master)
+This repository hosts tools that depend on the [ServiceX Client](https://github.com/ssl-hep/ServiceX_frontend/tree/master). These tools facilitate `ServiceX`'s general usage and offer specific features that replace parts of an analyser workflow.
 
 ### To install 
 ```
 pip install servicex-analysis-utils
 ```
+#### Requirements
+This package depends requires a `servicex.yml` configuration file granting access to one endpoint with a deployed ServiceX backend.
 
-##### This package contains the to_awk() function:
+### This package contains: 
+#### `to_awk()`:
 ```
 Load an awkward array from the deliver() output with uproot or uproot.dask.
 
@@ -22,5 +25,24 @@ Returns:
     dict: keys are sample names and values are awkward arrays, uproot generator objects or dask-awkward arrays.
 ```
 
+
+#### `get-structure()`:
+
+```
+    Creates and sends the ServiceX request from user inputed datasets to retrieve file stucture.
+    Calls print_structure_from_str() to dump the structure in a user-friendly format
+
+    Parameters:
+      datasets (dict,str,[str]): The datasets from which to print the file structures.
+                                 A name can be given as the key of each dataset in a dictionary  
+      kwargs : Arguments to be propagated to print_structure_from_str, e.g filter_branch
+```
+
+Function can be called from the command line, e.g: 
+
+```
+$ servicex-get-structure "mc23_13TeV:some-dataset-rucio-id" --filter_branch "truth"
+```
+
 ## Documentation
-The different functions are documented in TBD 
+The different functions are documented in [readthedcos](https://servicex-analysis-utils.readthedocs.io/en/latest/file_introspecting.html) 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_build/doctrees/environment.pickle

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: ca3626de684797951ef03443c45ac66f
+tags: 645f666f9bcd5a90fca523b33c5a78b7