gwpy 4.0.0rc2__tar.gz

gwpy-4.0.0rc2/.gitattributes

@@ -0,0 +1 @@
+gwpy/_version.py export-subst

gwpy-4.0.0rc2/.github/copilot-instructions.md

@@ -0,0 +1,94 @@
+# GWpy
+
+GWpy is a Python library toolkit for gravitational-wave astrophysics.
+See the `README.md` file for basic information and the `docs/` folder for
+user and developer documentation.
+
+## Tech stack
+
+-   **Programming Language**: Python 3.10+ (development uses Python 3.12)
+
+-   **Platform support**: Linux, macOS, Windows
+
+-   **Versioning**: `setuptools_scm`
+
+-   **Packaging**: `pyproject.toml` installable with `pip`/`uv` with extra dependency-groups
+    for non-Python dependencies installable with `conda`.
+
+-   **Testing**: `pytest` (config in `pyproject.toml`)
+
+-   **Linting/formatting**: `ruff` (config in `pyproject.toml`), plus `mypy` settings
+
+-   **Documentation**: Sphinx sources under `docs/` and `examples/`
+
+-   **CLI entry points**: Defined in `pyproject.toml` (e.g., `gwpy-plot`)
+
+## Repository layout (high level)
+
+-   `gwpy/` — main package.
+    Each subfolder (e.g., `gwpy/astro/`) is a subpackage with its own
+    `__init__.py` and `tests/` folder.
+
+-   `docs/` — user/developer documentation (Sphinx).
+
+-   `examples/` — runnable examples and a lightweight integration test (`test_examples.py`).
+
+-   `tests` are colocated inside package subfolders (e.g. `gwpy/astro/tests/`).
+
+-   The `worktrees/` directory may be present to hold multiple git worktrees -
+    ignore it during repo-wide scans and analysis.
+
+## Coding guidelines
+
+-   **Style: follow PEP 8 with opinionated `ruff` rules in `pyproject.toml`.
+    The project runs `ruff` in CI and locally via `python -m ruff .`.
+    All features should uses the latest syntax supported by the minimum Python
+    version.
+
+-   **Type checking**: all code should include comprehensive type annotations following
+    PEP 563, 585, and 604.
+    `mypy` is configured to check typing.
+
+-   **Documentation**: all public classes, methods, and functions should include
+    docstrings following the NumPy/SciPy docstring standard.
+    Use Sphinx-compatible reStructuredText markup and follow SemBR (https://sembr.org/)
+    where appropriate.
+    Docstrings should include type hints even if the function is already annotated.
+
+-   **Tests**: use `pytest`. New code must include unit tests.
+    Run tests locally via:
+
+    ```shell
+    uv pip install . --group dev
+    uv run pytest gwpy/ examples/
+    ```
+
+    -   Keep tests small and focused; prefer `pytest.mark.parametrize` or separate tests
+        over large tests with multiple independent assertions.
+        Use mocking where appropriate to avoid slow or flaky tests.
+
+    -   Tests that require optional dependencies should be marked using `@pytest.mark.requires`.
+
+## Commands & quick-start (recommended)
+
+-   Preferred quick dev setup (isolated environment):
+
+    Use `uv` to manage virtual environments (https://pypa.github.io/uv/).
+
+    # create & activate venv
+    uv venv --seed 
+    . .venv/bin/activate
+
+    # install editable package with dev extras (per `CONTRIBUTING.md`)
+    uv pip install . --group dev
+
+-   Run tests (fast subset):
+
+    python -m pytest gwpy/ -q
+
+-   Run ruff locally:
+
+    python -m ruff .
+
+-   If you need reproducible, CI-like envs, prefer conda + conda-forge binaries
+    (especially when `lalsuite` or other heavy scientific packages are required).

gwpy-4.0.0rc2/.gitignore

@@ -0,0 +1,56 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+eggs/
+/gwpy/_version.py
+lib/
+lib64/
+parts/
+sdist/
+var/
+venv/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+Portfile
+.coverage
+.eggs/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Sphinx documentation
+# -- see /docs/.gitignore
+
+# OS/editor files
+*.swp
+.DS_Store
+.idea
+.vscode
+
+# Examples output
+/examples/*.png
+/examples/*/*.png
+
+# Patches
+/*.patch
+
+# py.test cache dir
+/.cache
+/.pytest_cache/
+
+# dqsegdb files
+__dqsegdb*.json
+__segments*.json

gwpy-4.0.0rc2/.gitlab/ci/compatibility.yml

@@ -0,0 +1,82 @@
+# -- Check dependency compatibility
+#
+# These jobs check that the minimum versions are well specified,
+# and that this project is compatible with the new pre-relase
+# versions of anything we can find.
+#
+
+spec:
+  inputs:
+    stage:
+      default: test
+      description: "Pipeline stage in which to add jobs"
+      type: string
+    pytest_options:
+      default: ""
+      description: "Extra options to pass to pytest"
+      type: string
+    minimum_python_version:
+      default: "3.11"
+      description: "Python version for minimum dependency compatibility check"
+      type: string
+    experimental_python_version:
+      default: "3.12"
+      description: "Python version for experimental dependency compatibility check"
+      type: string
+
+---
+
+include:
+  - local: .gitlab/ci/rules.yml
+
+  # configure minimum dependency compatibility job
+  - local: .gitlab/ci/test-job.yml
+    inputs:
+      stage: $[[ inputs.stage ]]
+      job_name: "compat_minimum"
+      install_target: "."
+      pip_cmd: "uv pip"
+      pip_options: "--group test --resolution lowest-direct"
+      pytest_options: $[[ inputs.pytest_options ]]
+
+  # configure experimental dependency compatibility job
+  - local: .gitlab/ci/test-job.yml
+    inputs:
+      stage: $[[ inputs.stage ]]
+      job_name: "compat_experimental"
+      install_target: "."
+      pip_cmd: "uv pip"
+      pip_options: "--group dev --upgrade --resolution highest --prerelease allow"
+      pytest_options: $[[ inputs.pytest_options ]]
+
+.compat:
+  needs: []
+  rules:
+    - if: '$CI_COMMIT_MESSAGE =~ /\[skip compat\]/'
+      when: never
+    - !reference [.rules_nightly, rules]
+    - !reference [.rules_full_test, rules]
+  before_script:
+    - uv venv --python ${PYTHON_VERSION}
+    - source .venv/bin/activate
+
+# test against the minimum specified requirements
+compat_minimum:
+  extends:
+    - .compat_minimum
+    - .compat
+  image: "ghcr.io/astral-sh/uv:python$[[ inputs.minimum_python_version ]]-bookworm"
+  variables:
+    PYTHON_VERSION: $[[ inputs.minimum_python_version ]]
+  artifacts:
+    paths:
+      - .coverage*
+
+# test against latest/pre-release versions
+compat_experimental:
+  extends:
+    - .compat_experimental
+    - .compat
+  image: "ghcr.io/astral-sh/uv:python$[[ inputs.experimental_python_version ]]-bookworm"
+  variables:
+    PYTHON_VERSION: $[[ inputs.experimental_python_version ]]

gwpy-4.0.0rc2/.gitlab/ci/coverage.yml

@@ -0,0 +1,32 @@
+# -- Python test coverage measurements
+
+spec:
+  inputs:
+
+---
+
+include:
+  - local: .gitlab/ci/rules.yml
+
+coverage:
+  stage: .post
+  image: python
+  rules: !reference [.rules_full_test, rules]
+  script:
+    # install coverage (with toml parsing extra)
+    - python -m pip install coverage[toml]
+    # combine coverage files from other jobs
+    - python -m coverage combine .coverage*
+    # write an HTML report
+    - python -m coverage html -d htmlcov
+    # print a report (for the record)
+    - python -m coverage report -m
+  allow_failure: true
+  artifacts:
+    name: htmlcov
+    expose_as: Coverage report
+    paths:
+      - htmlcov/index.html
+      - htmlcov
+  # report coverage here, now that we have all of the information
+  coverage: '/^TOTAL\s+.*\s+(\d+\.?\d*)%/'

gwpy-4.0.0rc2/.gitlab/ci/init-creds.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+#
+# Initialise credentials for jobs
+#
+
+if [ "${KERBEROS_KEYTAB}" = "" ]; then
+echo -e "\x1B[94mNo KERBEROS_KEYTAB configured, skipping credential init.\x1B[0m"
+exit 0
+fi
+
+# install tooling
+conda install -c conda-forge -q -y ciecplib krb5
+
+# unpack keytab
+export KRB5_KTNAME="${CI_PROJECT_DIR}/.keytab"
+echo "${KERBEROS_KEYTAB}" | base64 -d > ${KRB5_KTNAME}
+chmod 0600 "${KRB5_KTNAME}"
+
+# find principal
+export KRB5_PRINCIPAL="$(klist -k ${KRB5_KTNAME} | tail -n 1 | awk '{print $2}')"
+
+# get Kerberos TGT
+kinit "${KRB5_PRINCIPAL}" -k -t "${KRB5_KTNAME}"
+klist
+
+# get LIGO.ORG X.509
+ecp-get-cert -i login.ligo.org --kerberos
+ecp-cert-info

gwpy-4.0.0rc2/.gitlab/ci/platforms.yml

@@ -0,0 +1,44 @@
+spec:
+  inputs:
+
+---
+
+.linux:
+  rules:
+    - if: '$CI_COMMIT_MESSAGE =~ /\[skip linux\]/'
+      when: never
+  tags:
+    - saas-linux-medium-amd64
+
+.macos:
+  rules:
+    # Only run macOS jobs inside the GWpy namespace where
+    # macOS runners are available
+    - if: '$CI_PROJECT_ROOT_NAMESPACE != "gwpy"'
+      when: never
+    - if: '$CI_COMMIT_MESSAGE =~ /\[skip macos\]/'
+      when: never
+  tags:
+    - saas-macos-medium-m1
+  image: macos-15-xcode-16
+  retry:
+    # retry all windows jobs up to 2 times on failure, they are flaky
+    max: 2
+    when: always
+
+.windows:
+  rules:
+    - if: '$CI_COMMIT_MESSAGE =~ /\[skip windows\]/'
+      when: never
+  variables:
+    # windows gitlab runners don't support symbolic links, so we can't
+    # run the tests that rely upon them
+    PYTEST_ADDOPTS: "-k 'not table\\\\rate and not table\\\\tiles'"
+    # pytest-xdist doesn't auto-detect the number of CPUs sometimes
+    PYTEST_XDIST_AUTO_NUM_WORKERS: "2"
+  tags:
+    - saas-windows-medium-amd64
+  retry:
+    # retry all windows jobs up to 2 times on failure, they are flaky
+    max: 2
+    when: always

gwpy-4.0.0rc2/.gitlab/ci/python-base.yml

@@ -0,0 +1,31 @@
+# Common elements for Python components
+
+spec:
+  inputs:
+    cache_dir:
+      default: ".cache/pip"
+      description: "The path to cache to (relative to CI_PROJECT_DIR)"
+    image:
+      default: "python"
+      description: "The default image to use for jobs"
+    job_prefix:
+      default: ".python"
+      description: "Prefix to apply to all templates"
+
+---
+
+$[[ inputs.job_prefix ]]_image:
+  image: $[[ inputs.image ]]
+
+$[[ inputs.job_prefix ]]_cache:
+  variables:
+    PIP_CACHE_DIR: "${CI_PROJECT_DIR}/$[[ inputs.cache_dir ]]"
+  cache:
+    key: "pip-${CI_JOB_NAME_SLUG}"
+    paths:
+      - $[[ inputs.cache_dir ]]
+
+$[[ inputs.job_prefix ]]_base:
+  extends:
+    - $[[ inputs.job_prefix ]]_image
+    - $[[ inputs.job_prefix ]]_cache

gwpy-4.0.0rc2/.gitlab/ci/python-dist.yml

@@ -0,0 +1,45 @@
+# -- Build Python project distributions
+
+spec:
+  inputs:
+    stage:
+      default: build
+      description: "Pipeline stage in which to add jobs"
+      type: string
+
+---
+
+include:
+  - local: .gitlab/ci/rules.yml
+
+build:
+  rules: !reference [.rules_build, rules]
+  needs: []
+  stage: $[[ inputs.stage ]]
+  image: ghcr.io/astral-sh/uv:alpine
+  variables:
+    # get the full history for setuptools-scm
+    GIT_DEPTH: 0
+    # debug setuptools-scm
+    SETUPTOOLS_SCM_DEBUG: 1
+  before_script:
+    # need git for setuptools-scm
+    - apk add --no-cache git
+  script:
+    - uv venv
+    - uv pip install build
+    - source .venv/bin/activate
+    # if running a default branch push pipeline, strip the +g<HASH> suffix
+    # from the version to give something that test.pypi.org will accept
+    - |
+      if [ "${CI_COMMIT_TAG}" = "" ] && [ "${CI_PIPELINE_SOURCE}" = "push" ] && [ "${CI_COMMIT_REF_PROTECTED}" = "true" ]; then
+        export SETUPTOOLS_SCM_OVERRIDES_FOR_GWPY="{local_scheme='no-local-version'}";
+      fi
+    # generate the distributions
+    - python -m build . -o .
+    - python -m tarfile --list *.tar.*
+    - python -m zipfile --list *.whl
+  artifacts:
+    paths:
+      - "*.tar.*"
+      - "*.whl"

gwpy-4.0.0rc2/.gitlab/ci/qa.yml

@@ -0,0 +1,143 @@
+# -- Quality Assurance jobs
+
+spec:
+  inputs:
+    stage:
+      default: test
+      description: "Pipeline stage in which to add jobs"
+      type: string
+    project_dir:
+      default: "."
+      description: "Project directory to scan"
+      type: string
+    requirements:
+      default: ""
+      description: "Extra requirements to install with pip"
+      type: string
+    ruff_options:
+      default: ""
+      description: "Extra options to pass to ruff check"
+      type: string
+    mypy_options:
+      default: ""
+      description: "Extra options to pass to mypy"
+      type: string
+    python_version:
+      default: "3.13"
+      description: "Python version to use for testing"
+      type: string
+    minimum_python_version:
+      default: "3.11"
+      description: "Python version for minimum dependency compatibility check"
+      type: string
+
+---
+
+include:
+  - component: gitlab.com/components/dependency-scanning/main@~latest
+    inputs:
+      stage: $[[ inputs.stage ]]
+      job_name: "dependency-scanning"
+  - component: gitlab.com/components/sast/sast@~latest
+    inputs:
+      stage: $[[ inputs.stage ]]
+      run_advanced_sast: true
+    rules:
+      - if: '$GITLAB_FEATURES =~ /\bsast_advanced\b/'
+  - component: gitlab.com/components/sast/sast@~latest
+    inputs:
+      stage: $[[ inputs.stage ]]
+      run_advanced_sast: false
+    rules:
+      - if: '$GITLAB_FEATURES !~ /\bsast_advanced\b/'
+  - local: .gitlab/ci/rules.yml
+  - local: .gitlab/ci/python-base.yml
+
+.qa:
+  extends: .rules_qa_security
+  stage: $[[ inputs.stage ]]
+  needs: []
+
+gitlab-advanced-sast:
+  needs: !reference [.qa, needs]
+  rules:
+    # skip if we just can't run advanced sast
+    - if: '$GITLAB_FEATURES !~ /\bsast_advanced\b/'
+      when: never
+    - !reference [.qa, rules]
+
+semgrep-sast:
+  needs: !reference [.qa, needs]
+  rules:
+    # skip if we can run advanced sast
+    - if: '$GITLAB_FEATURES =~ /\bsast_advanced\b/'
+      when: never
+    - !reference [.qa, rules]
+
+ruff:
+  extends: .qa
+  image: ghcr.io/astral-sh/ruff:alpine
+  script:
+    - ruff check
+          $[[ inputs.project_dir ]]
+          $[[ inputs.ruff_options ]]
+          --exit-zero
+    - ruff check
+          $[[ inputs.project_dir ]]
+          $[[ inputs.ruff_options ]]
+          --exit-zero
+          --output-format gitlab
+          --output-file gl-ruff.json
+  artifacts:
+    reports:
+      codequality: gl-ruff.json
+
+ty:
+  extends: .qa
+  image: ghcr.io/astral-sh/uv:debian
+  variables:
+    UV_MANAGED_PYTHON: 1
+  script:
+    # Install the project
+    - uv venv --python $[[ inputs.python_version ]]
+    - uv pip install -e . --group dev
+    # Run ty and format for gitlab
+    - uvx ty check
+          $[[ inputs.project_dir ]]
+          --exit-zero
+          --output-format gitlab
+          > gl-ty.json
+    # Run ty and print to console
+    - uvx ty check
+          $[[ inputs.project_dir ]]
+          --exit-zero
+  artifacts:
+    reports:
+      codequality: gl-ty.json
+
+rstcheck:
+  extends:
+    - .python_base
+    - .qa
+  image: ghcr.io/astral-sh/uv:debian
+  script:
+    - uvx --with rstcheck[sphinx] python .gitlab/ci/rstcheck.py > gl-rstcheck.json
+    - uvx python -m json.tool gl-rstcheck.json
+  artifacts:
+    reports:
+      codequality: gl-rstcheck.json
+
+uv.lock:
+  image: ghcr.io/astral-sh/uv:debian
+  extends:
+    - .qa
+  script:
+    # Generate uv.lock file with minimum dependencies
+    - uv venv --python $[[ inputs.minimum_python_version ]]
+    - uv lock --resolution lowest-direct
+  artifacts:
+    paths:
+      - uv.lock
+
+dependency-scanning:
+  needs: ["uv.lock"]

gwpy-4.0.0rc2/.gitlab/ci/rstcheck.py

@@ -0,0 +1,113 @@
+"""Run rstcheck and report output for codeclimate."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    TypedDict,
+)
+
+from rstcheck_core.config import RstcheckConfig
+from rstcheck_core.runner import RstcheckMainRunner
+
+if TYPE_CHECKING:
+    from typing import Literal
+
+    from rstcheck_core.types import LintError
+
+    Severity = Literal["info", "minor", "major", "critical", "blocker"]
+
+MESSAGE_RE = re.compile(
+    r"\((?P<severity>[A-Z]+)/[0-9]+\)(\s+)(?P<message>.*)",
+)
+SEVERITY: dict[str, Severity] = {
+    "ERROR": "major",
+    "SEVERE": "major",
+    "INFO": "info",
+    "WARNING": "minor",
+}
+
+
+class CodeQualityLocation(TypedDict):
+    """Location parameter in a `CodeQualityItem`."""
+
+    path: str
+    lines: dict[str, int]
+
+
+class CodeQualityItem(TypedDict):
+    """Gitlab Code Quality item.
+
+    See <https://docs.gitlab.com/ci/testing/code_quality/#code-quality-report-format>.
+    """
+
+    check_name: str
+    description: str
+    fingerprint: str
+    location: CodeQualityLocation
+    severity: Severity
+
+
+def rstcheck(
+    config_path: Path,
+    check_paths: list[str | Path],
+    *,
+    recursive: bool = True,
+) -> RstcheckMainRunner:
+    """Create, execute, and return an `rstcheck_core.runner.RstcheckMainRunner`."""
+    config = RstcheckConfig(
+        config_path=config_path,
+        recursive=recursive,
+    )
+    runner = RstcheckMainRunner(
+        check_paths=list(map(Path, check_paths)),
+        rstcheck_config=config,
+    )
+    runner.check()
+    return runner
+
+
+def codeclimate_item(item: LintError) -> CodeQualityItem:
+    """Construct a codeclimate item for this rstcheck lint error."""
+    fingerprint = hashlib.sha1(
+        "".join(map(str, item.values())).encode("utf-8"),
+        usedforsecurity=False,
+    ).hexdigest()
+    match = MESSAGE_RE.match(item["message"]).groupdict()
+    return CodeQualityItem({
+        "check_name": match["message"],
+        "description": match["message"],
+        "fingerprint": fingerprint,
+        "location": {
+            "path": str(item["source_origin"]),
+            "lines": {
+                "begin": (lineno := int(item["line_number"])),
+                "end": lineno,
+            },
+        },
+        "severity": SEVERITY.get(match["severity"], "info"),
+    })
+
+
+def codeclimate(items: list[LintError]) -> list[CodeQualityItem]:
+    """Parse a list of errors for codeclimate."""
+    return [codeclimate_item(item) for item in items]
+
+
+def main() -> None:
+    """Run `rstcheck` and print a codeclimate JSON report."""
+    results = rstcheck(
+        Path("pyproject.toml"),
+        ["docs"],
+    )
+    issues = codeclimate(results.errors)
+    json.dump(issues, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()