ruff-sync 0.0.1.dev2__py3-none-any.whl

ruff_sync-0.0.1.dev2.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: ruff-sync
+Version: 0.0.1.dev2
+Summary: Syncronize ruff linter config settings accross projects
+Author-email: Gabriel Gore <gabriel59kg@gmail.com>
+License: MIT
+License-File: LICENSE.md
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: tomlkit<2.0.0,>=0.12.3
+Description-Content-Type: text/markdown
+
+[![codecov](https://codecov.io/gh/Kilo59/ruff-sync/graph/badge.svg?token=kMZw0XtoFW)](https://codecov.io/gh/Kilo59/ruff-sync)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Kilo59/ruff-sync/main.svg)](https://results.pre-commit.ci/latest/github/Kilo59/ruff-sync/main)
+[![Wily](https://img.shields.io/badge/%F0%9F%A6%8A%20wily-passing-brightgreen.svg)](https://wily.readthedocs.io/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+# ruff-sync
+
+**Keep your Ruff config consistent across every repo — automatically.**
+
+`ruff-sync` is a CLI tool that pulls a canonical [Ruff](https://docs.astral.sh/ruff/) configuration from an upstream `pyproject.toml` (hosted anywhere — GitHub, GitLab, a raw URL) and merges it into your local project, preserving your comments, formatting, and project-specific overrides.
+
+## The Problem
+
+If you maintain more than one Python project, you've probably copy-pasted your `[tool.ruff]` config between repos more than once. When you decide to enable a new rule or bump your target Python version, you get to do it again — in _every_ repo. Configs drift, standards diverge, and your "shared" style guide becomes a polite suggestion.
+
+### How Other Ecosystems Solve This
+
+| Ecosystem | Mechanism | Limitation for Ruff users |
+|-----------|-----------|---------------------------|
+| **ESLint** | [Shareable configs](https://eslint.org/docs/latest/extend/shareable-configs) — publish an npm package, then `extends: ["my-org-config"]` | Requires a package registry (npm). Python doesn't have an equivalent convention. |
+| **Prettier** | [Shared configs](https://prettier.io/docs/sharing-configurations) — same npm-package pattern, referenced via `"prettier": "@my-org/prettier-config"` in `package.json` | Same — tightly coupled to npm. |
+| **Ruff** | [`extend`](https://docs.astral.sh/ruff/configuration/#config-file-discovery) — extend from a _local_ file path (great for monorepos) | Only supports local paths. No native remote URL support ([requested in astral-sh/ruff#12352](https://github.com/astral-sh/ruff/issues/12352)). |
+
+Ruff's `extend` is perfect inside a monorepo, but if your projects live in **separate repositories**, there's no built-in way to inherit config from a central source.
+
+**That's what `ruff-sync` does.**
+
+## How It Works
+
+```
+┌─────────────────────────────┐
+│  Upstream repo              │
+│  (your "source of truth")   │
+│                             │
+│  pyproject.toml             │
+│    [tool.ruff]              │
+│    target-version = "py310" │
+│    lint.select = [...]      │
+└──────────┬──────────────────┘
+           │  ruff-sync downloads
+           │  & extracts [tool.ruff]
+           ▼
+┌─────────────────────────────┐
+│  Your local project         │
+│                             │
+│  pyproject.toml             │
+│    [tool.ruff]  ◄── merged  │
+│    # your comments kept ✓   │
+│    # formatting kept ✓      │
+│    # per-file-ignores kept ✓│
+└─────────────────────────────┘
+```
+
+1. You point `ruff-sync` at the URL of your canonical `pyproject.toml`.
+2. It downloads the file, extracts the `[tool.ruff]` section.
+3. It **merges** the upstream config into your local `pyproject.toml` — updating values that changed, adding new rules, but preserving your local comments, whitespace, and any sections you've chosen to exclude (like `per-file-ignores`).
+
+No package registry. No publishing step. Just a URL.
+
+## Quick Start
+
+### Install
+
+<!-- ### PyPi Install
+
+```console
+pip install ruff-sync
+``` -->
+
+From Git (with [`uv`](https://docs.astral.sh/uv/guides/tools/)):
+
+```console
+uv tool install git+https://github.com/Kilo59/ruff-sync
+```
+
+From Git (with [`pipx`](https://pipx.pypa.io/stable/) — recommended):
+
+```console
+pipx install git+https://github.com/Kilo59/ruff-sync
+```
+
+Or with pip:
+
+```console
+pip install git+https://github.com/Kilo59/ruff-sync
+```
+
+### Usage
+
+```console
+# Sync from a GitHub URL (blob URLs are auto-converted to raw)
+ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml
+
+# Sync into a specific project directory
+ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml --source ./my-project
+
+# Exclude specific sections from being overwritten using dotted paths
+ruff-sync https://github.com/my-org/standards/blob/main/pyproject.toml --exclude lint.per-file-ignores lint.ignore
+```
+
+### CLI Reference
+
+```
+usage: ruff-sync [-h] [--source SOURCE] [--exclude EXCLUDE [EXCLUDE ...]] upstream
+
+positional arguments:
+  upstream              The URL to download the pyproject.toml file from.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --source SOURCE       The directory to sync the pyproject.toml file to. Default: .
+  --exclude EXCLUDE [EXCLUDE ...]
+                        Exclude certain ruff configs. Default: lint.per-file-ignores
+```
+
+## Key Features
+
+- **Format-preserving merges** — Uses [tomlkit](https://github.com/sdispater/tomlkit) under the hood, so your comments, whitespace, and TOML structure are preserved. No reformatting surprises.
+- **GitHub URL support** — Paste a GitHub blob URL and it will automatically convert it to the raw content URL.
+- **Selective exclusions** — Keep project-specific overrides (like `target-version`) from being clobbered by the upstream config.
+- **Works with any host** — GitHub, GitLab, Bitbucket, or any raw URL that serves a `pyproject.toml`.
+
+## Configuration
+
+You can configure `ruff-sync` itself in your `pyproject.toml`:
+
+```toml
+[tool.ruff-sync]
+# Use simple names for top-level keys, and dotted paths for nested keys
+exclude = [
+    "target-version",          # A top-level key under [tool.ruff]
+    "lint.per-file-ignores",   # A nested key under [tool.ruff.lint]
+    "lint.ignore"
+]
+```
+
+This sets the default exclusions so you don't need to pass `--exclude` on the command line every time.
+*Note: Any explicitly provided CLI arguments will override the list in `pyproject.toml`.*
+
+## Example Workflow
+
+A typical setup for an organization:
+
+1. **Create a "standards" repo** with your canonical `pyproject.toml` containing your shared `[tool.ruff]` config.
+2. **In each project**, run `ruff-sync` pointing at that repo — either manually, in a Makefile, or as a CI step.
+3. **When you update the standard**, re-run `ruff-sync` in each project to pull the changes. Your local comments and `per-file-ignores` stay intact.
+
+```console
+# In each project repo:
+ruff-sync https://github.com/my-org/python-standards/blob/main/pyproject.toml
+git diff pyproject.toml  # review the changes
+git commit -am "sync ruff config from upstream"
+```
+
+## Contributing
+
+This project uses:
+
+- [uv](https://docs.astral.sh/uv/) for dependency management
+- [Ruff](https://docs.astral.sh/ruff/) for linting and formatting
+- [mypy](https://mypy-lang.org/) for type checking (strict mode)
+- [pytest](https://docs.pytest.org/) for testing
+
+```console
+# Setup
+uv sync --group dev
+
+# Run checks
+uv run ruff check . --fix   # lint
+uv run ruff format .        # format
+uv run mypy .               # type check
+uv run pytest -vv           # test
+```
+
+## Dogfooding
+
+To see `ruff-sync` in action on a complex, real-world configuration, you can "dogfood" it by syncing this project's own `pyproject.toml` with a large upstream config like Pydantic's.
+
+We've provided a script to make this easy:
+
+```console
+./scripts/dogfood.sh
+```
+
+This will download Pydantic's Ruff configuration and merge it into the local `pyproject.toml`. You can then use `git diff` to see how it merged the keys while preserving the existing structure and comments.
+
+**To revert the changes after testing:**
+
+```console
+git checkout pyproject.toml
+```
+
+## License
+
+[MIT](LICENSE.md)

ruff_sync-0.0.1.dev2.dist-info/RECORD

@@ -0,0 +1,6 @@
+ruff_sync.py,sha256=kyz1Vmwgyv3DEHvLlBJyLQjgRLePlu33ZUhsvxXTPs8,9699
+ruff_sync-0.0.1.dev2.dist-info/METADATA,sha256=ckyU-Z7SwdroP9meJf3kv9hOLhFOs2PYcZT-mk-sTII,8467
+ruff_sync-0.0.1.dev2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ruff_sync-0.0.1.dev2.dist-info/entry_points.txt,sha256=z8TlIElMWLlqY_YWglHeMBksDohf2voVih6YnCBCWzk,45
+ruff_sync-0.0.1.dev2.dist-info/licenses/LICENSE.md,sha256=RcCP8t8xyCx2cvMZSLjBrPqJfctciWC6q85ceQAcEfA,1080
+ruff_sync-0.0.1.dev2.dist-info/RECORD,,

ruff_sync-0.0.1.dev2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ruff_sync-0.0.1.dev2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ruff-sync = ruff_sync:main

ruff_sync-0.0.1.dev2.dist-info/licenses/LICENSE.md

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2023 Gabriel Gore
+
+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.

ruff_sync.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import pathlib
+import warnings
+from argparse import ArgumentParser
+from collections.abc import Iterable, Mapping
+from functools import lru_cache
+from io import StringIO
+from typing import Any, Final, Literal, NamedTuple, overload
+
+import httpx
+import tomlkit
+from httpx import URL
+from tomlkit import TOMLDocument, table
+from tomlkit.items import Table
+from tomlkit.toml_file import TOMLFile
+
+__version__ = "0.0.1.dev0"
+
+_DEFAULT_EXCLUDE: Final[set[str]] = {"lint.per-file-ignores"}
+
+LOGGER = logging.getLogger(__name__)
+
+
+class Arguments(NamedTuple):
+    upstream: URL
+    source: pathlib.Path
+    exclude: Iterable[str]
+
+    @classmethod
+    @lru_cache(maxsize=1)
+    def fields(cls) -> set[str]:
+        return set(cls._fields)
+
+
+@lru_cache(maxsize=1)
+def get_config(
+    source: pathlib.Path,
+) -> Mapping[Literal["upstream", "source", "exclude"], str | list[str]]:
+    local_toml = source / "pyproject.toml"
+    # TODO: use pydantic to validate the toml file
+    cfg_result = {}
+    if local_toml.exists():
+        toml = tomlkit.parse(local_toml.read_text())
+        config = toml.get("tool", {}).get("ruff-sync")
+        if config:
+            for arg, value in config.items():
+                if arg in Arguments.fields():
+                    cfg_result[arg] = value
+                else:
+                    warnings.warn(f"Unknown ruff-sync configuration: {arg}", stacklevel=2)
+    return cfg_result
+
+
+@lru_cache(maxsize=1)
+def _resolve_source(source: str | pathlib.Path) -> pathlib.Path:
+    if isinstance(source, str):
+        source = pathlib.Path(source)
+    return source.resolve(strict=True)
+
+
+def _get_cli_parser() -> ArgumentParser:
+    # TODO: determine if args was provided by user or not
+    # https://docs.python.org/3/library/argparse.html#nargs
+    parser = ArgumentParser()
+    parser.add_argument(
+        "upstream",
+        type=URL,
+        help="The URL to download the pyproject.toml file from.",
+    )
+    parser.add_argument(
+        "--source",
+        type=pathlib.Path,
+        default=".",
+        help="The directory to sync the pyproject.toml file to. Default: .",
+        required=False,
+    )
+    parser.add_argument(
+        "--exclude",
+        nargs="+",
+        help=f"Exclude certain ruff configs. Default: {' '.join(_DEFAULT_EXCLUDE)}",
+        default=None,
+    )
+    return parser
+
+
+def github_url_to_raw_url(url: URL) -> URL:
+    """Convert a GitHub URL to its corresponding raw content URL
+
+    Args:
+        url (URL): The GitHub URL to be converted.
+
+    Returns:
+        URL: The corresponding raw content URL.
+    """
+    url_str = str(url)
+    if "github.com" in url_str and "/blob/" in url_str:
+        raw_url_str = url_str.replace("github.com", "raw.githubusercontent.com").replace(
+            "/blob/", "/"
+        )
+        return httpx.URL(raw_url_str)
+    else:
+        return url
+
+
+async def download(url: URL, client: httpx.AsyncClient) -> StringIO:
+    """Download a file from a URL and return a StringIO object."""
+    response = await client.get(url)
+    response.raise_for_status()
+    return StringIO(response.text)
+
+
+@overload
+def get_ruff_tool_table(
+    toml: str | TOMLDocument,
+    create_if_missing: Literal[True] = ...,
+    exclude: Iterable[str] = ...,
+) -> Table: ...
+
+
+@overload
+def get_ruff_tool_table(
+    toml: str | TOMLDocument,
+    create_if_missing: Literal[False] = ...,
+    exclude: Iterable[str] = ...,
+) -> Table | None: ...
+
+
+def get_ruff_tool_table(
+    toml: str | TOMLDocument,
+    create_if_missing: bool = True,
+    exclude: Iterable[str] = (),
+) -> Table | None:
+    """Get the tool.ruff section from a TOML string.
+    If it does not exist, create it.
+    """
+    if isinstance(toml, str):
+        doc: TOMLDocument = tomlkit.parse(toml)
+    else:
+        doc = toml
+    try:
+        tool: Table = doc["tool"]  # type: ignore[assignment]
+        ruff = tool["ruff"]
+        LOGGER.debug("Found `tool.ruff` section.")
+    except KeyError:
+        if not create_if_missing:
+            return None
+        LOGGER.info("No `tool.ruff` section found, creating it.")
+        tool = table(True)
+        ruff = table()
+        tool.append("ruff", ruff)
+        doc.append("tool", tool)
+    if not isinstance(ruff, Table):
+        raise TypeError(f"Expected table, got {type(ruff)}")
+    _apply_exclusions(ruff, exclude)
+    return ruff
+
+
+def _apply_exclusions(tbl: Table, exclude: Iterable[str]) -> None:
+    """Remove excluded keys from a ruff table, supporting dotted paths.
+
+    Keys can be simple (e.g. ``"target-version"``) to match top-level ruff
+    keys, or dotted (e.g. ``"lint.per-file-ignores"``) to reach into nested
+    sub-tables.
+    """
+    for key_path in exclude:
+        parts = key_path.split(".")
+        target: Any = tbl
+        for part in parts[:-1]:
+            target = target.get(part) if hasattr(target, "get") else None
+            if target is None:
+                break
+        if target is not None and hasattr(target, "pop"):
+            leaf = parts[-1]
+            if leaf in target:
+                LOGGER.info(f"Excluding `{key_path}` from upstream ruff config.")
+                target.pop(leaf)
+
+
+def toml_ruff_parse(toml_s: str, exclude: Iterable[str]) -> TOMLDocument:
+    """Parse a TOML string for the tool.ruff section excluding certain ruff configs."""
+    ruff_toml: TOMLDocument = tomlkit.parse(toml_s)["tool"]["ruff"]  # type: ignore[index,assignment]
+    for section in exclude:
+        LOGGER.info(f"Exluding section `lint.{section}` from ruff config.")
+        ruff_toml["lint"].pop(section, None)  # type: ignore[union-attr]
+    return ruff_toml
+
+
+def merge_ruff_toml(
+    source: TOMLDocument, upstream_ruff_doc: TOMLDocument | Table | None
+) -> TOMLDocument:
+    """Merge the source and upstream tool ruff config with better whitespace preservation."""  # noqa: E501
+    if not upstream_ruff_doc:
+        LOGGER.warning("No upstream ruff config section found.")
+        return source
+
+    source_tool_ruff = get_ruff_tool_table(source)
+
+    def _recursive_update(source_table: Any, upstream: Any) -> None:
+        """Recursively update a TOML table to preserve formatting of existing keys."""
+        if hasattr(upstream, "items") or isinstance(upstream, Mapping):
+            items = upstream.items()
+        else:
+            return
+
+        for key, value in items:
+            if key in source_table:
+                if hasattr(source_table[key], "items") and (
+                    hasattr(value, "items") or isinstance(value, Mapping)
+                ):
+                    # Structural fix: if the target is a proxy (dotted key),
+                    # and we are adding NEW keys to it, we must convert it to a real
+                    # table to ensure children get correct headers.
+                    source_sub_keys = set(source_table[key].keys())
+                    upstream_sub_keys = set(value.keys())
+                    if not upstream_sub_keys.issubset(source_sub_keys):
+                        current_val = source_table[key].unwrap()
+                        # DELETE PROXY FIRST to avoid structural doubling
+                        del source_table[key]
+                        # ADD AS REAL TABLE
+                        source_table.add(key, current_val)
+
+                    _recursive_update(source_table[key], value)
+                else:
+                    # Overwrite existing value
+                    source_table[key] = (
+                        value.unwrap() if hasattr(value, "unwrap") else value
+                    )
+            else:
+                # Add new key/value
+                source_table[key] = value.unwrap() if hasattr(value, "unwrap") else value
+
+    _recursive_update(source_tool_ruff, upstream_ruff_doc)
+
+    return source
+
+
+async def sync(
+    args: Arguments,
+) -> None:
+    """Sync the upstream pyproject.toml file to the source directory."""
+    print("Syncing Ruff...")
+    if args.source.is_file():
+        _source_toml_path = args.source
+    else:
+        _source_toml_path = args.source / "pyproject.toml"
+    source_toml_file = TOMLFile(_source_toml_path.resolve(strict=True))
+
+    # NOTE: there's no particular reason to use async here.
+    async with httpx.AsyncClient() as client:
+        file_buffer = await download(args.upstream, client)
+        LOGGER.info(f"Downloaded upstream file from {args.upstream}")
+
+    upstream_ruff_toml = get_ruff_tool_table(
+        file_buffer.read(), create_if_missing=False, exclude=args.exclude
+    )
+    merged_toml = merge_ruff_toml(
+        source_toml_file.read(),
+        upstream_ruff_toml,
+    )
+    source_toml_file.write(merged_toml)
+    print(f"Updated {_source_toml_path.resolve().relative_to(pathlib.Path.cwd())}")
+
+
+PARSER: Final[ArgumentParser] = _get_cli_parser()
+
+
+def main() -> None:
+    args = PARSER.parse_args()
+    config = get_config(args.source)
+
+    # Merge exclude: use CLI value if explicitly provided, else file config,
+    # else the built-in default.
+    exclude: Iterable[str]
+    if args.exclude is not None:
+        # User passed --exclude on the CLI — that takes precedence
+        exclude = args.exclude
+    elif "exclude" in config:
+        exclude = config["exclude"]
+        LOGGER.info(f"Using exclude from [tool.ruff-sync]: {list(exclude)}")
+    else:
+        exclude = _DEFAULT_EXCLUDE
+
+    # Convert non-raw github upstream url to the raw equivalent
+    args.upstream = github_url_to_raw_url(args.upstream)
+
+    asyncio.run(
+        sync(
+            Arguments(
+                upstream=args.upstream,
+                source=args.source,
+                exclude=exclude,
+            )
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()