standard 0.1.0__py3-none-any.whl

standard-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: standard
+Version: 0.1.0
+Summary: A predictable Python utility library with an agent-first interface
+Author: Standard contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: configuration,pydantic,toml,utilities,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic-settings<3,>=2.6
+Requires-Dist: pyyaml<7,>=6
+Provides-Extra: aws
+Requires-Dist: boto3<2,>=1.35; extra == 'aws'
+Provides-Extra: fastapi
+Requires-Dist: fastapi<1,>=0.115; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# Standard
+
+**A small Python utility library with predictable behavior and agent-first guidance.**
+
+The project and intended PyPI distribution are named `standard`; the Python import package and command are named `std`. Standard is currently an alpha source checkout, not a published PyPI release. The PyPI project named [`standard`](https://pypi.org/project/standard/) belongs to someone else, so do not install `standard` from PyPI expecting this project.
+
+The core provides YAML/TOML configuration, Pydantic Settings sources, immutable snapshots, recursive mapping helpers, and atomic text writes. FastAPI and AWS integrations are optional extras.
+
+## Install from this checkout
+
+Run these commands from the repository root. Choose one integration command if you need that extra; each installs this checkout and its dependencies.
+
+| Need | Command | Import path |
+| --- | --- | --- |
+| Core only | `python -m pip install -e .` | `std` |
+| FastAPI | `python -m pip install -e '.[fastapi]'` | `std.fastapi` |
+| AWS | `python -m pip install -e '.[aws]'` | `std.aws` |
+| Both integrations | `python -m pip install -e '.[fastapi,aws]'` | `std.fastapi`, `std.aws` |
+
+The intended published install forms are `standard`, `standard[fastapi]`, and `standard[aws]`. They are not available for this project until the existing PyPI name is resolved.
+
+## First use
+
+Create `config/settings.yaml`:
+
+```yaml
+database:
+  host: localhost
+```
+
+Then load a value from it:
+
+```python
+from std.config import ConfigManager
+
+config = ConfigManager.from_file("config/settings.yaml")
+host = config.snapshot.get_path("database.host", "localhost")
+```
+
+For Pydantic Settings, create `config/app.yaml`:
+
+```yaml
+host: localhost
+port: 8080
+```
+
+```python
+from std.config import YamlSettings
+
+
+class Settings(YamlSettings):
+    std_config_file = "config/app.yaml"
+    host: str
+    port: int = 8080
+
+
+settings = Settings()
+```
+
+By default, Pydantic Settings resolves values in this order: constructor values, Standard config files, process environment, dotenv, and file secrets. Callers can change the order through Pydantic's `settings_customise_sources` hook.
+
+## Agent guidance
+
+```bash
+std guide
+std skill show
+std skill install
+```
+
+`std guide` summarizes the library for coding agents. `std skill show` prints the packaged idiomatic-Python skill. `std skill install` writes it to `.agents/skills/standard-python/SKILL.md` and refuses to overwrite an existing file unless you pass `--force`.
+
+The source repository contains the development checks, end-to-end tests, and full documentation site. The published distribution is intended to contain only the working library, its CLI, and the required package metadata, README, and license.

standard-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+std/__init__.py,sha256=QlL2NiR-0TsgDyskZc9kIkGR-RgiXC9n2IovyHAZsWQ,56
+std/cli.py,sha256=mHeUcPWw-QUtUbXH4UEryYqk6r3-0n5bV6ZdkSKPvXU,3942
+std/collections.py,sha256=HC9BUaAqb193z5446d66KTOUsf0N85fPGEqt19Gg-f4,3797
+std/files.py,sha256=M6CF_4A9vDXiUEF6vX20HkRxTrX4ousOE-RzX9mWkL0,1985
+std/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+std/aws/__init__.py,sha256=Rib0dLOc3ZFztFtPtf5bhkoq_WZ3wIPpNDO6tb_XE94,3864
+std/config/__init__.py,sha256=rfcLky6wH4Tmp_cJSIn4CUAeGU0cp-aK1nB30dFGAEg,730
+std/config/errors.py,sha256=Wh2hJTZGQPASKJH3Z4gA3JPhFF87YsKLmlSE9a_jSCc,1159
+std/config/loader.py,sha256=nsetK9BGBsiJ8sKv3Q1woolb45WqjpVgIO2xeQQE19w,17254
+std/config/snapshot.py,sha256=8AQf6YYfTK-ptbbWTbpzkBuNqJnxf5Um0KrmrH3fZ8w,3071
+std/config/sources.py,sha256=kvPqVJ2vokMKKpNR0IqgyebKxq3UjRJj4Wjolw7ukLg,5677
+std/fastapi/__init__.py,sha256=SMNNt6B4YDWSCzUGCqrLlNHRqS0VlFeEqpyerVPe36Q,1269
+std/skills/idiomatic-python.md,sha256=9L5Iudh-TCB9dd09F5raOZl3Z6PAYIoPdwlORk26xxg,3763
+standard-0.1.0.dist-info/METADATA,sha256=JVa-7n-30nqPNOit32hjYzjsCwkLRr0dYyE1WOLeLb0,3714
+standard-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+standard-0.1.0.dist-info/entry_points.txt,sha256=ch5_ikNJzT7M1ZAKXs-STbZjQtPdWmqr6Zo24YwxJVc,37
+standard-0.1.0.dist-info/licenses/LICENSE,sha256=sTIUP5MvMnfCSD0TdNTwjyFwBdAsnTBG2PfgodF7c9k,1078
+standard-0.1.0.dist-info/RECORD,,

standard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

standard-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+std = std.cli:main

standard-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Standard contributors
+
+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.

std/__init__.py

@@ -0,0 +1,3 @@
+"""Standard Python utilities."""
+
+__version__ = "0.1.0"

std/aws/__init__.py

@@ -0,0 +1,107 @@
+"""Optional AWS Secrets Manager settings source."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from importlib import import_module
+from typing import Any, NoReturn
+
+try:
+    # The optional type environment intentionally omits third-party boto3 stubs.
+    boto3: Any = import_module("boto3")
+except ImportError as error:  # pragma: no cover - depends on installation extra
+    raise ImportError(
+        "AWS integration requires the aws extra; from a checkout run `pip install -e '.[aws]'`"
+    ) from error
+
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource
+
+
+class AwsSecretError(RuntimeError):
+    """A secret could not be retrieved or did not contain a JSON object."""
+
+
+def _unique_json_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    """Build a JSON object while rejecting ambiguous duplicate keys."""
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON object key")
+        result[key] = value
+    return result
+
+
+def _reject_non_finite_number(value: str) -> NoReturn:
+    """Reject Python's non-standard JSON NaN and Infinity extensions."""
+    raise ValueError(f"non-standard JSON numeric constant: {value}")
+
+
+def load_secret(
+    secret_id: str,
+    *,
+    region_name: str | None = None,
+    client: Any | None = None,
+) -> dict[str, Any]:
+    """Load a JSON object from AWS Secrets Manager without exposing secret data."""
+    if not secret_id.strip():
+        raise ValueError("secret_id must not be empty")
+    try:
+        secrets_client = (
+            client
+            if client is not None
+            else boto3.client("secretsmanager", region_name=region_name)
+        )
+        response = secrets_client.get_secret_value(SecretId=secret_id)
+        if "SecretString" in response:
+            raw = response["SecretString"]
+        elif "SecretBinary" in response:
+            binary = response["SecretBinary"]
+            raw = (
+                binary.decode("utf-8")
+                if isinstance(binary, bytes)
+                else bytes(binary).decode("utf-8")
+            )
+        else:
+            raise AwsSecretError("AWS Secrets Manager returned no secret payload")
+        value = json.loads(
+            raw,
+            object_pairs_hook=_unique_json_object,
+            parse_constant=_reject_non_finite_number,
+        )
+    except AwsSecretError:
+        raise
+    except Exception:
+        raise AwsSecretError("AWS Secrets Manager request or JSON decoding failed") from None
+    if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value):
+        raise AwsSecretError("AWS secret payload must be a JSON object with string keys")
+    return dict(value)
+
+
+class AwsSecretsManagerSettingsSource(PydanticBaseSettingsSource):
+    """Pydantic source that maps an AWS Secrets Manager JSON object to fields."""
+
+    def __init__(
+        self,
+        settings_cls: type[BaseSettings],
+        secret_id: str,
+        *,
+        region_name: str | None = None,
+        client: Any | None = None,
+    ) -> None:
+        """Configure the source with a Settings model and secret identifier."""
+        super().__init__(settings_cls)
+        self.secret_id = secret_id
+        self.region_name = region_name
+        self.client = client
+
+    def __call__(self) -> dict[str, object]:
+        """Return the secret object as a mapping of Settings field values."""
+        return load_secret(self.secret_id, region_name=self.region_name, client=self.client)
+
+    def get_field_value(self, field: object, field_name: str) -> tuple[object, str, bool]:
+        """Satisfy the Pydantic source protocol; this source returns a full mapping."""
+        return None, field_name, False
+
+
+__all__ = ["AwsSecretError", "AwsSecretsManagerSettingsSource", "load_secret"]

std/cli.py

@@ -0,0 +1,106 @@
+"""Agent-facing command line guidance for the Standard library."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from importlib import resources
+from pathlib import Path
+
+from std import __version__
+from std.files import atomic_write_text
+
+_DISTRIBUTION_NAME = "standard"
+
+_GUIDE = """Standard targets the `standard` distribution and is imported as `std`.
+
+Use `std.config.ConfigManager` for YAML/TOML configuration and Pydantic Settings
+sources. Snapshots are immutable; call `to_dict()` for an isolated mutable copy.
+`reload()` is explicit and atomic. Core helpers are `std.collections` and
+`std.files`. FastAPI and AWS adapters are optional: install
+`standard[fastapi]` or `standard[aws]` before importing `std.fastapi` or
+`std.aws`. The existing PyPI project named `standard` is unrelated; until the
+name is resolved, install extras from this checkout with `pip install -e '.[fastapi]'`
+or `pip install -e '.[aws]'`.
+
+Run `std skill show` to print the portable idiomatic-Python skill. Run
+`std skill install` to copy it to `.agents/skills/standard-python/SKILL.md`.
+"""
+
+
+def _skill_text() -> str:
+    return (
+        resources.files("std").joinpath("skills", "idiomatic-python.md").read_text(encoding="utf-8")
+    )
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="std",
+        description="Standard library and coding-agent guidance",
+    )
+    parser.add_argument("--version", action="version", version=f"std {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    guide = subparsers.add_parser("guide", help="show concise instructions for coding agents")
+    guide.add_argument("--format", choices=("text", "json"), default="text")
+
+    skill = subparsers.add_parser("skill", help="show or install the idiomatic Python skill")
+    skill_subparsers = skill.add_subparsers(dest="skill_command", required=True)
+    skill_subparsers.add_parser("show", help="print the portable skill document")
+    skill_subparsers.add_parser("path", help="print the packaged skill resource path")
+    install = skill_subparsers.add_parser(
+        "install", help="copy the skill into the current repository"
+    )
+    install.add_argument(
+        "destination",
+        nargs="?",
+        default=".agents/skills/standard-python/SKILL.md",
+        help="destination file (default: .agents/skills/standard-python/SKILL.md)",
+    )
+    install.add_argument("--force", action="store_true", help="replace an existing destination")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the ``std`` command."""
+    args = _parser().parse_args(argv)
+    if args.command == "guide":
+        if args.format == "json":
+            print(
+                json.dumps(
+                    {
+                        "distribution": _DISTRIBUTION_NAME,
+                        "import": "std",
+                        "version": __version__,
+                        "guide": _GUIDE,
+                    }
+                )
+            )
+        else:
+            print(_GUIDE.rstrip())
+        return 0
+    if args.skill_command == "show":
+        print(_skill_text(), end="")
+        return 0
+    if args.skill_command == "path":
+        print(resources.files("std").joinpath("skills", "idiomatic-python.md"))
+        return 0
+    target = Path(args.destination)
+    if (target.exists() or target.is_symlink()) and not args.force:
+        print(f"refusing to overwrite existing path: {target} (pass --force)", file=sys.stderr)
+        return 2
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(target, _skill_text(), mode=0o644)
+    except OSError as error:
+        print(f"could not install skill at {target}: {error}", file=sys.stderr)
+        return 1
+    print(target)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

std/collections.py

@@ -0,0 +1,100 @@
+"""Small, predictable helpers for nested mappings."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from typing import Any, TypeVar
+
+_MISSING = object()
+V = TypeVar("V")
+
+
+def deep_merge(*mappings: Mapping[str, Any]) -> dict[str, Any]:
+    """Merge mappings without mutating inputs; lists append and later conflicts win.
+
+    Nested mappings merge recursively. Lists concatenate in argument order.
+    Any other type conflict replaces the earlier value with the later value.
+    Values are copied recursively, so the result is independent of mutable inputs.
+    """
+    result: dict[str, Any] = {}
+    for mapping in mappings:
+        if not isinstance(mapping, Mapping):
+            raise TypeError("deep_merge accepts mappings only")
+        result = _merge_pair(result, mapping)
+    return result
+
+
+def _copy_value(value: Any, active: set[int] | None = None) -> Any:
+    if isinstance(value, (Mapping, list, tuple)):
+        current_active = active if active is not None else set()
+        identity = id(value)
+        if identity in current_active:
+            raise ValueError("cyclic mappings and sequences cannot be merged")
+        current_active.add(identity)
+        try:
+            if isinstance(value, Mapping):
+                return {key: _copy_value(item, current_active) for key, item in value.items()}
+            if isinstance(value, list):
+                return [_copy_value(item, current_active) for item in value]
+            return tuple(_copy_value(item, current_active) for item in value)
+        finally:
+            current_active.remove(identity)
+    return deepcopy(value)
+
+
+def _merge_pair(left: Mapping[str, Any], right: Mapping[str, Any]) -> dict[str, Any]:
+    merged = {key: _copy_value(value) for key, value in left.items()}
+    for key, value in right.items():
+        previous = merged.get(key, _MISSING)
+        if isinstance(previous, Mapping) and isinstance(value, Mapping):
+            merged[key] = _merge_pair(previous, value)
+        elif isinstance(previous, list) and isinstance(value, list):
+            merged[key] = _copy_value(previous) + _copy_value(value)
+        else:
+            merged[key] = _copy_value(value)
+    return merged
+
+
+def get_path(
+    mapping: Mapping[str, Any],
+    path: str | Sequence[str],
+    default: V | None = None,
+) -> Any | V | None:
+    """Read a dotted or segmented path from nested mappings.
+
+    A missing segment returns ``default``. Empty path segments in a dotted path
+    are ignored, so ``"a..b"`` is treated as ``("a", "b")``.
+    """
+    parts = (
+        tuple(part for part in path.split(".") if part) if isinstance(path, str) else tuple(path)
+    )
+    current: Any = mapping
+    for part in parts:
+        if not isinstance(current, Mapping) or part not in current:
+            return default
+        current = current[part]
+    return current
+
+
+def set_path(mapping: dict[str, Any], path: str | Sequence[str], value: Any) -> None:
+    """Set a nested mapping value, creating intermediate dictionaries in place."""
+    parts = (
+        tuple(part for part in path.split(".") if part) if isinstance(path, str) else tuple(path)
+    )
+    if not parts or any(not isinstance(part, str) or not part for part in parts):
+        raise ValueError("path must contain at least one non-empty string segment")
+    current: dict[str, Any] = mapping
+    for part in parts[:-1]:
+        if part not in current:
+            child: Any = {}
+            current[part] = child
+        else:
+            child = current[part]
+        if not isinstance(child, dict):
+            raise TypeError(f"cannot descend through non-mapping segment {part!r}")
+        current = child
+    current[parts[-1]] = value
+
+
+__all__ = ["deep_merge", "get_path", "set_path"]

std/config/__init__.py

@@ -0,0 +1,31 @@
+"""YAML/TOML configuration loading and Pydantic Settings integration."""
+
+from std.config.errors import (
+    ConfigError,
+    ConfigFormatError,
+    ConfigInterpolationError,
+    MissingConfigSourceError,
+)
+from std.config.loader import ConfigManager
+from std.config.snapshot import ConfigSnapshot
+from std.config.sources import (
+    ConfigSettingsSource,
+    TomlSettings,
+    TomlSettingsSource,
+    YamlSettings,
+    YamlSettingsSource,
+)
+
+__all__ = [
+    "ConfigError",
+    "ConfigFormatError",
+    "ConfigInterpolationError",
+    "ConfigManager",
+    "ConfigSettingsSource",
+    "ConfigSnapshot",
+    "MissingConfigSourceError",
+    "TomlSettings",
+    "TomlSettingsSource",
+    "YamlSettings",
+    "YamlSettingsSource",
+]

std/config/errors.py

@@ -0,0 +1,40 @@
+"""Public errors raised while loading and resolving configuration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class ConfigError(Exception):
+    """Base error with optional source and location context."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        source: Path | None = None,
+        location: str | None = None,
+    ) -> None:
+        """Build a safe error message with optional source and location context."""
+        self.message = message
+        self.source = source
+        self.location = location
+        context = []
+        if source is not None:
+            context.append(str(source))
+        if location:
+            context.append(location)
+        prefix = ":".join(context)
+        super().__init__(f"{prefix}: {message}" if prefix else message)
+
+
+class MissingConfigSourceError(ConfigError):
+    """A required configuration file or directory is missing."""
+
+
+class ConfigFormatError(ConfigError):
+    """A source has invalid syntax, a bad root, or an unsupported format."""
+
+
+class ConfigInterpolationError(ConfigError):
+    """A placeholder is malformed or cannot be resolved safely."""