isoperiod 1.2.1__tar.gz

isoperiod-1.2.1/.editorconfig

@@ -0,0 +1,33 @@
+# https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{html,css,js,json,sh,yml,yaml}]
+indent_size = 2
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+# Ignore binary or generated files
+[*.{png,jpg,gif,ico,woff,woff2,ttf,eot,svg,pdf}]
+charset = unset
+end_of_line = unset
+indent_style = unset
+indent_size = unset
+trim_trailing_whitespace = unset
+insert_final_newline = unset
+max_line_length = unset
+
+[*.{diff,patch}]
+trim_trailing_whitespace = false

isoperiod-1.2.1/.githooks/pre-commit

@@ -0,0 +1,47 @@
+#!/bin/sh
+#
+# Pre-commit hook: runs ruff format and lint checks via uv.
+# Requires uv on PATH: https://docs.astral.sh/uv/getting-started/installation/
+#
+# Installed automatically by post-generation hook via:
+#   git config core.hooksPath .githooks
+#
+# To install manually in an existing clone:
+#   make install-hooks
+
+# Redirect output to stderr.
+exec 1>&2
+
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+format_err=0
+check_err=0
+err=0
+
+echo 'Running "uv run ruff format --check"'
+uv run ruff format --check
+
+if [ "$?" -eq 1 ]; then
+    format_err=1
+    err=1
+fi
+
+echo 'Running "uv run ruff check"'
+uv run ruff check
+
+if [ "$?" -eq 1 ]; then
+    check_err=1
+    err=1
+fi
+
+if [ "${format_err}" -eq 1 ] ; then
+    echo "${RED}Run \"ruff format\" before committing${NC}"
+fi
+
+if [ "${check_err}" -eq 1 ] ; then
+    echo "${RED}Correct ruff errors before committing${NC}"
+fi
+
+if [ "${err}" -eq 1 ] ; then
+    exit 1
+fi

isoperiod-1.2.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug Report
+description: Something isn't working as expected.
+title: "BUG: "
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: What happened? What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to trigger the bug.
+      placeholder: |
+        1. Install with `uv pip install isoperiod`
+        2. Run `...`
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: "isoperiod version"
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.13"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Logs, tracebacks, screenshots, or anything else that helps.
+    validations:
+      required: false

isoperiod-1.2.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

isoperiod-1.2.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature Request
+description: Suggest something new.
+title: "FEAT: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the feature
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: What problem does this solve? What's the use case?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+    validations:
+      required: false

isoperiod-1.2.1/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      all-dependencies:
+        patterns:
+          - "*"

isoperiod-1.2.1/.github/pull_request_template.md

@@ -0,0 +1,9 @@
+## Issue ticket number and link
+
+## Overview
+
+<!-- 1-3 sentences of problem this PR addresses -->
+
+## Main changes
+
+<!-- List of the core changes to point reviewers towards -->

isoperiod-1.2.1/.github/workflows/pipeline.yml

@@ -0,0 +1,152 @@
+name: Pipeline
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - develop
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read
+
+  pages: write
+  id-token: write
+
+
+jobs:
+
+  test-python:
+    uses: NERC-CEH/dri-cicd/.github/workflows/test-python.yml@main
+    with:
+      use_uv: true
+      use_pyright: true
+      coverage_threshold: 90
+
+
+  build-docs:
+    uses: NERC-CEH/dri-cicd/.github/workflows/build-docs.yml@main
+    with:
+      use_uv: true
+      pages_artifact_name: pages-artifact
+
+  deploy-docs:
+    needs: [build-docs]
+    if: github.ref == 'refs/heads/main'
+    uses: NERC-CEH/dri-cicd/.github/workflows/deploy-docs.yml@main
+    with:
+      pages_artifact_name: pages-artifact
+
+
+  release-ready:
+    if: github.event_name == 'pull_request' && github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Check version bump and changelog
+        run: |
+          BASE_VER=$(git show origin/main:pyproject.toml | grep '^version' | sed 's/.*"\(.*\)"/\1/')
+          NEW_VER=$(grep '^version' pyproject.toml | sed 's/.*"\(.*\)"/\1/')
+
+          if [ "$BASE_VER" = "$NEW_VER" ]; then
+            echo "ERROR: merges to main require a version bump (current: $NEW_VER)"
+            exit 1
+          fi
+
+          echo "Version bumped: $BASE_VER -> $NEW_VER"
+
+          CHANGELOG="CHANGELOG/${NEW_VER}.md"
+
+          if [ ! -f "$CHANGELOG" ]; then
+            echo "ERROR: $CHANGELOG not found"
+            exit 1
+          fi
+
+          if grep -q "<!-- Add release notes here -->" "$CHANGELOG"; then
+            echo "ERROR: $CHANGELOG still contains the stub placeholder"
+            exit 1
+          fi
+
+          LINES=$(tail -n +2 "$CHANGELOG" | grep -vc '^$')
+          if [ "$LINES" -eq 0 ]; then
+            echo "ERROR: $CHANGELOG has no content beyond the heading"
+            exit 1
+          fi
+
+          echo "Changelog looks good"
+
+  release:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [test-python]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Configure git identity
+        run: |
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+
+      - name: Release
+        id: release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION=$(grep '^version' pyproject.toml | sed 's/.*"\(.*\)"/\1/')
+          if git ls-remote --tags origin | grep -q "refs/tags/v$VERSION$"; then
+            echo "Tag v$VERSION already exists - skipping release"
+            exit 0
+          fi
+          make release
+          echo "released=true" >> "$GITHUB_OUTPUT"
+
+  build-dist:
+    needs: [release]
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: false
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: [build-dist]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/isoperiod
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

isoperiod-1.2.1/.gitignore

@@ -0,0 +1,167 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+.benchmarks/
+benchmark*.svg
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+# Per-member API pages generated by sphinx.ext.autosummary at build time.
+docs/source/api/_api/
+# Using the plot directive from code in src/examples will copy outputs to docs/src/examples.  No need to commit this.
+docs/src
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VSCode
+.vscode

isoperiod-1.2.1/CHANGELOG/1.0.0.md

@@ -0,0 +1,38 @@
+# 1.0.0
+
+The first stable, versioned public release of `isoperiod`. Developed within UKCEH's FDRI programme, the library
+provides ISO 8601 period and duration arithmetic for environmental timeseries data, making the grid a timeseries is
+measured on (i.e. its sampling resolution and periodicity) an object that can be compared and validated.
+
+## Features
+
+### Core
+
+- **`Period`** - the central object representing a repeating period that splits the timeline into consecutive, numbered
+intervals, covering both fixed-length (microsecond through to multi-day) and calendar-aligned (monthly, annual)
+periods.
+- Built from an ISO 8601 duration string (`"PT15M"`, `"P1D"`, `"P1Y"`), from a named unit (`Period.of_days(1)`), or
+from a `datetime.timedelta`.
+- Immutable, hashable and sortable, so periods work as dictionary keys, in sets, and in order of length.
+
+### Offsets and origins
+
+- **Offsets** shift every interval boundary off its natural position, written as `<duration>+<offset>` - an
+extension of the ISO 8601 duration format - so a hydrological day (`"P1D+T9H"`) or a water year (`"P1Y+9MT9H"`)
+becomes a value that can be stored and passed around.
+- **Origins** pin the grid to a chosen datetime, with the `"2024-01-01/P7D"` form.
+
+### Intervals and ordinals
+
+- Every interval on the timeline carries an integer **ordinal**
+- `ordinal()` and `datetime()` map between timestamps and intervals, and are inverses of one another.
+- `floor()` snaps a timestamp to its interval start, `interval()` gives that interval's half-open bounds, and
+`range()` walks every interval overlapping a window of time.
+
+### Comparison and alignment
+
+- `is_aligned()` checks that a timestamp sits exactly on a period boundary - the check to run on incoming data
+before trusting its claimed resolution.
+- `is_subperiod_of()` reports whether one period's intervals nest cleanly inside another's, and `count()` gives how
+many fit where that number is constant.
+- `is_epoch_agnostic()` identifies periods that split the timeline the same way whatever epoch is used.

isoperiod-1.2.1/CHANGELOG/1.1.0.md

@@ -0,0 +1,48 @@
+# 1.1.0
+
+A minor release covering how a `Period` renders itself. `str()` now represents periods that carry an origin,
+and `repr()` reports a time zone accurately.
+
+The documentation was also reworked so that every example is executed and its real output published alongside it.
+
+## Changed
+
+### `str()` format
+
+A period built with an origin previously rendered as its duration and derived offset, which discarded the origin and so
+could not be parsed back. It now renders in the `<origin>/<duration>` form it was built from:
+
+|                                            | 1.0.0       | 1.1.0                         |
+|--------------------------------------------|-------------|-------------------------------|
+| `str(Period.of("2024-01-01/P7D"))`         | `"P7D+1D"`  | `"2024-01-01/P7D"`            |
+| `str(Period.of("1883-01-01T09:00/P1D"))`   | `"P1D+T9H"` | `"1883-01-01T09:00:00/P1D"`   |
+| `str(Period.of("2024-02-29T09:30/PT15M"))` | `"PT15M"`   | `"2024-02-29T09:30:00/PT15M"` |
+
+`Period.of(str(period)) == period` now holds for every period.
+
+### `repr()` is the string form plus the time zone
+
+`repr()` now adds nothing to `str()` beyond the time zone, and only when there is one:
+
+|                | 1.0.0             | 1.1.0            |
+|----------------|-------------------|------------------|
+| naive          | `PT15M[]`         | `PT15M`          |
+| UTC            | `PT1H[Z]`         | `PT1H[Z]`        |
+| fixed offset   | `PT1H[+05:30]`    | `PT1H[+05:30]`   |
+| with an origin | `P7D+1D[]-105555` | `2024-01-01/P7D` |
+
+## Fixed
+
+- **A named time zone reported the offset it used in the nineteenth century.** The offset was sampled at
+  `datetime.min`, so `repr()` of a period at `Europe/London` gave `P1D[-00:01:15]`, its Local Mean Time before standard
+  time was adopted. A `zoneinfo.ZoneInfo` is now identified by its key: `P1D[Europe/London]`.
+- **Two different periods could share a `repr()`.** A `tzinfo` whose `utcoffset()` returns `None` - which
+  `datetime` permits - rendered as `PT1S[]`, identical to a naive period. Such a zone is now named after its class, so
+  no two unequal periods render alike.
+
+## Documentation
+
+- Every example in the user guide is now executed when the documentation is built, and the output shown beneath it is
+  what that code produced rather than something written by hand. The code lives in `docs/source/examples/`, is linted
+  and type checked with the rest of the project, and is run by the test suite.
+- Docstring examples use standard `>>>` doctests, collected by pytest, so a changed return value fails the build.

isoperiod-1.2.1/CHANGELOG/1.2.0.md

@@ -0,0 +1,23 @@
+# 1.2.0
+
+A minor release adding two properties for rendering a `Period` in English words.
+
+## Features
+
+### `verbose` and `descriptive`
+
+`Period.verbose` spells a period's duration out in full, appending its offset or origin in brackets. `descriptive`
+names the period's frequency with a common word where one exists (e.g. "Daily", "Yearly"), falling back to the plain
+duration otherwise, and recognises two grids by name: the UK Water Day (`P1D+T9H`) and the UK Water Year (`P1Y+9MT9H`).
+
+Examples:
+
+|                               | `verbose`                    | `descriptive`                |
+|-------------------------------|------------------------------|------------------------------|
+| `Period.of_years(1)`          | `"1 year"`                   | `"Yearly"`                   |
+| `Period.of_minutes(15)`       | `"15 minutes"`               | `"15 minutes"`               |
+| `Period.of("P1D+T9H")`        | `"1 day (+9 hours)"`         | `"Daily (UK Water Day)"`     |
+| `Period.of("2024-01-01/P7D")` | `"7 days (from 2024-01-01)"` | `"Weekly (from 2024-01-01)"` |
+
+Both are for display only: neither is accepted by `Period.of` or any other constructor, and `str()` remains the
+parseable form.

isoperiod-1.2.1/CHANGELOG/1.2.1.md

@@ -0,0 +1,30 @@
+# 1.2.1
+
+A patch release with no changes to the library. It is the first release published to [PyPI](https://pypi.org/project/isoperiod/).
+
+## Installation
+
+isoperiod can now be installed from PyPI:
+
+```bash
+pip install isoperiod
+```
+
+or with uv:
+
+```bash
+uv add isoperiod
+```
+
+Installing from the git repository still works, but is no longer needed.
+
+## Packaging
+
+- Each release merged to `main` is now built and published to PyPI automatically, using trusted publishing.
+- Package metadata now includes keywords and classifiers for the supported Python versions (3.12 and 3.13) and for
+  the bundled type hints (`Typing :: Typed`).
+- The README links to `LICENSE` and `CITATION.cff` are now full URLs, so they work on the PyPI project page.
+
+## Documentation
+
+- The installation guide now installs from PyPI instead of the git repository.