Metadata-Version: 2.4
Name: codesorter
Version: 0.2.0
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/
Project-URL: Issue Tracker, https://github.com/praw-dev/CodeSorter/issues
Project-URL: Source Code, https://github.com/praw-dev/CodeSorter
Author-email: Joel Payne <lilspazjoekp@gmail.com>
Maintainer-email: Joel Payne <lilspazjoekp@gmail.com>, Bryce Boe <bbzbryce@gmail.com>
License: Copyright (c) 2022, Joel Payne
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE.txt
Keywords: codemod,codesorter,libcst,sort
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: libcst<2.0.0,>=1.8.6
Requires-Dist: pathspec>=1.1.1
Description-Content-Type: text/x-rst

############
 CodeSorter
############

CodeSorter is a LibCST codemod that automatically sorts and organizes Python code.

**********
 Features
**********

- **Smart Sorting**: Automatically sorts functions, classes, and methods alphabetically
- **Decorator Awareness**: Properly handles ``@property``, ``@staticmethod``,
  ``@classmethod``, and ``@pytest.fixture`` decorators
- **Hierarchical Organization**: Maintains logical grouping within classes and modules
- **Constant Grouping**: Orders each scope as constants, then classes, then functions,
  sorting constants by dependency while preserving enum and dataclass field order
- **Keyword Sorting**: Alphabetizes keyword arguments in calls, keyword-only parameters,
  and dict string keys, while preserving ``*``/``**`` unpacking semantics
- **Pytest Integration**: Special handling for pytest fixtures with proper scope
  ordering
- **CLI Interface**: Simple command-line interface for easy integration
- **Pre-commit Hook**: Ready-to-use pre-commit hook for automated code organization

**************
 Installation
**************

From PyPI:

.. code-block:: bash

    # using uv and add to the lint dependency group
    uv add --group lint codesorter
    # or using pip
    pip install codesorter

From Source:

.. code-block:: bash

    git clone https://github.com/praw-dev/CodeSorter.git
    cd CodeSorter
    uv pip install -e .

Development Installation:

.. code-block:: bash

    git clone https://github.com/praw-dev/CodeSorter.git
    cd CodeSorter
    uv sync

*******
 Usage
*******

Command Line Interface
======================

The simplest way to use CodeSorter is through the command-line interface:

.. code-block:: bash

    # Sort a single file
    codesorter my_file.py

    # Sort all Python files in a directory
    codesorter my_project/

    # Sort with additional options
    codesorter --help

Pre-commit Hook
===============

Add CodeSorter to your pre-commit configuration to automatically sort code on every
commit:

.. code-block:: yaml

    # .pre-commit-config.yaml
    repos:
      - repo: https://github.com/praw-dev/CodeSorter
        rev: v0.0.3
        hooks:
          - id: codesorter

Or use the check-only variant, which fails the hook without modifying files:

.. code-block:: yaml

    repos:
      - repo: https://github.com/praw-dev/CodeSorter
        rev: v0.0.3
        hooks:
          - id: codesorter-check

Programmatic Usage
==================

You can also use CodeSorter programmatically:

.. code-block:: python

    import libcst as cst
    from codesorter.sort_code import SortCodeCommand
    from libcst.codemod import CodemodContext

    # Parse your code
    code = """
    def z_function():
        pass

    def a_function():
        pass
    """

    # Create context and command
    context = CodemodContext()
    command = SortCodeCommand(context)

    # Transform the code
    result = command.transform_module(cst.parse_module(code))
    print(result.code)

**************
 How It Works
**************

CodeSorter uses LibCST (Concrete Syntax Tree) to parse and transform Python code. It
applies sophisticated sorting rules:

Function Sorting
================

- Functions are sorted alphabetically by name
- Global functions are sorted separately from class methods

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

Pytest Fixture Sorting
======================

- Fixtures are sorted by scope (session, package, module, class, function)
- Within each scope, fixtures are sorted alphabetically
- ``autouse`` fixtures are handled specially

Example Transformation
======================

**Before:**

.. code-block:: python

    class MyClass:
        def z_method(self):
            pass

        @property
        def a_property(self):
            pass

        @staticmethod
        def b_static():
            pass

**After:**

.. code-block:: python

    class MyClass:
        @property
        def a_property(self):
            pass

        @staticmethod
        def b_static():
            pass

        def z_method(self):
            pass

*************
 Development
*************

Setting Up Development Environment
==================================

.. code-block:: bash

    # Clone the repository
    git clone https://github.com/praw-dev/CodeSorter.git
    cd CodeSorter

    # Install with development dependencies
    uv sync

    # Install pre-commit hooks
    uv run pre-commit install

Running Tests
=============

.. code-block:: bash

    # Run all tests
    uv run pytest

    # Run a specific test file
    uv run pytest tests/test_sort_code.py

    # Run the full tox matrix (tests, type, pre-commit)
    uv run tox

Code Quality
============

The project uses several tools to maintain code quality:

- **Ruff**: Fast linting and formatting
- **Pyright**: Type checking
- **Pre-commit**: Automated quality checks

Run all quality checks:

.. code-block:: bash

    uv run pre-commit run --all-files

**************
 Contributing
**************

1. Fork the repository
2. Create a feature branch: ``git checkout -b feature-name``
3. Make your changes and add tests
4. Run the test suite: ``uv run pytest``
5. Run pre-commit hooks: ``pre-commit run --all-files``
6. Commit your changes: ``git commit -m "Add feature"``
7. Push to your fork: ``git push origin feature-name``
8. Create a Pull Request

**********
 Examples
**********

See the ``examples/`` directory for before and after examples of CodeSorter in action:

- ``examples/before_example.py``: Unsorted code
- ``examples/after_example.py``: Same code after sorting

*********
 License
*********

This project is licensed under the MIT License - see the `LICENSE.txt
<https://github.com/praw-dev/CodeSorter/blob/main/LICENSE.txt>`_ file for details.

***********
 Changelog
***********

See the `change log
<https://codesorter.readthedocs.io/en/latest/package_info/change_log.html>`_ for the
full list of changes.
