codesorter 0.2.5__tar.gz → 0.2.6__tar.gz

{codesorter-0.2.5 → codesorter-0.2.6}/CHANGES.rst

@@ -4,6 +4,23 @@
 
 codesorter follows `semantic versioning <https://semver.org/>`_.
 
+********************
+ 0.2.6 (2026/06/14)
+********************
+
+**Added**
+
+- Documentation page describing how barriers limit sorting to segments between
+  side-effecting statements, and how to relocate a statement that should not be a
+  barrier.
+
+**Changed**
+
+- Refresh the documentation: the installation instructions use uv-native commands, the
+  class-method ordering reference and example now match the implementation, and the
+  barrier relocation example is split into separate, color-tinted before and after
+  blocks.
+
 ********************
  0.2.5 (2026/06/14)
 ********************

{codesorter-0.2.5 → codesorter-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codesorter
-Version: 0.2.5
+Version: 0.2.6
 Summary: A Python codemod that sorts and organizes code in your files.
 Project-URL: Change Log, https://codesorter.readthedocs.io/en/latest/package_info/change_log.html
 Project-URL: Documentation, https://codesorter.readthedocs.io/
@@ -60,6 +60,15 @@ Description-Content-Type: text/x-rst
 
 CodeSorter is a LibCST codemod that automatically sorts and organizes Python code.
 
+.. warning::
+
+    Only apply CodeSorter to a code base you own or maintain. Reordering an entire file
+    is a sweeping, opinionated change that conflicts with in-flight work and erases the
+    history of carefully chosen ordering. Opening a pull request that runs CodeSorter
+    across **someone else's** project is strongly discouraged — it is noisy,
+    unsolicited, and burdensome to review. Adopt it as a pre-commit hook in your own
+    repositories instead, where every contributor benefits from the consistent ordering.
+
 **********
  Features
 **********
@@ -85,10 +94,10 @@ From PyPI:
 
 .. code-block:: bash
 
-    # using uv and add to the lint dependency group
+    # install the codesorter CLI as a standalone tool
+    uv tool install codesorter
+    # or add it to a project's lint dependency group
     uv add --group lint codesorter
-    # or using pip
-    pip install codesorter
 
 From Source:
 
@@ -96,7 +105,7 @@ From Source:
 
     git clone https://github.com/praw-dev/CodeSorter.git
     cd CodeSorter
-    uv pip install -e .
+    uv tool install .
 
 Development Installation:
 
@@ -137,7 +146,7 @@ commit:
     # .pre-commit-config.yaml
     repos:
       - repo: https://github.com/praw-dev/CodeSorter
-        rev: v0.0.3
+        rev: v0.2.5
         hooks:
           - id: codesorter
 
@@ -147,7 +156,7 @@ Or use the check-only variant, which fails the hook without modifying files:
 
     repos:
       - repo: https://github.com/praw-dev/CodeSorter
-        rev: v0.0.3
+        rev: v0.2.5
         hooks:
           - id: codesorter-check
 
@@ -195,10 +204,18 @@ Function Sorting
 Class Method Sorting
 ====================
 
-- Methods are sorted with special consideration for decorators: - ``@property`` methods
-  (getters, setters, deleters) - ``@staticmethod`` methods - ``@classmethod`` methods -
-  Regular instance methods
-- Methods within classes maintain their logical grouping
+- Methods are grouped by kind, in this order:
+
+  - ``@abstractmethod`` methods
+  - pytest fixtures (``autouse`` fixtures first)
+  - ``@staticmethod`` methods
+  - ``@classmethod`` methods
+  - cached properties and ``@property`` methods (getter, then setter, then deleter)
+  - ``@contextmanager`` methods
+  - regular instance methods
+
+- Within each group, methods are sorted alphabetically, with leading-underscore
+  (``_private`` and ``__dunder__``) names ahead of public ones
 
 Pytest Fixture Sorting
 ======================
@@ -231,14 +248,14 @@ Example Transformation
 .. code-block:: python
 
     class MyClass:
-        @property
-        def a_property(self):
-            pass
-
         @staticmethod
         def b_static():
             pass
 
+        @property
+        def a_property(self):
+            pass
+
         def z_method(self):
             pass
 

{codesorter-0.2.5 → codesorter-0.2.6}/README.rst

@@ -4,6 +4,15 @@
 
 CodeSorter is a LibCST codemod that automatically sorts and organizes Python code.
 
+.. warning::
+
+    Only apply CodeSorter to a code base you own or maintain. Reordering an entire file
+    is a sweeping, opinionated change that conflicts with in-flight work and erases the
+    history of carefully chosen ordering. Opening a pull request that runs CodeSorter
+    across **someone else's** project is strongly discouraged — it is noisy,
+    unsolicited, and burdensome to review. Adopt it as a pre-commit hook in your own
+    repositories instead, where every contributor benefits from the consistent ordering.
+
 **********
  Features
 **********
@@ -29,10 +38,10 @@ From PyPI:
 
 .. code-block:: bash
 
-    # using uv and add to the lint dependency group
+    # install the codesorter CLI as a standalone tool
+    uv tool install codesorter
+    # or add it to a project's lint dependency group
     uv add --group lint codesorter
-    # or using pip
-    pip install codesorter
 
 From Source:
 
@@ -40,7 +49,7 @@ From Source:
 
     git clone https://github.com/praw-dev/CodeSorter.git
     cd CodeSorter
-    uv pip install -e .
+    uv tool install .
 
 Development Installation:
 
@@ -81,7 +90,7 @@ commit:
     # .pre-commit-config.yaml
     repos:
       - repo: https://github.com/praw-dev/CodeSorter
-        rev: v0.0.3
+        rev: v0.2.5
         hooks:
           - id: codesorter
 
@@ -91,7 +100,7 @@ Or use the check-only variant, which fails the hook without modifying files:
 
     repos:
       - repo: https://github.com/praw-dev/CodeSorter
-        rev: v0.0.3
+        rev: v0.2.5
         hooks:
           - id: codesorter-check
 
@@ -139,10 +148,18 @@ Function Sorting
 Class Method Sorting
 ====================
 
-- Methods are sorted with special consideration for decorators: - ``@property`` methods
-  (getters, setters, deleters) - ``@staticmethod`` methods - ``@classmethod`` methods -
-  Regular instance methods
-- Methods within classes maintain their logical grouping
+- Methods are grouped by kind, in this order:
+
+  - ``@abstractmethod`` methods
+  - pytest fixtures (``autouse`` fixtures first)
+  - ``@staticmethod`` methods
+  - ``@classmethod`` methods
+  - cached properties and ``@property`` methods (getter, then setter, then deleter)
+  - ``@contextmanager`` methods
+  - regular instance methods
+
+- Within each group, methods are sorted alphabetically, with leading-underscore
+  (``_private`` and ``__dunder__``) names ahead of public ones
 
 Pytest Fixture Sorting
 ======================
@@ -175,14 +192,14 @@ Example Transformation
 .. code-block:: python
 
     class MyClass:
-        @property
-        def a_property(self):
-            pass
-
         @staticmethod
         def b_static():
             pass
 
+        @property
+        def a_property(self):
+            pass
+
         def z_method(self):
             pass
 

{codesorter-0.2.5 → codesorter-0.2.6}/codesorter/const.py

@@ -39,4 +39,4 @@ PLAIN_DECORATOR_PARTS = 1
 
 PROPERTY_DECORATOR_PARTS = 2
 
-__version__ = "0.2.5"
+__version__ = "0.2.6"

codesorter-0.2.6/docs/_static/custom.css

@@ -0,0 +1,26 @@
+/* Tint the before/after code blocks on the barriers page.
+   Translucent fills layer over the page background, so they read correctly in
+   both the light and dark Furo themes. */
+.codesorter-before,
+.codesorter-after {
+    border-left: 4px solid;
+    border-radius: 0.2rem;
+    margin-bottom: 1rem;
+    padding-left: 0.4rem;
+}
+
+.codesorter-before {
+    background-color: rgba(229, 83, 75, 0.08);
+    border-left-color: #e5534b;
+}
+
+.codesorter-after {
+    background-color: rgba(63, 185, 80, 0.08);
+    border-left-color: #3fb950;
+}
+
+/* Let the container tint show through instead of Furo's code background. */
+.codesorter-before div.highlight,
+.codesorter-after div.highlight {
+    background: transparent;
+}

{codesorter-0.2.5 → codesorter-0.2.6}/docs/code_overview/sort_code.rst

@@ -2,9 +2,10 @@
  Sort Code
 ###########
 
-The :class:`.SortCodeCommand` is the libcst codemod that performs the reordering. It is
-applied by the CLI, but can also be used directly as a libcst codemod (for example via
-``python -m libcst.tool codemod codesorter.sort_code.SortCodeCommand``).
+The :class:`.SortCodeCommand` is the libcst codemod that performs the reordering. The
+``codesorter`` CLI applies it to the files you pass it; you can also use it directly as
+a libcst codemod in your own tooling by constructing it with a ``CodemodContext`` and
+calling ``transform_module`` (see the programmatic example in the README).
 
 .. autoclass:: codesorter.sort_code.SortCodeCommand
 

{codesorter-0.2.5 → codesorter-0.2.6}/docs/conf.py

@@ -16,6 +16,8 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
 ]
+html_css_files = ["custom.css"]
+html_static_path = ["_static"]
 html_theme = "furo"
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),

{codesorter-0.2.5 → codesorter-0.2.6}/docs/index.rst

@@ -1,5 +1,11 @@
 .. include:: ../README.rst
 
+.. toctree::
+    :hidden:
+    :caption: Usage
+
+    usage/barriers
+
 .. toctree::
     :hidden:
     :caption: Code Overview

codesorter-0.2.6/docs/usage/barriers.rst

@@ -0,0 +1,87 @@
+######################
+ Sorting and Barriers
+######################
+
+CodeSorter reorders the classes, functions, and assignments within a module or class
+body, but only within a *segment* of consecutive definitions. Any statement that is not
+a sortable definition acts as a **barrier**, and no definition is ever moved across one.
+
+Barriers include bare expression statements (a function call on its own line such as
+``sys.path.insert(0, str(ROOT))``), ``if`` / ``for`` / ``while`` / ``with`` blocks,
+``import`` statements, and similar. A barrier splits the surrounding definitions into
+independent segments, each sorted on its own.
+
+********************
+ Why barriers exist
+********************
+
+A statement sitting between definitions may depend on one of them, or be depended upon,
+in ways that reordering would break. There are two cases, and only the first is visible
+to a static tool:
+
+1. The statement *references* a definition that would otherwise move after it:
+
+   .. code-block:: python
+
+       ROOT = Path(__file__).resolve().parent
+       sys.path.insert(0, str(ROOT))  # uses ROOT
+
+   If ``ROOT`` were sorted after the ``sys.path.insert`` call, the module would raise
+   ``NameError`` on import.
+
+2. A later definition depends on the statement's *side effect*, which no name reference
+   reveals:
+
+   .. code-block:: python
+
+       configure_settings()
+       DEFAULT_TIMEOUT = settings.get("timeout")  # reads what configure_settings() set up
+
+   ``DEFAULT_TIMEOUT`` does not mention ``configure_settings`` by name, yet it must run
+   after it. Moving the constant ahead of the call would silently read an unconfigured
+   value — a wrong result rather than a crash.
+
+Because side effects are opaque, CodeSorter cannot prove that crossing an arbitrary
+statement is safe, so it treats every non-definition statement as a barrier.
+
+**********************
+ Relocating a barrier
+**********************
+
+The cost of this rule is small: a barrier that genuinely sits in the middle of a block
+of definitions keeps the definitions on either side from sorting together. If a
+statement legitimately should *not* separate your definitions — you know it has no
+ordering relationship with them — move it yourself so it no longer sits between them.
+For example, hoist a one-off call to the top of the module (just below the imports) or
+to the bottom.
+
+**Before** — the call sits between the classes, splitting them into two segments, so
+``Alpha`` and ``Beta`` cannot sort together:
+
+.. code-block:: python
+    :class: codesorter-before
+
+    class Beta: ...
+
+
+    warnings.filterwarnings("ignore")
+
+
+    class Alpha: ...
+
+**After** — relocate the call above both classes; ``Alpha`` and ``Beta`` now form a
+single segment and sort into order:
+
+.. code-block:: python
+    :class: codesorter-after
+
+    warnings.filterwarnings("ignore")
+
+
+    class Alpha: ...
+
+
+    class Beta: ...
+
+CodeSorter will not perform this move for you, precisely because it cannot prove the
+move preserves behavior — only you know whether the statement is safe to relocate.