minimindslab-datetime-span 0.1.0__tar.gz

minimindslab_datetime_span-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MiniMindsLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

minimindslab_datetime_span-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: minimindslab-datetime-span
+Version: 0.1.0
+Summary: Parse, normalize, and compare simple UTC datetime spans with deterministic formatting.
+Author: MiniMindsLab
+License: MIT
+Keywords: datetime,timespan,utc,iso8601,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MiniMindsLab DateTime Span
+
+`minimindslab-datetime-span` is a tiny, pure-Python utility for parsing, validating, formatting, and comparing UTC datetime spans.
+
+## Features
+
+- Parse UTC ISO-8601 datetime strings (`Z` or `+00:00`).
+- Model spans with inclusive/exclusive boundaries.
+- Deterministic canonical formatting.
+- Compare spans for overlap, containment, and adjacency.
+- CLI that reads from a file or stdin and prints canonicalized spans.
+
+## Span Format
+
+Library and CLI accept bracketed span lines:
+
+- `[START,END]` inclusive start and end
+- `(START,END)` exclusive start and end
+- `[START,END)` inclusive start, exclusive end
+- `(START,END]` exclusive start, inclusive end
+
+Datetimes must be UTC and ISO-like (e.g. `2024-01-02T03:04:05Z`).
+
+Canonical output uses second precision and `Z`, e.g.:
+
+`[2024-01-02T03:04:05Z,2024-01-02T04:04:05Z)`
+
+## CLI
+
+```bash
+# From a file
+miniminds-datetime-span --file spans.txt
+
+# From stdin
+printf '[2024-01-01T00:00:00Z,2024-01-01T01:00:00Z)\n' | miniminds-datetime-span
+```
+
+Each non-empty, non-comment line (`# ...`) is parsed and canonicalized.

minimindslab_datetime_span-0.1.0/README.md

@@ -0,0 +1,38 @@
+# MiniMindsLab DateTime Span
+
+`minimindslab-datetime-span` is a tiny, pure-Python utility for parsing, validating, formatting, and comparing UTC datetime spans.
+
+## Features
+
+- Parse UTC ISO-8601 datetime strings (`Z` or `+00:00`).
+- Model spans with inclusive/exclusive boundaries.
+- Deterministic canonical formatting.
+- Compare spans for overlap, containment, and adjacency.
+- CLI that reads from a file or stdin and prints canonicalized spans.
+
+## Span Format
+
+Library and CLI accept bracketed span lines:
+
+- `[START,END]` inclusive start and end
+- `(START,END)` exclusive start and end
+- `[START,END)` inclusive start, exclusive end
+- `(START,END]` exclusive start, inclusive end
+
+Datetimes must be UTC and ISO-like (e.g. `2024-01-02T03:04:05Z`).
+
+Canonical output uses second precision and `Z`, e.g.:
+
+`[2024-01-02T03:04:05Z,2024-01-02T04:04:05Z)`
+
+## CLI
+
+```bash
+# From a file
+miniminds-datetime-span --file spans.txt
+
+# From stdin
+printf '[2024-01-01T00:00:00Z,2024-01-01T01:00:00Z)\n' | miniminds-datetime-span
+```
+
+Each non-empty, non-comment line (`# ...`) is parsed and canonicalized.

minimindslab_datetime_span-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "minimindslab-datetime-span"
+version = "0.1.0"
+description = "Parse, normalize, and compare simple UTC datetime spans with deterministic formatting."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "MiniMindsLab" }]
+dependencies = []
+keywords = ["datetime", "timespan", "utc", "iso8601", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Utilities"
+]
+
+[project.scripts]
+miniminds-datetime-span = "minimindslab_datetime_span.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

minimindslab_datetime_span-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

minimindslab_datetime_span-0.1.0/src/minimindslab_datetime_span/__init__.py

@@ -0,0 +1,17 @@
+"""MiniMindsLab DateTime Span library."""
+
+from .core import (
+    DateTimeSpan,
+    SpanParseError,
+    parse_utc_datetime,
+    parse_span,
+)
+
+__all__ = [
+    "DateTimeSpan",
+    "SpanParseError",
+    "parse_utc_datetime",
+    "parse_span",
+]
+
+__version__ = "0.1.0"

minimindslab_datetime_span-0.1.0/src/minimindslab_datetime_span/__main__.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .core import SpanParseError, parse_span
+
+
+def _iter_lines(path: str | None):
+    if path:
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                yield line
+    else:
+        for line in sys.stdin:
+            yield line
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Canonicalize UTC datetime spans.")
+    parser.add_argument("--file", "-f", dest="file", help="Input text file; defaults to stdin")
+    args = parser.parse_args(argv)
+
+    try:
+        for raw in _iter_lines(args.file):
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            print(parse_span(line).canonical())
+    except (OSError, SpanParseError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

minimindslab_datetime_span-0.1.0/src/minimindslab_datetime_span/core.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+
+class SpanParseError(ValueError):
+    """Raised when datetime or span parsing/validation fails."""
+
+
+def parse_utc_datetime(value: str) -> datetime:
+    s = value.strip()
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(s)
+    except ValueError as exc:
+        raise SpanParseError(f"Invalid ISO-8601 datetime: {value!r}") from exc
+    if dt.tzinfo is None:
+        raise SpanParseError(f"Datetime must include UTC timezone: {value!r}")
+    if dt.utcoffset() != timedelta(0):
+        raise SpanParseError(f"Datetime must be UTC (+00:00 or Z): {value!r}")
+    return dt.astimezone(timezone.utc)
+
+
+def _fmt_utc(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+@dataclass(frozen=True)
+class DateTimeSpan:
+    start: datetime
+    end: datetime
+    start_inclusive: bool = True
+    end_inclusive: bool = False
+
+    def __post_init__(self) -> None:
+        s = self.start.astimezone(timezone.utc)
+        e = self.end.astimezone(timezone.utc)
+        object.__setattr__(self, "start", s)
+        object.__setattr__(self, "end", e)
+        if e < s:
+            raise SpanParseError("Invalid span: end precedes start")
+
+    def canonical(self) -> str:
+        l = "[" if self.start_inclusive else "("
+        r = "]" if self.end_inclusive else ")"
+        return f"{l}{_fmt_utc(self.start)},{_fmt_utc(self.end)}{r}"
+
+    def overlaps(self, other: "DateTimeSpan") -> bool:
+        if self.end < other.start or other.end < self.start:
+            return False
+        if self.end == other.start:
+            return self.end_inclusive and other.start_inclusive
+        if other.end == self.start:
+            return other.end_inclusive and self.start_inclusive
+        return True
+
+    def contains(self, other: "DateTimeSpan") -> bool:
+        left_ok = self.start < other.start or (self.start == other.start and (self.start_inclusive or not other.start_inclusive))
+        right_ok = self.end > other.end or (self.end == other.end and (self.end_inclusive or not other.end_inclusive))
+        return left_ok and right_ok
+
+    def is_adjacent(self, other: "DateTimeSpan") -> bool:
+        if self.end == other.start:
+            return not (self.end_inclusive and other.start_inclusive)
+        if other.end == self.start:
+            return not (other.end_inclusive and self.start_inclusive)
+        return False
+
+
+def parse_span(text: str) -> DateTimeSpan:
+    s = text.strip()
+    if len(s) < 5:
+        raise SpanParseError("Invalid span syntax")
+    if s[0] not in "([" or s[-1] not in ")]":
+        raise SpanParseError("Span must start with '(' or '[' and end with ')' or ']'")
+    body = s[1:-1]
+    parts = body.split(",")
+    if len(parts) != 2:
+        raise SpanParseError("Span must contain exactly one comma separating start and end")
+    start = parse_utc_datetime(parts[0])
+    end = parse_utc_datetime(parts[1])
+    return DateTimeSpan(start, end, start_inclusive=(s[0] == "["), end_inclusive=(s[-1] == "]"))

minimindslab_datetime_span-0.1.0/src/minimindslab_datetime_span.egg-info/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: minimindslab-datetime-span
+Version: 0.1.0
+Summary: Parse, normalize, and compare simple UTC datetime spans with deterministic formatting.
+Author: MiniMindsLab
+License: MIT
+Keywords: datetime,timespan,utc,iso8601,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MiniMindsLab DateTime Span
+
+`minimindslab-datetime-span` is a tiny, pure-Python utility for parsing, validating, formatting, and comparing UTC datetime spans.
+
+## Features
+
+- Parse UTC ISO-8601 datetime strings (`Z` or `+00:00`).
+- Model spans with inclusive/exclusive boundaries.
+- Deterministic canonical formatting.
+- Compare spans for overlap, containment, and adjacency.
+- CLI that reads from a file or stdin and prints canonicalized spans.
+
+## Span Format
+
+Library and CLI accept bracketed span lines:
+
+- `[START,END]` inclusive start and end
+- `(START,END)` exclusive start and end
+- `[START,END)` inclusive start, exclusive end
+- `(START,END]` exclusive start, inclusive end
+
+Datetimes must be UTC and ISO-like (e.g. `2024-01-02T03:04:05Z`).
+
+Canonical output uses second precision and `Z`, e.g.:
+
+`[2024-01-02T03:04:05Z,2024-01-02T04:04:05Z)`
+
+## CLI
+
+```bash
+# From a file
+miniminds-datetime-span --file spans.txt
+
+# From stdin
+printf '[2024-01-01T00:00:00Z,2024-01-01T01:00:00Z)\n' | miniminds-datetime-span
+```
+
+Each non-empty, non-comment line (`# ...`) is parsed and canonicalized.

minimindslab_datetime_span-0.1.0/src/minimindslab_datetime_span.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/minimindslab_datetime_span/__init__.py
+src/minimindslab_datetime_span/__main__.py
+src/minimindslab_datetime_span/core.py
+src/minimindslab_datetime_span.egg-info/PKG-INFO
+src/minimindslab_datetime_span.egg-info/SOURCES.txt
+src/minimindslab_datetime_span.egg-info/dependency_links.txt
+src/minimindslab_datetime_span.egg-info/entry_points.txt
+src/minimindslab_datetime_span.egg-info/top_level.txt
+tests/test_datetime_span.py

minimindslab_datetime_span-0.1.0/src/minimindslab_datetime_span.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

minimindslab_datetime_span-0.1.0/src/minimindslab_datetime_span.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+miniminds-datetime-span = minimindslab_datetime_span.__main__:main

minimindslab_datetime_span-0.1.0/src/minimindslab_datetime_span.egg-info/top_level.txt

@@ -0,0 +1 @@
+minimindslab_datetime_span

minimindslab_datetime_span-0.1.0/tests/test_datetime_span.py

@@ -0,0 +1,71 @@
+import io
+import os
+import tempfile
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+
+from minimindslab_datetime_span import DateTimeSpan, SpanParseError, parse_span
+from minimindslab_datetime_span.__main__ import main
+
+
+class DateTimeSpanTests(unittest.TestCase):
+    def test_acceptance_parse_and_canonical(self):
+        span = parse_span("[2024-01-01T00:00:00Z,2024-01-01T01:02:03+00:00)")
+        self.assertEqual(span.canonical(), "[2024-01-01T00:00:00Z,2024-01-01T01:02:03Z)")
+
+    def test_acceptance_end_precedes_start(self):
+        with self.assertRaisesRegex(SpanParseError, "end precedes start"):
+            parse_span("[2024-01-01T02:00:00Z,2024-01-01T01:00:00Z)")
+
+    def test_acceptance_comparison(self):
+        a = parse_span("[2024-01-01T00:00:00Z,2024-01-01T01:00:00Z)")
+        b = parse_span("[2024-01-01T00:30:00Z,2024-01-01T02:00:00Z)")
+        c = parse_span("[2024-01-01T01:00:00Z,2024-01-01T02:00:00Z)")
+        d = parse_span("[2024-01-01T00:10:00Z,2024-01-01T00:20:00Z)")
+
+        self.assertTrue(a.overlaps(b))
+        self.assertTrue(a.contains(d))
+        self.assertTrue(a.is_adjacent(c))
+        self.assertFalse(a.overlaps(c))
+
+    def test_cli_stdin(self):
+        in_data = "# comment\n\n[2024-01-01T00:00:00Z,2024-01-01T01:00:00Z)\n"
+        out = io.StringIO()
+        err = io.StringIO()
+        with redirect_stdout(out), redirect_stderr(err):
+            import sys
+            old_stdin = sys.stdin
+            sys.stdin = io.StringIO(in_data)
+            try:
+                rc = main([])
+            finally:
+                sys.stdin = old_stdin
+        self.assertEqual(rc, 0)
+        self.assertEqual(out.getvalue().strip(), "[2024-01-01T00:00:00Z,2024-01-01T01:00:00Z)")
+        self.assertEqual(err.getvalue(), "")
+
+    def test_cli_file(self):
+        fd, path = tempfile.mkstemp(text=True)
+        os.close(fd)
+        try:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write("[2024-01-01T00:00:00Z,2024-01-01T00:00:01Z]\n")
+            out = io.StringIO()
+            with redirect_stdout(out):
+                rc = main(["--file", path])
+            self.assertEqual(rc, 0)
+            self.assertEqual(out.getvalue().strip(), "[2024-01-01T00:00:00Z,2024-01-01T00:00:01Z]")
+        finally:
+            os.unlink(path)
+
+    def test_negative_invalid_syntax(self):
+        with self.assertRaises(SpanParseError):
+            parse_span("2024-01-01T00:00:00Z,2024-01-01T01:00:00Z")
+
+    def test_negative_non_utc_rejected(self):
+        with self.assertRaisesRegex(SpanParseError, "UTC"):
+            parse_span("[2024-01-01T00:00:00+01:00,2024-01-01T01:00:00+01:00)")
+
+
+if __name__ == "__main__":
+    unittest.main()