Merge pull request #17 from Medical-Event-Data-Standard/dev

Release Candidate 0.1

Author: mmcdermott

.github/workflows/tests.yaml

@@ -31,10 +31,6 @@ jobs:
         run: |
           pytest -v --cov=src
 
-      - name: Check README code snippets
-        run: |
-          python -m doctest README.md
-
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4.0.1
         with:

README.md

@@ -0,0 +1,44 @@
+"""Test set-up and fixtures code."""
+
+import json
+import tempfile
+from contextlib import contextmanager
+from datetime import datetime
+from functools import partial
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+@contextmanager
+def print_warnings(caplog: pytest.LogCaptureFixture):
+    """Captures all logged warnings within this context block and prints them upon exit.
+
+    This is useful in doctests, where you want to show printed outputs for documentation and testing purposes.
+    """
+
+    n_current_records = len(caplog.records)
+
+    with caplog.at_level("WARNING"):
+        yield
+    # Print all captured warnings upon exit
+    for record in caplog.records[n_current_records:]:
+        print(f"Warning: {record.getMessage()}")
+
+
+@pytest.fixture(autouse=True)
+def _setup_doctest_namespace(
+    doctest_namespace: dict[str, Any],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    doctest_namespace.update(
+        {
+            "MagicMock": MagicMock,
+            "patch": patch,
+            "print_warnings": partial(print_warnings, caplog),
+            "json": json,
+            "datetime": datetime,
+            "tempfile": tempfile,
+        }
+    )

conftest.py

@@ -0,0 +1,28 @@
+"""Generate the code reference pages."""
+
+import re
+from pathlib import Path
+
+import mkdocs_gen_files
+
+root = Path(__file__).parent.parent
+readme = root / "README.md"
+
+# Src links are of the form `(src/.../*.py)`.
+SRC_LINK_RE = re.compile(r"\(src/[^)]+\.py\)")
+
+if not readme.is_file():
+    raise FileNotFoundError(f"{readme} not found")
+
+readme_lines = readme.read_text().splitlines()
+
+remapped_lines = []
+for line in readme_lines:
+    if SRC_LINK_RE.search(line):
+        # Replace src/.../*.py with the corresponding markdown file
+        line = SRC_LINK_RE.sub(lambda m: f"(api/{m.group(0)[5:-4]})", line)
+    remapped_lines.append(line)
+
+home_path = "index.md"
+with mkdocs_gen_files.open(home_path, "w") as fd:
+    fd.write("\n".join(remapped_lines))

docs/copy_README.py

@@ -24,6 +24,7 @@ markdown_extensions:
   - pymdownx.tabbed:
       alternate_style: true
   - pymdownx.superfences
+  - github-callouts
 
 extra_javascript:
   - javascripts/mathjax.js
@@ -34,9 +35,12 @@ plugins:
   - gen-files:
       scripts:
         - docs/gen_ref_pages.py
+        - docs/copy_README.py
   - literate-nav:
       nav_file: SUMMARY.md
   - section-index
   - mkdocstrings
   - git-authors
   - git-revision-date-localized
+
+watch: [src, README.md]

mkdocs.yml

@@ -30,19 +30,24 @@ tests = ["pytest", "pytest-cov[toml]"]
 docs = [
   "mkdocs==1.6.1", "mkdocs-material==9.6.7", "mkdocstrings[python,shell]==0.28.2", "mkdocs-gen-files==0.5.0",
   "mkdocs-literate-nav==0.6.1", "mkdocs-section-index==0.3.9", "mkdocs-git-authors-plugin==0.9.2",
-  "mkdocs-git-revision-date-localized-plugin==1.3.0"
+  "mkdocs-git-revision-date-localized-plugin==1.3.0", "markdown-callouts",
 ]
 
+[project.urls]
+Homepage = "https://github.com/mmcdermott/flexible_schema"
+Issues = "https://github.com/mmcdermott/flexible_schema/issues"
+
 [tool.pytest.ini_options]
 addopts = [
   "--color=yes",
   "--doctest-modules",
   "--ignore=docs",
+  "--doctest-glob=README.md",
 ]
+doctest_optionflags = ["NORMALIZE_WHITESPACE", "ELLIPSIS"]
 
-[project.urls]
-Homepage = "https://github.com/mmcdermott/flexible_schema"
-Issues = "https://github.com/mmcdermott/flexible_schema/issues"
+[tool.coverage.report]
+exclude_also = ["@(abc\\.)?abstractmethod"]
 
 [tool.ruff]
 target-version = "py310"

pyproject.toml

@@ -1,5 +1,5 @@
-from .base import Optional, Schema, SchemaValidationError
+from .base import Schema
+from .columns import Column, Nullability, Optional, Required
+from .exceptions import SchemaValidationError, TableValidationError
 from .json import JSONSchema
 from .pyarrow import PyArrowSchema
-
-__all__ = ["JSONSchema", "Optional", "PyArrowSchema", "Schema", "SchemaValidationError"]