undersort 0.1.4__tar.gz → 0.1.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: undersort
-Version: 0.1.4
+Version: 0.1.6
 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
@@ -33,6 +33,8 @@ A Python tool that automatically sorts class methods by visibility (public, prot
 
 - Automatically reorders class methods based on visibility and method type
 - Two-level sorting: primary by visibility, secondary by method type
+- Optional module-level mode that sorts top-level functions and classes, with
+  dependency analysis so decorators, base classes, and annotations keep working
 - Fully configurable ordering via `pyproject.toml`
 - Pre-commit hook integration
 - Colored output for better readability
@@ -68,6 +70,21 @@ order = ["public", "protected", "private"]
 # Options: "class" (classmethod), "static" (staticmethod), "instance" (regular methods)
 # Default: ["instance", "class", "static"]
 method_type_order = ["instance", "class", "static"]
+
+# Exclude files/directories matching these patterns (optional)
+# Patterns support glob syntax (e.g., "tests/*", "migrations/*.py", "**/generated/*")
+# exclude = ["tests/*", "migrations/*.py"]
+
+# Also sort module-level functions and classes (optional, default: false)
+# sort_module_level = true
+
+# Allow decorated module-level definitions to move (optional, default: false)
+# Leave off unless your decorators have no order-dependent import-time side effects
+# sort_decorated = true
+
+# Target Python version, used to decide whether annotations are evaluated eagerly
+# (optional; inferred from [project] requires-python when not set)
+# python_version = "3.12"
 ```
 
 ### Method Visibility Rules
@@ -107,6 +124,103 @@ Example order with default configuration:
 8. Private class methods
 9. Private static methods
 
+## Module-Level Sorting (optional)
+
+By default undersort only reorders methods inside classes. Enable `sort_module_level`
+to apply the same visibility ordering to top-level functions and classes:
+
+```toml
+[tool.undersort]
+sort_module_level = true
+```
+
+Or from the command line: `undersort --sort-module-level src/` (use
+`--no-sort-module-level` to override the config file for one run).
+
+Classes and functions are ordered in a single stream by the same naming rules
+(`public` → `protected` → `private`).
+
+### Safety Rules
+
+Unlike methods in a class body, module-level definitions execute in order, so
+reordering them can break a module. undersort only moves a definition when it is
+provably safe:
+
+**Non-definition statements are barriers.** Definitions are only reordered within
+runs of consecutive `def`/`class` statements. An import, assignment, or `if` block
+between them splits the file into independent runs, so nothing moves across it:
+
+```python
+def _helper(): ...
+def public_a(): ...    # these two are sorted together
+
+CONSTANT = compute()   # barrier -- nothing crosses this line
+
+def _other(): ...
+def public_b(): ...    # these two are sorted together
+```
+
+**Definition-time references are respected.** A definition never moves above
+something it needs when it is defined. That includes decorators, base classes and
+`metaclass=` keywords, default argument values, and class bodies (which run
+eagerly, though method bodies inside them do not):
+
+```python
+class _Base: ...
+
+class Public(_Base):   # stays below _Base despite being public
+    ...
+```
+
+References made inside a function or method body impose no constraint, since they
+resolve when the function is called rather than when it is defined.
+
+**Annotations are handled according to the effective evaluation semantics.**
+Annotations are eagerly evaluated -- and therefore constrain ordering -- unless
+either of the following applies, in which case annotated types are free to move:
+
+- the module starts with `from __future__ import annotations` (PEP 563)
+- the target Python version is 3.14 or newer, where annotations are lazy by
+  default (PEP 649)
+
+The target version comes from `python_version`, or the project's
+`requires-python` lower bound, or the running interpreter, in that order.
+
+**Redefined names never move.** If a name is defined more than once at the top
+level (`@overload` blocks, `@singledispatch` registrations, conditional
+redefinitions), all of its definitions stay put.
+
+**Decorated definitions are pinned by default.** A decorator runs at import time
+and can have side effects whose *order* matters — `@app.route`, `@cli.command`,
+`@register` and friends append to a registry as the module loads. No static
+analysis can tell a registering decorator from a pure one, so decorated
+definitions keep their position unless you opt in:
+
+```toml
+[tool.undersort]
+sort_decorated = true    # only if you know your decorators are order-independent
+```
+
+**`# nosort` still applies**, both file-level and on individual definitions.
+Note that at module level a pinned definition acts as a hard anchor: nothing is
+reordered across it. This is stricter than the class-method behaviour, because
+top-level statements execute in order.
+
+### Known Limitation
+
+undersort guarantees that reordering never breaks *name resolution* — nothing
+moves above a name it needs at definition time. It cannot fully guarantee
+*side-effect order*. Pinning decorated definitions covers the common registry
+pattern, but two cases remain outside static reach:
+
+- classes whose creation has side effects through a base class defined in another
+  module (`__init_subclass__` hooks, registering metaclasses)
+- any definition whose mere position is load-bearing for reasons not visible in
+  the file
+
+If your module has import-time ordering semantics like these, mark the affected
+definitions with `# nosort`, or leave `sort_module_level` off for that file.
+
 ### Skipping Sorting with `# nosort`
 
 You can prevent sorting at different levels using `# nosort` comments (case-insensitive):
@@ -185,9 +299,27 @@ undersort --diff example.py
 
 # Combine flags
 undersort --check --diff src/
+
+# Exclude specific files or directories
+undersort --exclude "tests/*" --exclude "migrations/*.py" src/
+
+# Multiple exclude patterns (can be combined with config file patterns)
+undersort --exclude "test_*.py" --exclude "*/legacy/*" .
+
+# Also sort module-level functions and classes
+undersort --sort-module-level src/
+
+# Override the config file for a single run
+undersort --no-sort-module-level src/
+
+# Tell undersort which Python version to assume for annotation semantics
+undersort --sort-module-level --python-version 3.14 src/
+
+# Also reorder decorated definitions (off by default, see Known Limitation)
+undersort --sort-module-level --sort-decorated src/
 ```
 
-**Note**: By default, undersort excludes all dot-prefixed directories (e.g., `.venv`, `.git`, `.pytest_cache`) and common build directories (`venv`, `__pycache__`, `node_modules`) when scanning directories recursively.
+**Note**: By default, undersort excludes all dot-prefixed directories (e.g., `.venv`, `.git`, `.pytest_cache`) and common build directories (`venv`, `__pycache__`, `node_modules`) when scanning directories recursively. You can add custom exclusions via CLI flags or the config file.
 
 ### Pre-commit Integration
 

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

@@ -6,6 +6,8 @@ A Python tool that automatically sorts class methods by visibility (public, prot
 
 - Automatically reorders class methods based on visibility and method type
 - Two-level sorting: primary by visibility, secondary by method type
+- Optional module-level mode that sorts top-level functions and classes, with
+  dependency analysis so decorators, base classes, and annotations keep working
 - Fully configurable ordering via `pyproject.toml`
 - Pre-commit hook integration
 - Colored output for better readability
@@ -41,6 +43,21 @@ order = ["public", "protected", "private"]
 # Options: "class" (classmethod), "static" (staticmethod), "instance" (regular methods)
 # Default: ["instance", "class", "static"]
 method_type_order = ["instance", "class", "static"]
+
+# Exclude files/directories matching these patterns (optional)
+# Patterns support glob syntax (e.g., "tests/*", "migrations/*.py", "**/generated/*")
+# exclude = ["tests/*", "migrations/*.py"]
+
+# Also sort module-level functions and classes (optional, default: false)
+# sort_module_level = true
+
+# Allow decorated module-level definitions to move (optional, default: false)
+# Leave off unless your decorators have no order-dependent import-time side effects
+# sort_decorated = true
+
+# Target Python version, used to decide whether annotations are evaluated eagerly
+# (optional; inferred from [project] requires-python when not set)
+# python_version = "3.12"
 ```
 
 ### Method Visibility Rules
@@ -80,6 +97,103 @@ Example order with default configuration:
 8. Private class methods
 9. Private static methods
 
+## Module-Level Sorting (optional)
+
+By default undersort only reorders methods inside classes. Enable `sort_module_level`
+to apply the same visibility ordering to top-level functions and classes:
+
+```toml
+[tool.undersort]
+sort_module_level = true
+```
+
+Or from the command line: `undersort --sort-module-level src/` (use
+`--no-sort-module-level` to override the config file for one run).
+
+Classes and functions are ordered in a single stream by the same naming rules
+(`public` → `protected` → `private`).
+
+### Safety Rules
+
+Unlike methods in a class body, module-level definitions execute in order, so
+reordering them can break a module. undersort only moves a definition when it is
+provably safe:
+
+**Non-definition statements are barriers.** Definitions are only reordered within
+runs of consecutive `def`/`class` statements. An import, assignment, or `if` block
+between them splits the file into independent runs, so nothing moves across it:
+
+```python
+def _helper(): ...
+def public_a(): ...    # these two are sorted together
+
+CONSTANT = compute()   # barrier -- nothing crosses this line
+
+def _other(): ...
+def public_b(): ...    # these two are sorted together
+```
+
+**Definition-time references are respected.** A definition never moves above
+something it needs when it is defined. That includes decorators, base classes and
+`metaclass=` keywords, default argument values, and class bodies (which run
+eagerly, though method bodies inside them do not):
+
+```python
+class _Base: ...
+
+class Public(_Base):   # stays below _Base despite being public
+    ...
+```
+
+References made inside a function or method body impose no constraint, since they
+resolve when the function is called rather than when it is defined.
+
+**Annotations are handled according to the effective evaluation semantics.**
+Annotations are eagerly evaluated -- and therefore constrain ordering -- unless
+either of the following applies, in which case annotated types are free to move:
+
+- the module starts with `from __future__ import annotations` (PEP 563)
+- the target Python version is 3.14 or newer, where annotations are lazy by
+  default (PEP 649)
+
+The target version comes from `python_version`, or the project's
+`requires-python` lower bound, or the running interpreter, in that order.
+
+**Redefined names never move.** If a name is defined more than once at the top
+level (`@overload` blocks, `@singledispatch` registrations, conditional
+redefinitions), all of its definitions stay put.
+
+**Decorated definitions are pinned by default.** A decorator runs at import time
+and can have side effects whose *order* matters — `@app.route`, `@cli.command`,
+`@register` and friends append to a registry as the module loads. No static
+analysis can tell a registering decorator from a pure one, so decorated
+definitions keep their position unless you opt in:
+
+```toml
+[tool.undersort]
+sort_decorated = true    # only if you know your decorators are order-independent
+```
+
+**`# nosort` still applies**, both file-level and on individual definitions.
+Note that at module level a pinned definition acts as a hard anchor: nothing is
+reordered across it. This is stricter than the class-method behaviour, because
+top-level statements execute in order.
+
+### Known Limitation
+
+undersort guarantees that reordering never breaks *name resolution* — nothing
+moves above a name it needs at definition time. It cannot fully guarantee
+*side-effect order*. Pinning decorated definitions covers the common registry
+pattern, but two cases remain outside static reach:
+
+- classes whose creation has side effects through a base class defined in another
+  module (`__init_subclass__` hooks, registering metaclasses)
+- any definition whose mere position is load-bearing for reasons not visible in
+  the file
+
+If your module has import-time ordering semantics like these, mark the affected
+definitions with `# nosort`, or leave `sort_module_level` off for that file.
+
 ### Skipping Sorting with `# nosort`
 
 You can prevent sorting at different levels using `# nosort` comments (case-insensitive):
@@ -158,9 +272,27 @@ undersort --diff example.py
 
 # Combine flags
 undersort --check --diff src/
+
+# Exclude specific files or directories
+undersort --exclude "tests/*" --exclude "migrations/*.py" src/
+
+# Multiple exclude patterns (can be combined with config file patterns)
+undersort --exclude "test_*.py" --exclude "*/legacy/*" .
+
+# Also sort module-level functions and classes
+undersort --sort-module-level src/
+
+# Override the config file for a single run
+undersort --no-sort-module-level src/
+
+# Tell undersort which Python version to assume for annotation semantics
+undersort --sort-module-level --python-version 3.14 src/
+
+# Also reorder decorated definitions (off by default, see Known Limitation)
+undersort --sort-module-level --sort-decorated src/
 ```
 
-**Note**: By default, undersort excludes all dot-prefixed directories (e.g., `.venv`, `.git`, `.pytest_cache`) and common build directories (`venv`, `__pycache__`, `node_modules`) when scanning directories recursively.
+**Note**: By default, undersort excludes all dot-prefixed directories (e.g., `.venv`, `.git`, `.pytest_cache`) and common build directories (`venv`, `__pycache__`, `node_modules`) when scanning directories recursively. You can add custom exclusions via CLI flags or the config file.
 
 ### Pre-commit Integration
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "undersort"
-version = "0.1.4"
+version = "0.1.6"
 description = "A tool to sort class methods by visibility (public, protected, private)"
 authors = [{ name = "KiviCode", email = "kivicode.dev@gmail.com" }]
 readme = "README.md"
@@ -50,6 +50,10 @@ order = ["public", "protected", "private"]
 # Default order if not specified: ["instance", "class", "static"]
 method_type_order = ["instance", "class", "static"]
 
+# Exclude files/directories matching these patterns (optional)
+# Patterns support glob syntax (e.g., "tests/*", "migrations/*.py", "**/generated/*")
+# exclude = ["tests/*", "migrations/*.py"]
+
 [tool.ruff]
 unsafe-fixes = true
 exclude = [".venv"]

undersort-0.1.6/tests/test_config.py

@@ -0,0 +1,271 @@
+"""Tests for configuration loading."""
+
+from pathlib import Path
+
+import pytest
+
+from undersort.config import _find_pyproject_toml, load_config
+
+
+class TestConfigLoading:
+    """Tests for configuration loading from pyproject.toml."""
+
+    def test_default_config(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that default config is returned when no pyproject.toml exists."""
+        monkeypatch.chdir(tmp_path)
+        config = load_config()
+        assert config == {
+            "order": ["public", "protected", "private"],
+            "method_type_order": None,
+            "exclude": None,
+            "sort_module_level": False,
+            "sort_decorated": False,
+            "python_version": None,
+        }
+
+    def test_load_custom_order(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading custom order from pyproject.toml."""
+        pyproject_content = """
+[tool.undersort]
+order = ["private", "protected", "public"]
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        config = load_config()
+        assert config == {
+            "order": ["private", "protected", "public"],
+            "method_type_order": None,
+            "exclude": None,
+            "sort_module_level": False,
+            "sort_decorated": False,
+            "python_version": None,
+        }
+
+    def test_invalid_order_values(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that invalid order values fall back to default."""
+        pyproject_content = """
+[tool.undersort]
+order = ["public", "invalid", "private"]
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        config = load_config()
+        assert config == {
+            "order": ["public", "protected", "private"],
+            "method_type_order": None,
+            "exclude": None,
+            "sort_module_level": False,
+            "sort_decorated": False,
+            "python_version": None,
+        }
+
+    def test_missing_order_key(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that missing order key returns default."""
+        pyproject_content = """
+[tool.undersort]
+some_other_key = "value"
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        config = load_config()
+        assert config == {
+            "order": ["public", "protected", "private"],
+            "method_type_order": None,
+            "exclude": None,
+            "sort_module_level": False,
+            "sort_decorated": False,
+            "python_version": None,
+        }
+
+    def test_missing_tool_section(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that missing tool.undersort section returns default."""
+        pyproject_content = """
+[project]
+name = "test"
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        config = load_config()
+        assert config == {
+            "order": ["public", "protected", "private"],
+            "method_type_order": None,
+            "exclude": None,
+            "sort_module_level": False,
+            "sort_decorated": False,
+            "python_version": None,
+        }
+
+    def test_find_pyproject_in_parent(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that pyproject.toml is found in parent directories."""
+        # Create pyproject.toml in parent
+        pyproject_content = """
+[tool.undersort]
+order = ["private", "public", "protected"]
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        # Change to subdirectory
+        subdir = tmp_path / "subdir" / "nested"
+        subdir.mkdir(parents=True)
+        monkeypatch.chdir(subdir)
+
+        config = load_config()
+        assert config == {
+            "order": ["private", "public", "protected"],
+            "method_type_order": None,
+            "exclude": None,
+            "sort_module_level": False,
+            "sort_decorated": False,
+            "python_version": None,
+        }
+
+    def test_corrupted_toml(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that corrupted TOML file falls back to default."""
+        pyproject_content = """
+[tool.undersort
+order = ["public"  # Invalid TOML
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        config = load_config()
+        assert config == {
+            "order": ["public", "protected", "private"],
+            "method_type_order": None,
+            "exclude": None,
+            "sort_module_level": False,
+            "sort_decorated": False,
+            "python_version": None,
+        }
+
+    def test_find_pyproject_toml_not_found(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test _find_pyproject_toml returns None when not found."""
+        monkeypatch.chdir(tmp_path)
+        result = _find_pyproject_toml()
+        assert result is None
+
+    def test_find_pyproject_toml_found(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test _find_pyproject_toml returns path when found."""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text("[project]\nname = 'test'")
+
+        monkeypatch.chdir(tmp_path)
+        result = _find_pyproject_toml()
+        assert result == pyproject_path
+
+    def test_load_exclude_patterns(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test loading exclude patterns from pyproject.toml."""
+        pyproject_content = """
+[tool.undersort]
+order = ["public", "protected", "private"]
+exclude = ["tests/*", "migrations/*.py"]
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        config = load_config()
+        assert config == {
+            "order": ["public", "protected", "private"],
+            "method_type_order": None,
+            "exclude": ["tests/*", "migrations/*.py"],
+            "sort_module_level": False,
+            "sort_decorated": False,
+            "python_version": None,
+        }
+
+    def test_invalid_exclude_type(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that invalid exclude type falls back to None."""
+        pyproject_content = """
+[tool.undersort]
+order = ["public", "protected", "private"]
+exclude = "invalid"
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        config = load_config()
+        assert config == {
+            "order": ["public", "protected", "private"],
+            "method_type_order": None,
+            "exclude": None,
+            "sort_module_level": False,
+            "sort_decorated": False,
+            "python_version": None,
+        }
+
+    def test_sort_module_level_enabled(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that sort_module_level is read from pyproject.toml."""
+        pyproject_content = """
+[tool.undersort]
+sort_module_level = true
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        assert load_config()["sort_module_level"] is True
+
+    def test_invalid_sort_module_level(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that a non-boolean sort_module_level falls back to the default."""
+        pyproject_content = """
+[tool.undersort]
+sort_module_level = "yes"
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        assert load_config()["sort_module_level"] is False
+
+    def test_python_version_from_requires_python(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that the target version is inferred from the project's requires-python."""
+        pyproject_content = """
+[project]
+name = "test"
+requires-python = ">=3.10,<4.0"
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        assert load_config()["python_version"] == (3, 10)
+
+    def test_explicit_python_version_wins(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that an explicit python_version overrides requires-python."""
+        pyproject_content = """
+[project]
+name = "test"
+requires-python = ">=3.10"
+
+[tool.undersort]
+python_version = "3.14"
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        assert load_config()["python_version"] == (3, 14)
+
+    def test_invalid_python_version_ignored(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that an unparseable python_version is ignored."""
+        pyproject_content = """
+[tool.undersort]
+python_version = "nonsense"
+"""
+        pyproject_path = tmp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        monkeypatch.chdir(tmp_path)
+        assert load_config()["python_version"] is None