sphinxnotes-data 1.0a2__tar.gz → 1.0a4__tar.gz

{sphinxnotes_data-1.0a2/src/sphinxnotes_data.egg-info → sphinxnotes_data-1.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinxnotes-data
-Version: 1.0a2
+Version: 1.0a4
 Summary: Use reStructuredText/markdown to define, constrain, render, and analyze data in Sphinx documentations
 Author: Shengyu Zhang
 Maintainer: Shengyu Zhang

sphinxnotes_data-1.0a4/src/sphinxnotes/data/__init__.py

@@ -0,0 +1,83 @@
+"""
+sphinxnotes.data
+~~~~~~~~~~~~~~~~
+
+:copyright: Copyright 2025 by the Shengyu Zhang.
+:license: BSD, see LICENSE for details.
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from sphinx.util import logging
+
+from . import meta
+from .data import (
+    Registry,
+    Form,
+    BoolFlag,
+    OperFlag,
+    Value,
+    ValueWrapper,
+    RawData,
+    Data,
+    Field,
+    Schema,
+)
+from .template import Phase, Template
+from .render import (
+    Caller,
+    pending_node,
+    RenderedNode,
+    rendered_node,
+    rendered_inline_node,
+    BaseDataDefiner,
+    BaseDataDefineRole,
+    BaseDataDefineDirective,
+    StrictDataDefineDirective,
+)
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+"""Python API for other Sphinx extesions."""
+__all__ = [
+    'Registry',
+    'Form',
+    'BoolFlag',
+    'OperFlag',
+    'Value',
+    'ValueWrapper',
+    'RawData',
+    'Data',
+    'Field',
+    'Schema',
+    'Phase',
+    'Template',
+    'Caller',
+    'pending_node',
+    'RenderedNode',
+    'rendered_node',
+    'rendered_inline_node',
+    'BaseDataDefiner',
+    'BaseDataDefineRole',
+    'BaseDataDefineDirective',
+    'BaseDataDefineDirective',
+    'StrictDataDefineDirective',
+]
+
+logger = logging.getLogger(__name__)
+
+
+def setup(app: Sphinx):
+    meta.pre_setup(app)
+
+    from . import config, template, render, adhoc
+
+    config.setup(app)
+    template.setup(app)
+    render.setup(app)
+    adhoc.setup(app)
+
+    return meta.post_setup(app)

sphinxnotes_data-1.0a4/src/sphinxnotes/data/config.py

@@ -0,0 +1,37 @@
+"""
+sphinxnotes.data.config
+~~~~~~~~~~~~~~~~~~~~~~~
+
+:copyright: Copyright 2025~2026 by the Shengyu Zhang.
+:license: BSD, see LICENSE for details.
+"""
+
+from sphinx.application import Sphinx
+from sphinx.config import Config as SphinxConfig
+
+
+class Config:
+    """Global config of extesion."""
+
+    template_debug: bool
+
+    date_fmt: str
+    time_fmt: str
+    datetime_fmt: str
+
+
+def _config_inited(app: Sphinx, config: SphinxConfig) -> None:
+    Config.template_debug = config.data_template_debug
+
+    Config.date_fmt = config.data_date_fmt
+    Config.time_fmt = config.data_time_fmt
+    Config.datetime_fmt = config.data_datetime_fmt
+
+
+def setup(app: Sphinx):
+    app.add_config_value('data_template_debug', False, '', bool)
+    app.add_config_value('data_date_fmt', '%Y-%m-%d', '', str)
+    app.add_config_value('data_time_fmt', '%H:%M:%S', '', str)
+    app.add_config_value('data_datetime_fmt', '%Y-%m-%d %H:%M:%S', '', str)
+
+    app.connect('config-inited', _config_inited)

{sphinxnotes_data-1.0a2 → sphinxnotes_data-1.0a4}/src/sphinxnotes/data/data.py

@@ -3,16 +3,18 @@ from typing import TYPE_CHECKING
 import re
 from dataclasses import dataclass, asdict, field as dataclass_field
 from ast import literal_eval
+from datetime import date, time, datetime
+
+from .config import Config
 
 if TYPE_CHECKING:
     from typing import Any, Callable, Generator, Self, Literal
 
+# =====================================
+# Basic classes: Value, Form, Flag, ...
+# =====================================
 
-#########################################
-# Basic classes: Value, Form, Flag, ... #
-#########################################
-
-type PlainValue = bool | int | float | str
+type PlainValue = bool | int | float | str | date | time | datetime
 type Value = None | PlainValue | list[PlainValue]
 
 
@@ -24,14 +26,9 @@ class ValueWrapper:
         if self.v is None:
             return None
         if isinstance(self.v, list):
-            if len(self.v) == 0:
-                return None
-            return self.v[0]
+            return self.v[0] if len(self.v) else None
         return self.v
 
-    def as_str(self) -> str | None:
-        return str(self.as_plain())
-
     def as_list(self) -> list[PlainValue]:
         if self.v is None:
             return []
@@ -40,13 +37,22 @@ class ValueWrapper:
         else:
             return [self.v]
 
+    def as_str(self) -> str | None:
+        v = self.as_plain()
+        return self._strify(v) if v is not None else None
+
     def as_str_list(self) -> list[str]:
-        if self.v is None:
-            return []
-        elif isinstance(self.v, list):
-            return [str(x) for x in self.v]
-        else:
-            return [str(self.v)]
+        return [self._strify(x) for x in self.as_list()]
+
+    @staticmethod
+    def _strify(v: PlainValue) -> str:
+        if isinstance(v, datetime):
+            return v.strftime(Config.datetime_fmt)
+        elif isinstance(v, date):
+            return v.strftime(Config.date_fmt)
+        elif isinstance(v, time):
+            return v.strftime(Config.time_fmt)
+        return str(v)
 
 
 @dataclass(frozen=True)
@@ -77,9 +83,44 @@ class OperFlag(Flag):
     store: FlagStore = 'assign'
 
 
-############
-# Registry #
-############
+# ========
+# Registry
+# ========
+
+
+def _bool_conv(v: str | None) -> bool:
+    v = v.lower().strip() if v is not None else None
+    if v in ('true', 'yes', '1', 'on', 'y', ''):
+        return True
+    if v in ('false', 'no', '0', 'off', 'n', None):
+        return False
+    # Same to :meth:`directives.flag`.
+    raise ValueError(f'no argument is allowed; "{v}" supplied')
+
+
+def _str_conv(v: str) -> str:
+    try:
+        vv = literal_eval(v)
+    except (ValueError, SyntaxError):
+        return v
+    return vv if isinstance(vv, str) else v
+
+
+def _date_conv(v: str) -> date:
+    return datetime.strptime(v, Config.date_fmt).date()
+
+
+def _time_conv(v: str) -> time:
+    return datetime.strptime(v, Config.time_fmt).time()
+
+
+def _datetime_conv(v: str) -> datetime:
+    return datetime.strptime(v, Config.datetime_fmt)
+
+
+_required_flag = BoolFlag('required')
+
+_sep_flag = OperFlag('sep', etype=str)
 
 
 class Registry:
@@ -95,33 +136,19 @@ class Registry:
         'num': float,
         'str': str,
         'string': str,
+        'date': date,
+        'time': time,
+        'datetime': datetime,
     }
 
-    """Internal type converters."""
-
-    @staticmethod
-    def _bool_conv(v: str | None) -> bool:
-        v = v.lower().strip() if v is not None else None
-        if v in ('true', 'yes', '1', 'on', 'y', ''):
-            return True
-        if v in ('false', 'no', '0', 'off', 'n', None):
-            return False
-        # Same to :meth:`directives.flag`.
-        raise ValueError(f'no argument is allowed; "{v}" supplied')
-
-    @staticmethod
-    def _str_conv(v: str) -> str:
-        try:
-            vv = literal_eval(v)
-        except (ValueError, SyntaxError):
-            return v
-        return vv if isinstance(vv, str) else v
-
     convs: dict[type, Callable[[str], Any]] = {
         bool: _bool_conv,
         int: int,
         float: float,
         str: _str_conv,
+        date: _date_conv,
+        time: _time_conv,
+        datetime: _datetime_conv,
     }
 
     forms: dict[str, Form] = {
@@ -132,9 +159,6 @@ class Registry:
 
     """Builtin flags."""
 
-    _required_flag = BoolFlag('required')
-    _sep_flag = OperFlag('sep', etype=str)
-
     flags: dict[str, BoolFlag] = {
         'required': _required_flag,
         'require': _required_flag,
@@ -147,9 +171,9 @@ class Registry:
     }
 
 
-##########################
-# Data, Field and Schema #
-##########################
+# ======================
+# Data, Field and Schema
+# ======================
 
 
 @dataclass
@@ -216,7 +240,7 @@ class Field:
             if self.etype is bool:
                 # Special case: A single bool field is valid even when
                 # value is not supplied.
-                return Registry._bool_conv(rawval)
+                return _bool_conv(rawval)
             return None
 
         # Strip whitespace. TODO: supported unchanged?
@@ -305,7 +329,7 @@ class DSLParser:
 
             self.field.etype = Registry.etypes[etype]
             self.field.ctype = Registry.forms[form].ctype
-            self.field.flags[Registry._sep_flag.name] = Registry.forms[form].sep
+            self.field.flags[_sep_flag.name] = Registry.forms[form].sep
             return
 
         # Match: Type only (e.g., "int")
@@ -341,7 +365,7 @@ class DSLParser:
                 )
 
             # Deal with builtin flags.
-            if flag == Registry._sep_flag:
+            if flag == _sep_flag:
                 # ctype default to list if 'sep by' is used without a 'xxx of xxx'.
                 if self.field.ctype is None:
                     self.field.ctype = list
@@ -360,7 +384,7 @@ class DSLParser:
 @dataclass(frozen=True)
 class Schema(object):
     name: Field | None
-    attrs: dict[str, Field]
+    attrs: dict[str, Field] | Field
     content: Field | None
 
     @classmethod
@@ -403,8 +427,8 @@ class Schema(object):
         else:
             rawattrs = data.attrs.copy()
             for key, field in self.attrs.items():
-                rawval = rawattrs.pop(key)
-                attrs[key] = self._parse_single(('attrs.' + key, field), rawval)
+                if rawval := rawattrs.pop(key, None):
+                    attrs[key] = self._parse_single(('attrs.' + key, field), rawval)
             for key, rawval in rawattrs.items():
                 raise ValueError(f'unknown attr: "{key}"')
 
@@ -415,35 +439,29 @@ class Schema(object):
 
         return Data(name, attrs, content)
 
-    def fields(
-        self, pred: Callable[[Field], bool] | None = None
-    ) -> Generator[tuple[str, Field]]:
-        def ok(f: Field) -> bool:
-            return not pred or pred(f)
-
-        if self.name and ok(self.name):
+    def fields(self) -> Generator[tuple[str, Field]]:
+        if self.name:
             yield 'name', self.name
 
-        for name, field in self.attrs.items():
-            if ok(field):
+        if isinstance(self.attrs, Field):
+            yield 'attrs', self.attrs
+        else:
+            for name, field in self.attrs.items():
                 yield name, field
 
-        if self.content and ok(self.content):
+        if self.content:
             yield 'content', self.content
 
-    def items(
-        self, data: Data, pred: Callable[[Field], bool] | None = None
-    ) -> Generator[tuple[str, Field, Value]]:
-        def ok(f: Field) -> bool:
-            return not pred or pred(f)
-
-        if self.name and ok(self.name):
+    def items(self, data: Data) -> Generator[tuple[str, Field, Value]]:
+        if self.name:
             yield 'name', self.name, data.name
 
-        for name, field in self.attrs.items():
-            if not ok(field):
-                continue
-            yield name, field, data.attrs.get(name)
+        if isinstance(self.attrs, Field):
+            for name, val in data.attrs:
+                yield name, self.attrs, val
+        else:
+            for name, field in self.attrs.items():
+                yield name, field, data.attrs.get(name)
 
-        if self.content and ok(self.content):
+        if self.content:
             yield 'content', self.content, data.content

{sphinxnotes_data-1.0a2 → sphinxnotes_data-1.0a4}/src/sphinxnotes/data/preset.py

@@ -1,5 +1,16 @@
+"""
+sphinxnotes.data.preset
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Preset templates and schemas.
+
+:copyright: Copyright 2026 by the Shengyu Zhang.
+:license: BSD, see LICENSE for details.
+"""
+
 from .data import Schema, Field
 from .template import Template, Phase
+from .config import Config
 
 
 class Directive:
@@ -10,7 +21,7 @@ class Directive:
     @staticmethod
     def template() -> Template:
         return Template(
-            debug=True,
+            debug=Config.template_debug,
             phase=Phase.Parsing,
             text=""".. note::
 
@@ -36,7 +47,7 @@ class Role:
     @staticmethod
     def template() -> Template:
         return Template(
-            debug=True,
+            debug=Config.template_debug,
             phase=Phase.Parsing,
             text="""``{{ content or 'None' }}``
 :abbr:`ⁱⁿᶠᵒ (This is a default template for rendering the data your deinfed

{sphinxnotes_data-1.0a2 → sphinxnotes_data-1.0a4/src/sphinxnotes_data.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinxnotes-data
-Version: 1.0a2
+Version: 1.0a4
 Summary: Use reStructuredText/markdown to define, constrain, render, and analyze data in Sphinx documentations
 Author: Shengyu Zhang
 Maintainer: Shengyu Zhang

{sphinxnotes_data-1.0a2 → sphinxnotes_data-1.0a4}/src/sphinxnotes_data.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ docs/_static/.gitkeep
 docs/_static/sphinx-notes.png
 src/sphinxnotes/data/__init__.py
 src/sphinxnotes/data/adhoc.py
+src/sphinxnotes/data/config.py
 src/sphinxnotes/data/data.py
 src/sphinxnotes/data/extra_contexts.py
 src/sphinxnotes/data/meta.py

{sphinxnotes_data-1.0a2 → sphinxnotes_data-1.0a4}/tests/test_data.py

@@ -1,22 +1,23 @@
 import os
 import sys
 import unittest
-from textwrap import dedent
+from datetime import date, time, datetime
 
 sys.path.insert(0, os.path.abspath('./src/sphinxnotes'))
 
 from data.data import Field, Registry, BoolFlag, OperFlag
+from data.config import Config
 
 class TestFieldParser(unittest.TestCase):
 
     # ==========================
     # Basic Types
     # ==========================
-    
+
     def test_basic_scalar(self):
         f = Field.from_dsl('int')
         self.assertEqual(f.parse('123'), 123)
-        
+
         f = Field.from_dsl('bool')
         self.assertTrue(f.parse('true'))
         self.assertTrue(f.parse('y'))
@@ -89,7 +90,7 @@ class TestFieldParser(unittest.TestCase):
         self.assertTrue(f.uniq)
         f = Field.from_dsl(r'int')
         self.assertFalse(f.uniq)
-        
+
         # Test default value.
         Registry.flags['ref'] = BoolFlag('ref', default=True)
         f = Field.from_dsl(r'int, ref')
@@ -103,7 +104,7 @@ class TestFieldParser(unittest.TestCase):
         self.assertEqual(f.group, 'foo')
         f = Field.from_dsl(r'int')
         self.assertEqual(f.group, None)
-        
+
         # Test append
         Registry.byflags['index'] = OperFlag('index', etype=str, store='append')
         f = Field.from_dsl(r'int, index by year')
@@ -111,6 +112,23 @@ class TestFieldParser(unittest.TestCase):
         f = Field.from_dsl(r'int, index by year, index by month')
         self.assertEqual(f.index, ['year', 'month'])
 
+    def test_datetime(self):
+        # FIXME: side effects
+        Config.date_fmt = '%Y-%m-%d'
+        Config.time_fmt = '%H:%M:%S'
+        Config.datetime_fmt = '%Y-%m-%d %H:%M:%S'
+
+        val = Field.from_dsl('date').parse('2023-10-01')
+        self.assertIsInstance(val, date)
+        self.assertEqual(val, date(2023, 10, 1))
+
+        val = Field.from_dsl('time').parse('14:30:00')
+        self.assertIsInstance(val, time)
+        self.assertEqual(val, time(14, 30, 0))
+
+        val = Field.from_dsl('datetime').parse('2023-10-01 14:30:00')
+        self.assertIsInstance(val, datetime)
+        self.assertEqual(val, datetime(2023, 10, 1, 14, 30, 0))
 
     # ==========================
     # Errors
@@ -119,9 +137,23 @@ class TestFieldParser(unittest.TestCase):
     def test_unsupported_modifier(self):
         with self.assertRaisesRegex(ValueError, 'unsupported type'):
             Field.from_dsl('list of unknown')
-            
+
         with self.assertRaisesRegex(ValueError, 'unknown modifier'):
             Field.from_dsl('int, random_mod')
 
+
+    def test_invalid_formats(self):
+        # FIXME: side effects
+        Config.date_fmt = '%Y-%m-%d'
+        Config.time_fmt = '%H:%M:%S'
+        Config.datetime_fmt = '%Y-%m-%d %H:%M:%S'
+
+        with self.assertRaisesRegex(ValueError, 'failed to parse'):
+            Field.from_dsl('date').parse('not-a-date')
+
+        with self.assertRaisesRegex(ValueError, 'failed to parse'):
+            Field.from_dsl('datetime').parse('2023/13/45')
+
+
 if __name__ == '__main__':
     unittest.main()

sphinxnotes_data-1.0a2/src/sphinxnotes/data/__init__.py

@@ -1,62 +0,0 @@
-"""
-sphinxnotes.data
-~~~~~~~~~~~~~~~~
-
-:copyright: Copyright 2025 by the Shengyu Zhang.
-:license: BSD, see LICENSE for details.
-"""
-
-from __future__ import annotations
-from typing import TYPE_CHECKING
-
-from sphinx.util import logging
-
-from . import meta
-from .data import (
-    Registry, Form, BoolFlag, OperFlag, 
-    Value, ValueWrapper,
-    RawData, Data,
-    Field, Schema,
-)
-from .template import Phase, Template
-from .render import (
-    Caller,
-    pending_node, RenderedNode, rendered_node, rendered_inline_node,
-    BaseDataDefiner, BaseDataDefineRole, BaseDataDefineDirective,
-    StrictDataDefineDirective,
-)
-
-if TYPE_CHECKING:
-    from sphinx.application import Sphinx
-
-
-"""Python API for other Sphinx extesions."""
-__all__ = [
-    'Registry', 'Form', 'BoolFlag', 'OperFlag',
-    'Value', 'ValueWrapper',
-    'RawData', 'Data',
-    'Field', 'Schema',
-
-    'Phase', 'Template',
-
-    'Caller',
-    'pending_node', 'RenderedNode', 'rendered_node', 'rendered_inline_node',
-    'BaseDataDefiner', 'BaseDataDefineRole', 'BaseDataDefineDirective',
-    'BaseDataDefineDirective', 'StrictDataDefineDirective',
-]
-
-logger = logging.getLogger(__name__)
-
-
-def setup(app: Sphinx):
-    meta.pre_setup(app)
-
-    from . import template
-    from . import render
-    from . import adhoc
-
-    template.setup(app)
-    render.setup(app)
-    adhoc.setup(app)
-
-    return meta.post_setup(app)