arcexpect 0.0.1__py3-none-any.whl

arcexpect/__init__.py

@@ -0,0 +1,427 @@
+"""Natural Python API for authoring ARC validation packages.
+
+The implementation is generated by Fable in :mod:`ArcExpect.py`.  This module
+keeps the generated names private and exposes the stable, Python-friendly
+surface used by validation-package authors.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, Callable
+
+from fable_library.list import of_seq as _fsharp_list
+from fable_library.map import of_seq as _fsharp_map
+
+from .py.arcvalidation_package import ARCValidationPackage
+from .py.arcvalidation_package import (
+    ARCValidationPackage_create_1ABB6492 as _create_validation_package,
+)
+from .py.badge import (
+    Badge,
+    BadgeColor_GREEN,
+    BadgeColor_ORANGE_2,
+    BadgeColor_RED,
+    BadgeStyle_Default,
+    BadgeStyle_GitLabScoped,
+)
+from .py.badge_creation import (
+    BadgeCreation_ofTestResults_Z31D5A57A as _badge_from_test_results,
+    BadgeCreation_ofValidationSummary_Z31D5A57A as _badge_from_validation_summary,
+)
+from .py.pyxpecto_runner import (
+    TestOutcome_Errored as Errored,
+    TestOutcome_Failed as Failed,
+    TestOutcome_Ignored as Ignored,
+    TestOutcome_Passed as Passed,
+    TestRunEntry,
+    TestRunResults,
+    PyxpectoRunner_runTestsWithResults as run_tests_with_results,
+    PyxpectoRunner_runTestsWithResultsAsync as run_tests_with_results_async,
+    TestRunResults__get_Errored as errored_test_entries,
+    TestRunResults__get_Failed as failed_test_entries,
+    TestRunResults__get_Ignored as ignored_test_entries,
+    TestRunResults__get_Passed as passed_test_entries,
+)
+from .py.serialization import (
+    combine_test_run_results,
+    to_json,
+    to_junit_xml,
+    to_nunit_xml,
+    write_json,
+    write_junit_xml,
+    write_nunit_xml,
+)
+from .py.top_level_api import (
+    Execute_BadgeCreation_ZC2625C3 as _create_badge,
+    Execute_JUnitReportCreation_Z721C83C5 as _create_junit_report,
+    Execute_SummaryCreation_Z721C83C5 as _create_summary,
+    Execute_ValidationAsync_9EC2FF9 as _validate_async,
+    Execute_ValidationPipeline_Z225F5B99 as _validation_pipeline,
+    Execute_Validation_9EC2FF9 as _validate,
+    Setup_Metadata_5C889F27 as _metadata_from_frontmatter,
+)
+from .py.validation_summary import (
+    ValidationPackageSummary,
+    ValidationResult,
+    ValidationSummary,
+)
+from .py.AVPRIndex.domain import (
+    Author,
+    Author_create_13011DE3 as _create_author,
+    OntologyAnnotation,
+    OntologyAnnotation_create_7074443B as _create_ontology_annotation,
+    SemVer,
+    SemVer_create_Z55658624 as _create_semver,
+    SemVer_toString_469FDD94 as semver_to_string,
+    SemVer_tryParse_Z721C83C5 as try_parse_semver,
+    ValidationPackageMetadata,
+    ValidationPackageMetadata_create_Z5610E3C0 as _create_metadata,
+    ValidationPackageMetadata_getSemanticVersionString_58FC932 as semantic_version,
+)
+from .py.AVPRIndex.frontmatter import (
+    AVPRIndex_Domain_ValidationPackageMetadata__ValidationPackageMetadata_extractFromScript_Static_Z721C83C5 as _metadata_from_script,
+    FrontmatterLanguage_FSharpFrontmatter,
+    FrontmatterLanguage_PythonFrontmatter,
+    FrontmatterLanguage_fromString_Z721C83C5 as _frontmatter_language_from_string,
+)
+from .py.fable_modules.fable_pyxpecto.pyxpecto import (
+    Assert_NET_equal as _expect_equal,
+    Assert_NET_notEqual as _expect_not_equal,
+    Expect_isEmpty as _expect_is_empty,
+    Expect_isFalse as _expect_is_false,
+    Expect_isSome as _expect_is_some,
+    Expect_isTrue as _expect_is_true,
+    Expect_stringContains as _expect_string_contains,
+    Test_ftestCase as _focused_test_case,
+    Test_ptestCase as _pending_test_case,
+    Test_testCase as _test_case,
+    Test_testCaseAsync as _test_case_async,
+    Test_testList as _test_list,
+)
+
+
+def _tests(tests: Iterable[Any] | None):
+    return _fsharp_list([] if tests is None else tests)
+
+
+class _StringComparer:
+    def Compare(self, left: str, right: str) -> int:
+        return (left > right) - (left < right)
+
+
+def _thresholds(thresholds: Mapping[str, str] | None):
+    if thresholds is None:
+        return None
+
+    return _fsharp_map(list(thresholds.items()), _StringComparer())
+
+
+def test_case(name: str, body: Callable[[], None]):
+    """Create a synchronous validation case."""
+    return _test_case(name, body)
+
+
+def test_case_async(name: str, body: Any):
+    """Create an asynchronous validation case from a Fable ``Async`` body."""
+    return _test_case_async(name, body)
+
+
+def pending_test_case(name: str, body: Callable[[], None]):
+    """Create a skipped validation case."""
+    return _pending_test_case(name, body)
+
+
+def focused_test_case(name: str, body: Callable[[], None]):
+    """Create a focused validation case."""
+    return _focused_test_case(name, body)
+
+
+def test_list(name: str, tests: Iterable[Any]):
+    """Group validation cases under a descriptive name."""
+    return _test_list(name, _tests(tests))
+
+
+class Expect:
+    """Assertions available to validation cases."""
+
+    @staticmethod
+    def equal(actual: Any, expected: Any, message: str = "") -> None:
+        _expect_equal(actual, expected, message)
+
+    @staticmethod
+    def not_equal(actual: Any, expected: Any, message: str = "") -> None:
+        _expect_not_equal(actual, expected, message)
+
+    @staticmethod
+    def is_true(value: bool, message: str = "") -> None:
+        _expect_is_true(value)(message)
+
+    @staticmethod
+    def is_false(value: bool, message: str = "") -> None:
+        _expect_is_false(value)(message)
+
+    @staticmethod
+    def is_empty(value: Any, message: str = "") -> None:
+        _expect_is_empty(value, message)
+
+    @staticmethod
+    def is_some(value: Any, message: str = "") -> None:
+        _expect_is_some(value, message)
+
+    @staticmethod
+    def string_contains(needle: str, value: str, message: str = "") -> None:
+        _expect_string_contains(needle, value, message)
+
+
+class FrontmatterLanguage:
+    """Supported validation-package frontmatter languages."""
+
+    FSHARP = FrontmatterLanguage_FSharpFrontmatter()
+    PYTHON = FrontmatterLanguage_PythonFrontmatter()
+
+    @staticmethod
+    def from_string(value: str):
+        return _frontmatter_language_from_string(value)
+
+
+class BadgeColor:
+    RED = BadgeColor_RED
+    ORANGE = BadgeColor_ORANGE_2
+    GREEN = BadgeColor_GREEN
+
+
+class BadgeStyle:
+    DEFAULT = BadgeStyle_Default()
+    GITLAB_SCOPED = BadgeStyle_GitLabScoped()
+
+
+def author(
+    full_name: str,
+    *,
+    email: str | None = None,
+    affiliation: str | None = None,
+    affiliation_link: str | None = None,
+) -> Author:
+    """Create validation-package author metadata."""
+    return _create_author(full_name, email, affiliation, affiliation_link)
+
+
+def ontology_annotation(
+    name: str,
+    *,
+    term_source_ref: str | None = None,
+    term_accession_number: str | None = None,
+) -> OntologyAnnotation:
+    """Create a validation-package tag."""
+    return _create_ontology_annotation(name, term_source_ref, term_accession_number)
+
+
+def semver(
+    major: int,
+    minor: int,
+    patch: int,
+    *,
+    pre_release: str | None = None,
+    build_metadata: str | None = None,
+) -> SemVer:
+    return _create_semver(major, minor, patch, pre_release, build_metadata)
+
+
+class Setup:
+    """Construct validation-package metadata and validation-case collections."""
+
+    @staticmethod
+    def metadata(
+        name: str,
+        summary: str,
+        description: str,
+        major_version: int,
+        minor_version: int,
+        patch_version: int,
+        programming_language: str = "python",
+        *,
+        pre_release_version_suffix: str | None = None,
+        build_metadata_version_suffix: str | None = None,
+        publish: bool | None = None,
+        authors: Iterable[Author] | None = None,
+        tags: Iterable[OntologyAnnotation] | None = None,
+        release_notes: str | None = None,
+        cqc_hook_endpoint: str | None = None,
+    ) -> ValidationPackageMetadata:
+        return _create_metadata(
+            name,
+            summary,
+            description,
+            major_version,
+            minor_version,
+            patch_version,
+            programming_language,
+            pre_release_version_suffix,
+            build_metadata_version_suffix,
+            publish,
+            None if authors is None else list(authors),
+            None if tags is None else list(tags),
+            release_notes,
+            cqc_hook_endpoint,
+        )
+
+    @staticmethod
+    def metadata_from_frontmatter(frontmatter: str, language: Any = FrontmatterLanguage.PYTHON) -> ValidationPackageMetadata:
+        return _metadata_from_frontmatter(frontmatter, language)
+
+    @staticmethod
+    def metadata_from_script(script_path: str) -> ValidationPackageMetadata:
+        """Read metadata from the leading frontmatter of a ``.py`` or ``.fsx`` script."""
+        return _metadata_from_script(script_path)
+
+    @staticmethod
+    def validation_package(
+        metadata: ValidationPackageMetadata,
+        *,
+        critical: Iterable[Any] | None = None,
+        non_critical: Iterable[Any] | None = None,
+    ) -> ARCValidationPackage:
+        return _create_validation_package(metadata, _tests(critical), _tests(non_critical))
+
+    @staticmethod
+    def validation_package_from_script(
+        script_path: str,
+        *,
+        critical: Iterable[Any] | None = None,
+        non_critical: Iterable[Any] | None = None,
+    ) -> ARCValidationPackage:
+        """Create a validation package using metadata parsed from its script frontmatter."""
+        return Setup.validation_package(
+            Setup.metadata_from_script(script_path),
+            critical=critical,
+            non_critical=non_critical,
+        )
+
+
+class Execute:
+    """Run validation packages and write their standard result artifacts."""
+
+    @staticmethod
+    def validation(package: ARCValidationPackage, *, payload: Mapping[str, Any] | None = None) -> ValidationSummary:
+        return _validate(None if payload is None else dict(payload))(package)
+
+    @staticmethod
+    def validation_async(package: ARCValidationPackage, *, payload: Mapping[str, Any] | None = None):
+        return _validate_async(None if payload is None else dict(payload))(package)
+
+    @staticmethod
+    def summary_creation(path: str, summary: ValidationSummary) -> None:
+        _create_summary(path)(summary)
+
+    @staticmethod
+    def junit_report_creation(path: str, summary: ValidationSummary) -> None:
+        _create_junit_report(path)(summary)
+
+    @staticmethod
+    def badge_creation(
+        path: str,
+        label_text: str,
+        summary: ValidationSummary,
+        *,
+        value_suffix: str | None = None,
+        thresholds: Mapping[str, str] | None = None,
+        default_color: str | None = None,
+    ) -> None:
+        _create_badge(path, label_text, value_suffix, _thresholds(thresholds), default_color)(summary)
+
+    @staticmethod
+    def validation_pipeline(
+        package: ARCValidationPackage,
+        base_path: str,
+        *,
+        badge_label_text: str | None = None,
+        value_suffix: str | None = None,
+        thresholds: Mapping[str, str] | None = None,
+        default_color: str | None = None,
+        payload: Mapping[str, Any] | None = None,
+    ) -> None:
+        _validation_pipeline(
+            base_path,
+            badge_label_text,
+            value_suffix,
+            _thresholds(thresholds),
+            default_color,
+            None if payload is None else dict(payload),
+        )(package)
+
+
+class BadgeCreation:
+    """Create badges directly from test results or validation summaries."""
+
+    @staticmethod
+    def from_test_results(
+        label_text: str,
+        results: TestRunResults,
+        *,
+        value_suffix: str | None = None,
+        thresholds: Mapping[str, str] | None = None,
+        default_color: str | None = None,
+    ) -> Badge:
+        return _badge_from_test_results(label_text, value_suffix, _thresholds(thresholds), default_color)(results)
+
+    @staticmethod
+    def from_validation_summary(
+        label_text: str,
+        summary: ValidationSummary,
+        *,
+        value_suffix: str | None = None,
+        thresholds: Mapping[str, str] | None = None,
+        default_color: str | None = None,
+    ) -> Badge:
+        return _badge_from_validation_summary(label_text, value_suffix, _thresholds(thresholds), default_color)(summary)
+
+
+__all__ = [
+    "ARCValidationPackage",
+    "Author",
+    "Badge",
+    "BadgeColor",
+    "BadgeCreation",
+    "BadgeStyle",
+    "Errored",
+    "Execute",
+    "Expect",
+    "Failed",
+    "FrontmatterLanguage",
+    "Ignored",
+    "OntologyAnnotation",
+    "Passed",
+    "SemVer",
+    "Setup",
+    "TestRunEntry",
+    "TestRunResults",
+    "ValidationPackageMetadata",
+    "ValidationPackageSummary",
+    "ValidationResult",
+    "ValidationSummary",
+    "author",
+    "combine_test_run_results",
+    "errored_test_entries",
+    "failed_test_entries",
+    "focused_test_case",
+    "ignored_test_entries",
+    "ontology_annotation",
+    "passed_test_entries",
+    "pending_test_case",
+    "run_tests_with_results",
+    "run_tests_with_results_async",
+    "semantic_version",
+    "semver",
+    "semver_to_string",
+    "test_case",
+    "test_case_async",
+    "test_list",
+    "to_json",
+    "to_junit_xml",
+    "to_nunit_xml",
+    "try_parse_semver",
+    "write_json",
+    "write_junit_xml",
+    "write_nunit_xml",
+]