feat(python): add cleed wrapper package

[Liam-Deacon]

Problem

Issue #37 asks for a cleed Python package that enables CLI usage and a path toward bundled binaries and wheels.

Solution

• Add pyproject.toml with minimal package metadata.
• Create a lightweight cleed Python package that provides a CLI wrapper for existing CLEED executables on PATH.
• Document the current wrapper behavior and future wheel packaging plan in Sphinx docs.

Testing

• Not run (packaging and docs only).

Follow-ups

• Decide on a build backend (scikit-build-core vs setuptools) for native binaries.
• Determine how to bundle executables and data into wheels.
• Add CI wheel builds (cibuildwheel) and smoke tests.

Summary by Sourcery

Introduce a minimal Python cleed package providing a CLI entry point that wraps existing CLEED executables discovered on PATH.

New Features:

• Add a cleed Python package exposing a cleed console script to run CLEED tools such as cleed_nsym, cleed_sym, csearch, and crfac from a Python installation.

Build:

• Add a pyproject.toml configured with setuptools to build and distribute the cleed package, including an optional phaseshifts extra dependency.

Documentation:

• Add initial Sphinx documentation page describing the Python package and its CLI wrapper behavior.

[sourcery-ai]

Reviewer's Guide

Introduces a minimal cleed Python package wired up via pyproject.toml, exposing a cleed console script that dispatches to existing CLEED executables found on PATH, and adds initial Sphinx docs for the Python package behavior and future binary/wheel packaging plans.

Sequence diagram for cleed CLI wrapper invocation flow

sequenceDiagram
    actor User
    participant Shell
    participant CleedCli as cleed.cli_main
    participant ArgParser as argparse_ArgumentParser
    participant Shutil as shutil
    participant Subproc as subprocess

    User->>Shell: run command
    Shell->>CleedCli: cleed tool args
    CleedCli->>ArgParser: build_parser()
    ArgParser-->>CleedCli: parser
    CleedCli->>ArgParser: parse_args(argv)
    ArgParser-->>CleedCli: args

    alt version flag
        CleedCli-->>User: print __version__
        CleedCli-->>Shell: exit 0
    else list_tools flag
        CleedCli-->>User: print TOOLS listing
        CleedCli-->>Shell: exit 0
    else missing tool
        CleedCli-->>User: print_help
        CleedCli-->>Shell: exit 2
    else unknown tool
        CleedCli-->>User: stderr Unknown tool
        CleedCli-->>User: stderr Use --list-tools
        CleedCli-->>Shell: exit 2
    else valid tool
        CleedCli->>Shutil: which(tool)
        Shutil-->>CleedCli: binary_path or None
        alt binary not found
            CleedCli-->>User: stderr Executable not found on PATH
            CleedCli-->>Shell: exit 127
        else binary found
            CleedCli->>CleedCli: normalize tool_args (strip leading --)
            CleedCli->>Subproc: run([binary] + tool_args, check False)
            Subproc-->>CleedCli: result.returncode
            CleedCli-->>Shell: exit result.returncode
        end
    end

Loading

Class diagram for cleed Python package and CLI module

classDiagram
    class cleed {
        +str __version__ = 0.0.0
    }

    class cli {
        +dict TOOLS
        +str resolve_tool(name str)
        +int run_tool(binary str, args List_str)
        +argparse_ArgumentParser build_parser()
        +int main(argv List_str_optional)
    }

    cleed <.. cli : imports __version__

    class pyproject_toml {
        +str name = cleed
        +str version = 0.0.0
        +str requires_python >= 3.8
        +list optional_dependency_phaseshifts
        +str console_script_cleed = cleed.cli:main
        +str build_backend = setuptools.build_meta
    }

    pyproject_toml --> cleed : defines package
    pyproject_toml --> cli : exposes console script

Loading

File-Level Changes

Change	Details	Files
Add a Python CLI wrapper that dispatches to existing CLEED executables on PATH.	Define a TOOLS registry of supported CLEED executables and their descriptions. Implement argument parsing with options for listing tools, printing the Python package version, or invoking a specific tool with passthrough arguments. Resolve requested tool names to actual executables on PATH and handle missing/unknown tools with appropriate exit codes and stderr messaging. Delegate tool execution to a helper that runs the subprocess and propagates the executable’s return code, while mapping FileNotFoundError to a 127 exit status. Provide a main entry point compatible with setuptools console_scripts.	python/cleed/cli.py
Create a minimal Python package with versioning and entry-point wiring.	Expose a __version__ constant and limit the public API via __all__. Configure setuptools-based packaging, including build-system requirements, project metadata, optional dependencies, and package discovery rooted under the python directory. Register the cleed console script entry point to call the new CLI wrapper.	python/cleed/__init__.py pyproject.toml
Add initial documentation for the Python package and CLI behavior.	Extend the Sphinx docs index to reference the new Python package documentation (content not fully shown in diff). Create a placeholder RST page for the Python package to describe the wrapper behavior and future wheels/binary distribution plan.	doc/index.rst doc/python_package.rst

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/issue-37-python-package

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Liam-Deacon]

Clarifications for #37:

• Do you want to commit to a build backend now (scikit-build-core vs setuptools + custom build), or keep this as a wrapper until the native build story is decided?
• Should the Python CLI wrap only PATH-based executables, or should we start bundling binaries into the package immediately?
• Preferred versioning scheme for the package (e.g., 2014.7.4 vs 0.x)?

[codacy-production]

Codacy's Analysis Summary

3 new issues (≤ 0 issue)
2 new security issues
13 complexity
0 duplications

Review Pull Request in Codacy →

✨ AI Reviewer available: add the codacy-review label to get contextual insights without leaving GitHub.