whl2conda.settings¶

@dataclasses.dataclass(kw_only=True)
class Whl2CondaSettings:
    """
    User settings for whl2conda.

    These are accessed through the global [settings][(m).] variable.

    The following settings are currently supported:

    * [auto_update_std_renames][.] - whether to automatically update std rename mappings
    * [conda_format][.] - default output conda package format
    * [pypi_indexes][.] - table of known extra pypi indexes

    """

    SETTINGS_FILENAME: ClassVar[str] = "settings.json"
    """Default base filename for saved settings."""

    DEFAULT_SETTINGS_FILE: ClassVar[Path] = (
        user_config_path("whl2conda") / SETTINGS_FILENAME
    )
    """Default filepath for saved settings."""

    # TODO:
    #   - difftool
    #   - pyproject defaults

    auto_update_std_renames: _BoolField = _BoolField()
    """
    Whether to automatically update the standard renames for operations
    that need them. Default is false.
    """

    conda_format: _CondaPackageFormatField = _CondaPackageFormatField()
    """
    The default output conda package format if not specified. Default is V2.
    """

    pypi_indexes: _SettingsField = _SettingsField(default=dict)
    """
    Dictionary of aliases for pypi package indexes from which wheels can be
    downloaded. Default is empty.
    """

    #
    # Internal attributes
    #

    _settings_file: Path = dataclasses.field(
        default=DEFAULT_SETTINGS_FILE, compare=False
    )
    """
    Location of underlying settings file.
    """

    _fieldnames: ClassVar[frozenset[str]] = frozenset()
    """
    Set of public field names.
    """

    @property
    def settings_file(self) -> Path:
        """
        Settings file for this settings object.

        Set from [from_file][..] constructor or else will be
        [DEFAULT_SETTINGS_FILE][(c).].
        """
        return self._settings_file

    #
    # Settings access/modification methods
    #

    def to_dict(self) -> dict[str, Any]:
        """
        Return dictionary containing public settings data.
        """
        return {
            k: v for k, v in dataclasses.asdict(self).items() if not k.startswith("_")
        }

    def get(self, key: str) -> Any:
        """
        Get a value from the settings by string key.

        The key may either be just the field name (e.g. 'conda-format')
        or can refer to am entry within dictionary-valued field
        (e.g. 'pypi-indexes.acme'). Note that the dashes in the first
        component of the key will be converted to underscores.
        """
        name, subkey = self._split_key(key)
        value = getattr(self, name)

        if subkey:
            if not isinstance(value, dict):
                raise KeyError(
                    f"Bad settings key '{key}': '{name}' is not a dictionary"
                )
            if subkey not in value:
                raise KeyError(f"'{key}' is not set'")
            value = value[subkey]

        return value

    def set(self, key: str, value: Any) -> None:
        """
        Set a value in the settings by string key.

        See [get][..] for details on key format.

        This does not save the settings file.
        """
        name, subkey = self._split_key(key)

        if not subkey:
            setattr(self, name, value)

        else:
            d = getattr(self, name)
            if not isinstance(d, dict):
                raise KeyError(
                    f"Bad settings key '{key}': '{name}' is not a dictionary"
                )
            d[subkey] = value

    def unset(self, key: str) -> None:
        """
        Unset attribute with given key.

        The setting will revert to its original value.

        See [get][..] for details on key format.

        This does not save the settings file.
        """
        name, subkey = self._split_key(key)

        if not subkey:
            delattr(self, name)

        else:
            d = getattr(self, name)
            if not isinstance(d, dict):
                raise KeyError(
                    f"Bad settings key '{key}': '{name}' is not a dictionary"
                )
            try:
                del d[subkey]
            except KeyError:
                pass

    def unset_all(self) -> None:
        """
        Unset all settings, and revert to default values.
        """
        for k in self._fieldnames:
            self.unset(k)

    #
    # File operations
    #

    @classmethod
    def from_file(cls, filename: Path | str = "") -> Whl2CondaSettings:
        """
        Return settings read from file.

        Arguments:
            filename: relative path to settings file (may start with '~')
                defaults to [DEFAULT_SETTINGS_FILE][(c).] if not specified.
        """
        settings = cls()
        settings.load(filename or cls.DEFAULT_SETTINGS_FILE)
        return settings

    def load(self, filename: Path | str, reset_all: bool = False) -> None:
        """
        Reload settings from file

        Args:
            filename: relative path to settings file (may start with '~')
            reset_all: if True, then all settings will be unset and reverted
                to default value prior to loading.
        """
        filepath = Path(Path(filename).expanduser())
        self._settings_file = filepath
        if reset_all:
            self.unset_all()
        if filepath.exists():
            contents = filepath.read_text("utf8")
            json_obj = json.loads(contents)
            for k, v in json_obj.items():
                if k in self._fieldnames:
                    try:
                        setattr(self, k, v)
                    except Exception as ex:
                        print(
                            f"Cannot read '{k}' from '{filepath}': {ex}",
                            file=sys.stderr,
                        )

    def save(self, filename: Path | str = "") -> None:
        """
        Write settings to specified file in JSON format.

        Args:
            filename: file to write. Defaults to [settings_file][..]
        """
        filepath = Path(filename or self._settings_file)
        json_obj = self.to_dict()
        json_obj["$whl2conda-version"] = __version__
        json_obj["$created"] = str(dt.datetime.now(tz=dt.timezone.utc))
        filepath.parent.mkdir(parents=True, exist_ok=True)
        filepath.write_text(json.dumps(json_obj, indent=2))

    #
    # Internal methods
    #

    def _split_key(self, key: str) -> tuple[str, str]:
        parts = key.split(".", maxsplit=1)
        name = _toidentifier(parts[0])
        if name not in self._fieldnames:
            raise KeyError(f"Unknown settings key '{key}'")
        return name, parts[1] if len(parts) > 1 else ""