chartrank 0.1.0__tar.gz

chartrank-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# --- Python bytecode and caches ---
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# --- Build and packaging artifacts ---
+build/
+dist/
+*.egg-info/
+
+# --- Test coverage reports ---
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# --- Virtual environments ---
+.venv/
+venv/
+
+# --- Documentation build output (MkDocs) ---
+site/
+
+# --- Notebooks and editors ---
+.ipynb_checkpoints/
+.vscode/
+.idea/
+
+# --- OS files ---
+.DS_Store
+Thumbs.db
+
+# --- Local working notes (not part of the project) ---
+.claude/
+PROJECT_GUIDE.md
+PREMIER_MESSAGE.md
+LISEZ-MOI_KIT.md
+docs/journal/

chartrank-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-15
+
+Early preview to reserve the name on PyPI. Not ready for use.
+
+### Added
+
+- `profile(df)`: minimal column profile (dtype, share of missing values,
+  number of distinct values).
+- Package structure (`src/` layout, hatchling build, empty modules).
+- Community files: README (EN/FR), license, contributing guide, code of conduct,
+  issue templates.
+- Continuous integration (GitHub Actions): ruff, mypy, and pytest with coverage
+  ≥ 85 % on Python 3.11 to 3.14 (Linux) and 3.11 (Windows, macOS), with
+  network access disabled during tests.
+- Documentation skeleton (MkDocs Material, English and French) published to
+  GitHub Pages; new `[docs]` extra.
+- Release workflow: a `v*` tag publishes to PyPI with Trusted Publishing;
+  a manual run publishes to TestPyPI.
+
+[Unreleased]: https://github.com/Adeshinan/chartrank/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Adeshinan/chartrank/releases/tag/v0.1.0

chartrank-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faïd Adéshinan ALAGBE
+
+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.

chartrank-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: chartrank
+Version: 0.1.0
+Summary: Early preview, not ready for use. Suggests and explains the right chart for your data and intent.
+Project-URL: Homepage, https://github.com/Adeshinan/chartrank
+Project-URL: Issues, https://github.com/Adeshinan/chartrank/issues
+Project-URL: Changelog, https://github.com/Adeshinan/chartrank/blob/main/CHANGELOG.md
+Author: Faïd Adéshinan ALAGBE
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chart-recommendation,data-visualization,eda,pandas,plotly
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+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 :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: plotly>=5.24
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocs-static-i18n>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-socket>=0.7; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs-static-i18n>=1.2; extra == 'docs'
+Provides-Extra: static
+Requires-Dist: kaleido>=1.0; extra == 'static'
+Description-Content-Type: text/markdown
+
+# ChartRank
+
+[![CI](https://github.com/Adeshinan/chartrank/actions/workflows/ci.yml/badge.svg)](https://github.com/Adeshinan/chartrank/actions/workflows/ci.yml)
+[![Docs](https://github.com/Adeshinan/chartrank/actions/workflows/docs.yml/badge.svg)](https://adeshinan.github.io/chartrank/)
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Suggests and explains the right chart for your data and intent.**
+
+> 🚧 Work in progress — v1.0 planned for December 2026.
+
+Give ChartRank one or two columns and an intent (`compare`, `distribution`,
+`relationship`, `composition`, `trend`). It proposes 3 to 5 charts drawn on your
+own data, marks the recommended one with ★, explains each with numbers computed
+from your data ("good for / avoid if"), and gives you the image or a standalone
+Python script to reproduce it. Deterministic, local, no AI.
+
+```python
+import chartrank as cr
+
+g = cr.suggest(df, x="Pclass", y="Fare", intent="compare")
+g.show()
+print(g.best.why)
+print(g.best.code)
+```
+
+*This API is the v1.0 target and is not available yet.*
+
+[Documentation](https://adeshinan.github.io/chartrank/) ·
+[Version française](README.fr.md) · License: [MIT](LICENSE)

chartrank-0.1.0/README.fr.md

@@ -0,0 +1,30 @@
+# ChartRank
+
+[![CI](https://github.com/Adeshinan/chartrank/actions/workflows/ci.yml/badge.svg)](https://github.com/Adeshinan/chartrank/actions/workflows/ci.yml)
+[![Docs](https://github.com/Adeshinan/chartrank/actions/workflows/docs.yml/badge.svg)](https://adeshinan.github.io/chartrank/fr/)
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)
+[![Licence : MIT](https://img.shields.io/badge/licence-MIT-green)](LICENSE)
+
+**Propose et explique le bon graphique selon vos données et votre intention.**
+
+> 🚧 En cours de développement — v1.0 prévue en décembre 2026.
+
+Donnez à ChartRank une ou deux colonnes et une intention (`compare`,
+`distribution`, `relationship`, `composition`, `trend`). Il propose 3 à 5
+graphiques dessinés sur vos données, marque la recommandation ★, explique chacun
+avec des chiffres calculés sur vos données (« bon pour / à éviter si ») et fournit
+l'image ou un script Python autonome pour le refaire. Déterministe, local, sans IA.
+
+```python
+import chartrank as cr
+
+g = cr.suggest(df, x="Pclass", y="Fare", intent="compare")
+g.show()
+print(g.best.why)
+print(g.best.code)
+```
+
+*Cette API est l'objectif de la v1.0 et n'est pas encore disponible.*
+
+[Documentation](https://adeshinan.github.io/chartrank/fr/) ·
+[English version](README.md) · Licence : [MIT](LICENSE)

chartrank-0.1.0/README.md

@@ -0,0 +1,30 @@
+# ChartRank
+
+[![CI](https://github.com/Adeshinan/chartrank/actions/workflows/ci.yml/badge.svg)](https://github.com/Adeshinan/chartrank/actions/workflows/ci.yml)
+[![Docs](https://github.com/Adeshinan/chartrank/actions/workflows/docs.yml/badge.svg)](https://adeshinan.github.io/chartrank/)
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Suggests and explains the right chart for your data and intent.**
+
+> 🚧 Work in progress — v1.0 planned for December 2026.
+
+Give ChartRank one or two columns and an intent (`compare`, `distribution`,
+`relationship`, `composition`, `trend`). It proposes 3 to 5 charts drawn on your
+own data, marks the recommended one with ★, explains each with numbers computed
+from your data ("good for / avoid if"), and gives you the image or a standalone
+Python script to reproduce it. Deterministic, local, no AI.
+
+```python
+import chartrank as cr
+
+g = cr.suggest(df, x="Pclass", y="Fare", intent="compare")
+g.show()
+print(g.best.why)
+print(g.best.code)
+```
+
+*This API is the v1.0 target and is not available yet.*
+
+[Documentation](https://adeshinan.github.io/chartrank/) ·
+[Version française](README.fr.md) · License: [MIT](LICENSE)

chartrank-0.1.0/pyproject.toml

@@ -0,0 +1,101 @@
+# ---------------------------------------------------------------------------
+# Build system: which tool turns the source tree into an installable package.
+# ---------------------------------------------------------------------------
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+# ---------------------------------------------------------------------------
+# Package metadata (PEP 621): what PyPI and pip read.
+# ---------------------------------------------------------------------------
+[project]
+name = "chartrank"
+dynamic = ["version"]  # read from src/chartrank/__init__.py (see [tool.hatch.version])
+description = "Early preview, not ready for use. Suggests and explains the right chart for your data and intent."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Faïd Adéshinan ALAGBE" }]
+requires-python = ">=3.11"
+dependencies = [
+    "pandas>=2.2",
+    "numpy>=1.26",
+    "plotly>=5.24",
+    "pyyaml>=6.0",
+]
+keywords = ["data-visualization", "plotly", "pandas", "eda", "chart-recommendation"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+static = ["kaleido>=1.0"]  # PNG / SVG export
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-socket>=0.7",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pandas-stubs>=2.2",
+    "types-PyYAML>=6.0",
+    "build>=1.2",
+    "twine>=6.0",
+    "chartrank[docs]",  # dev also installs the docs tools
+]
+docs = [
+    "mkdocs-material>=9.5",
+    "mkdocs-static-i18n>=1.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/Adeshinan/chartrank"
+Issues = "https://github.com/Adeshinan/chartrank/issues"
+Changelog = "https://github.com/Adeshinan/chartrank/blob/main/CHANGELOG.md"
+
+# ---------------------------------------------------------------------------
+# Hatchling settings
+# ---------------------------------------------------------------------------
+[tool.hatch.version]
+path = "src/chartrank/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chartrank"]
+
+[tool.hatch.build.targets.sdist]
+# Source archive: code, tests and the files a packager needs, nothing else.
+include = ["src/", "tests/", "README.md", "README.fr.md", "LICENSE", "CHANGELOG.md"]
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+extend-exclude = ["docs/spec"]  # reference documents, not project code
+
+[tool.ruff.lint]
+# E/W: style, F: real errors, I: import order, UP: modern syntax, B: likely bugs
+select = ["E", "W", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["src", "tests"]
+# -ra: summary of skipped/failed tests; --disable-socket: no network (ENF-05);
+# --doctest-modules: the examples in docstrings are run as tests.
+addopts = "-ra --disable-socket --doctest-modules"
+
+[tool.coverage.run]
+source = ["chartrank"]
+branch = true

chartrank-0.1.0/src/chartrank/__init__.py

@@ -0,0 +1,7 @@
+"""ChartRank: suggests and explains the right chart for your data and intent."""
+
+from chartrank.profile import profile
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "profile"]

chartrank-0.1.0/src/chartrank/catalog.py

@@ -0,0 +1,4 @@
+"""Chart catalog.
+
+Declarative table mapping (variable types, intent) to candidate charts.
+"""

chartrank-0.1.0/src/chartrank/cli.py

@@ -0,0 +1 @@
+"""Command-line interface: profile, suggest and rank commands."""

chartrank-0.1.0/src/chartrank/codegen.py

@@ -0,0 +1 @@
+"""Code generation: turn a ChartSpec into a standalone, commented Python script."""

chartrank-0.1.0/src/chartrank/dictionary.py

@@ -0,0 +1,4 @@
+"""Data dictionary.
+
+Load and validate YAML or dict metadata (units, order, labels, roles).
+"""

chartrank-0.1.0/src/chartrank/gallery.py

@@ -0,0 +1 @@
+"""Gallery: object returned by suggest(), with show(), best and indexing."""

chartrank-0.1.0/src/chartrank/guards.py

@@ -0,0 +1,4 @@
+"""Guard rules.
+
+Best-practice checks (log scale, top N, overplotting...) applied to candidates.
+"""

chartrank-0.1.0/src/chartrank/profile.py

@@ -0,0 +1,50 @@
+"""Column profiling: semantic types and indicators.
+
+Version 0.1 is minimal: for each column, its pandas dtype, the share of missing
+values and the number of distinct values. Semantic types come in task 1.1.
+"""
+
+import pandas as pd
+
+
+def profile(df: pd.DataFrame) -> pd.DataFrame:
+    """Describe each column of ``df``.
+
+    Args:
+        df: The data to describe. It is never modified.
+
+    Returns:
+        One row per column (same order as ``df``), with:
+
+        - ``dtype``: the pandas dtype, as text (e.g. ``"float64"``);
+        - ``missing``: share of missing values, between 0 and 1;
+        - ``distinct``: number of distinct non-missing values.
+
+    Raises:
+        TypeError: If ``df`` is not a pandas DataFrame.
+
+    Example:
+        >>> import pandas as pd
+        >>> import chartrank as cr
+        >>> cr.profile(pd.DataFrame({"Age": [22.0, None, 38.0, 22.0]}))
+               dtype  missing  distinct
+        Age  float64     0.25         2
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError(
+            f"profile() expects a pandas DataFrame, got {type(df).__name__}. "
+            "Convert your data first, e.g. pd.DataFrame(data) or pd.read_csv(path)."
+        )
+
+    n_rows = len(df)
+    rows = {
+        column: {
+            "dtype": str(df[column].dtype),
+            "missing": df[column].isna().sum() / n_rows if n_rows else 0.0,
+            "distinct": df[column].nunique(dropna=True),
+        }
+        for column in df.columns
+    }
+    return pd.DataFrame.from_dict(
+        rows, orient="index", columns=["dtype", "missing", "distinct"]
+    )

chartrank-0.1.0/src/chartrank/recommend.py

@@ -0,0 +1 @@
+"""Recommender: combines catalog and guards, ranks candidates, picks the star chart."""

chartrank-0.1.0/src/chartrank/render/__init__.py

@@ -0,0 +1 @@
+"""Rendering backends that turn a ChartSpec into a figure."""

chartrank-0.1.0/src/chartrank/render/plotly.py

@@ -0,0 +1 @@
+"""Plotly backend: ChartSpec to plotly.graph_objects.Figure, with the common theme."""

chartrank-0.1.0/src/chartrank/spec.py

@@ -0,0 +1 @@
+"""ChartSpec: neutral, engine-independent description of a chart."""

chartrank-0.1.0/src/chartrank/target.py

@@ -0,0 +1,4 @@
+"""Target analysis.
+
+Task detection and association measures between variables and a target.
+"""

chartrank-0.1.0/tests/test_import.py

@@ -0,0 +1,7 @@
+"""Smoke tests: the package can be imported and exposes its version."""
+
+import chartrank
+
+
+def test_version_is_exposed() -> None:
+    assert chartrank.__version__ == "0.1.0"

chartrank-0.1.0/tests/test_no_network.py

@@ -0,0 +1,12 @@
+"""The test suite runs without network access (ENF-05)."""
+
+import socket
+
+import pytest
+from pytest_socket import SocketBlockedError
+
+
+@pytest.mark.filterwarnings("ignore:A test tried to use socket.socket")
+def test_network_is_blocked() -> None:
+    with pytest.raises(SocketBlockedError):
+        socket.socket(socket.AF_INET, socket.SOCK_STREAM)

chartrank-0.1.0/tests/test_profile.py

@@ -0,0 +1,62 @@
+"""Tests for the minimal profile (task 0.4): dtype, missing share, distinct count."""
+
+import numpy as np
+import pandas as pd
+import pytest
+
+import chartrank as cr
+
+
+@pytest.fixture
+def passengers() -> pd.DataFrame:
+    """A tiny Titanic-like DataFrame: 4 passengers, a few missing values."""
+    return pd.DataFrame(
+        {
+            "Pclass": [1, 3, 3, 2],
+            "Sex": ["female", "male", "male", None],
+            "Age": [38.0, np.nan, 26.0, np.nan],
+        }
+    )
+
+
+def test_one_row_per_column_in_original_order(passengers: pd.DataFrame) -> None:
+    result = cr.profile(passengers)
+    assert list(result.index) == ["Pclass", "Sex", "Age"]
+    assert list(result.columns) == ["dtype", "missing", "distinct"]
+
+
+def test_dtype(passengers: pd.DataFrame) -> None:
+    result = cr.profile(passengers)
+    assert result.loc["Pclass", "dtype"] == "int64"
+    assert result.loc["Age", "dtype"] == "float64"
+
+
+def test_missing_is_a_share_between_0_and_1(passengers: pd.DataFrame) -> None:
+    result = cr.profile(passengers)
+    assert result.loc["Pclass", "missing"] == 0.0
+    assert result.loc["Sex", "missing"] == 0.25  # 1 missing out of 4
+    assert result.loc["Age", "missing"] == 0.5  # 2 missing out of 4
+
+
+def test_distinct_ignores_missing_values(passengers: pd.DataFrame) -> None:
+    result = cr.profile(passengers)
+    assert result.loc["Pclass", "distinct"] == 3  # 1, 2, 3
+    assert result.loc["Sex", "distinct"] == 2  # female, male (None not counted)
+    assert result.loc["Age", "distinct"] == 2  # 38, 26
+
+
+def test_empty_dataframe_has_no_missing_values() -> None:
+    result = cr.profile(pd.DataFrame({"Fare": pd.Series([], dtype="float64")}))
+    assert result.loc["Fare", "missing"] == 0.0
+    assert result.loc["Fare", "distinct"] == 0
+
+
+def test_input_dataframe_is_not_modified(passengers: pd.DataFrame) -> None:
+    before = passengers.copy()
+    cr.profile(passengers)
+    pd.testing.assert_frame_equal(passengers, before)
+
+
+def test_rejects_non_dataframe_with_clear_message() -> None:
+    with pytest.raises(TypeError, match="expects a pandas DataFrame"):
+        cr.profile([1, 2, 3])  # type: ignore[arg-type]