httk-core 2.0.0__tar.gz → 2.1.1__tar.gz

{httk_core-2.0.0/src/httk_core.egg-info → httk_core-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httk-core
-Version: 2.0.0
+Version: 2.1.1
 Summary: httk₂ core functionality
 Author-email: Rickard Armiento <rickard-gpg@armiento.net>
 License-Expression: AGPL-3.0-or-later
@@ -20,13 +20,19 @@ Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: default
+Requires-Dist: numpy>=1.26; extra == "default"
+Requires-Dist: cryptography>=42; extra == "default"
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.26; extra == "numpy"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: isort; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Requires-Dist: pyright; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
+Requires-Dist: numpy>=1.26; extra == "dev"
+Requires-Dist: pydoclint<1,>=0.9; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: furo; extra == "docs"
@@ -42,22 +48,24 @@ Dynamic: license-file
 
 # httk-core
 
-![Status: Pre-release](https://img.shields.io/badge/status-pre--release-red)
+![Status: Early beta](https://img.shields.io/badge/status-early--beta-orange)
 
-> **⚠️ PRE-RELEASE**
+> **⚠️ EARLY BETA**
 >
-> The version assigned to *httk-core* designates the overall version of *httk₂*,
-> and thus starts at v2.0.0. However, versions v2.0.* are to be considered
-> prereleases, and semantic versioning will not be used until v2.1.0.
+> This is an early beta release of *httk₂*. The organization of the packages
+> and their APIs should not yet be regarded as stable, and may change between
+> releases.
 
-`httk-core` is the central lightweight dependency shared by httk₂ modules.
+`httk-core` is the central lightweight dependency shared by *httk₂* modules.
 
 It provides:
 
 - the `httk.core` package within the PEP 420 native `httk` namespace;
 - shared view/backend and data-stream primitives; and
 - plugin discovery and aggregate operations such as `httk.core.load`, to which
-  other httk modules can register handlers.
+  other httk modules can register capabilities.
+- the extensible `httk` executable, a lazy top-level command registry, and
+  stdlib-backed Ed25519 signing.
 
 Most users should install the [`httk2`](https://github.com/httk/httk2)
 metapackage, which selects a useful set of httk modules:
@@ -72,5 +80,5 @@ Install only the core package with:
 pip install httk-core
 ```
 
-Other distributions, such as `httk-io`, install their own packages under the
-same `httk` namespace and can then be imported as `httk.io`.
+Other distributions, such as `httk-atomistic`, install their own packages under the
+same `httk` namespace and can then be imported as `httk.atomistic`.

httk_core-2.1.1/README.md

@@ -0,0 +1,36 @@
+# httk-core
+
+![Status: Early beta](https://img.shields.io/badge/status-early--beta-orange)
+
+> **⚠️ EARLY BETA**
+>
+> This is an early beta release of *httk₂*. The organization of the packages
+> and their APIs should not yet be regarded as stable, and may change between
+> releases.
+
+`httk-core` is the central lightweight dependency shared by *httk₂* modules.
+
+It provides:
+
+- the `httk.core` package within the PEP 420 native `httk` namespace;
+- shared view/backend and data-stream primitives; and
+- plugin discovery and aggregate operations such as `httk.core.load`, to which
+  other httk modules can register capabilities.
+- the extensible `httk` executable, a lazy top-level command registry, and
+  stdlib-backed Ed25519 signing.
+
+Most users should install the [`httk2`](https://github.com/httk/httk2)
+metapackage, which selects a useful set of httk modules:
+
+```console
+pip install httk2
+```
+
+Install only the core package with:
+
+```console
+pip install httk-core
+```
+
+Other distributions, such as `httk-atomistic`, install their own packages under the
+same `httk` namespace and can then be imported as `httk.atomistic`.

{httk_core-2.0.0 → httk_core-2.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "httk-core"
-version = "2.0.0"
+version = "2.1.1"
 description = "httk₂ core functionality"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -35,23 +35,40 @@ Documentation = "https://docs.httk.org/httk-core/"
 Repository = "https://github.com/httk/httk-core"
 Issues = "https://github.com/httk/httk-core/issues"
 
+[project.scripts]
+httk = "httk.core.cli:main"
+
 [tool.setuptools]
 package-dir = {"" = "src"}
 
 [tool.setuptools.packages.find]
 where = ["src"]
+# httk is a PEP 420 namespace shared across the httk-* repositories, so the
+# top-level httk/ has no __init__.py; find must be told to include namespaces or
+# it discovers nothing under it. httk.core.project is the anchor package this
+# build adds inside httk.core.
+namespaces = true
 
 [tool.setuptools.package-data]
 "httk.core" = ["py.typed"]
+"httk.core.optimade.filter" = ["*.ebnf", "README.md"]
+"httk.registry.schemas.core" = ["*.json", "LICENSE", "LICENSE.httk", "README.md"]
+"httk.core.docs" = ["assets/*"]
 
 [project.optional-dependencies]
+default = [
+  "numpy>=1.26",
+  "cryptography>=42",
+]
+numpy = ["numpy>=1.26"]
 dev = [
   "pytest>=8.0",
-  "black",
-  "ruff",
-  "isort",
+  "pytest-xdist>=3.6",
+  "ruff>=0.16,<0.17",
   "pyright",
-  "mypy"
+  "mypy",
+  "numpy>=1.26",
+  "pydoclint>=0.9,<1"
 ]
 docs = [
   "sphinx",
@@ -68,24 +85,41 @@ release = [
 ]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-
-[tool.isort]
-profile = "black"
+addopts = "-n 4 --dist loadgroup -m 'not extended'"
+markers = [
+  "extended: full-depth test case; selected only by the extended test profile",
+]
 
 [tool.ruff]
 target-version = "py312"
 src = ["src", "examples"]
-
-[tool.black]
-target-version = ["py312"]
 line-length = 120
-skip-string-normalization = true
+
+[tool.ruff.lint]
+# TRY002: raising plain Exception is accepted httk style.
+# TRY004: the ValueError/TypeError choice is public API; do not churn it.
+# BLE001: broad excepts deliberately isolate plugin/loader/handler failures.
+ignore = ["TRY002", "TRY004", "BLE001"]
+
+[tool.ruff.format]
+# preserve replaces black's skip-string-normalization: existing quote styles are kept.
+quote-style = "preserve"
+
+[tool.pydoclint]
+style = "sphinx"
+arg-type-hints-in-docstring = false
+check-return-types = false
+check-yield-types = false
+check-class-attributes = false
+skip-checking-raises = true
 
 [tool.pyright]
 pythonVersion = "3.12"
 include = ["src", "examples"]
 reportMissingImports = true
-extraPaths = []
+# The examples import httk as an installed package would; point pyright at the
+# in-tree sources so they resolve without relying on an editable install.
+extraPaths = ["src"]
 
 [tool.mypy]
 python_version = "3.12"
@@ -96,5 +130,5 @@ explicit_package_bases = true
 warn_unused_ignores = true
 
 [[tool.mypy.overrides]]
-module = ["yaml", "markdown", "docutils", "docutils.*"]
+module = ["yaml", "markdown", "docutils", "docutils.*", "sphinx", "sphinx.*"]
 ignore_missing_imports = true

httk_core-2.1.1/src/httk/core/__init__.py

@@ -0,0 +1,245 @@
+"""Public core APIs for loading, reporting, project anchors, and registration.
+
+Importing this package discovers installed capability modules and exposes
+their registered readers, writers, adapters, and related public APIs.
+
+The deliberate public surface is defined by ``__all__``.
+"""
+
+#
+#    The high-throughput toolkit (httk)
+#    Copyright (C) 2012-2024 the httk AUTHORS
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU Affero General Public License as
+#    published by the Free Software Foundation, either version 3 of the
+#    License, or (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU Affero General Public License for more details.
+#
+#    You should have received a copy of the GNU Affero General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from . import exactmath  # noqa: F401 - intentional module-level import for ``from httk.core import exactmath``
+from ._discover import discover_and_register as _discover_and_register
+from ._sentinel import MISSING, MissingType
+from .citations import credits, register_citation
+from .cli import CLIContext
+from .data_records import DataRecord, DataRecordEntry
+from .dataset_loader import DatasetLoader, DatasetLoaderRecord, DatasetMeta
+from .datasets import Dataset, DatasetDistribution, DatasetRecord
+from .datastream import (
+    BytestreamFileView,
+    BytestreamLike,
+    BytestreamURLView,
+    CompressionCodec,
+    DatastreamLike,
+    DatastreamURL,
+    TextstreamFileView,
+    TextstreamLike,
+    TextstreamURLView,
+    known_compressions,
+    register_compression,
+)
+from .entry_ids import (
+    ALTERNATIVE_ID_PATTERN,
+    ALTERNATIVE_KIND_PATTERN,
+    ENTRY_ID_PATTERN,
+    IMMUTABLE_ID_PATTERN,
+    check_entry_id,
+    check_immutable_id,
+    format_alternative_id,
+    format_entry_id,
+    format_immutable_id,
+    is_url_safe_id,
+    parse_alternative_id,
+    parse_entry_id,
+    parse_immutable_id,
+)
+from .entry_provider import EntryProvider, RelatedEntry
+from .entry_types import Calculation, File, Reference
+from .fetching import fetch
+from .files import FileEntry, FileRecord
+from .loading import has_reader_for, load, load_many, load_source
+from .precision import combined_precision, decimal_precision
+from .property_definitions import (
+    EntryTypeDefinition,
+    PropertyDefinition,
+    apply_definition_prefix,
+    known_definition_prefixes,
+    register_definition_prefix,
+    standard_entry_type,
+)
+from .provenance import ProductLink, Run, RunEdge, RunEntry
+from .register.cli import register_cli_command
+from .register.entries import (
+    known_entry_providers,
+    register_entry_family,
+    register_entry_provider,
+    register_entry_record,
+    register_optimade_entry_binding,
+)
+from .register.io import (
+    register_format_adapter,
+    register_format_serializer,
+    register_reader,
+    register_writer,
+)
+from .register.members import (
+    known_project_member_kinds,
+    project_member_handler,
+    register_project_member_kind,
+)
+from .register.schemas import (
+    load_entry_type_definition,
+    load_property_definition,
+    register_entry_type_definition,
+    register_property_definition,
+)
+from .saving import has_writer_for, save
+from .services import Service, ServiceRecord
+from .storage.identity import content_id
+from .storage.markers import (
+    IdentitySkip,
+    Indexed,
+    Related,
+    Shape,
+    Skip,
+    StorageInfo,
+    StrongLink,
+    Unique,
+    WeakLink,
+    stored_property,
+)
+from .vectors import (
+    FracScalar,
+    FracVector,
+    MutableFracVector,
+    NumericVector,
+    ScalarLike,
+    SurdScalar,
+    SurdVector,
+    VectorLike,
+    numpy_available,
+    to_numeric,
+    to_numeric_scalar,
+)
+from .views import Backend, View, coerce, coerce_view, unview, unwrap
+
+_discover_and_register()
+
+__all__ = [
+    "ALTERNATIVE_ID_PATTERN",
+    "ALTERNATIVE_KIND_PATTERN",
+    "ENTRY_ID_PATTERN",
+    "IMMUTABLE_ID_PATTERN",
+    "MISSING",
+    "Backend",
+    "BytestreamFileView",
+    "BytestreamLike",
+    "BytestreamURLView",
+    "CLIContext",
+    "Calculation",
+    "CompressionCodec",
+    "DataRecord",
+    "DataRecordEntry",
+    "Dataset",
+    "DatasetDistribution",
+    "DatasetLoader",
+    "DatasetLoaderRecord",
+    "DatasetMeta",
+    "DatasetRecord",
+    "DatastreamLike",
+    "DatastreamURL",
+    "EntryProvider",
+    "EntryTypeDefinition",
+    "File",
+    "FileEntry",
+    "FileRecord",
+    "FracScalar",
+    "FracVector",
+    "IdentitySkip",
+    "Indexed",
+    "MissingType",
+    "MutableFracVector",
+    "NumericVector",
+    "ProductLink",
+    "PropertyDefinition",
+    "Reference",
+    "Related",
+    "RelatedEntry",
+    "Run",
+    "RunEdge",
+    "RunEntry",
+    "ScalarLike",
+    "Service",
+    "ServiceRecord",
+    "Shape",
+    "Skip",
+    "StorageInfo",
+    "StrongLink",
+    "SurdScalar",
+    "SurdVector",
+    "TextstreamFileView",
+    "TextstreamLike",
+    "TextstreamURLView",
+    "Unique",
+    "VectorLike",
+    "View",
+    "WeakLink",
+    "apply_definition_prefix",
+    "check_entry_id",
+    "check_immutable_id",
+    "coerce",
+    "coerce_view",
+    "combined_precision",
+    "content_id",
+    "credits",
+    "decimal_precision",
+    "fetch",
+    "format_alternative_id",
+    "format_entry_id",
+    "format_immutable_id",
+    "has_reader_for",
+    "has_writer_for",
+    "is_url_safe_id",
+    "known_compressions",
+    "known_definition_prefixes",
+    "known_entry_providers",
+    "known_project_member_kinds",
+    "load",
+    "load_entry_type_definition",
+    "load_many",
+    "load_property_definition",
+    "load_source",
+    "numpy_available",
+    "parse_alternative_id",
+    "parse_entry_id",
+    "parse_immutable_id",
+    "project_member_handler",
+    "register_citation",
+    "register_cli_command",
+    "register_compression",
+    "register_definition_prefix",
+    "register_entry_family",
+    "register_entry_provider",
+    "register_entry_record",
+    "register_entry_type_definition",
+    "register_format_adapter",
+    "register_format_serializer",
+    "register_optimade_entry_binding",
+    "register_project_member_kind",
+    "register_property_definition",
+    "register_reader",
+    "register_writer",
+    "save",
+    "standard_entry_type",
+    "stored_property",
+    "to_numeric",
+    "to_numeric_scalar",
+    "unview",
+    "unwrap",
+]

httk_core-2.1.1/src/httk/core/_discover.py

@@ -0,0 +1,48 @@
+#
+#    The high-throughput toolkit (httk)
+#    Copyright (C) 2012-2024 the httk AUTHORS
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU Affero General Public License as
+#    published by the Free Software Foundation, either version 3 of the
+#    License, or (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU Affero General Public License for more details.
+#
+#    You should have received a copy of the GNU Affero General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import importlib
+import importlib.util
+import pkgutil
+
+
+def _import_registry_packages(path, prefix: str) -> None:
+    for module in sorted(pkgutil.iter_modules(path, prefix), key=lambda item: item.name):
+        if not module.ispkg:
+            continue
+        if importlib.util.find_spec(module.name) is not None:
+            importlib.import_module(module.name)
+
+
+def discover_and_register() -> None:
+    """Eagerly import registration packages from the available registry tiers.
+
+    The reserved ``cli``, ``entries``, ``io``, and ``schemas`` sub-namespaces
+    are each walked independently. Registration packages are imported eagerly
+    so installation errors fail fast, but they must only register lazy
+    references: they must not resolve registries or load resource data while
+    being imported.
+    """
+    importlib.import_module("httk.registry")
+
+    prefix = "httk.registry."
+    for namespace in ("cli", "entries", "io", "schemas"):
+        namespace_name = f"{prefix}{namespace}"
+        if importlib.util.find_spec(namespace_name) is None:
+            continue
+        namespace_module = importlib.import_module(namespace_name)
+        _import_registry_packages(namespace_module.__path__, f"{namespace_name}.")

httk_core-2.1.1/src/httk/core/_iris.py

@@ -0,0 +1,5 @@
+"""Retained internal alias; the implementation moved to :mod:`httk.core.validation.iris`."""
+
+from .validation.iris import is_absolute_iri
+
+__all__ = ["is_absolute_iri"]

httk_core-2.1.1/src/httk/core/_json.py

@@ -0,0 +1,70 @@
+"""Deterministic JSON helpers shared across httk.core.
+
+The on-disk representation of ``project.json`` is shared with *httk-workflow*:
+compact, key-sorted, non-ASCII-preserving encoding with a trailing newline,
+written atomically by rename.
+"""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+def json_bytes(value: object) -> bytes:
+    """Encode compact, deterministic UTF-8 JSON."""
+
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def read_json(path: Path) -> dict[str, object]:
+    """Read a JSON object from *path*.
+
+    :param path: File to read.
+    :return: The decoded JSON object.
+    :raises ValueError: If the file cannot be read or does not hold a JSON object.
+    """
+
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"cannot read JSON object {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"expected JSON object in {path}")
+    return value
+
+
+def _fsync_directory(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def write_json_atomic(path: Path, value: object, *, durable: bool = False) -> None:
+    """Atomically replace *path* with the JSON encoding of *value*.
+
+    :param path: File to replace.
+    :param value: JSON-encodable value to write.
+    :param durable: Whether to ``fsync`` the file and its directory so the write survives a crash.
+    """
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.tmp.", dir=path.parent)
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(json_bytes(value))
+            handle.write(b"\n")
+            if durable:
+                handle.flush()
+                os.fsync(handle.fileno())
+        os.replace(temporary, path)
+        if durable:
+            _fsync_directory(path.parent)
+    finally:
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass