codevariability 0.2.0__py3-none-any.whl

codevariability-0.2.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: codevariability
+Version: 0.2.0
+Summary: Source-code similarity matrices, representative rankings, and independent group comparison.
+Author: Otávio Gomes
+Maintainer: Otávio Gomes
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/otaviouss/codevariability-py
+Project-URL: Documentation, https://github.com/otaviouss/codevariability-py/tree/main/docs
+Project-URL: Source, https://github.com/otaviouss/codevariability-py
+Project-URL: Issues, https://github.com/otaviouss/codevariability-py/issues
+Keywords: code similarity,source code analysis,ast,software metrics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.5.0
+Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: Pygments<3,>=2.20.0
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: hypothesis>=6.168.3; extra == "dev"
+Requires-Dist: mypy>=2.4; extra == "dev"
+Requires-Dist: ruff>=0.14; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# CodeVariability for Python
+
+CodeVariability compares UTF-8 source-code files and returns similarity
+matrices, descriptive statistics, representative rankings, and comparisons
+between independent groups. It helps you identify common structures and
+unusual variants in a collection without executing the submitted code.
+
+Version **0.2.0** is the first release of this independent repository. The API is alpha. The distribution name is `codevariability`;
+the import name and command are `codevariability`.
+
+## Installation
+
+Python 3.10 or later is required. Install from PyPI:
+
+```bash
+python -m pip install codevariability==0.2.0
+```
+
+For development, install a checkout with `python -m pip install .`.
+The historical 0.1.2 code is the implementation baseline; 0.2.0 is the first
+public PyPI release. Use a new virtual environment when migrating from a
+local historical installation.
+
+## Quick start
+
+This example creates its own inputs and works with an installed package:
+
+```python
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from codevariability import analyze
+
+with TemporaryDirectory() as directory:
+    folder = Path(directory)
+    (folder / "a.py").write_text("def total(a, b):\n    return a + b\n", encoding="utf-8")
+    (folder / "b.py").write_text("def sum_values(x, y):\n    return x + y\n", encoding="utf-8")
+    result = analyze(folder, metrics="all")
+    print(result.statistics)
+    print(result.ranking)
+    print(result.most_representative)
+```
+
+The runnable [example](https://github.com/otaviouss/codevariability-py/blob/main/examples/basic.py) also exports JSON, CSV, and Excel.
+For the bundled input files, the CLI is:
+
+```bash
+codevariability analyze examples/inputs --metrics all --output analysis-output
+codevariability analyze examples/inputs --metrics cosine jaccard --output analysis-output/report.xlsx
+```
+
+## Inputs and metrics
+
+Pass a directory or a list of file paths to `analyze()`. Directory scans are
+not recursive. File basenames must be unique. Files are decoded as UTF-8,
+including an optional BOM. Use `extensions="py"` or a list of extensions to
+filter a directory.
+
+| Metric | What it compares |
+| --- | --- |
+| `cosine` | Word frequencies in the full document. |
+| `jaccard` | Sets of words in the full document. |
+| `lcs` | The longest common subsequence of code tokens. |
+| `levenshtein` | Token sequences using unit edit costs. |
+| `ast_tree_edit_similarity` | Ordered, normalized Python syntax trees. |
+
+`metrics="all"` includes all applicable metrics. Python AST analysis requires
+Python inputs; explicit selection on incompatible inputs raises `AnalysisError`.
+Source files are read in full. For Markdown, token and AST metrics use the
+identified fenced code blocks; textual metrics include the full document.
+
+## Results and export
+
+`AnalysisResult` exposes `matrices`, `statistics`, `representativeness`,
+`ranking`, `rankings_by_metric`, `most_representative`, and `most_distinct`.
+Similarities range from 0 to 1. Statistics use each unique pair once. Rankings
+average within each available dimension and then give dimensions equal weight.
+
+Use `result.export(directory, formats=("json", "csv"))` for machine-readable
+results and tables, or `result.to_excel(path)` for a workbook. Outputs include
+metric identifiers, normalization and runtime versions, and input hashes.
+Spreadsheet exports escape formula-like labels; JSON retains the original
+labels. See [input/output details](https://github.com/otaviouss/codevariability-py/blob/main/docs/FORMATS.md).
+
+`compare_groups()` supports two groups or a mapping of two or more groups,
+file-label permutation tests, and Holm-adjusted p-values. Each group needs at
+least two files and groups must not share physical files. A complete example
+is in [examples/groups.py](https://github.com/otaviouss/codevariability-py/blob/main/examples/groups.py).
+
+## Optional JavaScript integration
+
+The Python library works without Node.js. To request structural JavaScript or
+TypeScript analysis through `compare_groups(..., include_ast=True)`, install
+the independent [codevariability-js](https://github.com/otaviouss/codevariability-js)
+package and make its command available on `PATH`. Alternatively, import a
+single-metric JSON with `load_matrix_json()` and attach it with `with_metric()`.
+The Python build and normal test suite require no JavaScript checkout.
+
+## Limits and errors
+
+Scores describe text, tokens, or syntax; they do not establish functional
+equivalence, correctness, authorship, or copied-code percentages. AST
+normalization removes concrete names and literal values. Different sources
+can therefore have structural similarity 1.
+
+Exact tree comparison can be expensive. The default `max_ted_cells=2_000_000`
+limits tables for each non-identical AST pair; exceeding it raises an error,
+without approximation. `None` removes the limit. It does not limit source
+file size, the full pairwise matrix, or total CPU time. Use trusted output
+directories and apply application-level resource limits for untrusted inputs.
+
+Expected input and serialization errors raise `AnalysisError`. JavaScript
+integration also supports `ast_timeout=120` seconds. See the
+[API](https://github.com/otaviouss/codevariability-py/blob/main/docs/API.md) and [metric definitions](https://github.com/otaviouss/codevariability-py/blob/main/docs/METRICS.md) for details.
+
+## Contributing and license
+
+See [CONTRIBUTING.md](https://github.com/otaviouss/codevariability-py/blob/main/CONTRIBUTING.md) for development and
+[PUBLICATION_CHECKLIST.md](https://github.com/otaviouss/codevariability-py/blob/main/PUBLICATION_CHECKLIST.md) for release preparation.
+The project uses the [MIT license](https://github.com/otaviouss/codevariability-py/blob/main/LICENSE), copyright 2026 Otávio Gomes.
+
+## Compatibility
+
+Arbitrary distinct nonempty group names are
+accepted; use `result.within_group_columns` to locate collision-safe within-group
+means. Keep files unchanged while an analysis runs; optional JavaScript results
+with different input hashes raise `AnalysisError`.
+
+Runtime minimums are scikit-learn 1.5.0 and Pygments 2.20.0; build minimum is
+setuptools 83.0.0 and development tests require pytest 9.0.3. These scopes are
+separate. See [API](docs/API.md) and [metric limits](docs/METRICS.md).
+
+Python AST normalization now uses v3 to identify corrected empty-program
+behavior. The TED formula ID remains v2; use compatible normalization IDs when
+comparing results across versions.

codevariability-0.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+codevariability/__init__.py,sha256=srjZaAHtnsEnfjVG6uXYDVMMhaoUvYhP4DCTk_O-X8c,544
+codevariability/analysis.py,sha256=R1RNb_t5X-PKgMHFKlZmag9_6GiJ65OTH1bPzNxqbcM,27622
+codevariability/ast_tree_edit.py,sha256=qIwP0VTxuvdScYV4CMdHa4F4Bdx8W1LsLK09dGj6T7s,12877
+codevariability/cli.py,sha256=zfNG1BlHOrRqh9P1BRThEyMvCHCQA5kSSMyvaapQoJA,2522
+codevariability/exceptions.py,sha256=8OBSVF2x0HAtm_bJBHYVvMCEh5fdyel0H03g8xM9VmA,85
+codevariability/group_comparison.py,sha256=jc6Glkp_rVy03pzMfiot1VNq03HBMecZ30d-vC-0Wkw,42228
+codevariability/interop.py,sha256=-HzPwR_5GxCXyH7gXopvF4WiIOmiyqj_VN8mnfm3LPw,3797
+codevariability/metrics.py,sha256=u9f1Aa-9b37eTsK16waZop6XFiMPbLwJlWw8Bq5zaxc,3140
+codevariability/normalization.py,sha256=eCO4ddYvDFt2njNrmgLx68NVQ7idG-a990768l9i7P0,7933
+codevariability/output.py,sha256=HbLTEJBGlPB-La0rm44UdqtBaxG_VRa4zvXjIcaH4cE,2418
+codevariability/spreadsheet.py,sha256=0GLcHkZGP6zX8RDlcD7nQsT42lgCIVcKDml73rRgVq8,2198
+codevariability/validation.py,sha256=-QmIbMqV_judKKhDmFXLFxrhasnUEM9qLxiqesVmPlk,4449
+codevariability-0.2.0.dist-info/licenses/LICENSE,sha256=D9r56CkUbcYQxajHJN_WbUo_mKmFeupRfGhvLtJm1oA,1070
+codevariability-0.2.0.dist-info/METADATA,sha256=HRUpVjIkBwrgbda9ZFgW4vDKBK0JS1XrwRypPA74N2c,7993
+codevariability-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+codevariability-0.2.0.dist-info/entry_points.txt,sha256=_x7ZYg8c9H38jQ-WGTuPH-Y8h8pt81RaXk8rd-MH_z0,61
+codevariability-0.2.0.dist-info/top_level.txt,sha256=e2BzckcZ3lCvCIcOE-xDidVw58QHJ7n5avhVM1nuPG4,16
+codevariability-0.2.0.dist-info/RECORD,,

codevariability-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codevariability-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codevariability = codevariability.cli:main

codevariability-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Otávio Gomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codevariability-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+codevariability