API

class Formatters(Enum):
    """The enumeration of the supported formatters."""
    CONDA = _FormatterValue[_CondaConfiguration, CondaEnvironment](name='conda',
                                                                   to_environments=_conda_mapper,
                                                                   serialize=_conda_writer,
                                                                   configuration=_CondaConfiguration.from_configuration)

    def test(self, formatter: dict | str) -> bool:
        """Checks if a formatter configuration dict refers to the current Formatter value."""
        return (isinstance(formatter, str) and self.value.name == formatter
                or isinstance(formatter, dict) and self.value.name in formatter)

    def _get_formatter_configuration(self, configuration: Configuration):
        """Builds a specific formatter configuration from the main configuration related to the current Formatter value.
        """
        for formatter in configuration.formatters:
            if self.test(formatter):
                return self.value.configuration(formatter)
        raise ValueError

    def build(self, conf: Configuration):
        """Build the list of the environments using the given configuration."""
        frmtter_conf = self._get_formatter_configuration(conf)
        return self.value.to_environments(conf, frmtter_conf)

    def write(self, conf: Configuration, output_dir: Path):
        """Build the list of the environments using the given configuration and writes them to the given output folder.
        """
        frmtter_conf = self._get_formatter_configuration(conf)
        envs = self.value.to_environments(conf, frmtter_conf)
        return self.value.serialize(envs, frmtter_conf, output_dir)

@dataclass(frozen=True)
class Configuration:
    """Representation of pyenvs configuration content."""

    formatters: list[dict | str]
    """Each formatter either can be a single character string of one of supported formatters or a key/value pair with 
    the key referencing to the formatter name and the value referencing to its specific configuration."""

    environments: list[str] | None
    """A reference list of the environments referenced by dependencies. If the list is provided, dependencies 
    referencing an unknown environment raise an error. If the list is not provided, it is inferred from the dependency
    environments. If an empty list is provided, no dependency is supposed to reference any specific environment."""

    dependencies: list[Dependency]
    """The list of the dependencies."""

    @staticmethod
    def from_dict(source: dict):
        """Builds a Configuration from a configuration dict."""
        return Configuration(
            formatters=source['configuration']['formatters'],
            environments=source['environments'] if 'environments' in source else None,
            dependencies=[Dependency.from_dict(d) for d in source['dependencies']]
        )

    def strict_dependencies(self) -> list[Dependency]:
        """Returns only the strict dependencies which are ones not specifying any environment."""
        return [d for d in self.dependencies if not d.environments]

    def env_dependencies(self, environment: str) -> list[Dependency]:
        """Returns all the specified environment dependencies which are strict ones and ones referring to the given
        environment."""
        return [d for d in self.dependencies if not d.environments or environment in d.environments]

    def _implicit_environments(self) -> list[str]:
        """Computes implicit environments which are ones contained in dependency environment lists."""
        return list(dict.fromkeys([e for dep in self.dependencies if dep.environments for e in dep.environments]))

    def effective_environments(self) -> list[str]:
        """Checks environments and computes effective ones.

        1. Computes the effective environments.
        2. If a global environment list is provided, checks its maps the implicit environment set.
        3. Returns the environment list if supplied, or default, the implicit environment list.
        """
        implicit_envs = self._implicit_environments()

        if self.environments is not None and set(self.environments) != set(implicit_envs):
            raise ValueError(
                f'if defined, environment list {self.environments} should match '
                f'the implicit environment dependency set {implicit_envs}')

        return implicit_envs if self.environments is None else self.environments

@dataclass(frozen=True)
class Dependency:
    """Representation of dependency features."""

    id: str
    version: str | None
    environments: list[str] | None
    source: str | None
    sha: str | None

    @staticmethod
    def from_dict(source: dict):
        """Builds a Dependency from a configuration dict."""

        assert 'id' in source, 'id is a mandatory dependency field'

        return Dependency(
            id=source['id'],
            version=str(source['version']) if 'version' in source else None,
            environments=source['environments'] if 'environments' in source else None,
            source=source['source'] if 'source' in source else None,
            sha=source['sha'] if 'sha' in source else None
        )

@dataclass(frozen=True)
class CondaEnvironment:
    """Conda environment file definition."""

    name: str
    channels: list[str] | None
    dependencies: list[str]
    pip_dependencies: list[str] | None

    def to_dict(self) -> dict:
        """Mapping to dict."""

        result = {
            'name': self.name
        }

        if self.channels:
            result['channels'] = self.channels

        dependencies: list = self.dependencies
        if self.pip_dependencies:
            dependencies.append({'pip': self.pip_dependencies})

        result['dependencies'] = dependencies
        return result

    def dump(self, path: Path, encoding: str):
        """Write to yml output file."""
        with open(path, 'w', encoding=encoding) as o:
            yaml.dump(self.to_dict(), o, sort_keys=False)

    @staticmethod
    def from_configuration(name: str, pip: list[str] | None, channels: list[str] | None, configuration: Configuration):
        """Build an environment from a standard configuration."""
        return CondaEnvironment.from_dependencies(name=name,
                                                  pip=pip,
                                                  channels=channels,
                                                  dependencies=configuration.dependencies)

    @staticmethod
    def from_dependencies(name: str, pip: list[str] | None, channels: list[str] | None, dependencies: list[Dependency]):
        """Build an environment from a dependency list."""
        deps = [CondaEnvironment._format_dependency(d) for d in dependencies if pip is None or d.id not in pip]
        pip_deps = [PipEnvironment.format_dependency(d) for d in dependencies if pip is not None and d.id in pip]
        return CondaEnvironment(name=name,
                                channels=channels,
                                dependencies=deps,
                                pip_dependencies=pip_deps)

    @staticmethod
    def _format_dependency(d: Dependency) -> str:
        """Formats a dependency to a conda dependency string."""
        result : str = d.id
        if d.version is not None:
            result += '=' + d.version
            if d.sha is not None:
                result += '=' + d.sha
        return result

@dataclass(frozen=True)
class PipEnvironment:
    """Pip environment file definition."""

    @staticmethod
    def format_dependency(d: Dependency) -> str:
        """Formats a dependency to a conda dependency string."""
        result : str = d.id
        if d.version is not None:
            result += '==' + d.version
        return result

class Formatters(Enum):
    """The enumeration of the supported formatters."""
    PYLINT = _FormatterValue[_PylintConfiguration, Pylintrc](name='pylint',
                                                             to_environments=_pylint_mapper,
                                                             serialize=_pylint_writer,
                                                             configuration=_PylintConfiguration.from_configuration)

    def test(self, formatter: dict | str) -> bool:
        """Checks if a formatter configuration dict refers to the current Formatter value."""
        return (isinstance(formatter, str) and self.value.name == formatter
                or isinstance(formatter, dict) and self.value.name in formatter)

    def _get_formatter_configuration(self, configuration: Configuration):
        """Builds a specific formatter configuration from the main configuration related to the current Formatter value.
        """
        for formatter in configuration.formatters:
            if self.test(formatter):
                return self.value.configuration(formatter)
        raise ValueError

    def build(self, conf: Configuration):
        """Build the list of the environments using the given configuration."""
        frmtter_conf = self._get_formatter_configuration(conf)
        return self.value.to_environments(conf, frmtter_conf)

    def write(self, conf: Configuration, output_dir: Path):
        """Build the list of the environments using the given configuration and writes them to the given output folder.
        """
        frmtter_conf = self._get_formatter_configuration(conf)
        envs = self.value.to_environments(conf, frmtter_conf)
        return self.value.serialize(envs, frmtter_conf, output_dir)

@dataclass(frozen=True)
class Configuration:
    """Representation of pyenvs lint configuration content."""

    formatters: list[dict | str]
    """Each formatter either can be a single character string of one of supported formatters or a key/value pair with 
    the key referencing to the formatter name and the value referencing to its specific configuration."""

    environments: list[str] | None
    """A reference list of the environments referenced by dependencies. If the list is provided, dependencies 
    referencing an unknown environment raise an error. If the list is not provided, it is inferred from the dependency
    environments. If an empty list is provided, no dependency is supposed to reference any specific environment."""

    sections: list[Section]
    """The list of the sections."""

    @staticmethod
    def from_dict(source: dict):
        """Builds a Configuration from a configuration dict."""
        return Configuration(
            formatters=source['configuration']['formatters'],
            environments=source['environments'] if 'environments' in source else None,
            sections=[Section.from_dict(s) for s in source['sections']]
        )

    def strict_rules(self) -> list[Section]:
        """Returns only the strict rules which are ones not specifying any environment."""
        return [sr for sr in [s.strict_rules() for s in self.sections] if len(sr) > 0]

    def env_rules(self, environment: str) -> list[Section]:
        """Returns all the specified environment rules which are strict ones and ones referring to the given
        environment."""
        return [er for er in [s.environment_rules(environment=environment) for s in self.sections] if len(er) > 0]

    def _implicit_environments(self) -> list[str]:
        """Computes implicit environments which are ones contained in dependency environment lists."""
        return list(dict.fromkeys([e for s in self.sections if s.rules
                                   for r in s.rules if r.environments
                                   for e in r.environments]))

    def effective_environments(self) -> list[str]:
        """Checks environments and computes effective ones.

        1. Computes the effective environments.
        2. If a global environment list is provided, cheks its maps the implicit environment set.
        3. Returns the environment list if supplied, or default, the implicit environment list.
        """
        implicit_envs = self._implicit_environments()

        if self.environments is not None and set(self.environments) != set(implicit_envs):
            raise ValueError(
                f'if defined, environment list {self.environments} should match '
                f'the implicit environment dependency set {implicit_envs}')

        return implicit_envs if self.environments is None else self.environments

@dataclass(frozen=True)
class Rule:
    """Representation of pyenvs lint rule content."""
    key: str
    value: str
    environments: list[str] | None

    @staticmethod
    def from_dict(source: dict):
        """Builds a Rule from a configuration dict."""

        assert 'key' in source, 'key is a mandatory section field'
        assert 'value' in source, 'value is a mandatory section field'

        return Rule(
            key=source['key'],
            value=source['value'],
            environments=source['environments'] if 'environments' in source else None,
        )

@dataclass(frozen=True)
class Section:
    """Representation of pyenvs lint section content."""
    name: str
    rules: list[Rule]

    @staticmethod
    def from_dict(source: dict):
        """Builds a Section from a configuration dict."""

        assert 'name' in source, 'name is a mandatory section field'
        assert 'rules' in source, 'rules is a mandatory section field'

        return Section(
            name=source['name'],
            rules=[Rule.from_dict(s) for s in source['rules']],
        )

    def environment_rules(self, environment: str):
        """Get a new section containing only rules for the given environment."""
        return Section(name=self.name,
                       rules=[r for r in self.rules if not r.environments or environment in r.environments])

    def strict_rules(self):
        """Get a new section containing only the strict rules."""
        return Section(name=self.name,
                       rules=[r for r in self.rules if not r.environments])

    def __len__(self):
        return len(self.rules)

@dataclass(frozen=True)
class Pylintrc:
    """Pylint configuration file definition."""
    name: str
    sections: list[Section]

    def dump(self, path: Path, encoding: str):
        """Write to yml output file."""
        with open(path, 'w', encoding=encoding) as pylintrc:
            for l in self.format():
                pylintrc.write(l)

    @staticmethod
    def from_configuration(name: str, configuration: Configuration):
        """Build an environment from a standard configuration."""
        return Pylintrc.from_rules(name=name, sections=configuration.sections)

    @staticmethod
    def from_rules(name: str, sections: list[Section]):
        """Build an environment from a dependency list."""
        return Pylintrc(name=name, sections=sections)

    def format(self) -> list[str]:
        """Formats a dependency to a pylint section rule string list."""
        result = []
        for s in self.sections:
            result.append(f"[{s.name}]\n")
            result.extend([f"{r.key}={r.value}\n" for r in s.rules])
            result.append('\n')
        return result