codesorter 0.2.4__tar.gz → 0.2.6__tar.gz

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

@@ -4,6 +4,35 @@
 
 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)
+********************
+
+**Changed**
+
+- Depend on ``ruff`` directly so the formatter is always installed alongside
+  ``codesorter``. The CLI shells out to ``ruff format``, which previously only worked
+  when ``ruff`` happened to be on ``PATH`` from another source; it is now a runtime
+  dependency, so ``codesorter`` is self-contained in a clean environment and in the
+  isolated pre-commit hook.
+
 ********************
  0.2.4 (2026/06/14)
 ********************

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codesorter
-Version: 0.2.4
+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/
@@ -51,6 +51,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: libcst<2.0.0,>=1.8.6
 Requires-Dist: pathspec>=1.1.1
+Requires-Dist: ruff>=0.1.2
 Description-Content-Type: text/x-rst
 
 ############
@@ -59,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
 **********
@@ -84,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:
 
@@ -95,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:
 
@@ -136,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
 
@@ -146,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
 
@@ -194,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
 ======================
@@ -230,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.4 → 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.4 → codesorter-0.2.6}/codesorter/const.py

@@ -39,4 +39,4 @@ PLAIN_DECORATOR_PARTS = 1
 
 PROPERTY_DECORATOR_PARTS = 2
 
-__version__ = "0.2.4"
+__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.4 → 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.4 → 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.4 → codesorter-0.2.6}/docs/contributing/pre_commit.rst

@@ -21,9 +21,9 @@ hook so the repository is always sorted by the code on the current branch:
 ***************************
 
 Because the hook uses ``language: system``, it runs the ``codesorter`` executable from
-your environment instead of an isolated one pre-commit manages. CodeSorter then invokes
-``ruff format`` as its formatter (configured in ``.libcst.codemod.yaml``). Both
-``codesorter`` and ``ruff`` must therefore be on ``PATH`` when the hook runs.
+your environment instead of an isolated one pre-commit manages. CodeSorter always
+invokes ``ruff format`` as its formatter, so both ``codesorter`` and ``ruff`` must be on
+``PATH`` when the hook runs.
 
 Install the development environment and the git hook:
 

{codesorter-0.2.4 → 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.

{codesorter-0.2.4 → codesorter-0.2.6}/pyproject.toml

@@ -16,8 +16,7 @@ docs = [
   "sphinx-autodoc-typehints>=2.5.0"
 ]
 lint = [
-  "pre-commit>=4.6.0",
-  "ruff>=0.15.17"
+  "pre-commit>=4.6.0"
 ]
 test = [
   "coverage>=7.14.1",
@@ -50,7 +49,8 @@ classifiers = [
 ]
 dependencies = [
   "libcst>=1.8.6,<2.0.0",
-  "pathspec>=1.1.1"
+  "pathspec>=1.1.1",
+  "ruff>=0.1.2"
 ]
 description = "A Python codemod that sorts and organizes code in your files."
 dynamic = ["version"]

{codesorter-0.2.4 → codesorter-0.2.6}/uv.lock

@@ -190,6 +190,7 @@ source = { editable = "." }
 dependencies = [
     { name = "libcst" },
     { name = "pathspec" },
+    { name = "ruff" },
 ]
 
 [package.dev-dependencies]
@@ -199,7 +200,6 @@ dev = [
     { name = "pre-commit" },
     { name = "pyright" },
     { name = "pytest" },
-    { name = "ruff" },
     { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "sphinx", version = "9.0.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" },
     { name = "sphinx", version = "9.1.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
@@ -219,7 +219,6 @@ docs = [
 ]
 lint = [
     { name = "pre-commit" },
-    { name = "ruff" },
 ]
 test = [
     { name = "coverage" },
@@ -235,6 +234,7 @@ type = [
 requires-dist = [
     { name = "libcst", specifier = ">=1.8.6,<2.0.0" },
     { name = "pathspec", specifier = ">=1.1.1" },
+    { name = "ruff", specifier = ">=0.1.2" },
 ]
 
 [package.metadata.requires-dev]
@@ -244,7 +244,6 @@ dev = [
     { name = "pre-commit", specifier = ">=4.6.0" },
     { name = "pyright", specifier = ">=1.1.410" },
     { name = "pytest", specifier = ">=9.0.3" },
-    { name = "ruff", specifier = ">=0.15.17" },
     { name = "sphinx", specifier = ">=8.1.3" },
     { name = "sphinx-autodoc-typehints", specifier = ">=2.5.0" },
     { name = "tox-uv", specifier = ">=1.35.2" },
@@ -254,10 +253,7 @@ docs = [
     { name = "sphinx", specifier = ">=8.1.3" },
     { name = "sphinx-autodoc-typehints", specifier = ">=2.5.0" },
 ]
-lint = [
-    { name = "pre-commit", specifier = ">=4.6.0" },
-    { name = "ruff", specifier = ">=0.15.17" },
-]
+lint = [{ name = "pre-commit", specifier = ">=4.6.0" }]
 test = [
     { name = "coverage", specifier = ">=7.14.1" },
     { name = "pytest", specifier = ">=9.0.3" },

codesorter-0.2.4/.libcst.codemod.yaml

@@ -1,36 +0,0 @@
-# String that LibCST should look for in code which indicates that the
-# module is generated code.
-generated_code_marker: '@generated'
-# Command line and arguments for invoking a code formatter. Anything
-# specified here must be capable of taking code via stdin and returning
-# formatted code via stdout.
-formatter: ['ruff', 'format', '-']
-# List of regex patterns which LibCST will evaluate against filenames to
-# determine if the module should be touched.
-blacklist_patterns:
-- '.*/\.bzr/.*'
-- '.*/\.direnv/.*'
-- '.*/\.eggs/.*'
-- '.*/\.git/.*'
-- '.*/\.hg/.*'
-- '.*/\.mypy_cache/.*'
-- '.*/\.nox/.*'
-- '.*/\.pytest_cache/.*'
-- '.*/\.ruff_cache/.*'
-- '.*/\.svn/.*'
-- '.*/\.tox/.*'
-- '.*/\.venv/.*'
-- '.*/__pycache__/.*'
-- '.*/__pypackages__/.*'
-- '.*/build/.*'
-- '.*/dist/.*'
-- '.*/env/.*'
-- '.*/node_modules/.*'
-- '.*/venv/.*'
-# List of modules that contain codemods inside of them.
-modules:
-- 'codesorter'
-# Absolute or relative path of the repository root, used for providing
-# full-repo metadata. Relative paths should be specified with this file
-# location as the base.
-repo_root: '.'