docwrap 0.1.0__py3-none-any.whl

docwrap/__init__.py

@@ -0,0 +1,59 @@
+"""Public facade for docwrap's supported library API.
+
+Example:
+    >>> import docwrap
+    >>> docwrap.wrap_source('def f(): pass')
+    'def f(): pass'
+"""
+
+from docwrap._config import clear_config_cache, resolve_config
+from docwrap._core import check, wrap_file_report, wrap_source, wrap_source_report
+from docwrap._exceptions import (
+    DocwrapConfigWarning,
+    DocwrapSkipWarning,
+    InvalidLineLengthError,
+    UnknownStyleError,
+)
+from docwrap._styles import get_styles
+from docwrap._types import (
+    DEFAULT_LINE_LENGTH,
+    DetailLevel,
+    DocstringChange,
+    DocstringSkip,
+    DocwrapConfig,
+    FillStyle,
+    ReflowMode,
+    SkipCode,
+    StyleName,
+    SummaryStart,
+    WrapCheckResult,
+    WrapReport,
+    WrapStatus,
+)
+
+__all__ = [
+    'DEFAULT_LINE_LENGTH',
+    'DetailLevel',
+    'DocstringChange',
+    'DocstringSkip',
+    'DocwrapConfig',
+    'DocwrapConfigWarning',
+    'DocwrapSkipWarning',
+    'FillStyle',
+    'InvalidLineLengthError',
+    'ReflowMode',
+    'SkipCode',
+    'StyleName',
+    'SummaryStart',
+    'UnknownStyleError',
+    'WrapCheckResult',
+    'WrapReport',
+    'WrapStatus',
+    'check',
+    'clear_config_cache',
+    'get_styles',
+    'resolve_config',
+    'wrap_file_report',
+    'wrap_source',
+    'wrap_source_report',
+]

docwrap/__main__.py

@@ -0,0 +1,8 @@
+"""Module entry point for `python -m docwrap`."""
+
+import sys
+
+from docwrap._cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())

docwrap/_canonical.py

@@ -0,0 +1,66 @@
+"""Canonical section registry for docstring roles."""
+
+from dataclasses import dataclass
+
+from docwrap._types import CanonicalRole
+
+
+@dataclass(frozen=True, slots=True)
+class CanonicalSection:
+    """Registry entry whose tuple position determines canonical section order.
+
+    The entry's position in `CANONICAL_SECTIONS` is the ordering authority.
+    Sphinx field mappings and target support belong to the Sphinx style.
+
+    Attributes:
+        role: Canonical docstring role represented by this entry.
+        google_header: Google header label, or `None` when unavailable.
+        numpy_header: NumPy header label, or `None` when unavailable.
+        return_like: Whether the role uses return-like entry handling.
+    """
+
+    role: CanonicalRole
+    google_header: str | None = None
+    numpy_header: str | None = None
+    return_like: bool = False
+
+
+CANONICAL_SECTIONS: tuple[CanonicalSection, ...] = (
+    CanonicalSection('param', google_header='Args', numpy_header='Parameters'),
+    CanonicalSection('keyword_param', google_header='Keyword Args'),
+    CanonicalSection('other_param', numpy_header='Other Parameters'),
+    CanonicalSection(
+        'returns',
+        google_header='Returns',
+        numpy_header='Returns',
+        return_like=True,
+    ),
+    CanonicalSection(
+        'yields',
+        google_header='Yields',
+        numpy_header='Yields',
+        return_like=True,
+    ),
+    CanonicalSection('raises', google_header='Raises', numpy_header='Raises'),
+    CanonicalSection('warns', google_header='Warns', numpy_header='Warns'),
+    CanonicalSection(
+        'attributes',
+        google_header='Attributes',
+        numpy_header='Attributes',
+    ),
+    CanonicalSection('methods', google_header='Methods', numpy_header='Methods'),
+    CanonicalSection('see_also', google_header='See Also', numpy_header='See Also'),
+    CanonicalSection('notes', google_header='Notes', numpy_header='Notes'),
+    CanonicalSection('references', google_header='References', numpy_header='References'),
+    CanonicalSection('examples', google_header='Examples', numpy_header='Examples'),
+    CanonicalSection('todo', google_header='Todo', numpy_header='Todo'),
+    CanonicalSection('warnings', google_header='Warnings', numpy_header='Warnings'),
+)
+
+CANONICAL_ORDER: tuple[CanonicalRole, ...] = tuple(section.role for section in CANONICAL_SECTIONS)
+
+CANONICAL_ORDER_SET: frozenset[CanonicalRole] = frozenset(CANONICAL_ORDER)
+
+RETURN_LIKE_ROLES: frozenset[CanonicalRole] = frozenset(
+    s.role for s in CANONICAL_SECTIONS if s.return_like
+)

docwrap/_classify.py

@@ -0,0 +1,56 @@
+"""Classify a pre-tool shell command into one of three outcomes."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+from docwrap._color import visible_controls
+from docwrap._detector import detect_commit
+from docwrap._grammar import CommitPlan, NoCommit, Rejection, classify_grammar
+from docwrap._shellparse import parse_command
+
+type _OUTCOME = Literal['unrelated', 'supported', 'unsupported']
+
+_REASON_PREFIX = 'docwrap: unsupported commit command'
+
+
+@dataclass(frozen=True, slots=True)
+class Classification:
+    """Outcome of classifying one command.
+
+    Args:
+        outcome: `unrelated`, `supported`, or `unsupported`.
+        plan: Resolved commit plan, or `NoCommit`, for a supported command.
+        reason: Deny reason for an unsupported command.
+    """
+
+    outcome: _OUTCOME
+    plan: CommitPlan | NoCommit | None = None
+    reason: str | None = None
+
+
+def _deny_reason(rejection: Rejection) -> str:
+    """Render a sanitized deny reason for a rejected command."""
+    return visible_controls(f'{_REASON_PREFIX}: {rejection.element}; {rejection.hint}')
+
+
+def classify_command(text: str, command_cwd: str | None) -> Classification:
+    """Classify a shell command as unrelated, supported, or unsupported.
+
+    Args:
+        text: Shell command text from the hook payload.
+        command_cwd: Absolute directory the command executes in, or `None` when
+            unknown.
+
+    Returns:
+        The classification. The grammar decides first; a rejected command is
+        unsupported when the detector finds a commit and unrelated otherwise.
+        A committing command with an unknown directory and no absolute route is
+        unsupported.
+    """
+    command = parse_command(text)
+    result = classify_grammar(command, command_cwd)
+    if isinstance(result, Rejection):
+        if detect_commit(command):
+            return Classification('unsupported', reason=_deny_reason(result))
+        return Classification('unrelated')
+    return Classification('supported', plan=result)