undersort 0.1.2__tar.gz → 0.1.4__tar.gz

{undersort-0.1.2 → undersort-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: undersort
-Version: 0.1.2
+Version: 0.1.4
 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
@@ -43,10 +43,15 @@ A Python tool that automatically sorts class methods by visibility (public, prot
 
 ```bash
 # Using uv (recommended)
-uv pip install -e .
+uv add undersort
 
 # Using pip
-pip install -e .
+pip install undersort
+
+# For development
+git clone https://github.com/kivicode/undersort
+cd undersort
+uv sync
 ```
 
 ## Configuration
@@ -85,6 +90,7 @@ Methods are sorted in two levels:
 2. **Secondary**: Within each visibility level, by method type (instance → class → static by default)
 
 The sorting algorithm **minimizes movement** to preserve the original order as much as possible:
+
 - Methods that need to move DOWN (to a later section) are placed at the **beginning** of their target section
 - Methods that need to move UP (to an earlier section) are placed at the **end** of their target section
 - Methods already in the correct section maintain their relative order
@@ -101,6 +107,51 @@ Example order with default configuration:
 8. Private class methods
 9. Private static methods
 
+### Skipping Sorting with `# nosort`
+
+You can prevent sorting at different levels using `# nosort` comments (case-insensitive):
+
+**File-level**: Skip entire file
+
+```python
+# nosort: file
+class Example:
+    def _protected(self):
+        pass
+    def public(self):
+        pass  # File won't be sorted
+```
+
+**Class-level**: Skip specific class
+
+```python
+class Example:  # nosort
+    def _protected(self):
+        pass
+    def public(self):
+        pass  # This class won't be sorted
+
+class Other:
+    def _protected(self):
+        pass
+    def public(self):
+        pass  # This class WILL be sorted
+```
+
+**Method-level**: Keep method in its current position
+
+```python
+class Example:
+    def public_a(self):
+        pass
+
+    def _protected(self):  # nosort
+        pass  # Stays here, between public methods
+
+    def public_b(self):
+        pass  # Will move up, but _protected stays in place
+```
+
 ## Usage
 
 ### Command Line
@@ -148,9 +199,10 @@ repos:
     hooks:
       - id: undersort
         name: undersort
-        entry: uv run undersort
-        language: system
+        entry: undersort
+        language: python
         types: [python]
+        additional_dependencies: ["undersort"]
 ```
 
 Then install the hook:

{undersort-0.1.2 → undersort-0.1.4}/README.md

@@ -16,10 +16,15 @@ A Python tool that automatically sorts class methods by visibility (public, prot
 
 ```bash
 # Using uv (recommended)
-uv pip install -e .
+uv add undersort
 
 # Using pip
-pip install -e .
+pip install undersort
+
+# For development
+git clone https://github.com/kivicode/undersort
+cd undersort
+uv sync
 ```
 
 ## Configuration
@@ -58,6 +63,7 @@ Methods are sorted in two levels:
 2. **Secondary**: Within each visibility level, by method type (instance → class → static by default)
 
 The sorting algorithm **minimizes movement** to preserve the original order as much as possible:
+
 - Methods that need to move DOWN (to a later section) are placed at the **beginning** of their target section
 - Methods that need to move UP (to an earlier section) are placed at the **end** of their target section
 - Methods already in the correct section maintain their relative order
@@ -74,6 +80,51 @@ Example order with default configuration:
 8. Private class methods
 9. Private static methods
 
+### Skipping Sorting with `# nosort`
+
+You can prevent sorting at different levels using `# nosort` comments (case-insensitive):
+
+**File-level**: Skip entire file
+
+```python
+# nosort: file
+class Example:
+    def _protected(self):
+        pass
+    def public(self):
+        pass  # File won't be sorted
+```
+
+**Class-level**: Skip specific class
+
+```python
+class Example:  # nosort
+    def _protected(self):
+        pass
+    def public(self):
+        pass  # This class won't be sorted
+
+class Other:
+    def _protected(self):
+        pass
+    def public(self):
+        pass  # This class WILL be sorted
+```
+
+**Method-level**: Keep method in its current position
+
+```python
+class Example:
+    def public_a(self):
+        pass
+
+    def _protected(self):  # nosort
+        pass  # Stays here, between public methods
+
+    def public_b(self):
+        pass  # Will move up, but _protected stays in place
+```
+
 ## Usage
 
 ### Command Line
@@ -121,9 +172,10 @@ repos:
     hooks:
       - id: undersort
         name: undersort
-        entry: uv run undersort
-        language: system
+        entry: undersort
+        language: python
         types: [python]
+        additional_dependencies: ["undersort"]
 ```
 
 Then install the hook:

{undersort-0.1.2 → undersort-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "undersort"
-version = "0.1.2"
+version = "0.1.4"
 description = "A tool to sort class methods by visibility (public, protected, private)"
 authors = [{ name = "KiviCode", email = "kivicode.dev@gmail.com" }]
 readme = "README.md"

undersort-0.1.4/tests/test_nosort.py

@@ -0,0 +1,190 @@
+"""Tests for nosort comment directives."""
+
+import tempfile
+from pathlib import Path
+
+from undersort.sorter import sort_file
+
+
+class TestNosortDirectives:
+    """Tests for # nosort comment functionality."""
+
+    def test_file_level_nosort(self) -> None:
+        """Test that file-level nosort prevents all sorting."""
+        source = """# nosort: file
+class Example:
+    def _protected(self):
+        pass
+
+    def public(self):
+        pass
+"""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(source)
+            temp_path = Path(f.name)
+
+        try:
+            order = ["public", "protected", "private"]
+            was_modified = sort_file(temp_path, order)
+
+            assert was_modified is False
+
+            with open(temp_path) as f:
+                result = f.read()
+
+            assert result == source
+        finally:
+            temp_path.unlink()
+
+    def test_class_level_nosort(self) -> None:
+        """Test that class-level nosort prevents sorting that class."""
+        source = """class Example:  # nosort
+    def _protected(self):
+        pass
+
+    def public(self):
+        pass
+"""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(source)
+            temp_path = Path(f.name)
+
+        try:
+            order = ["public", "protected", "private"]
+            was_modified = sort_file(temp_path, order)
+
+            assert was_modified is False
+
+            with open(temp_path) as f:
+                result = f.read()
+
+            assert result == source
+        finally:
+            temp_path.unlink()
+
+    def test_method_level_nosort(self) -> None:
+        """Test that method-level nosort keeps that method in place."""
+        source = """class Example:
+    def public_a(self):
+        pass
+
+    def _protected_x(self):  # nosort
+        pass
+
+    def public_b(self):
+        pass
+"""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(source)
+            temp_path = Path(f.name)
+
+        try:
+            order = ["public", "protected", "private"]
+            was_modified = sort_file(temp_path, order)
+
+            assert was_modified is False
+
+            with open(temp_path) as f:
+                result = f.read()
+
+            protected_idx = result.find("def _protected_x")
+            public_a_idx = result.find("def public_a")
+            public_b_idx = result.find("def public_b")
+
+            assert public_a_idx < protected_idx < public_b_idx
+        finally:
+            temp_path.unlink()
+
+    def test_multiple_nosort_methods(self) -> None:
+        """Test multiple methods with nosort."""
+        source = """class Example:
+    def public_a(self):
+        pass
+
+    def _protected_x(self):  # nosort
+        pass
+
+    def public_b(self):  # nosort
+        pass
+
+    def _protected_y(self):
+        pass
+"""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(source)
+            temp_path = Path(f.name)
+
+        try:
+            order = ["public", "protected", "private"]
+            was_modified = sort_file(temp_path, order)
+
+            assert was_modified is False
+
+            with open(temp_path) as f:
+                result = f.read()
+
+            assert result == source
+        finally:
+            temp_path.unlink()
+
+    def test_nosort_case_insensitive(self) -> None:
+        """Test that NOSORT and NoSort also work."""
+        source = """class Example:  # NOSORT
+    def _protected(self):
+        pass
+
+    def public(self):
+        pass
+"""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(source)
+            temp_path = Path(f.name)
+
+        try:
+            order = ["public", "protected", "private"]
+            was_modified = sort_file(temp_path, order)
+
+            assert was_modified is False
+        finally:
+            temp_path.unlink()
+
+    def test_nosort_with_other_classes(self) -> None:
+        """Test that nosort on one class doesn't affect others."""
+        source = """class First:  # nosort
+    def _protected(self):
+        pass
+
+    def public(self):
+        pass
+
+class Second:
+    def _protected(self):
+        pass
+
+    def public(self):
+        pass
+"""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(source)
+            temp_path = Path(f.name)
+
+        try:
+            order = ["public", "protected", "private"]
+            was_modified = sort_file(temp_path, order)
+
+            assert was_modified is True
+
+            with open(temp_path) as f:
+                result = f.read()
+
+            first_protected_idx = result.find("class First")
+            first_protected_method_idx = result.find("def _protected", first_protected_idx)
+            first_public_idx = result.find("def public", first_protected_idx)
+            second_class_idx = result.find("class Second")
+            second_public_idx = result.find("def public", second_class_idx)
+            second_protected_idx = result.find("def _protected", second_class_idx)
+
+            assert first_protected_method_idx < first_public_idx
+            assert second_public_idx < second_protected_idx
+        finally:
+            temp_path.unlink()

{undersort-0.1.2 → undersort-0.1.4}/undersort/__init__.py

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

{undersort-0.1.2 → undersort-0.1.4}/undersort/sorter.py

@@ -9,6 +9,46 @@ import libcst as cst
 from undersort import logger
 
 
+def has_nosort_comment(node: cst.FunctionDef | cst.ClassDef) -> bool:
+    """Check if a node has a nosort comment.
+
+    Args:
+        node: The node to check
+
+    Returns:
+        True if the node has a # nosort comment
+    """
+    if hasattr(node, "leading_lines"):
+        for line in node.leading_lines:
+            if isinstance(line, cst.EmptyLine) and line.comment and "nosort" in line.comment.value.lower():
+                return True
+
+    return bool(
+        hasattr(node, "body")
+        and hasattr(node.body, "header")
+        and isinstance(node.body.header, cst.TrailingWhitespace)
+        and node.body.header.comment
+        and "nosort" in node.body.header.comment.value.lower()
+    )
+
+
+def file_has_nosort(module: cst.Module) -> bool:
+    """Check if a file has a file-level nosort directive.
+
+    Args:
+        module: The module to check
+
+    Returns:
+        True if the file has a # nosort: file comment
+    """
+    for line in module.header:
+        if isinstance(line, cst.EmptyLine) and line.comment:
+            comment_text = line.comment.value.lower()
+            if "nosort" in comment_text and "file" in comment_text:
+                return True
+    return False
+
+
 def get_method_visibility(method_name: str) -> Literal["public", "private", "protected"]:
     """Determine method visibility based on naming convention.
 
@@ -71,7 +111,9 @@ class MethodSorter(cst.CSTTransformer):
         self.modified = False
 
     def leave_ClassDef(  # noqa: PLR0912, PLR0915
-        self, original_node: cst.ClassDef, updated_node: cst.ClassDef
+        self,
+        original_node: cst.ClassDef,
+        updated_node: cst.ClassDef,  # noqa: ARG002
     ) -> cst.ClassDef:
         """Sort methods within a class definition.
 
@@ -82,6 +124,9 @@ class MethodSorter(cst.CSTTransformer):
         Returns:
             ClassDef with sorted methods
         """
+        if has_nosort_comment(updated_node):
+            return updated_node
+
         methods = []
         non_methods = []
 
@@ -94,7 +139,17 @@ class MethodSorter(cst.CSTTransformer):
         if not methods:
             return updated_node
 
-        method_with_index = [(i, method) for i, method in enumerate(methods)]
+        sortable_methods = []
+        nosort_methods = []
+
+        for i, method in enumerate(methods):
+            if has_nosort_comment(method):
+                nosort_methods.append((i, method))
+            else:
+                sortable_methods.append((i, method))
+
+        if not sortable_methods:
+            return updated_node
 
         method_groups: dict[str, dict[str, list[tuple[int, cst.FunctionDef]]]] = {
             "public": {"class": [], "static": [], "instance": []},
@@ -102,7 +157,7 @@ class MethodSorter(cst.CSTTransformer):
             "private": {"class": [], "static": [], "instance": []},
         }
 
-        for idx, method in method_with_index:
+        for idx, method in sortable_methods:
             visibility = get_method_visibility(method.name.value)
             method_type = get_method_type(method)
             method_groups[visibility][method_type].append((idx, method))
@@ -145,9 +200,15 @@ class MethodSorter(cst.CSTTransformer):
 
             current_position += len(group)
 
-        if methods != sorted_methods:
+        all_sorted = sorted_methods[:]
+        for orig_idx, nosort_method in sorted(nosort_methods, key=lambda x: x[0]):
+            all_sorted.insert(orig_idx, nosort_method)
+
+        if methods != all_sorted:
             self.modified = True
 
+        sorted_methods = all_sorted
+
         leading_non_methods = []
         trailing_non_methods = []
         found_method = False
@@ -193,6 +254,9 @@ def sort_file(
     except cst.ParserSyntaxError as e:
         raise ValueError(f"Syntax error in {file_path}: {e}")
 
+    if file_has_nosort(tree):
+        return False
+
     sorter = MethodSorter(order, method_type_order)
     new_tree = tree.visit(sorter)
 

{undersort-0.1.2 → undersort-0.1.4}/uv.lock

@@ -905,7 +905,7 @@ wheels = [
 
 [[package]]
 name = "undersort"
-version = "0.1.2"
+version = "0.1.4"
 source = { editable = "." }
 dependencies = [
     { name = "libcst", version = "1.1.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.9'" },