undersort 0.1.6__tar.gz → 0.1.7__tar.gz

{undersort-0.1.6 → undersort-0.1.7}/.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
 
@@ -49,15 +49,13 @@ jobs:
           enable-cache: true
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync
+        run: uv sync --python ${{ matrix.python-version }}
 
       - name: Run tests
-        run: uv run pytest -v --cov=undersort --cov-report=term-missing
+        run: uv run --python ${{ matrix.python-version }} pytest -v --cov=undersort --cov-report=term-missing
 
   publish:
     name: Publish to PyPI

{undersort-0.1.6 → undersort-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: undersort
-Version: 0.1.6
+Version: 0.1.7
 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
@@ -13,14 +13,12 @@ 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: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.8
+Requires-Python: >=3.11
 Requires-Dist: libcst>=1.1.0
 Requires-Dist: rich>=13.0.0
 Description-Content-Type: text/markdown
@@ -63,7 +61,9 @@ Configure the method ordering in your `pyproject.toml`:
 ```toml
 [tool.undersort]
 # Method visibility ordering (primary sort)
-# Options: "public", "protected", "private"
+# Required groups: "public", "protected", "private"
+# Optional groups: "init" (creational dunders), "dunder" (all other magic methods)
+# Omit the optional groups to keep magic methods inside "public" (the default).
 order = ["public", "protected", "private"]
 
 # Method type ordering within each visibility level (secondary sort, optional)
@@ -93,6 +93,46 @@ method_type_order = ["instance", "class", "static"]
 - **Protected methods**: Single underscore prefix (e.g., `def _method()`)
 - **Private methods**: Double underscore prefix, not magic (e.g., `def __method()`)
 
+#### Separating dunder methods
+
+By default magic methods count as **public**, which leaves `__init__` mixed in with
+ordinary public methods. Add either of the two optional groups to `order` to pull
+them out:
+
+- **`init`** — creational dunders: `__new__`, `__init__`, `__init_subclass__`, `__post_init__`
+- **`dunder`** — every other magic method: `__str__`, `__get__`, `__eq__`, ...
+
+```toml
+[tool.undersort]
+order = ["init", "dunder", "public", "protected", "private"]
+method_type_order = ["static", "class", "instance"]
+```
+
+```python
+# before                              # after
+class C:                              class C:
+    @classmethod                          def __init__(self) -> None: ...
+    def default(cls): ...
+                                          def __str__(self) -> str: ...
+    def __init__(self) -> None: ...
+                                          @classmethod
+    def random_public(self): ...          def default(cls): ...
+
+    def __str__(self) -> str: ...         def random_public(self): ...
+```
+
+The groups are positional, so `order = ["public", "protected", "private", "init", "dunder"]`
+puts the magic methods last instead.
+
+Notes:
+
+- `public`, `protected` and `private` must always be present, so no method can be
+  silently dropped. `init` and `dunder` are optional.
+- Using `init` without `dunder` leaves non-creational magic methods in `public`.
+- Name-mangled methods (`__method`, no trailing underscores) remain **private** —
+  they are not dunders.
+- An existing `order` that does not mention the new groups behaves exactly as before.
+
 ### Method Type Rules
 
 - **Class methods**: Decorated with `@classmethod`

{undersort-0.1.6 → undersort-0.1.7}/README.md

@@ -36,7 +36,9 @@ Configure the method ordering in your `pyproject.toml`:
 ```toml
 [tool.undersort]
 # Method visibility ordering (primary sort)
-# Options: "public", "protected", "private"
+# Required groups: "public", "protected", "private"
+# Optional groups: "init" (creational dunders), "dunder" (all other magic methods)
+# Omit the optional groups to keep magic methods inside "public" (the default).
 order = ["public", "protected", "private"]
 
 # Method type ordering within each visibility level (secondary sort, optional)
@@ -66,6 +68,46 @@ method_type_order = ["instance", "class", "static"]
 - **Protected methods**: Single underscore prefix (e.g., `def _method()`)
 - **Private methods**: Double underscore prefix, not magic (e.g., `def __method()`)
 
+#### Separating dunder methods
+
+By default magic methods count as **public**, which leaves `__init__` mixed in with
+ordinary public methods. Add either of the two optional groups to `order` to pull
+them out:
+
+- **`init`** — creational dunders: `__new__`, `__init__`, `__init_subclass__`, `__post_init__`
+- **`dunder`** — every other magic method: `__str__`, `__get__`, `__eq__`, ...
+
+```toml
+[tool.undersort]
+order = ["init", "dunder", "public", "protected", "private"]
+method_type_order = ["static", "class", "instance"]
+```
+
+```python
+# before                              # after
+class C:                              class C:
+    @classmethod                          def __init__(self) -> None: ...
+    def default(cls): ...
+                                          def __str__(self) -> str: ...
+    def __init__(self) -> None: ...
+                                          @classmethod
+    def random_public(self): ...          def default(cls): ...
+
+    def __str__(self) -> str: ...         def random_public(self): ...
+```
+
+The groups are positional, so `order = ["public", "protected", "private", "init", "dunder"]`
+puts the magic methods last instead.
+
+Notes:
+
+- `public`, `protected` and `private` must always be present, so no method can be
+  silently dropped. `init` and `dunder` are optional.
+- Using `init` without `dunder` leaves non-creational magic methods in `public`.
+- Name-mangled methods (`__method`, no trailing underscores) remain **private** —
+  they are not dunders.
+- An existing `order` that does not mention the new groups behaves exactly as before.
+
 ### Method Type Rules
 
 - **Class methods**: Decorated with `@classmethod`

{undersort-0.1.6 → undersort-0.1.7}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "undersort"
-version = "0.1.6"
+version = "0.1.7"
 description = "A tool to sort class methods by visibility (public, protected, private)"
 authors = [{ name = "KiviCode", email = "kivicode.dev@gmail.com" }]
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.11"
 license = { text = "MIT" }
 keywords = ["sorting", "code-formatter", "linter", "python", "class-methods"]
 classifiers = [
@@ -16,11 +16,9 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Quality Assurance",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]

undersort-0.1.7/tests/test_dunder_order.py

@@ -0,0 +1,201 @@
+"""Tests for splitting dunder methods out of the public group (issue #1)."""
+
+from pathlib import Path
+
+import libcst as cst
+import pytest
+
+from undersort.config import load_config
+from undersort.sorter import MethodSorter, get_method_visibility, is_dunder, sort_module_definitions
+
+FULL = ["init", "dunder", "public", "protected", "private"]
+LEGACY = ["public", "protected", "private"]
+TYPE_ORDER = ["static", "class", "instance"]
+
+
+def method_names(source: str) -> list[str]:
+    """List method names of the first class, in order.
+
+    Args:
+        source: The source code
+
+    Returns:
+        The method names
+    """
+    module = cst.parse_module(source)
+    class_def = next(s for s in module.body if isinstance(s, cst.ClassDef))
+    return [item.name.value for item in class_def.body.body if isinstance(item, cst.FunctionDef)]
+
+
+def sort_class(source: str, order: list[str], method_type_order: list[str] | None = None) -> str:
+    """Sort methods of a class snippet with the given ordering.
+
+    Args:
+        source: The source code
+        order: Visibility ordering
+        method_type_order: Optional method type ordering
+
+    Returns:
+        The sorted source
+    """
+    module = cst.parse_module(source)
+    return module.visit(MethodSorter(order, method_type_order)).code
+
+
+SAMPLE = """class C:
+    def _helper(self): ...
+
+    @classmethod
+    def default(cls): ...
+
+    def __init__(self) -> None: ...
+
+    def public_a(self): ...
+
+    def __str__(self) -> str: ...
+
+    def __private(self): ...
+"""
+
+
+class TestVisibilityClassification:
+    """Tests for the order-aware visibility classifier."""
+
+    def test_dunder_detection(self) -> None:
+        """Only names wrapped in double underscores are dunders."""
+        assert is_dunder("__init__") is True
+        assert is_dunder("__str__") is True
+        assert is_dunder("__private") is False
+        assert is_dunder("_protected") is False
+        assert is_dunder("public") is False
+
+    def test_dunders_are_public_without_configuration(self) -> None:
+        """Legacy behaviour: magic methods count as public."""
+        assert get_method_visibility("__init__") == "public"
+        assert get_method_visibility("__str__", LEGACY) == "public"
+
+    def test_dunder_group_captures_magic_methods(self) -> None:
+        """With a dunder group, magic methods leave the public group."""
+        order = ["dunder", "public", "protected", "private"]
+        assert get_method_visibility("__str__", order) == "dunder"
+        assert get_method_visibility("__init__", order) == "dunder"
+
+    def test_init_group_captures_creational_dunders(self) -> None:
+        """Creational dunders form their own group when requested."""
+        assert get_method_visibility("__init__", FULL) == "init"
+        assert get_method_visibility("__new__", FULL) == "init"
+        assert get_method_visibility("__init_subclass__", FULL) == "init"
+        assert get_method_visibility("__post_init__", FULL) == "init"
+        assert get_method_visibility("__str__", FULL) == "dunder"
+
+    def test_init_group_without_dunder_group(self) -> None:
+        """Non-creational dunders fall back to public when no dunder group exists."""
+        order = ["init", "public", "protected", "private"]
+        assert get_method_visibility("__init__", order) == "init"
+        assert get_method_visibility("__str__", order) == "public"
+
+    def test_non_dunder_underscores_unaffected(self) -> None:
+        """Name-mangled and protected names keep their existing groups."""
+        assert get_method_visibility("__private", FULL) == "private"
+        assert get_method_visibility("_protected", FULL) == "protected"
+        assert get_method_visibility("public", FULL) == "public"
+
+
+class TestIssueScenarios:
+    """The two cases reported in issue #1."""
+
+    def test_init_no_longer_trails_a_classmethod(self) -> None:
+        """__init__ can be pulled ahead of a public classmethod."""
+        source = "class C:\n    @classmethod\n    def default(cls): ...\n\n    def __init__(self) -> None: ...\n"
+        assert method_names(sort_class(source, FULL, TYPE_ORDER)) == ["__init__", "default"]
+
+    def test_dunders_group_together(self) -> None:
+        """__init__ and __str__ end up adjacent instead of split by a public method."""
+        source = (
+            "class C:\n    def __init__(self) -> None: ...\n\n"
+            "    def random_public(self): ...\n\n"
+            "    def __str__(self) -> str: ...\n"
+        )
+        assert method_names(sort_class(source, FULL, TYPE_ORDER)) == ["__init__", "__str__", "random_public"]
+
+    def test_legacy_order_is_unchanged(self) -> None:
+        """An order without dunder groups keeps magic methods in the public group."""
+        assert method_names(sort_class(SAMPLE, LEGACY, TYPE_ORDER)) == [
+            "default",
+            "__init__",
+            "public_a",
+            "__str__",
+            "_helper",
+            "__private",
+        ]
+
+    def test_full_order_groups_everything(self) -> None:
+        """Creational, generic dunder, public, protected and private all separate."""
+        assert method_names(sort_class(SAMPLE, FULL, TYPE_ORDER)) == [
+            "__init__",
+            "__str__",
+            "default",
+            "public_a",
+            "_helper",
+            "__private",
+        ]
+
+    def test_dunders_can_be_placed_last(self) -> None:
+        """The groups are positional, so dunders can also go at the end."""
+        order = ["public", "protected", "private", "init", "dunder"]
+        assert method_names(sort_class(SAMPLE, order, TYPE_ORDER))[-2:] == ["__init__", "__str__"]
+
+    def test_blank_lines_stay_sane(self) -> None:
+        """Moving a dunder to the front does not collapse the spacing."""
+        source = "class C:\n    @classmethod\n    def default(cls): ...\n\n    def __init__(self) -> None: ...\n"
+        result = sort_class(source, FULL, TYPE_ORDER)
+        assert (
+            result == "class C:\n    def __init__(self) -> None: ...\n\n    @classmethod\n    def default(cls): ...\n"
+        )
+
+
+class TestOrderValidation:
+    """Tests for validating the extended order option."""
+
+    @pytest.mark.parametrize(
+        "order",
+        [
+            ["init", "dunder", "public", "protected", "private"],
+            ["dunder", "public", "protected", "private"],
+            ["public", "protected", "private"],
+            ["private", "protected", "public"],
+        ],
+    )
+    def test_valid_orders_accepted(self, order: list[str], tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Orders containing all required groups are accepted."""
+        (tmp_path / "pyproject.toml").write_text(f"[tool.undersort]\norder = {order!r}\n".replace("'", '"'))
+        monkeypatch.chdir(tmp_path)
+        assert load_config()["order"] == order
+
+    @pytest.mark.parametrize(
+        "order",
+        [
+            ["init", "dunder", "public"],
+            ["public", "protected", "private", "bogus"],
+            ["public", "public", "protected", "private"],
+            "notalist",
+        ],
+    )
+    def test_invalid_orders_fall_back(self, order: object, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Incomplete, unknown, duplicated or malformed orders fall back to the default."""
+        rendered = repr(order).replace("'", '"')
+        (tmp_path / "pyproject.toml").write_text(f"[tool.undersort]\norder = {rendered}\n")
+        monkeypatch.chdir(tmp_path)
+        assert load_config()["order"] == ["public", "protected", "private"]
+
+
+class TestModuleLevelDunders:
+    """Dunder grouping also applies to module-level definitions."""
+
+    def test_module_dunder_grouped(self) -> None:
+        """A module-level __getattr__ follows the configured dunder group."""
+        source = "def _helper():\n    pass\n\n\ndef __getattr__(name):\n    pass\n"
+        module = cst.parse_module(source)
+        new_module, modified = sort_module_definitions(module, FULL, True)
+        assert modified is True
+        assert new_module.code.index("__getattr__") < new_module.code.index("_helper")

{undersort-0.1.6 → undersort-0.1.7}/tests/test_sorter.py

@@ -1,8 +1,10 @@
 import tempfile
 from pathlib import Path
 
+import libcst as cst
 import pytest
 
+from undersort.deps import eager_names
 from undersort.sorter import get_method_visibility, sort_file
 
 
@@ -486,3 +488,22 @@ class Example:
             assert protected_instance_idx < protected_class_idx < protected_static_idx
         finally:
             temp_path.unlink()
+
+
+def test_long_implicit_string_concatenation_does_not_recurse(tmp_path: Path) -> None:
+    pieces = "\n".join(f'    "chunk{i}"' for i in range(3000))
+    source = (
+        f"PACKED = (\n{pieces}\n)\n\n\nclass A:\n    BLOB = (\n{pieces}\n    )\n\n"
+        "    def _b(self):\n        pass\n\n    def a(self):\n        pass\n"
+    )
+    path = tmp_path / "packed.py"
+    path.write_text(source)
+
+    assert sort_file(path, ["public", "protected", "private"], sort_module_level=True)
+    assert path.read_text().index("def a(") < path.read_text().index("def _b(")
+
+
+def test_eager_names_walks_long_concatenation() -> None:
+    pieces = " ".join(f'"c{i}"' for i in range(3000))
+    module = cst.parse_module(f"class A(Base):\n    X = ({pieces})\n")
+    assert "Base" in eager_names(module.body[0], eager_annotations=False)

{undersort-0.1.6 → undersort-0.1.7}/undersort/__init__.py

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

{undersort-0.1.6 → undersort-0.1.7}/undersort/config.py

@@ -7,7 +7,9 @@ from typing import Any
 from undersort import logger
 from undersort.deps import parse_python_version
 
-VALID_VISIBILITIES = {"public", "protected", "private"}
+REQUIRED_VISIBILITIES = {"public", "protected", "private"}
+OPTIONAL_VISIBILITIES = {"init", "dunder"}
+VALID_VISIBILITIES = REQUIRED_VISIBILITIES | OPTIONAL_VISIBILITIES
 VALID_METHOD_TYPES = {"class", "static", "instance"}
 
 
@@ -69,8 +71,9 @@ def _load_orderings(config: dict[str, Any], result: dict[str, Any], pyproject_pa
     """
     if "order" in config:
         order = config["order"]
-        if sorted(order) != sorted(VALID_VISIBILITIES):
-            logger.warning(f"Invalid order values in {pyproject_path}. Using default order.")
+        problem = _order_problem(order)
+        if problem:
+            logger.warning(f"Invalid order in {pyproject_path}: {problem}. Using default order.")
         else:
             result["order"] = order
 
@@ -82,6 +85,36 @@ def _load_orderings(config: dict[str, Any], result: dict[str, Any], pyproject_pa
             result["method_type_order"] = method_type_order
 
 
+def _order_problem(order: Any) -> str | None:
+    """Validate a configured visibility order.
+
+    ``public``, ``protected`` and ``private`` must all appear, so no method can be
+    silently dropped. The dunder groups are optional: leaving them out keeps magic
+    methods in ``public``, which is how earlier versions behaved.
+
+    Args:
+        order: The configured value
+
+    Returns:
+        A description of the problem, or None if the order is usable
+    """
+    if not isinstance(order, list) or not all(isinstance(value, str) for value in order):
+        return "must be a list of strings"
+
+    unknown = [value for value in order if value not in VALID_VISIBILITIES]
+    if unknown:
+        return f"unknown group(s) {sorted(unknown)}; valid groups are {sorted(VALID_VISIBILITIES)}"
+
+    if len(set(order)) != len(order):
+        return "contains duplicate groups"
+
+    missing = REQUIRED_VISIBILITIES - set(order)
+    if missing:
+        return f"missing required group(s) {sorted(missing)}"
+
+    return None
+
+
 def _load_module_level_options(config: dict[str, Any], result: dict[str, Any], pyproject_path: Path) -> None:
     """Read the module-level sorting options into the result.
 

{undersort-0.1.6 → undersort-0.1.7}/undersort/deps.py

@@ -146,6 +146,25 @@ class _EagerNameCollector(cst.CSTVisitor):
         self.names: set[str] = set()
         self.eager_annotations = eager_annotations
 
+    def visit_ConcatenatedString(self, node: cst.ConcatenatedString) -> bool:
+        """Walk an implicit string concatenation without recursing per literal.
+
+        Args:
+            node: The concatenated string
+
+        Returns:
+            False -- parts are visited manually
+        """
+        # libcst nests each extra literal one level deeper; long chains exceed the recursion limit.
+        stack: list[cst.BaseExpression] = [node]
+        while stack:
+            part = stack.pop()
+            if isinstance(part, cst.ConcatenatedString):
+                stack.extend((part.right, part.left))
+            else:
+                part.visit(self)
+        return False
+
     def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:
         """Collect eager references of a function definition, skipping its body.