funcsort 0.2.0__py3-none-any.whl

funcsort/__init__.py

@@ -0,0 +1,3 @@
+"""funcsort - Sort class methods and module-level functions into configurable groups."""
+
+__version__ = "0.2.0"

funcsort/config.py

@@ -0,0 +1,158 @@
+"""Configuration loading for funcsort.
+
+Configuration is read with confkit from a dedicated ``funcsort.toml`` (preferred) or,
+as a fallback, the ``[tool.funcsort]`` table of ``pyproject.toml``. Both files use the
+same ``[tool.funcsort]`` section and keys. The values are resolved into a single
+immutable :class:`Settings` value object that drives the engine.
+
+The confkit container class ``tool.funcsort`` is the single source of truth for the
+config shape; values are read directly off it (no parallel schema definition).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from .config_types import GroupTable, TomlList
+from confkit import Config
+
+from funcsort.groups import (
+    Group,
+    MemberKind,
+    MethodKind,
+    Scope,
+    compile_matcher,
+    default_groups,
+)
+from . import logger
+
+_CONFIG_FILENAMES = ("funcsort.toml", "pyproject.toml")
+_DEFAULT_METHOD_TYPE_ORDER = (MethodKind.INSTANCE, MethodKind.CLASS, MethodKind.STATIC)
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Resolved funcsort configuration that drives the sorter.
+
+    Attributes:
+        groups: Ordered groups; output order and membership rules for members.
+        method_type_order: Secondary ordering of method types within each group.
+        exclude: Glob patterns of files/directories to skip.
+        sort_module: Whether module-level functions are sorted.
+    """
+
+    groups: list[Group]
+    method_type_order: list[MethodKind] = field(
+        default_factory=lambda: list(_DEFAULT_METHOD_TYPE_ORDER),
+    )
+    exclude: tuple[str, ...] = ()
+    sort_module: bool = True
+
+
+def load_settings() -> Settings:
+    """Load and resolve configuration into a :class:`Settings`.
+
+    Falls back to built-in defaults when no config file or section is present, or when
+    the configured groups are invalid.
+    """
+    path = find_config_file()
+    if path is None:
+        return Settings(groups=default_groups())
+
+    class _Cfg(Config[Any]): ...
+
+    _Cfg.write_on_edit = False
+    _Cfg.set_file(path)
+
+    # confkit derives the section name from the class qualname, so the nested classes
+    # must be named ``tool`` -> ``funcsort`` to address ``[tool.funcsort]``. This class
+    # is the single definition of the config shape.
+    class tool:  # noqa: N801 - intentional: forms the "tool.funcsort" section path
+        class funcsort:  # noqa: N801
+            method_type_order = _Cfg(TomlList([str(t) for t in _DEFAULT_METHOD_TYPE_ORDER]))
+            exclude = _Cfg(TomlList([]))
+            sort_module = _Cfg(True)
+            groups = _Cfg(GroupTable([]))
+
+    cfg = tool.funcsort
+    return Settings(
+        groups=_build_groups(cfg.groups, path) if cfg.groups else default_groups(),
+        method_type_order=_parse_method_type_order(cfg.method_type_order, path),
+        exclude=tuple(cfg.exclude),
+        sort_module=cfg.sort_module,
+    )
+
+
+def find_config_file() -> Path | None:
+    """Find ``funcsort.toml`` (preferred) or ``pyproject.toml`` in cwd or a parent."""
+    current_dir = Path.cwd()
+    for directory in [current_dir, *current_dir.parents]:
+        for filename in _CONFIG_FILENAMES:
+            candidate = directory / filename
+            if candidate.exists():
+                return candidate
+    return None
+
+
+def _build_groups(raw_groups: list[dict[str, Any]], path: Path) -> list[Group]:
+    """Build groups from a user-defined ``[[tool.funcsort.groups]]`` block.
+
+    On any malformed entry, warn and fall back to the built-in default groups so a
+    broken config never silently drops members.
+    """
+    try:
+        return [_build_group(entry) for entry in raw_groups]
+    except (KeyError, ValueError, TypeError, re.error) as exc:
+        logger.warning(f"Invalid groups in {path}: {exc}. Using default groups.")
+        return default_groups()
+
+
+def _build_group(entry: dict[str, Any]) -> Group:
+    """Build a single :class:`Group` from a raw config table."""
+    name = entry["name"]
+    tokens = _as_tokens(entry["match"])
+    if not tokens:
+        msg = f"group {name!r} has an empty 'match'"
+        raise ValueError(msg)
+    decorator_tokens = _as_tokens(entry.get("decorator"))
+    decorators = tuple(compile_matcher(token) for token in decorator_tokens) if decorator_tokens else None
+    default_kinds = frozenset({MemberKind.FUNCTION})
+    return Group(
+        name=name,
+        matchers=tuple(compile_matcher(token) for token in tokens),
+        kinds=_parse_enum_set(entry.get("kind"), MemberKind, default_kinds) or default_kinds,
+        types=_parse_enum_set(entry.get("type"), MethodKind, None),
+        scopes=_parse_enum_set(entry.get("scope"), Scope, None),
+        decorators=decorators,
+    )
+
+
+def _as_tokens(value: Any) -> list[str]:  # noqa: ANN401 - TOML scalar or list
+    """Normalise a string-or-list config value into a list of strings."""
+    if value is None:
+        return []
+    return [value] if isinstance(value, str) else list(value)
+
+
+def _parse_method_type_order(raw: list[str], path: Path) -> list[MethodKind]:
+    """Parse and validate the method type order, falling back to the default."""
+    try:
+        return [MethodKind(value) for value in raw]
+    except ValueError:
+        logger.warning(f"Invalid method_type_order values in {path}. Using default.")
+        return list(_DEFAULT_METHOD_TYPE_ORDER)
+
+
+def _parse_enum_set[E: StrEnum](value: Any, enum: type[E], default: frozenset[E] | None) -> frozenset[E] | None:  # noqa: ANN401
+    """Parse a string/list config value into a frozenset of enum members.
+
+    ``None`` or an ``"any"`` token resolves to ``default`` (typically "no filter").
+    """
+    if value is None:
+        return default
+    members = {enum(item) for item in _as_tokens(value) if item != "any"}
+    return frozenset(members) if members else default

funcsort/config_types.py

@@ -0,0 +1,77 @@
+"""Custom confkit data types for funcsort.
+
+These subclass confkit's public :class:`~confkit.BaseDataType` so funcsort can store
+*native* TOML arrays and array-of-tables (``[[tool.funcsort.groups]]``) instead of
+confkit's default stringified representation.
+
+confkit's TOML parser stores a value natively only when ``str(native) == str(value)``
+and always hands ``convert`` the stringified form on read. By making ``__str__`` the
+Python ``repr`` of the native value, these types round-trip cleanly: confkit writes
+idiomatic TOML, and ``convert`` parses the repr back with :func:`ast.literal_eval`.
+
+This module depends only on confkit's public API and never modifies the confkit package.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+from typing import Any, cast, override
+
+from confkit import BaseDataType
+
+
+class TomlList(BaseDataType[list[Any]]):
+    """A confkit value that is a native TOML array (round-trips as a Python list)."""
+
+    def __init__(self, default: list[Any] | None = None) -> None:
+        """Initialise with a default list (empty when omitted)."""
+        super().__init__(default if default is not None else [])
+
+    @override
+    def __str__(self) -> str:
+        """Return a repr so confkit stores the value as a native TOML array."""
+        return repr(self.value)
+
+    @override
+    def convert(self, value: Any) -> list[Any]:  # noqa: ANN401 - confkit hands us str or native
+        """Parse a stored value back into a list, tolerating native and legacy forms."""
+        if isinstance(value, list):
+            return value
+        if not isinstance(value, str):
+            return [value]
+        try:
+            parsed = ast.literal_eval(value)
+        except (ValueError, SyntaxError):
+            return [item.strip() for item in value.split(",") if item.strip()]
+        if isinstance(parsed, Iterable) and not isinstance(parsed, (str, bytes)):
+            return list(parsed)  # pyright: ignore[reportUnknownArgumentType]
+        return [parsed]
+
+
+class GroupTable(BaseDataType[list[dict[str, Any]]]):
+    """A confkit value holding a list of group tables (``[[tool.funcsort.groups]]``)."""
+
+    def __init__(self, default: list[dict[str, Any]] | None = None) -> None:
+        """Initialise with a default list of group dicts (empty when omitted)."""
+        super().__init__(default if default is not None else [])
+
+    @override
+    def __str__(self) -> str:
+        """Return a repr so confkit stores the value as native TOML tables."""
+        return repr(self.value)
+
+    @override
+    def convert(self, value: Any) -> list[dict[str, Any]]:  # noqa: ANN401 - str or native
+        """Parse a stored value back into a list of group dicts."""
+        if isinstance(value, list):
+            return value
+        if not isinstance(value, str):
+            return []
+        try:
+            parsed = ast.literal_eval(value)
+        except (ValueError, SyntaxError):
+            return []
+        if not isinstance(parsed, list):
+            return []
+        return cast("list[dict[str, Any]]", parsed)

funcsort/groups.py

@@ -0,0 +1,184 @@
+"""Generic, configuration-driven sorting model for funcsort.
+
+This module is the pure engine: it knows nothing about libcst or TOML. It defines
+the value objects (:class:`Group`, :class:`Member`, :class:`Classification`) and the
+:func:`classify` placement rule that drive the sorter, plus the built-in
+:func:`default_groups` used when no configuration is supplied.
+
+A :class:`Group` is matched against a member's *name* by regular expression
+(first-match-wins down an ordered list), optionally narrowed by member kind, method
+type, scope and decorators. Users replace the default group list via configuration to
+take full control of what is sorted and in which order.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+# Curated set of object/class lifecycle dunders treated as the "creational" group by
+# default. Every other magic method (``__x__``) falls into the generic "dunder" group.
+DEFAULT_CREATIONAL_DUNDERS: tuple[str, ...] = (
+    "__new__",
+    "__init__",
+    "__init_subclass__",
+    "__post_init__",
+    "__set_name__",
+)
+
+
+class Scope(StrEnum):
+    """Where a member lives."""
+
+    CLASS = "class"
+    MODULE = "module"
+
+
+class MemberKind(StrEnum):
+    """What kind of statement a sortable member is."""
+
+    FUNCTION = "function"
+    ASSIGNMENT = "assignment"
+
+
+class MethodKind(StrEnum):
+    """Secondary classification of a function by its binding."""
+
+    INSTANCE = "instance"
+    CLASS = "class"
+    STATIC = "static"
+
+
+@dataclass(frozen=True)
+class Member:
+    """A single sortable statement within a class or module body.
+
+    Attributes:
+        index: Original position within the body (used to minimise movement).
+        node: The underlying libcst node (kept opaque to this module).
+        kind: Whether the member is a function or an assignment.
+        name: The function name or the assignment's target name.
+        method_type: Binding of a function; :attr:`MethodKind.INSTANCE` for assignments.
+        scope: Whether the member lives in a class or module body.
+        decorators: Normalised, dotted decorator names applied to the member.
+    """
+
+    index: int
+    node: object
+    kind: MemberKind
+    name: str
+    method_type: MethodKind
+    scope: Scope
+    decorators: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Group:
+    """An ordered bucket members are placed into, matched by name regex.
+
+    Attributes:
+        name: Human-readable identifier (used in diagnostics and bucket keys).
+        matchers: Pre-compiled patterns; a member matches if *any* one searches its name.
+        kinds: Member kinds this group accepts (defaults to functions only).
+        types: Method types this group accepts; ``None`` means any.
+        scopes: Scopes this group accepts; ``None`` means any.
+        decorators: If set, the member must carry a decorator whose name matches one of
+            these patterns; ``None`` means no decorator requirement.
+    """
+
+    name: str
+    matchers: tuple[re.Pattern[str], ...]
+    kinds: frozenset[MemberKind] = field(default_factory=lambda: frozenset({MemberKind.FUNCTION}))
+    types: frozenset[MethodKind] | None = None
+    scopes: frozenset[Scope] | None = None
+    decorators: tuple[re.Pattern[str], ...] | None = None
+
+    def accepts(self, member: Member) -> bool:
+        """Return whether ``member`` belongs to this group."""
+        if member.kind not in self.kinds:
+            return False
+        if self.types is not None and member.method_type not in self.types:
+            return False
+        if self.scopes is not None and member.scope not in self.scopes:
+            return False
+        if self.decorators is not None and not self._matches_decorator(member):
+            return False
+        return any(matcher.search(member.name) for matcher in self.matchers)
+
+    def targets_assignments(self) -> bool:
+        """Return whether this group can ever match an assignment member."""
+        return MemberKind.ASSIGNMENT in self.kinds
+
+    def _matches_decorator(self, member: Member) -> bool:
+        """Return whether any of the member's decorators match this group's filter."""
+        assert self.decorators is not None  # noqa: S101 - guarded by caller
+        return any(pattern.search(name) for name in member.decorators for pattern in self.decorators)
+
+
+@dataclass(frozen=True)
+class Classification:
+    """The result of placing a member into a group.
+
+    Using a value object instead of an ``Optional[str]`` keeps call sites explicit
+    and lets the placement result grow fields without churn.
+    """
+
+    member: Member
+    group: Group | None
+
+    @property
+    def is_matched(self) -> bool:
+        """Return whether the member was matched by any group."""
+        return self.group is not None
+
+
+def exact(name: str) -> re.Pattern[str]:
+    """Compile a matcher that matches ``name`` exactly (whole string)."""
+    return re.compile(r"\A" + re.escape(name) + r"\Z")
+
+
+def compile_matcher(token: str) -> re.Pattern[str]:
+    """Compile a configured ``match``/``decorator`` token.
+
+    A bare Python identifier is treated as an exact-name match; anything else is a regex.
+    """
+    if token.isidentifier():
+        return exact(token)
+    return re.compile(token)
+
+
+def default_groups(creational_dunders: tuple[str, ...] | list[str] = DEFAULT_CREATIONAL_DUNDERS) -> list[Group]:
+    """Return the built-in groups, in output order.
+
+    The matchers are deliberately *mutually exclusive* so membership is independent of
+    the groups' order (only the output order changes when a user reorders them):
+    creational (exact names) -> dunder (other ``__x__``) -> public (no leading
+    underscore) -> protected (single leading underscore) -> private (leading ``__``,
+    non-magic).
+    """
+    return [
+        Group("creational", tuple(exact(name) for name in creational_dunders)),
+        Group("dunder", (_dunder_matcher(creational_dunders),)),
+        Group("public", (re.compile(r"^[^_]"),)),
+        Group("protected", (re.compile(r"^_([^_]|$)"),)),
+        # Leading ``__`` that is not a magic method. Excludes exactly the dunder pattern
+        # so creational/dunder/private together cover every ``__``-prefixed name.
+        Group("private", (re.compile(r"^(?!__.+__$)__"),)),
+    ]
+
+
+def classify(member: Member, groups: list[Group]) -> Classification:
+    """Place ``member`` into the first group that accepts it (first-match-wins)."""
+    for group in groups:
+        if group.accepts(member):
+            return Classification(member, group)
+    return Classification(member, None)
+
+
+def _dunder_matcher(creational_dunders: tuple[str, ...] | list[str]) -> re.Pattern[str]:
+    """Match any magic method (``__x__``) that is not one of the creational names."""
+    if not creational_dunders:
+        return re.compile(r"^__.+__$")
+    alternation = "|".join(re.escape(name) for name in creational_dunders)
+    return re.compile(rf"^(?!(?:{alternation})$)__.+__$")

funcsort/logger.py

@@ -0,0 +1,32 @@
+"""Logging configuration for funcsort."""
+
+from rich.console import Console
+from rich.syntax import Syntax
+
+console = Console()
+
+
+def info(message: str) -> None:
+    """Log an info message."""
+    console.print(f"[blue][INFO][/blue] {message}")
+
+
+def success(message: str) -> None:
+    """Log a success message."""
+    console.print(f"[green][OK][/green] {message}")
+
+
+def warning(message: str) -> None:
+    """Log a warning message."""
+    console.print(f"[yellow][WARNING][/yellow] {message}", highlight=False)
+
+
+def error(message: str) -> None:
+    """Log an error message."""
+    console.print(f"[red][ERROR][/red] {message}", highlight=False)
+
+
+def diff(content: str) -> None:
+    """Print a diff with syntax highlighting."""
+    syntax = Syntax(content, "diff", theme="monokai", line_numbers=False)
+    console.print(syntax)

funcsort/main.py

@@ -0,0 +1,171 @@
+"""Main entry point for funcsort CLI."""
+
+from __future__ import annotations
+
+import fnmatch
+import sys
+from pathlib import Path
+
+from herogold.argparse import Actions, Argument, parser
+
+from funcsort.config import Settings, load_settings
+from funcsort.sorter import sort_file
+
+from . import logger
+
+_EXCLUDE_DIRS = {"venv", "__pycache__", "node_modules"}
+
+
+class _Cli:
+    """Declarative CLI flags; defining them registers the options on the shared parser."""
+
+    check = Argument("check", action=Actions.STORE_BOOL, default=False, help="Check without modifying files")
+    diff = Argument("diff", action=Actions.STORE_BOOL, default=False, help="Show a diff of the changes")
+    recursive = Argument("recursive", action=Actions.STORE_BOOL, default=True, help="Recurse into directories")
+    sort_module = Argument("sort-module", action=Actions.STORE_BOOL, default=True, help="Sort module-level functions")
+    exclude = Argument[list[str]](
+        "exclude",
+        action=Actions.APPEND,
+        default=[],
+        help="Exclude files/dirs matching a glob pattern",
+    )
+
+
+# Defining ``_Cli`` registers the Argument descriptors on the shared parser via
+# ``__set_name__``; the class itself is not needed afterwards.
+del _Cli
+
+# STORE_BOOL registers a --flag/--no-flag pair without an explicit default, so pin the
+# real defaults here. sort_module defaults to None so the config value wins unless the
+# user passes the flag explicitly.
+parser.description = "Sort class methods and module-level functions into configurable groups"
+parser.set_defaults(check=False, diff=False, recursive=True, sort_module=None)
+parser.add_argument("paths", nargs="+", type=Path, help="Python files or directories to sort")
+
+
+def collect_python_files(path: Path, recursive: bool = True, exclude_patterns: list[str] | None = None) -> list[Path]:
+    """Collect Python files from a file or directory path.
+
+    Args:
+        path: File or directory to search.
+        recursive: Whether to descend into subdirectories.
+        exclude_patterns: Glob patterns to skip.
+
+    Returns:
+        Sorted list of matching ``.py`` file paths.
+    """
+    if path.is_file():
+        return [path] if path.suffix == ".py" else []
+
+    if not path.is_dir():
+        return []
+
+    pattern = "**/*.py" if recursive else "*.py"
+    files = [
+        f
+        for f in path.glob(pattern)
+        if not any(part in _EXCLUDE_DIRS or (part.startswith(".") and part != ".") for part in f.parts)
+    ]
+    if exclude_patterns:
+        files = [f for f in files if not _matches_any_pattern(f, exclude_patterns)]
+    return sorted(files)
+
+
+def main() -> int:
+    """Run the funcsort CLI."""
+    args = parser.parse_args()
+    settings = load_settings()
+
+    sort_module = settings.sort_module if args.sort_module is None else args.sort_module
+    exclude_patterns = _resolve_exclude(settings, args.exclude)
+
+    all_files: list[Path] = []
+    for path in args.paths:
+        if not path.exists():
+            logger.error(f"Path not found: {path}")
+            continue
+        all_files.extend(collect_python_files(path, args.recursive, exclude_patterns))
+
+    if not all_files:
+        logger.warning("No Python files found")
+        return 0
+
+    modified_files: list[Path] = []
+    unmatched_names: set[str] = set()
+    errors = False
+    for file_path in all_files:
+        try:
+            result = sort_file(
+                file_path,
+                groups=settings.groups,
+                method_type_order=settings.method_type_order,
+                sort_module=sort_module,
+                check_only=args.check,
+                show_diff=args.diff,
+            )
+        except Exception as e:  # noqa: BLE001 - report and continue across files
+            logger.error(f"Error processing {file_path}: {e}")
+            errors = True
+            continue
+
+        unmatched_names.update(member.name for member in result.unmatched)
+        if not result.modified:
+            continue
+        modified_files.append(file_path)
+        if not args.check:
+            logger.success(f"Sorted {file_path}")
+
+    _report_unmatched(unmatched_names)
+    return _report(modified_files, errors, check_only=args.check)
+
+
+def _matches_any_pattern(file_path: Path, patterns: list[str]) -> bool:
+    """Return whether ``file_path`` matches any of the glob ``patterns``."""
+    path_str = str(file_path)
+    for pattern in patterns:
+        if fnmatch.fnmatch(path_str, pattern):
+            return True
+        if "/" not in pattern:
+            if fnmatch.fnmatch(file_path.name, pattern):
+                return True
+            continue
+        if fnmatch.fnmatch(path_str, f"*/{pattern}"):
+            return True
+        for part_idx in range(len(file_path.parts)):
+            subpath = str(Path(*file_path.parts[part_idx:]))
+            if fnmatch.fnmatch(subpath, pattern):
+                return True
+    return False
+
+
+def _resolve_exclude(settings: Settings, cli_exclude: list[str] | None) -> list[str] | None:
+    """Merge config and CLI exclusion patterns."""
+    patterns = [*settings.exclude, *(cli_exclude or [])]
+    return patterns or None
+
+
+def _report_unmatched(unmatched_names: set[str]) -> None:
+    """Warn about members that matched no group and were moved to the end."""
+    if unmatched_names:
+        names = ", ".join(sorted(unmatched_names))
+        logger.warning(f"Members matched no group and were moved to the end: {names}. Configure a group for them.")
+
+
+def _report(modified_files: list[Path], errors: bool, *, check_only: bool) -> int:
+    """Emit a summary and return the process exit code."""
+    if check_only and modified_files:
+        logger.warning(f"Files that need sorting: {len(modified_files)}")
+        for f in modified_files:
+            logger.console.print(f"  - {f}")
+        return 1
+
+    if not modified_files and not errors:
+        logger.info("All files are already sorted correctly")
+    elif modified_files and not check_only:
+        logger.success(f"Sorted {len(modified_files)} file(s) successfully")
+
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())