Skip to content

cli

ruff_sync.cli

Synchronize Ruff linter configuration across Python projects.

This module provides a CLI tool and library for downloading, parsing, and merging Ruff configuration from upstream sources (like GitHub/GitLab) into local projects.

__all__ module-attribute 

__all__ = [
    "Arguments",
    "ColoredFormatter",
    "OutputFormat",
    "get_config",
    "main",
]

__version__ module-attribute 

__version__ = version('ruff-sync')

CIProvider module-attribute 

CIProvider = Literal[GITHUB, GITLAB]

LOGGER module-attribute 

LOGGER = getLogger(__name__)

PARSER module-attribute 

PARSER = _get_cli_parser()

OutputFormat

Bases: str, Enum

Output formats for the CLI.

Source code in src/ruff_sync/constants.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
@enum.unique
class OutputFormat(str, enum.Enum):
    """Output formats for the CLI."""

    TEXT = "text"
    JSON = "json"
    GITHUB = "github"
    GITLAB = "gitlab"
    SARIF = "sarif"

    @override
    def __str__(self) -> str:
        """Return the string value for argparse help."""
        return self.value

TEXT class-attribute instance-attribute 

TEXT = 'text'

JSON class-attribute instance-attribute 

JSON = 'json'

GITHUB class-attribute instance-attribute 

GITHUB = 'github'

GITLAB class-attribute instance-attribute 

GITLAB = 'gitlab'

SARIF class-attribute instance-attribute 

SARIF = 'sarif'

__str__ 

__str__()

Return the string value for argparse help.

Source code in src/ruff_sync/constants.py 
59
60
61
62
@override
def __str__(self) -> str:
    """Return the string value for argparse help."""
    return self.value

ColoredFormatter

Bases: Formatter

Logging Formatter to add colors.

Source code in src/ruff_sync/cli.py 
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
class ColoredFormatter(logging.Formatter):
    """Logging Formatter to add colors."""

    RESET: ClassVar[str] = "\x1b[0m"
    COLORS: ClassVar[Mapping[int, str]] = {
        logging.DEBUG: "\x1b[36m",  # Cyan
        logging.INFO: "\x1b[32m",  # Green
        logging.WARNING: "\x1b[33m",  # Yellow
        logging.ERROR: "\x1b[31m",  # Red
        logging.CRITICAL: "\x1b[1;31m",  # Bold Red
    }

    def __init__(self, fmt: str = "%(message)s") -> None:
        """Initialize the formatter with a format string."""
        super().__init__(fmt)

    @override
    def format(self, record: logging.LogRecord) -> str:
        """Format the log record with colors if the output is a TTY."""
        if sys.stderr.isatty():
            color = self.COLORS.get(record.levelno, self.RESET)
            return f"{color}{super().format(record)}{self.RESET}"
        return super().format(record)

RESET class-attribute 

RESET = '\x1b[0m'

COLORS class-attribute 

COLORS = {
    DEBUG: "\x1b[36m",
    INFO: "\x1b[32m",
    WARNING: "\x1b[33m",
    ERROR: "\x1b[31m",
    CRITICAL: "\x1b[1;31m",
}

__init__ 

__init__(fmt='%(message)s')

Initialize the formatter with a format string.

Source code in src/ruff_sync/cli.py 
84
85
86
def __init__(self, fmt: str = "%(message)s") -> None:
    """Initialize the formatter with a format string."""
    super().__init__(fmt)

format 

format(record)

Format the log record with colors if the output is a TTY.

Source code in src/ruff_sync/cli.py 
88
89
90
91
92
93
94
@override
def format(self, record: logging.LogRecord) -> str:
    """Format the log record with colors if the output is a TTY."""
    if sys.stderr.isatty():
        color = self.COLORS.get(record.levelno, self.RESET)
        return f"{color}{super().format(record)}{self.RESET}"
    return super().format(record)

Arguments

Bases: NamedTuple

CLI arguments for the ruff-sync tool.

Source code in src/ruff_sync/cli.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
class Arguments(NamedTuple):
    """CLI arguments for the ruff-sync tool."""

    command: str
    upstream: tuple[URL, ...]
    to: pathlib.Path
    exclude: Iterable[str]
    verbose: int
    branch: str = DEFAULT_BRANCH
    path: str | None = None
    semantic: bool = False
    diff: bool = True
    init: bool = False
    pre_commit: bool | MissingType = MISSING
    save: bool | None = None
    output_format: OutputFormat = OutputFormat.TEXT
    validate: bool | MissingType = MISSING  # run --validate checks before writing
    strict: bool | MissingType = MISSING  # treat warnings as errors (implies --validate)

    @property
    @deprecated("Use 'to' instead")
    def source(self) -> pathlib.Path:
        """Deprecated: use 'to' instead."""
        return self.to

    @classmethod
    @lru_cache(maxsize=1)
    def fields(cls) -> set[str]:
        """Return the set of all field names, including deprecated ones."""
        return set(cls._fields) | {"source"}

    def resolve(self) -> ExecutionArgs:
        """Resolve all MISSING sentinels to their effective defaults for execution."""
        from ruff_sync.constants import resolve_bool_flags  # noqa: PLC0415

        eff_validate, eff_strict, eff_pre_commit = resolve_bool_flags(
            self.validate,
            self.strict,
            self.pre_commit,
        )
        return ExecutionArgs(
            command=self.command,
            upstream=self.upstream,
            to=self.to,
            exclude=self.exclude,
            verbose=self.verbose,
            branch=self.branch,
            path=self.path,
            semantic=self.semantic,
            diff=self.diff,
            init=self.init,
            pre_commit=eff_pre_commit,
            save=self.save,
            output_format=self.output_format,
            validate=eff_validate,
            strict=eff_strict,
        )

command instance-attribute 

command

upstream instance-attribute 

upstream

to instance-attribute 

to

exclude instance-attribute 

exclude

verbose instance-attribute 

verbose

branch class-attribute instance-attribute 

branch = DEFAULT_BRANCH

path class-attribute instance-attribute 

path = None

semantic class-attribute instance-attribute 

semantic = False

diff class-attribute instance-attribute 

diff = True

init class-attribute instance-attribute 

init = False

pre_commit class-attribute instance-attribute 

pre_commit = MISSING

save class-attribute instance-attribute 

save = None

output_format class-attribute instance-attribute 

output_format = TEXT

validate class-attribute instance-attribute 

validate = MISSING

strict class-attribute instance-attribute 

strict = MISSING

source property 

source

Deprecated: use 'to' instead.

fields cached classmethod 

fields()

Return the set of all field names, including deprecated ones.

Source code in src/ruff_sync/cli.py 
122
123
124
125
126
@classmethod
@lru_cache(maxsize=1)
def fields(cls) -> set[str]:
    """Return the set of all field names, including deprecated ones."""
    return set(cls._fields) | {"source"}

resolve 

resolve()

Resolve all MISSING sentinels to their effective defaults for execution.

Source code in src/ruff_sync/cli.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def resolve(self) -> ExecutionArgs:
    """Resolve all MISSING sentinels to their effective defaults for execution."""
    from ruff_sync.constants import resolve_bool_flags  # noqa: PLC0415

    eff_validate, eff_strict, eff_pre_commit = resolve_bool_flags(
        self.validate,
        self.strict,
        self.pre_commit,
    )
    return ExecutionArgs(
        command=self.command,
        upstream=self.upstream,
        to=self.to,
        exclude=self.exclude,
        verbose=self.verbose,
        branch=self.branch,
        path=self.path,
        semantic=self.semantic,
        diff=self.diff,
        init=self.init,
        pre_commit=eff_pre_commit,
        save=self.save,
        output_format=self.output_format,
        validate=eff_validate,
        strict=eff_strict,
    )

ExecutionArgs

Bases: NamedTuple

Resolved arguments for execution logic — all sentinels replaced with concrete values.

Source code in src/ruff_sync/cli.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
class ExecutionArgs(NamedTuple):
    """Resolved arguments for execution logic — all sentinels replaced with concrete values."""

    command: str
    upstream: tuple[URL, ...]
    to: pathlib.Path
    exclude: Iterable[str]
    verbose: int
    branch: str
    path: str | None
    semantic: bool
    diff: bool
    init: bool
    pre_commit: bool  # plain bool — MISSING resolved to default
    save: bool | None
    output_format: OutputFormat
    validate: bool  # plain bool — MISSING resolved to default
    strict: bool  # plain bool — MISSING resolved to default

command instance-attribute 

command

upstream instance-attribute 

upstream

to instance-attribute 

to

exclude instance-attribute 

exclude

verbose instance-attribute 

verbose

branch instance-attribute 

branch

path instance-attribute 

path

semantic instance-attribute 

semantic

diff instance-attribute 

diff

init instance-attribute 

init

pre_commit instance-attribute 

pre_commit

save instance-attribute 

save

output_format instance-attribute 

output_format

validate instance-attribute 

validate

strict instance-attribute 

strict

ResolvedArgs

Bases: NamedTuple

Internal container for resolved arguments.

Source code in src/ruff_sync/cli.py 
176
177
178
179
180
181
182
183
184
class ResolvedArgs(NamedTuple):
    """Internal container for resolved arguments."""

    upstream: tuple[URL, ...]
    to: pathlib.Path
    exclude: Iterable[str]
    branch: str
    path: str | None
    output_format: OutputFormat

upstream instance-attribute 

upstream

to instance-attribute 

to

exclude instance-attribute 

exclude

branch instance-attribute 

branch

path instance-attribute 

path

output_format instance-attribute 

output_format

CLIArguments

Bases: Protocol

Protocol for parsed CLI arguments from ArgumentParser.

Source code in src/ruff_sync/cli.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
class CLIArguments(Protocol):
    """Protocol for parsed CLI arguments from ArgumentParser."""

    command: str | None
    upstream: list[URL]
    to: str | None
    source: str | None
    exclude: list[str] | None
    verbose: int
    branch: str | None
    path: str | None
    pre_commit: bool | None
    output_format: OutputFormat | None
    # Subcommand specific
    init: bool
    save: bool | None
    semantic: bool
    diff: bool
    validate: bool | None
    strict: bool | None

command instance-attribute 

command

upstream instance-attribute 

upstream

to instance-attribute 

to

source instance-attribute 

source

exclude instance-attribute 

exclude

verbose instance-attribute 

verbose

branch instance-attribute 

branch

path instance-attribute 

path

pre_commit instance-attribute 

pre_commit

output_format instance-attribute 

output_format

init instance-attribute 

init

save instance-attribute 

save

semantic instance-attribute 

semantic

diff instance-attribute 

diff

validate instance-attribute 

validate

strict instance-attribute 

strict

get_config cached 

get_config(source)

Read [tool.ruff-sync] configuration from pyproject.toml.

Examples:

>>> import pathlib
>>> config = get_config(pathlib.Path("."))
>>> if "upstream" in config:
...     print(f"Syncing from {config['upstream']}")
Source code in src/ruff_sync/cli.py 
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
@lru_cache(maxsize=1)
def get_config(
    source: pathlib.Path,
) -> Config:
    """Read [tool.ruff-sync] configuration from pyproject.toml.

    Examples:
        >>> import pathlib
        >>> config = get_config(pathlib.Path("."))
        >>> if "upstream" in config:
        ...     print(f"Syncing from {config['upstream']}")
    """
    local_toml = source / RuffConfigFileName.PYPROJECT_TOML
    # TODO: use pydantic to validate the toml file
    cfg_result: Config = {}
    if local_toml.exists():
        toml = tomlkit.parse(local_toml.read_text())
        config = toml.get("tool", {}).get("ruff-sync")
        if config:
            allowed_keys = set(Config.__annotations__.keys())
            for raw_key, value in config.items():
                # Check for legacy 'source' key to emit deprecation warning
                if raw_key.replace("-", "_") == ConfKey.to_attr(ConfKey.SOURCE):
                    LOGGER.warning(
                        f"DeprecationWarning: [tool.ruff-sync] '{raw_key}' "
                        f"is deprecated. Use '{ConfKey.TO}' instead."
                    )

                # Map legacy names (source, pre_commit_sync) to canonical
                # (to, pre-commit-version-sync)
                canonical_key = ConfKey.get_canonical(raw_key)

                # Normalize TOML key (dashes) to internal Python attribute name (underscores)
                # e.g. "pre-commit-version-sync" -> "pre_commit_version_sync"
                arg_attr = ConfKey.to_attr(canonical_key)

                if arg_attr in allowed_keys:
                    cfg_result[arg_attr] = value  # type: ignore[literal-required]
                else:
                    LOGGER.warning(f"Unknown ruff-sync configuration: {raw_key}")

            # Ensure 'to' is populated if 'source' was used
            to_attr = ConfKey.to_attr(ConfKey.TO)
            source_attr = ConfKey.to_attr(ConfKey.SOURCE)
            if source_attr in cfg_result and to_attr not in cfg_result:
                cfg_result[to_attr] = cfg_result[source_attr]  # type: ignore[literal-required]
    return cfg_result

main 

main()

Run the ruff-sync CLI.

Source code in src/ruff_sync/cli.py 
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
def main() -> int:
    """Run the ruff-sync CLI."""
    # Handle backward compatibility: default to 'pull' if no command provided
    if len(sys.argv) > 1 and sys.argv[1] not in (
        "pull",
        "check",
        "inspect",
        "-h",
        "--help",
        "--version",
    ):
        sys.argv.insert(1, "pull")
    elif len(sys.argv) == 1:
        sys.argv.append("pull")

    args = PARSER.parse_args()

    # Configure logging
    log_level = {
        0: logging.WARNING,
        1: logging.INFO,
    }.get(args.verbose, logging.DEBUG)

    # Configure logging for the entire ruff_sync package
    root_logger = logging.getLogger("ruff_sync")
    root_logger.setLevel(log_level)

    # Avoid adding multiple handlers if main() is called multiple times (e.g. in tests)
    if not root_logger.handlers:
        handler = logging.StreamHandler()
        handler.setFormatter(ColoredFormatter())
        root_logger.addHandler(handler)

    root_logger.propagate = "PYTEST_CURRENT_TEST" in os.environ

    # Determine target 'to' from CLI or use default '.'
    # Defer Path conversion to avoid pyfakefs issues with captured Path class
    arg_to = args.to or args.source
    initial_to = pathlib.Path(arg_to) if arg_to else pathlib.Path()
    config: Config = get_config(initial_to)

    # Resolve all arguments (honoring CLI overrides over config values)
    resolved = _resolve_args(args, config, initial_to)

    resolved_upstream = tuple(
        resolve_raw_url(u, branch=resolved.branch, path=resolved.path) for u in resolved.upstream
    )

    # Resolve validation flags from CLI (with CLI --strict implying validate=True)
    # and fall back to config. Bidirectional implications are handled by
    # resolve_bool_flags() inside Arguments.resolve(), so we store raw sentinels here.
    raw_validate = _resolve_validate(args, config)
    raw_strict = _resolve_strict(args, config)

    exec_args = Arguments(
        command=args.command,
        upstream=resolved_upstream,
        to=resolved.to,
        exclude=resolved.exclude,
        verbose=args.verbose,
        branch=resolved.branch,
        path=resolved.path,
        semantic=getattr(args, "semantic", False),
        diff=getattr(args, "diff", True),
        init=getattr(args, "init", False),
        pre_commit=_resolve_pre_commit(args, config),
        save=getattr(args, "save", None),
        output_format=resolved.output_format,
        validate=raw_validate,
        strict=raw_strict,
    )

    # Warn if the specified output format doesn't match the current CI environment
    _validate_ci_output_format(exec_args)

    try:
        if exec_args.command == "inspect":
            from ruff_sync.tui import get_tui_app  # noqa: PLC0415

            app_class = get_tui_app()
            return app_class(exec_args).run() or 0

        if exec_args.command == "check":
            return asyncio.run(check(exec_args))
        return asyncio.run(pull(exec_args))
    except DependencyError as e:
        LOGGER.error(f"❌ {e}")  # noqa: TRY400
        return 1
    except UpstreamError as e:
        for url, err in e.errors:
            LOGGER.error(f"❌ Failed to fetch {url}: {err}")  # noqa: TRY400
        return 4

inspect 

inspect()

Entry point for the ruff-inspect console script.

Source code in src/ruff_sync/cli.py 
742
743
744
745
746
747
748
749
750
751
752
753
754
def inspect() -> int:
    """Entry point for the ruff-inspect console script."""
    # Handle optional subcommands/args if user passed any to ruff-inspect
    # but primarily ensure "inspect" is the command.
    if len(sys.argv) > 1 and sys.argv[1] not in ("-h", "--help", "--version"):
        # If they passed args but no command, insert 'inspect'
        if sys.argv[1] not in ("pull", "check", "inspect"):
            sys.argv.insert(1, "inspect")
    else:
        # Default to 'inspect' if no args or just flags
        sys.argv.insert(1, "inspect")

    return main()