py10x-universe 0.1.3__py3-none-any.whl

core_10x/unit_tests/test_documentation.py

@@ -0,0 +1,172 @@
+"""
+Test documentation examples by extracting and running code blocks at runtime.
+
+This module automatically extracts Python code blocks from documentation files
+and runs them as tests to ensure examples remain functional.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+from core_10x.ts_store import TsStore
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+# Add the project root to Python path for imports
+project_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+# Module-level variable for documentation files to avoid duplication
+DOCUMENTATION_FILES = [
+    'README.md',
+    'GETTING_STARTED.md',
+    'INSTALLATION.md',
+    'CONTRIBUTING.md',
+]
+
+
+def extract_code_blocks_from_file(filepath: Path) -> Generator[tuple[str, str], None, None]:
+    """Extract Python code blocks from a markdown file."""
+    content = filepath.read_text(encoding='utf-8')
+
+    # Find code blocks (```python ... ```)
+    pattern = r'```python\s*\n(.*?)\n```'
+    matches = re.findall(pattern, content, re.DOTALL)
+
+    for i, code_block in enumerate(matches, 1):
+        # Clean up the code block
+        code_block = code_block.strip()
+
+        # Skip empty blocks
+        if not code_block:
+            continue
+
+        # Generate a test name from the file and block number
+        test_name = f'{filepath.stem}_block_{i}'
+        yield test_name, code_block
+
+
+def extract_code_blocks_from_docs() -> Generator[tuple[str, str, str], None, None]:
+    """Extract all Python code blocks from documentation files."""
+    docs_dir = project_root
+
+    for doc_file in DOCUMENTATION_FILES:
+        filepath = docs_dir / doc_file
+        for test_name, code_block in extract_code_blocks_from_file(filepath):
+            yield f'{test_name}', code_block, doc_file
+
+
+def is_ui_code_block(code_block: str) -> bool:
+    """Check if a code block contains UI-related imports or usage."""
+    ui_indicators = [
+        'import ui_10x',
+        'from ui_10x',
+        'ui_10x.',
+    ]
+    return any(indicator in code_block for indicator in ui_indicators)
+
+
+def validate_python_syntax(code: str) -> bool:
+    """Validate that code has valid Python syntax."""
+    try:
+        ast.parse(code)
+        return True
+    except SyntaxError:
+        return False
+
+
+@pytest.mark.parametrize(
+    'test_name,code_block,future_annotations',
+    [
+        (name, code, future_annotations)
+        for name, code, src in extract_code_blocks_from_docs()
+        for future_annotations in (True, False)
+        if not is_ui_code_block(code)  # Skip UI code blocks - tested separately
+    ],
+)
+def test_documentation_code_block_execution(test_name: str, code_block: str, future_annotations: bool):
+    """Test that documentation code blocks can execute successfully."""
+    # Skip if code block is empty
+    if not code_block.strip():
+        pytest.skip('Empty code block')
+
+    # Validate syntax
+    assert validate_python_syntax(code_block), f'Syntax error in {test_name}'
+
+    doc_file_name = test_name.split('_block_')[0]
+    fake_module_name = f'__doc_test_{doc_file_name}__'
+    if fake_module_name not in sys.modules:
+        fake_module = type(sys)('module')
+        fake_module.__dict__.update(
+            {
+                '__name__': fake_module_name,
+                '__file__': f'<{doc_file_name}>',
+                '__builtins__': __builtins__,
+            }
+        )
+        sys.modules[fake_module_name] = fake_module
+    if future_annotations:
+        exec('from __future__ import annotations', fake_module.__dict__)
+
+    try:
+        exec(code_block, fake_module.__dict__)
+    finally:
+        # Clean up the fake module
+        if fake_module_name in sys.modules:
+            del sys.modules[fake_module_name]
+
+        TsStore.s_instances.clear()
+
+
+@pytest.mark.parametrize(
+    'test_name,code_block,source_file',
+    [
+        (f'{src}_{name}', code, src)
+        for name, code, src in extract_code_blocks_from_docs()
+        if is_ui_code_block(code)  # Only test UI code blocks
+    ],
+)
+def test_documentation_ui_code_block_syntax(test_name: str, code_block: str, source_file: str):
+    """Test that UI documentation code blocks have valid syntax (execution tested separately in UI tests)."""
+    # Skip if code block is empty
+    if not code_block.strip():
+        pytest.skip('Empty code block')
+
+    # Validate syntax only for UI blocks (execution requires async UI environment)
+    assert validate_python_syntax(code_block), f'Syntax error in UI code block {source_file} {test_name}'
+
+
+def test_documentation_files_and_code_blocks():
+    """Test that documentation files exist and contain Python code blocks."""
+    docs_dir = project_root
+    total_blocks = 0
+    ui_blocks = 0
+    core_blocks = 0
+
+    # Check that all expected documentation files exist
+    for filename in DOCUMENTATION_FILES:
+        filepath = docs_dir / filename
+        assert filepath.exists(), f'Documentation file {filename} not found'
+        assert filepath.stat().st_size > 0, f'Documentation file {filename} is empty'
+
+    # Check that files contain Python code blocks
+    for _name, code, _src in extract_code_blocks_from_docs():
+        total_blocks += 1
+        if is_ui_code_block(code):
+            ui_blocks += 1
+        else:
+            core_blocks += 1
+
+    # Ensure we found some code blocks
+    assert total_blocks > 0, 'No Python code blocks found in documentation'
+    assert core_blocks > 0, 'No core Python code blocks found in documentation'
+
+    # We expect some UI blocks but most should be core functionality
+    assert core_blocks >= ui_blocks, f'Expected more core blocks ({core_blocks}) than UI blocks ({ui_blocks})'

core_10x/unit_tests/test_environment_variables.py

@@ -0,0 +1,15 @@
+from core_10x.environment_variables import EnvVars
+from core_10x.xdate_time import XDateTime, date
+
+
+def test_env_vars_date_format_applies_to_xdatetime(monkeypatch):
+    # Change via environment variable and ensure it is applied on first access
+    custom_fmt = '%d/%m/%Y'
+    monkeypatch.setenv('XX_DATE_FORMAT', custom_fmt)
+
+    # Accessing EnvVars.date_format should convert and apply to XDateTime
+    fmt = EnvVars.date_format
+    assert fmt == custom_fmt
+
+    d = date(2024, 1, 2)
+    assert XDateTime.date_to_str(d) == '02/01/2024'

core_10x/unit_tests/test_filters.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from datetime import date  # noqa: TC003
+
+import pytest
+from core_10x.trait_filter import (
+    AND,
+    BETWEEN,
+    EQ,
+    GE,
+    GT,
+    IN,
+    LE,
+    LT,
+    NE,
+    NIN,
+    NOT_EMPTY,
+    OR,
+    f,
+)
+from core_10x.traitable import Traitable, XNone
+
+
+class Person(Traitable):
+    first_name: str
+    last_name: str
+    age: int
+    dob: date
+
+
+def test_filters():
+    p = Person(first_name='Sasha', last_name='Davidovich')
+
+    r = OR(f(age=BETWEEN(50, 70), first_name=NE('Sasha')), f(age=17))
+
+    assert r.prefix_notation() == {'$or': [{'age': {'$gte': 50, '$lte': 70}, 'first_name': {'$ne': 'Sasha'}}, {'age': {'$eq': 17}}]}
+    assert not r.eval(p)
+
+
+def test_or():
+    p = Person(first_name='Sasha', last_name='Davidovich')
+    r1, r2 = f(age=BETWEEN(50, 70)), f(first_name=EQ('Sasha'))
+    r3 = OR(r1, r2)
+    r4 = OR(r1)
+    r5 = OR(r2)
+    r6 = OR()
+    assert r1.prefix_notation() == {'age': {'$gte': 50, '$lte': 70}}
+    assert r2.prefix_notation() == {'first_name': {'$eq': 'Sasha'}}
+    assert r3.prefix_notation() == {'$or': [r1.prefix_notation(), r2.prefix_notation()]}
+
+    assert r4.prefix_notation() == r1.prefix_notation()
+    assert r5.prefix_notation() == r2.prefix_notation()
+    assert r6.prefix_notation() == {'$in': []}
+
+    assert not r1.eval(p)
+    assert r2.eval(p)
+    assert r3.eval(p)
+    assert not r4.eval(p)
+    assert r5.eval(p)
+    assert not r6.eval(p)
+
+    r7 = OR(OR(), OR())
+    assert r7.prefix_notation() == {'$in': []}
+    assert not r7.eval(p)
+
+    r8 = OR(OR(), AND())
+    assert r7.prefix_notation() == {'$in': []}
+    assert r8.eval(p)
+
+
+def test_and():
+    p = Person(first_name='Sasha', last_name='Davidovich')
+
+    r1, r2 = f(age=BETWEEN(50, 70)), f(first_name=EQ('Sasha'))
+    r3 = AND(r1, r2)
+    r4 = AND(r1)
+    r5 = AND(r2)
+    r6 = AND()
+    assert r1.prefix_notation() == {'age': {'$gte': 50, '$lte': 70}}
+    assert r2.prefix_notation() == {'first_name': {'$eq': 'Sasha'}}
+    assert r3.prefix_notation() == {'$and': [r1.prefix_notation(), r2.prefix_notation()]}
+
+    assert r4.prefix_notation() == r1.prefix_notation()
+    assert r5.prefix_notation() == r2.prefix_notation()
+    assert r6.prefix_notation() == {}
+
+    assert not r1.eval(p)
+    assert r2.eval(p)
+    assert not r3.eval(p)
+    assert not r4.eval(p)
+    assert r5.eval(p)
+    assert r6.eval(p)
+
+    r7 = AND(AND(), AND())
+    assert r7.prefix_notation() == {}
+    assert r7.eval(p)
+
+    r8 = AND(AND(), OR())
+    assert r8.prefix_notation() == {'$in': []}
+    assert not r8.eval(p)
+
+
+def test_simple_ops_eval_and_prefix():
+    assert EQ(5).eval(5)
+    assert not EQ(5).eval(4)
+    assert EQ('x').prefix_notation() == {'$eq': 'x'}
+
+    assert NE(5).eval(4)
+    assert not NE(5).eval(5)
+    assert NE('x').prefix_notation() == {'$ne': 'x'}
+
+    assert GT(5).eval(6)
+    assert not GT(5).eval(5)
+    assert GT(5).prefix_notation() == {'$gt': 5}
+
+    assert GE(5).eval(5)
+    assert GE(5).eval(6)
+    assert not GE(5).eval(4)
+    assert GE(5).prefix_notation() == {'$gte': 5}
+
+    assert LT(5).eval(4)
+    assert not LT(5).eval(5)
+    assert LT(5).prefix_notation() == {'$lt': 5}
+
+    assert LE(5).eval(5)
+    assert LE(5).eval(4)
+    assert not LE(5).eval(6)
+    assert LE(5).prefix_notation() == {'$lte': 5}
+
+
+def test_in_nin():
+    assert IN([1, 2, 3]).eval(2)
+    assert not IN([1, 2, 3]).eval(4)
+    assert IN((1, 2)).prefix_notation() == {'$in': (1, 2)}
+
+    assert NIN([1, 2, 3]).eval(4)
+    assert not NIN([1, 2, 3]).eval(2)
+    assert NIN([1, 2]).prefix_notation() == {'$nin': [1, 2]}
+
+
+def test_between_bounds_and_prefix():
+    b = BETWEEN(1, 5)
+    assert b.eval(3)
+    assert b.eval(1)
+    assert b.eval(5)
+    assert not b.eval(0)
+    assert not b.eval(6)
+    assert b.prefix_notation() == {'$gte': 1, '$lte': 5}
+
+    b_ex = BETWEEN(1, 5, bounds=(False, False))
+    assert b_ex.eval(2)
+    assert not b_ex.eval(1)
+    assert not b_ex.eval(5)
+    assert b_ex.prefix_notation() == {'$gt': 1, '$lt': 5}
+
+
+def test_not_empty_and_bool_ops_eval_and_prefix():
+    assert NOT_EMPTY().eval('abc')
+    assert not NOT_EMPTY().eval('')
+    with pytest.raises(NotImplementedError):
+        NOT_EMPTY().prefix_notation()
+
+    a = AND(EQ(5), GT(3))
+    assert a.eval(5)
+    assert not a.eval(3)
+    assert a.prefix_notation() == {'$and': [{'$eq': 5}, {'$gt': 3}]}
+
+    o = OR(EQ(1), EQ(2))
+    assert o.eval(1)
+    assert o.eval(2)
+    assert not o.eval(3)
+    assert o.prefix_notation() == {'$or': [{'$eq': 1}, {'$eq': 2}]}
+
+    # single-argument behaviors: prefix_notation returns inner dict
+    single_and = AND(EQ(7))
+    assert single_and.prefix_notation() == {'$eq': 7} or single_and.prefix_notation() == {'$eq': 7}
+
+    # empty BoolOp
+    assert OR().prefix_notation() == {'$in': []}
+    assert AND().prefix_notation() == {}
+
+
+def test_f_named_expressions_eval_and_prefix():
+    d = Person(age=10, first_name='Bob', last_name='')
+
+    # named expressions may be raw values (wrapped to EQ) or filters
+    filt = f(age=EQ(10), first_name='Bob')
+    assert filt.eval(d)
+    assert filt.prefix_notation() == {'age': {'$eq': 10}, 'first_name': {'$eq': 'Bob'}}
+
+    # mismatch
+    filt2 = f(age=EQ(11), first_name='Bob')
+    assert not filt2.eval(d)
+
+    # ensure f uses Person.get_value for named fields
+    assert f(age=10).eval(d)  # 10 wrapped as EQ(10) -> matches d.get_value('age') == 10
+    assert not f(age=9).eval(d)
+
+    # f with multiple named expressions
+    multi = f(age=EQ(10), first_name=NE('Alice'), last_name=NOT_EMPTY())
+    assert multi.eval(Person(age=10, first_name='Bob', last_name='Smith'))
+    assert not f(last_name=NOT_EMPTY()).eval(Person(last_name=''))  # empty string -> NOT_EMPTY false
+
+
+def test_named_serializers():
+    class P(Person):
+        @classmethod
+        def age_serialize(cls, t, v):
+            return f'age:{v}'  # noinspection PyUnusedLocal
+
+    trait = P.trait('age')
+
+    assert trait is P.trait('age')
+
+    assert trait.serialize_value(5) == 'age:5'
+
+    assert EQ(5).prefix_notation(trait=trait, traitable_class=P.s_bclass) == {'$eq': 'age:5'}
+
+    assert BETWEEN(1, 5).prefix_notation(trait=trait, traitable_class=P.s_bclass) == {
+        '$gte': 'age:1',
+        '$lte': 'age:5',
+    }
+
+    x = OR(f(age=LE(70)), f(first_name=NE('Sasha')), f(last_name=XNone))
+    assert x.prefix_notation(traitable_class=P.s_bclass) == {
+        '$or': [{'age': {'$lte': 'age:70'}}, {'first_name': {'$ne': 'Sasha'}}, {'last_name': {'$eq': None}}]
+    }
+
+    x = f(age=BETWEEN(50, 70), first_name=NE('Sasha'))
+
+    assert f(x, P.s_bclass).prefix_notation() == x.prefix_notation(traitable_class=P.s_bclass)
+
+    r = OR(f(age=BETWEEN(50, 70), first_name=NE('Sasha')), f(age=17))
+    assert r.prefix_notation(traitable_class=P.s_bclass) == {
+        '$or': [
+            {'age': {'$gte': 'age:50', '$lte': 'age:70'}, 'first_name': {'$ne': 'Sasha'}},
+            {'age': {'$eq': 'age:17'}},
+        ]
+    }