Stuff

.appveyor.yml

@@ -3,8 +3,10 @@
 # to create a "native" platform experience, using as few cross-platform
 # helper tools as possible.
 #
-# On Linux/Mac a virtualenv is used for testing. The effective virtual env
-# is available under ~/VENV.
+# On all platforms `hatch` is used for testing, and managing the test
+# environment. This yields a near-identical environment/behavior across
+# platforms and Python versions. The main difference between running tests
+# on Appveyor and locally should be the service setup (e.g., SSH, HTTPBIN).
 #
 # All workers support remote login. Login details are shown at the top of each
 # CI run log.
@@ -40,10 +42,6 @@
 #     Desktop (a required .txt extension will be added automatically). The session
 #     will run until the file is removed (or 60 min have passed)
 #
-#   - in a terminal execute, for example, `C:\datalad_debug.bat 39` to set up the
-#     environment to debug in a Python 3.8 session (should generally match the
-#     respective CI run configuration).
-
 
 # do not make repository clone cheap: interfers with VCS-based version determination
 shallow_clone: false
@@ -52,21 +50,13 @@ shallow_clone: false
 build: off
 
 environment:
-  ## unless indicated otherwise, we test datalad_next
-  #DTS: datalad_next
-  ## SSH testing is done via a side-loaded container that provides a POSIX/SSHable
-  ## server environment
-  #DATALAD_TESTS_DOCKER_SSHD_SECKEY_DOWNLOADURL: https://ci.appveyor.com/api/projects/mih/datalad-ci-docker-containers/artifacts/recipes/sshd/id_rsa?job=sshd
-  #DATALAD_TESTS_DOCKER_SSHD_DOWNLOADURL: https://ci.appveyor.com/api/projects/mih/datalad-ci-docker-containers/artifacts/sshd.dockerimg.gz?job=sshd
-  #DATALAD_TESTS_DOCKER_SSHD_CONTAINER_NAME: test-sshd
-  ## std SSH container runtime setup
-  #DATALAD_TESTS_SERVER_SSH_HOST: datalad-test-sshd
-  #DATALAD_TESTS_SERVER_SSH_PORT: 2222
-  #DATALAD_TESTS_SERVER_SSH_LOGIN: sshuser
-  #DATALAD_TESTS_SERVER_SSH_SECKEY: /home/appveyor/.ssh/datalad_tests_id_rsa
-  #DATALAD_TESTS_SERVER_SSH_PATH: /usr/local/apache2/htdocs
-  #DATALAD_TESTS_SERVER_LOCALPATH: /home/appveyor/DLTMP/sshdroot
-
+  # place coverage files to a known location regardless of where a test run
+  # is happening
+  COVERAGE_ROOT: /home/appveyor/DLTMP
+  # we pin hatch's data file to make it easy to cache it
+  HATCH_DATA_DIR: /home/appveyor/hatch-data-dir
+  # same for pip
+  PIP_CACHE: /home/appveyor/.cache/pip
   # Do not use `image` as a matrix dimension, to have fine-grained control over
   # what tests run on which platform
   # The ID variable had no impact, but sorts first in the CI run overview
@@ -77,59 +67,36 @@ environment:
 
     # Ubuntu core tests
     - job_name: test-linux
-      APPVEYOR_BUILD_WORKER_IMAGE: Ubuntu2004
-      PY: 3.10
-      # datalad-annex git remote needs something after git-annex_8.20211x
+      APPVEYOR_BUILD_WORKER_IMAGE: Ubuntu2204
+      PY: 3.9
       INSTALL_GITANNEX: git-annex -m snapshot
-      CODECOV_BINARY: https://uploader.codecov.io/latest/linux/codecov
-      # 'test_publish_target_url' relies on a strict `localhost` target
-      # setup, we don't have that
-      #KEYWORDS: not test_publish_target_url
-      #DEPLOY_HTTPBIN_IMAGE: yes
-      #INSTALL_SYSPKGS:
-      #DATALAD_TESTS_SSH: 1
 
     # same as 'test-linux', but TMPDIR is on a crippled filesystem, causing
     # most, if not all test datasets to be created on that filesystem
     - job_name: test-linux-crippled
-      APPVEYOR_BUILD_WORKER_IMAGE: Ubuntu2004
-      PY: 3.10
+      APPVEYOR_BUILD_WORKER_IMAGE: Ubuntu2204
+      PY: 3.9
       # datalad-annex git remote needs something after git-annex_8.20211x
       INSTALL_GITANNEX: git-annex -m snapshot
-      CODECOV_BINARY: https://uploader.codecov.io/latest/linux/codecov
-      #DEPLOY_HTTPBIN_IMAGE: yes
-      #INSTALL_SYSPKGS:
-      #DATALAD_TESTS_SSH: 1
 
     # Windows core tests
     - job_name: test-win
-      # ~35 min
       APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
       # Python version specification is non-standard on windows
-      PY: 39-x64
+      PY: 3.9
       INSTALL_GITANNEX: git-annex -m datalad/packages
-      #DATALAD_TESTS_SSH: 1
-      #DATALAD_TESTS_SERVER_SSH_SECKEY: C:\DLTMP\datalad_tests_id_rsa
-      #DATALAD_TESTS_SERVER_LOCALPATH: C:\DLTMP\sshdroot
+      COVERAGE_ROOT: C:\DLTMP
+      HATCH_DATA_DIR: C:\hatch-data-dir
+      PIP_CACHE: C:\Users\appveyor\AppData\Local\pip\Cache
 
     # MacOS core tests
     - job_name: test-mac
-      APPVEYOR_BUILD_WORKER_IMAGE: macos-monterey
-      PY: 3.8
+      APPVEYOR_BUILD_WORKER_IMAGE: macos-sonoma
+      PY: 3.12
       INSTALL_GITANNEX: git-annex
-      DATALAD_LOCATIONS_SOCKETS: /Users/appveyor/DLTMP/sockets
-      CODECOV_BINARY: https://uploader.codecov.io/latest/macos/codecov
-      #DATALAD_TESTS_SSH: 1
-      # no docker on Mac, we log into self
-      # 'test_publish_target_url' relies git-annex being installed on the
-      # target, but we only have that in a personal env
-      #KEYWORDS: not test_publish_target_url
-      #DATALAD_TESTS_SERVER_SSH_HOST: localhost
-      #DATALAD_TESTS_SERVER_SSH_PORT: 22
-      #DATALAD_TESTS_SERVER_SSH_LOGIN: appveyor
-      #DATALAD_TESTS_SERVER_SSH_SECKEY: /Users/appveyor/.ssh/datalad_tests_id_rsa
-      #DATALAD_TESTS_SERVER_SSH_PATH: /Users/appveyor/DLTMP/riaroot
-      #DATALAD_TESTS_SERVER_LOCALPATH: /Users/appveyor/DLTMP/riaroot
+      COVERAGE_ROOT: /Users/appveyor/DLTMP
+      HATCH_DATA_DIR: /Users/appveyor/hatch-data-dir
+      PIP_CACHE: /Users/appveyor/.cache/pip
 
 
 # only run the CI if there are code or tooling changes
@@ -163,12 +130,9 @@ for:
 
     cache:
       # pip cache
-      - /home/appveyor/.cache/pip -> .appveyor.yml
-      # cache the docker image for httpbin. in 2023 it has not changed in
-      # 4 years, not worth pulling each time
-      # given the low change frequency we also do not invalidate the cache
-      # but would do manually, if needed
-      #- /home/appveyor/cache/httpbin.dockerimg
+      - "${PIP_CACHE} -> .appveyor.yml"
+      # hatch-managed python versions
+      - "${HATCH_DATA_DIR}/env/virtual/.pythons -> pyproject.toml"
 
     # init cannot use any components from the repo, because it runs prior to
     # cloning it
@@ -189,13 +153,9 @@ for:
       - "[ \"x$PY\" != x ]"
       # Missing system software
       - tools/appveyor/install-syspkgs $INSTALL_SYSPKGS
-      # If a particular Python version is requested, use env setup (using the
-      # appveyor provided environments/installation). Note, these are broken
-      # on the ubuntu images
-      # https://help.appveyor.com/discussions/problems/28217-appveyor-ubunu-image-with-python3-lzma-module
-      # Otherwise create a virtualenv using the default Python 3, to enable uniform
-      # use of python/pip executables below
-      - "[ \"x$PY\" != x ] && . ${HOME}/venv${PY}/bin/activate || virtualenv -p 3 ${HOME}/dlvenv && . ${HOME}/dlvenv/bin/activate; ln -s \"$VIRTUAL_ENV\" \"${HOME}/VENV\""
+      # activate Python env solely to get `python` to become available consistently
+      # hatch will manage the actual testing environment
+      - '. ${HOME}/venv${PY}/bin/activate'
       - tools/appveyor/install-git-annex ${INSTALL_GITANNEX}
       # enable the git-annex provisioned by the installer
       - "[ -f ${HOME}/dlinstaller_env.sh ] && . ${HOME}/dlinstaller_env.sh || true"
@@ -225,13 +185,12 @@ for:
           export TMPDIR=/crippledfs
         fi
       - echo TMPDIR=$TMPDIR
-      - hatch test --cover --doctest-modules
+      - 'hatch run tests.py${PY}:run-cov --doctest-modules --durations 10'
 
     after_test:
-      - python -m coverage xml
-      - "curl -Os $CODECOV_BINARY"
-      - chmod +x codecov
-      - ./codecov
+      - 'hatch run tests.py${PY}:cov-combine'
+      - 'hatch run tests.py${PY}:coverage xml'
+      - 'codecovcli --auto-load-params-from AppVeyor upload-process -n "appveyor-$APPVEYOR_JOB_NAME" --disable-search -f coverage.xml'
 
     on_finish:
       # conditionally block the exit of a CI run for direct debugging
@@ -246,7 +205,9 @@ for:
         - job_name: test-win
     cache:
       # pip cache
-      - C:\Users\appveyor\AppData\Local\pip\Cache -> .appveyor.yml
+      - "%PIP_CACHE% -> .appveyor.yml"
+      # hatch-managed python versions
+      - "%HATCH_DATA_DIR%\\env\\virtual\\.pythons -> pyproject.toml"
 
     # init cannot use any components from the repo, because it runs prior to
     # cloning it
@@ -288,12 +249,12 @@ for:
       #- tools\appveyor\verify-ssh-access
 
     test_script:
-      - hatch test --cover
+      - cmd: 'hatch run tests.py%PY%:run-cov --doctest-modules --durations 10'
 
     after_test:
-      - cmd: python -m coverage xml
-      - cmd: curl -fsSL -o codecov.exe "https://uploader.codecov.io/latest/windows/codecov.exe"
-      - cmd: .\codecov.exe -f "coverage.xml"
+      - cmd: 'hatch run tests.py%PY%:cov-combine'
+      - cmd: 'hatch run tests.py%PY%:coverage xml'
+      - cmd: 'codecovcli --auto-load-params-from AppVeyor upload-process -n "appveyor-%APPVEYOR_JOB_NAME%" --disable-search -f coverage.xml'
 
     on_finish:
       # conditionally block the exit of a CI run for direct debugging
@@ -304,10 +265,7 @@ for:
 # ALL TEST RUNS
 #
 build_script:
-  # install the pieces that we need in this CI run
-  - python -m pip install hatch coverage
-  #- python -m pip install -r requirements-devel.txt
-  #- python -m pip install .
+  - python -m pip install hatch codecov-cli
 
 after_build:
   # Identity setup

.gitignore

@@ -3,3 +3,4 @@ dist/
 docs/generated
 docs/_build
 *.swp
+datasalad/_version.py

CHANGELOG.md

@@ -1,3 +1,17 @@
+# v0.3.0 (2024-09-21)
+
+## Documentation
+
+- fix typos [[fd70937b]](https://github.com/datalad/datasalad/commit/fd70937b)
+- update project classifiers [[2c983daa]](https://github.com/datalad/datasalad/commit/2c983daa)
+- Contributing guide:
+  - describe new developer conveniences [[0a45fd46]](https://github.com/datalad/datasalad/commit/0a45fd46)
+  - snipped on releasing a new version [[b82c58c3]](https://github.com/datalad/datasalad/commit/b82c58c3)
+
+## New features
+
+- provide package version at standard location [[a17eb7c0]](https://github.com/datalad/datasalad/commit/a17eb7c0)
+
 # v0.2.1 (2024-07-14)
 
 ## Bug Fixes

CONTRIBUTING.md

@@ -8,15 +8,32 @@
 
 ## Developer cheat sheet
 
-[Hatch](https://hatch.pypa.io) is used for packaging and development tasks.
-Here are a few pointers. For full detail, see the hatch docs.
+[Hatch](https://hatch.pypa.io) is used as a convenience solution for packaging and development tasks.
+Hatch takes care of managing dependencies and environments, including the Python interpreter itself.
+If not installed yet, installing via [pipx](https://github.com/pypa/pipx) is recommended (`pipx install hatch`).
 
-### Run the tests
+Below is a list of some provided convenience commands.
+An accurate overview of provided convenience scripts can be obtained by running: `hatch env show`.
+All command setup can be found in `pyproject.toml`, and given alternatively managed dependencies, all commands can also be used without `hatch`.
+
+### Run the tests (with coverage reporting)
 
 ```
 hatch test [--cover]
 ```
 
+There is also a setup for matrix test runs, covering all current Python versions:
+
+```
+hatch run tests:run [<select tests>]
+```
+
+This can also be used to run tests for a specific Python version only:
+
+```
+hatch run tests.py3.10:run [<select tests>]
+```
+
 ### Build the HTML documentation (under `docs/_build/html`)
 
 ```
@@ -31,26 +48,28 @@ hatch run docs:clean
 hatch run types:check
 ```
 
-### Check the `datasalad` version
+### Check commit messages for compliance with [Conventional Commits](https://www.conventionalcommits.org)
+
+```
+hatch run cz:check-commits
+```
 
-`hatch` determines the version from the VCS tags. This can help check that
-things are correct without having to build a release.
+### Show would-be auto-generated changelog for the next release
 
 ```
-hatch version
+hatch run cz:show-changelog
 ```
 
 ### Create a new release
 
 ```
-cz bump --changelog
+hatch run cz:bump-version
 ```
 
-The new version is determined automatically from the nature of the commits
-made since the last release. A changelog is generated and committed.
+The new version is determined automatically from the nature of the (conventional) commits made since the last release.
+A changelog is generated and committed.
 
-In cases where the generated changelog needs to be edited afterwards (typos,
-unnecessary complexity, etc.), the created version tag needs to be advanced.
+In cases where the generated changelog needs to be edited afterwards (typos, unnecessary complexity, etc.), the created version tag needs to be advanced.
 
 
 ### Build a new source package and wheel
@@ -65,6 +84,7 @@ hatch build
 hatch publish
 ```
 
+
 ## When should I consider a contribution to `datasalad`?
 
 This project's main purpose is to be a core library for DataLad.

README.md

@@ -99,5 +99,5 @@ Developers are advised to never reuse any components with names starting with
 ## Contributing
 
 Contributions to this library are welcome! Please see the [contributing
-guidelines](CONTRIBUTING.md) for details on scope on styles of potential
-contributions.
+guidelines](https://github.com/datalad/datasalad/blob/main/CONTRIBUTING.md) for
+details on scope and style of potential contributions.

datasalad/__init__.py

@@ -0,0 +1,5 @@
+from datasalad._version import __version__
+
+__all__ = [
+    '__version__',
+]

datasalad/runners/__init__.py

@@ -1,4 +1,4 @@
-"""High-level utilties for execution of subprocesses
+"""High-level utilities for execution of subprocesses
 
 This module provides relevant components for subprocess execution.
 Execution errors are communicated with the

docs/index.rst

@@ -85,7 +85,7 @@ Why ``datasalad``?
 
 This is a base library for DataLad, hence the name ``Data-sa-Lad``.  The ``sa``
 might stand for "support assemblage", or "smart assets".  More importantly, the
-library is a mixture of more-or-less standalone utilties that "make up the
+library is a mixture of more-or-less standalone utilities that "make up the
 salad".
 
 After ~10 years of developing DataLad, these utilities have been factored out