undersort 0.1.0__py3-none-any.whl

undersort/__init__.py

@@ -0,0 +1,3 @@
+"""undersort - Sort class methods by visibility."""
+
+__version__ = "0.1.0"

undersort/config.py

@@ -0,0 +1,67 @@
+"""Configuration loading for undersort."""
+
+import tomllib
+from pathlib import Path
+
+from undersort import logger
+
+
+def load_config() -> dict[str, list[str] | None]:
+    """Load configuration from pyproject.toml.
+
+    Returns:
+        Dictionary with 'order' and 'method_type_order' keys.
+    """
+    default_config: dict[str, list[str] | None] = {
+        "order": ["public", "protected", "private"],
+        "method_type_order": None,
+    }
+
+    pyproject_path = _find_pyproject_toml()
+    if not pyproject_path:
+        return default_config
+
+    try:
+        with open(pyproject_path, "rb") as f:
+            data = tomllib.load(f)
+    except Exception as e:
+        logger.warning(f"Could not load {pyproject_path}: {e}")
+        return default_config
+
+    if "tool" not in data or "undersort" not in data["tool"]:
+        return default_config
+
+    config = data["tool"]["undersort"]
+    result: dict[str, list[str] | None] = default_config.copy()
+
+    if "order" in config:
+        order = config["order"]
+        valid_visibility_values = {"public", "protected", "private"}
+        if not all(v in valid_visibility_values for v in order):
+            logger.warning(f"Invalid order values in {pyproject_path}. Using default order.")
+        else:
+            result["order"] = order
+
+    if "method_type_order" in config:
+        method_type_order = config["method_type_order"]
+        valid_method_types = {"class", "static", "instance"}
+        if not all(v in valid_method_types for v in method_type_order):
+            logger.warning(f"Invalid method_type_order values in {pyproject_path}. Using default.")
+        else:
+            result["method_type_order"] = method_type_order
+
+    return result
+
+
+def _find_pyproject_toml() -> Path | None:
+    """Find pyproject.toml in current or parent directories.
+
+    Returns:
+        Path to pyproject.toml if found, None otherwise.
+    """
+    current_dir = Path.cwd()
+    for directory in [current_dir, *current_dir.parents]:
+        pyproject_path = directory / "pyproject.toml"
+        if pyproject_path.exists():
+            return pyproject_path
+    return None

undersort/logger.py

@@ -0,0 +1,32 @@
+"""Logging configuration for undersort."""
+
+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)

undersort/main.py

@@ -0,0 +1,130 @@
+"""Main entry point for undersort CLI."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from undersort import logger
+from undersort.config import load_config
+from undersort.sorter import sort_file
+
+
+def collect_python_files(path: Path, recursive: bool = True) -> list[Path]:
+    """Collect Python files from a path (file or directory).
+
+    Args:
+        path: File or directory path
+        recursive: If True, recursively search directories
+
+    Returns:
+        List of Python file paths
+    """
+    # Common directories to exclude
+    exclude_dirs = {
+        ".venv",
+        "venv",
+        ".git",
+        "__pycache__",
+        ".pytest_cache",
+        ".mypy_cache",
+        ".ruff_cache",
+        "node_modules",
+    }
+
+    if path.is_file():
+        return [path] if path.suffix == ".py" else []
+
+    if path.is_dir():
+        pattern = "**/*.py" if recursive else "*.py"
+        all_files = path.glob(pattern)
+        filtered_files = [f for f in all_files if not any(excluded in f.parts for excluded in exclude_dirs)]
+
+        return sorted(filtered_files)
+
+    return []
+
+
+def main() -> int:
+    """Main entry point for undersort."""
+    parser = argparse.ArgumentParser(description="Sort class methods by visibility (public, protected, private)")
+    parser.add_argument(
+        "paths",
+        nargs="+",
+        type=Path,
+        help="Python files or directories to sort",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Check if files need sorting without modifying them",
+    )
+    parser.add_argument(
+        "--diff",
+        action="store_true",
+        help="Show diff of changes",
+    )
+    parser.add_argument(
+        "--no-recursive",
+        dest="recursive",
+        action="store_false",
+        default=True,
+        help="Don't recursively search directories",
+    )
+
+    args = parser.parse_args()
+
+    config = load_config()
+
+    all_files: list[Path] = []
+    for path in args.paths:
+        if not path.exists():
+            logger.error(f"Path not found: {path}")
+            continue
+
+        python_files = collect_python_files(path, args.recursive)
+        all_files.extend(python_files)
+
+    if not all_files:
+        logger.warning("No Python files found")
+        return 0
+
+    modified_files: list[Path] = []
+    errors = False
+
+    for file_path in all_files:
+        try:
+            was_modified = sort_file(
+                file_path,
+                config["order"],
+                method_type_order=config.get("method_type_order"),
+                check_only=args.check,
+                show_diff=args.diff,
+            )
+
+            if not was_modified:
+                continue
+
+            modified_files.append(file_path)
+            if not args.check:
+                logger.success(f"Sorted {file_path}")
+
+        except Exception as e:
+            logger.error(f"Error processing {file_path}: {e}")
+            errors = True
+
+    if args.check 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 args.check:
+        logger.success(f"Sorted {len(modified_files)} file(s) successfully")
+
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

undersort/sorter.py

@@ -0,0 +1,179 @@
+"""Core sorting logic for class methods."""
+
+import difflib
+from pathlib import Path
+
+import libcst as cst
+
+from undersort import logger
+
+
+def get_method_visibility(method_name: str) -> str:
+    """Determine method visibility based on naming convention.
+
+    Args:
+        method_name: The name of the method
+
+    Returns:
+        'public' for method (no underscore prefix) or magic methods (__method__),
+        'protected' for _method (single underscore),
+        'private' for __method (dunder prefix, not magic method)
+    """
+    if method_name.startswith("__") and method_name.endswith("__"):
+        return "public"
+
+    if method_name.startswith("__"):
+        return "private"
+
+    if method_name.startswith("_"):
+        return "protected"
+
+    return "public"
+
+
+def get_method_type(method: cst.FunctionDef) -> str:
+    """Determine method type based on decorators.
+
+    Args:
+        method: The FunctionDef node
+
+    Returns:
+        'class' for @classmethod,
+        'static' for @staticmethod,
+        'instance' for regular instance methods (default)
+    """
+    for decorator in method.decorators:
+        decorator_name = decorator.decorator
+        if isinstance(decorator_name, cst.Name):
+            if decorator_name.value == "classmethod":
+                return "class"
+            if decorator_name.value == "staticmethod":
+                return "static"
+    return "instance"
+
+
+class MethodSorter(cst.CSTTransformer):
+    """Transformer to sort class methods by visibility and type."""
+
+    def __init__(self, order: list[str], method_type_order: list[str] | None = None):
+        """Initialize the transformer.
+
+        Args:
+            order: List specifying the desired order of visibility levels
+                   (e.g., ["public", "protected", "private"])
+            method_type_order: Optional list specifying the order of method types
+                              within each visibility level
+                              (e.g., ["class", "static", "instance"])
+        """
+        self.order = order
+        self.method_type_order = method_type_order or ["class", "static", "instance"]
+        self.modified = False
+
+    def leave_ClassDef(self, original_node: cst.ClassDef, updated_node: cst.ClassDef) -> cst.ClassDef:
+        """Sort methods within a class definition.
+
+        Args:
+            original_node: Original class definition node
+            updated_node: Updated class definition node
+
+        Returns:
+            ClassDef with sorted methods
+        """
+        methods = []
+        non_methods = []
+
+        for item in updated_node.body.body:
+            if isinstance(item, cst.FunctionDef):
+                methods.append(item)
+            else:
+                non_methods.append(item)
+
+        if not methods:
+            return updated_node
+
+        method_groups: dict[str, dict[str, list[cst.FunctionDef]]] = {
+            "public": {"class": [], "static": [], "instance": []},
+            "protected": {"class": [], "static": [], "instance": []},
+            "private": {"class": [], "static": [], "instance": []},
+        }
+
+        for method in methods:
+            visibility = get_method_visibility(method.name.value)
+            method_type = get_method_type(method)
+            method_groups[visibility][method_type].append(method)
+
+        sorted_methods = []
+        for visibility in self.order:
+            for method_type in self.method_type_order:
+                sorted_methods.extend(method_groups[visibility][method_type])
+
+        if methods != sorted_methods:
+            self.modified = True
+
+        leading_non_methods = []
+        trailing_non_methods = []
+        found_method = False
+        original_items = list(updated_node.body.body)
+
+        for item in original_items:
+            if isinstance(item, cst.FunctionDef):
+                found_method = True
+            elif not found_method:
+                leading_non_methods.append(item)
+            else:
+                trailing_non_methods.append(item)
+
+        new_body = leading_non_methods + sorted_methods + trailing_non_methods
+
+        return updated_node.with_changes(body=updated_node.body.with_changes(body=new_body))
+
+
+def sort_file(
+    file_path: Path,
+    order: list[str],
+    method_type_order: list[str] | None = None,
+    check_only: bool = False,
+    show_diff: bool = False,
+) -> bool:
+    """Sort methods in a Python file.
+
+    Args:
+        file_path: Path to the Python file
+        order: Method visibility ordering configuration
+        method_type_order: Optional method type ordering within each visibility level
+        check_only: If True, only check if file needs sorting
+        show_diff: If True, show diff of changes
+
+    Returns:
+        True if file was modified (or needs modification in check mode)
+    """
+    with open(file_path, encoding="utf-8") as f:
+        source_code = f.read()
+
+    try:
+        tree = cst.parse_module(source_code)
+    except cst.ParserSyntaxError as e:
+        raise ValueError(f"Syntax error in {file_path}: {e}")
+
+    sorter = MethodSorter(order, method_type_order)
+    new_tree = tree.visit(sorter)
+
+    if not sorter.modified:
+        return False
+
+    new_code = new_tree.code
+
+    if show_diff:
+        diff = difflib.unified_diff(
+            source_code.splitlines(keepends=True),
+            new_code.splitlines(keepends=True),
+            fromfile=str(file_path),
+            tofile=str(file_path),
+        )
+        logger.diff("".join(diff))
+
+    if not check_only:
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(new_code)
+
+    return True

undersort-0.1.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: undersort
+Version: 0.1.0
+Summary: A tool to sort class methods by visibility (public, protected, private)
+Project-URL: Homepage, https://github.com/kivicode/undersort
+Project-URL: Repository, https://github.com/kivicode/undersort
+Project-URL: Issues, https://github.com/kivicode/undersort/issues
+Author-email: KiviCode <kivicode.dev@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: class-methods,code-formatter,linter,python,sorting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Requires-Dist: libcst>=1.1.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# undersort
+
+A Python tool that automatically sorts class methods by visibility (public, protected, private) and type (class, static, instance).
+
+## Features
+
+- Automatically reorders class methods based on visibility and method type
+- Two-level sorting: primary by visibility, secondary by method type
+- Fully configurable ordering via `pyproject.toml`
+- Pre-commit hook integration
+- Colored output for better readability
+- Check mode for CI/CD validation
+- Diff mode to preview changes
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv pip install -e .
+
+# Using pip
+pip install -e .
+```
+
+## Configuration
+
+Configure the method ordering in your `pyproject.toml`:
+
+```toml
+[tool.undersort]
+# Method visibility ordering (primary sort)
+# Options: "public", "protected", "private"
+order = ["public", "protected", "private"]
+
+# Method type ordering within each visibility level (secondary sort, optional)
+# Options: "class" (classmethod), "static" (staticmethod), "instance" (regular methods)
+# Default: ["class", "static", "instance"]
+method_type_order = ["class", "static", "instance"]
+```
+
+### Method Visibility Rules
+
+- **Public methods**: No underscore prefix (e.g., `def method()`) or magic methods (e.g., `__init__`, `__str__`)
+- **Protected methods**: Single underscore prefix (e.g., `def _method()`)
+- **Private methods**: Double underscore prefix, not magic (e.g., `def __method()`)
+
+### Method Type Rules
+
+- **Class methods**: Decorated with `@classmethod`
+- **Static methods**: Decorated with `@staticmethod`
+- **Instance methods**: Regular methods (no special decorator)
+
+### Sorting Behavior
+
+Methods are sorted in two levels:
+
+1. **Primary**: By visibility (public → protected → private)
+2. **Secondary**: Within each visibility level, by method type (class → static → instance by default)
+
+Example: With default configuration, the order would be:
+
+1. Public class methods
+2. Public static methods
+3. Public instance methods
+4. Protected class methods
+5. Protected static methods
+6. Protected instance methods
+7. Private class methods
+8. Private static methods
+9. Private instance methods
+
+## Usage
+
+### Command Line
+
+```bash
+# Sort a single file
+undersort example.py
+
+# Sort multiple files
+undersort file1.py file2.py file3.py
+
+# Sort all Python files in a directory (recursive by default)
+undersort src/
+
+# Sort all Python files in current directory and subdirectories
+undersort .
+
+# Non-recursive directory sorting (only files in the directory, not subdirectories)
+undersort src/ --no-recursive
+
+# Wildcards work too (expanded by shell)
+undersort *.py
+undersort src/**/*.py
+
+# Check if files need sorting (useful for CI)
+undersort --check example.py
+undersort --check src/
+
+# Show diff of changes
+undersort --diff example.py
+
+# Combine flags
+undersort --check --diff src/
+```
+
+**Note**: By default, undersort excludes common directories like `.venv`, `.git`, `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, and `node_modules` when scanning directories.
+
+### Pre-commit Integration
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: undersort
+        name: undersort
+        entry: uv run undersort
+        language: system
+        types: [python]
+```
+
+Then install the hook:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+## Example
+
+### Before
+
+```python
+class Example:
+    def _protected_instance(self):
+        pass
+
+    @staticmethod
+    def public_static():
+        pass
+
+    def __init__(self):
+        pass
+
+    @classmethod
+    def _protected_class(cls):
+        pass
+
+    def public_instance(self):
+        pass
+
+    def __private_method(self):
+        pass
+
+    @classmethod
+    def public_class(cls):
+        pass
+```
+
+### After (with default config)
+
+```python
+class Example:
+    @classmethod
+    def public_class(cls):
+        pass
+
+    @staticmethod
+    def public_static():
+        pass
+
+    def __init__(self):
+        pass
+
+    def public_instance(self):
+        pass
+
+    @classmethod
+    def _protected_class(cls):
+        pass
+
+    def _protected_instance(self):
+        pass
+
+    def __private_method(self):
+        pass
+```
+
+The methods are now organized by:
+
+1. **Visibility**: public (including `__init__`) → protected → private
+2. **Type** (within each visibility): class → static → instance
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run on example file
+uv run undersort example.py
+
+# Test with check mode
+uv run undersort --check example.py
+
+# View diff
+uv run undersort --diff example.py
+```
+
+## License
+
+MIT

undersort-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+undersort/__init__.py,sha256=CkdkH89paBK7UDcOe3qKMCmrdffwFLXlBOjRy6O5PUI,75
+undersort/config.py,sha256=k4B0Nwn96bZI0IdgXr44B81VL1KwA9Kzky8zX18Tduc,2124
+undersort/logger.py,sha256=KYBTO3jzT-0trh3mzumWGhEDxBTrEb-TXbDX__q716E,832
+undersort/main.py,sha256=5uNQhc0uw2apT690AJaeiiN2Gpgx6GHE77X8k1lz4Xk,3457
+undersort/sorter.py,sha256=7J8tAQZo24ax7FYi6mwIEK9Ba4cZ1I5jmMWm-RHtnhg,5598
+undersort-0.1.0.dist-info/METADATA,sha256=rRmI4tP1nTCAbCIfEGujFMl6Gl9lfvRnSxKRiF9GPWI,5719
+undersort-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+undersort-0.1.0.dist-info/entry_points.txt,sha256=CwO819_Zbd6xM-I557Ztr0qAfgTvBFFVajD69BZn_QQ,50
+undersort-0.1.0.dist-info/licenses/LICENSE,sha256=xwugI0v9V_GNs5ZwtKo57TI0qByufJy6P9lHtB88nm4,1075
+undersort-0.1.0.dist-info/RECORD,,

undersort-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

undersort-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+undersort = undersort.main:main

undersort-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vladimir Kirilenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.