undersort 0.1.5__tar.gz → 0.1.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: undersort
-Version: 0.1.5
+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
@@ -72,6 +74,17 @@ 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
@@ -111,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):
@@ -195,6 +305,18 @@ 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. You can add custom exclusions via CLI flags or the config file.

{undersort-0.1.5 → 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
@@ -45,6 +47,17 @@ 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
@@ -84,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):
@@ -168,6 +278,18 @@ 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. You can add custom exclusions via CLI flags or the config file.

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "undersort"
-version = "0.1.5"
+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"

{undersort-0.1.5 → undersort-0.1.6}/tests/test_config.py

@@ -14,7 +14,14 @@ class TestConfigLoading:
         """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}
+        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."""
@@ -27,7 +34,14 @@ order = ["private", "protected", "public"]
 
         monkeypatch.chdir(tmp_path)
         config = load_config()
-        assert config == {"order": ["private", "protected", "public"], "method_type_order": None, "exclude": None}
+        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."""
@@ -40,7 +54,14 @@ order = ["public", "invalid", "private"]
 
         monkeypatch.chdir(tmp_path)
         config = load_config()
-        assert config == {"order": ["public", "protected", "private"], "method_type_order": None, "exclude": None}
+        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."""
@@ -53,7 +74,14 @@ some_other_key = "value"
 
         monkeypatch.chdir(tmp_path)
         config = load_config()
-        assert config == {"order": ["public", "protected", "private"], "method_type_order": None, "exclude": None}
+        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."""
@@ -66,7 +94,14 @@ name = "test"
 
         monkeypatch.chdir(tmp_path)
         config = load_config()
-        assert config == {"order": ["public", "protected", "private"], "method_type_order": None, "exclude": None}
+        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."""
@@ -84,7 +119,14 @@ order = ["private", "public", "protected"]
         monkeypatch.chdir(subdir)
 
         config = load_config()
-        assert config == {"order": ["private", "public", "protected"], "method_type_order": None, "exclude": None}
+        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."""
@@ -97,7 +139,14 @@ order = ["public"  # Invalid TOML
 
         monkeypatch.chdir(tmp_path)
         config = load_config()
-        assert config == {"order": ["public", "protected", "private"], "method_type_order": None, "exclude": None}
+        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."""
@@ -130,6 +179,9 @@ exclude = ["tests/*", "migrations/*.py"]
             "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:
@@ -148,4 +200,72 @@ exclude = "invalid"
             "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