feat: add datacompy compare CLI with multi-backend support

.github/workflows/edgetest.yml

@@ -14,19 +14,19 @@ jobs:
     runs-on: ubuntu-latest
     name: running edgetest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           ref: ${{ github.ref_name }}
 
       - name: Set up Python 3.12
-        uses: conda-incubator/setup-miniconda@v3
+        uses: conda-incubator/setup-miniconda@8ee1f361103df19b6f8c8655fd3967a8ecb162d5  # v4.0.1
         with:
           auto-update-conda: true
           python-version: '3.12'
           channels: conda-forge
 
       - name: Setup Java JDK
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287  # v5.3.0
         with:
           java-version: '17'
           distribution: 'adopt'
@@ -44,7 +44,7 @@ jobs:
           edgetest -c pyproject.toml --export
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1  # v8.1.1
         with:
           branch: edgetest-patch
           base: ${{ github.ref_name }}

.github/workflows/publish-docs.yml

@@ -12,12 +12,12 @@ jobs:
     permissions:
       contents: write
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
       with:
         # fetch all tags so `versioneer` can properly determine current version
         fetch-depth: 0
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
       with:
         python-version: '3.12'
     - name: Install dependencies
@@ -26,7 +26,7 @@ jobs:
       run: make sphinx
       shell: bash
     - name: Publish
-      uses: JamesIves/github-pages-deploy-action@4.0.0
+      uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f  # v4.8.0
       with:
         branch: gh-pages
         folder: docs/build/html

.github/workflows/publish-package.yml

@@ -13,12 +13,12 @@ jobs:
     permissions:
       id-token: write
     steps:
-    - uses: actions/checkout@ee0669bd1cc54295c223e0bb666b733df41de1c5 # pin@v2.7.0
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
       with:
         # fetch all tags so `versioneer` can properly determine current version
         fetch-depth: 0
     - name: Set up Python
-      uses: actions/setup-python@e9aba2c848f5ebd159c070c61ea2c4e2b122355e # pin@v2.3.4
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
       with:
         python-version: '3.12'
     - name: Install dependencies

.github/workflows/test-package.yml

@@ -17,9 +17,9 @@ jobs:
   lint-and-format:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
         with:
           python-version: "3.12"
       - name: Install dependencies
@@ -47,13 +47,13 @@ jobs:
       PANDAS_VERSION: ${{ matrix.pandas-version }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
         with:
           python-version: ${{ matrix.python-version }}
       - name: Setup Java JDK
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287  # v5.3.0
         with:
           java-version: "17"
           distribution: "adopt"
@@ -92,13 +92,13 @@ jobs:
       PANDAS_VERSION: ${{ matrix.pandas-version }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
         with:
           python-version: ${{ matrix.python-version }}
       - name: Setup Java JDK
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287  # v5.3.0
         with:
           java-version: "17"
           distribution: "adopt"
@@ -129,9 +129,9 @@ jobs:
       PYTHON_VERSION: ${{ matrix.python-version }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install datacompy

CLAUDE.md

@@ -80,6 +80,16 @@ Tolerances (`abs_tol`, `rel_tol`) can be a single float (applied globally) or a
 - **Imports**: Only absolute imports (relative imports banned via ruff TID252)
 - **Pre-commit hooks**: ruff (lint + format), trailing whitespace, debug statements, end-of-file fixer, pyproject-fmt
 
+## Testing Conventions
+
+- Write plain pytest functions, not class-based test suites. Use `def test_*()` at module level.
+- Do not group tests into `class Test*` unless the upstream codebase already does so in the same file.
+
+## Documentation Conventions
+
+- Do not use em dashes ("--" or "---") in documentation or docstrings; rewrite the sentence instead.
+- Do not use emojis in documentation, docstrings, or commit messages.
+
 ## Branching
 
 - `develop` is the active development branch for v1

datacompy/cli/__init__.py

@@ -0,0 +1,45 @@
+#
+# Copyright 2026 Capital One Services, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""DataComPy command-line interface.
+
+Entry point: ``datacompy`` (installed via ``[project.scripts]``) or
+``python -m datacompy``.
+
+Examples
+--------
+Compare two CSV files using the Polars backend (default):
+
+.. code-block:: bash
+
+    datacompy compare --left a.csv --right b.csv --on id
+
+Emit a JSON report to stdout:
+
+.. code-block:: bash
+
+    datacompy compare --left a.csv --right b.csv --on id --json
+
+Use Pandas and compare on the DataFrame index:
+
+.. code-block:: bash
+
+    datacompy compare --left a.csv --right b.csv --on-index --backend pandas
+"""
+
+from datacompy.cli.main import main
+from datacompy.cli.parser import build_parser
+
+__all__ = ["build_parser", "main"]

datacompy/cli/__main__.py

@@ -0,0 +1,20 @@
+#
+# Copyright 2026 Capital One Services, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Allows ``python -m datacompy`` to invoke the CLI."""
+
+from datacompy.cli import main
+
+raise SystemExit(main())