Skip to content

constants

ruff_sync.constants

Constants used across ruff-sync.

__all__ module-attribute 

__all__ = [
    "DEFAULT_BRANCH",
    "DEFAULT_EXCLUDE",
    "DEFAULT_PATH",
    "MISSING",
    "ConfKey",
    "MissingType",
    "OutputFormat",
    "resolve_defaults",
]

DEFAULT_EXCLUDE module-attribute 

DEFAULT_EXCLUDE = {'lint.per-file-ignores'}

DEFAULT_BRANCH module-attribute 

DEFAULT_BRANCH = 'main'

DEFAULT_PATH module-attribute 

DEFAULT_PATH = ''

MISSING module-attribute 

MISSING = SENTINEL

MissingType

Bases: Enum

Used to represent a missing value sentinel.

This can be used to properly type fields that use the MissingType.SENTINEL as a default.

Example

from ruff_sync.constants import MissingType, MISSING def foo(bar: int | None | MissingType = MISSING) -> None: ... if bar is MissingType.SENTINEL: ... print("bar is missing") ... else: ... print(f"bar is {bar}")

Source code in src/ruff_sync/constants.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
class MissingType(enum.Enum):
    """Used to represent a missing value sentinel.

    This can be used to properly type fields that use the `MissingType.SENTINEL` as a default.

    Example:
        >>> from ruff_sync.constants import MissingType, MISSING
        >>> def foo(bar: int | None | MissingType = MISSING) -> None:
        ...     if bar is MissingType.SENTINEL:
        ...         print("bar is missing")
        ...     else:
        ...         print(f"bar is {bar}")
    """

    SENTINEL = enum.auto()

SENTINEL class-attribute instance-attribute 

SENTINEL = auto()

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

ConfKey

Bases: str, Enum

Centralized configuration keys for [tool.ruff-sync].

These are the canonical names used in the pyproject.toml configuration file.

Source code in src/ruff_sync/constants.py 
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 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
@enum.unique
class ConfKey(str, enum.Enum):
    """Centralized configuration keys for [tool.ruff-sync].

    These are the canonical names used in the pyproject.toml configuration file.
    """

    UPSTREAM = "upstream"
    TO = "to"
    EXCLUDE = "exclude"
    BRANCH = "branch"
    PATH = "path"
    PRE_COMMIT_VERSION_SYNC = "pre-commit-version-sync"
    OUTPUT_FORMAT = "output-format"
    SEMANTIC = "semantic"
    DIFF = "diff"
    INIT = "init"
    SAVE = "save"
    VERBOSE = "verbose"

    # Legacy / Alias Keys
    SOURCE = "source"  # Legacy for 'to'
    PRE_COMMIT = "pre-commit"  # Legacy for 'pre-commit-version-sync'
    PRE_COMMIT_SYNC_LEGACY = "pre-commit-sync"  # Legacy for 'pre-commit-version-sync'

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

    @classmethod
    def to_attr(cls, key: str | ConfKey) -> str:
        """Normalize a configuration key to its Python attribute name (underscore)."""
        return str(key).replace("-", "_")

    @classmethod
    def get_canonical(cls, key: str) -> str:
        """Map legacy or aliased configuration keys to their canonical names.

        Args:
            key: The raw key from the configuration file.

        Returns:
            The canonical ConfKey name (still as a string for use in logic).
        """
        # Normalize the input key to underscores for robust alias matching
        norm_key = cls.to_attr(key)

        # Handle aliases for 'to'
        if norm_key == cls.to_attr(cls.SOURCE):
            return cls.TO.value

        # Handle aliases for 'pre-commit-version-sync'
        if norm_key in (
            cls.to_attr(cls.PRE_COMMIT_SYNC_LEGACY),
            cls.to_attr(cls.PRE_COMMIT),
        ):
            return cls.PRE_COMMIT_VERSION_SYNC.value

        # Return the original key (even if unknown, let 'allowed_keys' handle it)
        return key

UPSTREAM class-attribute instance-attribute 

UPSTREAM = 'upstream'

TO class-attribute instance-attribute 

TO = 'to'

EXCLUDE class-attribute instance-attribute 

EXCLUDE = 'exclude'

BRANCH class-attribute instance-attribute 

BRANCH = 'branch'

PATH class-attribute instance-attribute 

PATH = 'path'

PRE_COMMIT_VERSION_SYNC class-attribute instance-attribute 

PRE_COMMIT_VERSION_SYNC = 'pre-commit-version-sync'

OUTPUT_FORMAT class-attribute instance-attribute 

OUTPUT_FORMAT = 'output-format'

SEMANTIC class-attribute instance-attribute 

SEMANTIC = 'semantic'

DIFF class-attribute instance-attribute 

DIFF = 'diff'

INIT class-attribute instance-attribute 

INIT = 'init'

SAVE class-attribute instance-attribute 

SAVE = 'save'

VERBOSE class-attribute instance-attribute 

VERBOSE = 'verbose'

SOURCE class-attribute instance-attribute 

SOURCE = 'source'

PRE_COMMIT class-attribute instance-attribute 

PRE_COMMIT = 'pre-commit'

PRE_COMMIT_SYNC_LEGACY class-attribute instance-attribute 

PRE_COMMIT_SYNC_LEGACY = 'pre-commit-sync'

__str__ 

__str__()

Return the string value for TOML keys.

Source code in src/ruff_sync/constants.py 
90
91
92
93
@override
def __str__(self) -> str:
    """Return the string value for TOML keys."""
    return self.value

to_attr classmethod 

to_attr(key)

Normalize a configuration key to its Python attribute name (underscore).

Source code in src/ruff_sync/constants.py 
95
96
97
98
@classmethod
def to_attr(cls, key: str | ConfKey) -> str:
    """Normalize a configuration key to its Python attribute name (underscore)."""
    return str(key).replace("-", "_")

get_canonical classmethod 

get_canonical(key)

Map legacy or aliased configuration keys to their canonical names.

Parameters:

Name Type Description Default
key str

The raw key from the configuration file.

 required

Returns:

Type Description
str

The canonical ConfKey name (still as a string for use in logic).
Source code in src/ruff_sync/constants.py 
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
@classmethod
def get_canonical(cls, key: str) -> str:
    """Map legacy or aliased configuration keys to their canonical names.

    Args:
        key: The raw key from the configuration file.

    Returns:
        The canonical ConfKey name (still as a string for use in logic).
    """
    # Normalize the input key to underscores for robust alias matching
    norm_key = cls.to_attr(key)

    # Handle aliases for 'to'
    if norm_key == cls.to_attr(cls.SOURCE):
        return cls.TO.value

    # Handle aliases for 'pre-commit-version-sync'
    if norm_key in (
        cls.to_attr(cls.PRE_COMMIT_SYNC_LEGACY),
        cls.to_attr(cls.PRE_COMMIT),
    ):
        return cls.PRE_COMMIT_VERSION_SYNC.value

    # Return the original key (even if unknown, let 'allowed_keys' handle it)
    return key

resolve_defaults 

resolve_defaults(branch, path, exclude)

Resolve MISSING sentinel values to their effective defaults.

This is the single source of truth for MISSING → default resolution across the CLI and internal logic, keeping the layers in sync.

Parameters:

Name Type Description Default
branch str | MissingType

The resolved branch value or MISSING.

 required
path str | MissingType

The resolved path value or MISSING.

 required
exclude Iterable[str] | MissingType

The resolved exclude iterable or MISSING.

 required

Returns:

Type Description
str

A (branch, path, exclude) tuple with defaults applied.
str | None

path is normalised to None (not "") so callers can forward
Iterable[str]

it directly to :func:~ruff_sync.core.resolve_raw_url.
Source code in src/ruff_sync/constants.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
154
def resolve_defaults(
    branch: str | MissingType,
    path: str | MissingType,
    exclude: Iterable[str] | MissingType,
) -> tuple[str, str | None, Iterable[str]]:
    """Resolve MISSING sentinel values to their effective defaults.

    This is the single source of truth for MISSING → default resolution across
    the CLI and internal logic, keeping the layers in sync.

    Args:
        branch: The resolved branch value or ``MISSING``.
        path: The resolved path value or ``MISSING``.
        exclude: The resolved exclude iterable or ``MISSING``.

    Returns:
        A ``(branch, path, exclude)`` tuple with defaults applied.
        ``path`` is normalised to ``None`` (not ``""``) so callers can forward
        it directly to :func:`~ruff_sync.core.resolve_raw_url`.
    """
    eff_branch = branch if branch is not MISSING else DEFAULT_BRANCH
    raw_path = path if path is not MISSING else DEFAULT_PATH
    # Normalise empty string → None: resolve_raw_url treats both the same,
    # but explicit None is the canonical "root directory" sentinel.
    eff_path: str | None = raw_path or None
    eff_exclude = exclude if exclude is not MISSING else DEFAULT_EXCLUDE
    return eff_branch, eff_path, eff_exclude