porringer 0.1.0__tar.gz

porringer-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Synodic Software
+
+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.

porringer-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.1
+Name: porringer
+Version: 0.1.0
+Author-Email: Synodic Software <contact@synodic.software>
+License: MIT
+Project-URL: homepage, https://github.com/Synodic-Software/Porringer
+Project-URL: repository, https://github.com/Synodic-Software/Porringer
+Requires-Python: >=3.13
+Requires-Dist: typer[all]>=0.15.2
+Requires-Dist: pydantic>=2.11.3
+Requires-Dist: platformdirs>=4.3.7
+Requires-Dist: userpath>=1.9.2
+Requires-Dist: packaging>=24.2
+Description-Content-Type: text/markdown
+
+# Porringer

porringer-0.1.0/README.md

@@ -0,0 +1 @@
+# Porringer

porringer-0.1.0/porringer/__init__.py

@@ -0,0 +1,5 @@
+"""Porringer package.
+
+This package provides the core functionality for the Porringer application,
+including API definitions, backend processing, console commands, and utility functions.
+"""

porringer-0.1.0/porringer/api.py

@@ -0,0 +1,21 @@
+"""API for Porringer"""
+
+from porringer.backend.command.plugin import PluginCommands
+from porringer.backend.command.self import SelfCommands
+from porringer.backend.resolver import resolve_configuration
+from porringer.backend.schema import Configuration, GlobalConfiguration
+from porringer.schema import (
+    APIParameters,
+    LocalConfiguration,
+)
+
+
+class API:
+    """_summary_"""
+
+    def __init__(self, local_configuration: LocalConfiguration, parameters: APIParameters) -> None:
+        """Initializes the API"""
+        self.configuration: Configuration = resolve_configuration(local_configuration, GlobalConfiguration())
+        self.parameters = parameters
+        self.plugin = PluginCommands(self.parameters.logger)
+        self.porringer = SelfCommands(self.parameters.logger)

porringer-0.1.0/porringer/backend/__init__.py

@@ -0,0 +1,5 @@
+"""Backend package for Porringer.
+
+This package contains modules and utilities for backend processing,
+including configuration resolution, plugin management, and command execution.
+"""

porringer-0.1.0/porringer/backend/builder.py

@@ -0,0 +1,92 @@
+"""Builder"""
+
+from importlib import metadata
+from inspect import getmodule
+from logging import Logger
+
+from packaging.version import Version
+
+from porringer.core.plugin_schema.environment import Environment
+from porringer.core.schema import Distribution, PluginParameters
+from porringer.schema import PluginInformation
+from porringer.utility.exception import PluginError
+from porringer.utility.utility import canonicalize_type
+
+
+class Builder:
+    """Helper class for building Porringer projects"""
+
+    def __init__(self, logger: Logger) -> None:
+        """Initializes the builder"""
+        self.logger = logger
+
+    def find_environments(self) -> list[PluginInformation[Environment]]:
+        """Searches for registered environment plugins
+
+        Raises:
+            PluginError: Raised if there is no plugin found
+
+        Returns:
+            A list of loaded plugins
+        """
+        group_name = 'environment'
+        plugin_types: list[PluginInformation[Environment]] = []
+
+        # Filter entries by type
+        for entry_point in list(metadata.entry_points(group=f'porringer.{group_name}')):
+            loaded_type = entry_point.load()
+
+            canonicalized = canonicalize_type(loaded_type)
+
+            if entry_point.dist is None:
+                self.logger.error(f"Plugin '{canonicalized.name}' is not installed. Skipping")
+                continue
+
+            # TODO: Add metadata to plugin information, percolate to pytest_synodic API
+
+            if not issubclass(loaded_type, Environment):
+                self.logger.warning(
+                    f"Found incompatible plugin. The '{canonicalized.name}' plugin must be an instance"
+                    f" of '{group_name}'"
+                )
+            else:
+                self.logger.warning(f'{group_name} plugin found: {canonicalized.name} from {getmodule(loaded_type)}')
+                plugin_types.append(PluginInformation(loaded_type, entry_point.dist))
+
+        if not plugin_types:
+            raise PluginError(f'No {group_name} plugin was found')
+
+        return plugin_types
+
+    @staticmethod
+    def build_environment(environment_type: PluginInformation[Environment]) -> Environment:
+        """Constructs a single environment from input type
+
+        Args:
+            environment_type: The type to construct
+
+        Returns:
+            The instantiated environment
+        """
+        pluginVersion = Version(environment_type.distribution.version)
+        pluginDistribution = Distribution(version=pluginVersion)
+        parameters = PluginParameters(distribution=pluginDistribution)
+
+        return environment_type.type(parameters)
+
+    @staticmethod
+    def build_environments(environment_types: list[PluginInformation[Environment]]) -> list[Environment]:
+        """Constructs environments from input types
+
+        Args:
+            environment_types: The types to construct
+
+        Returns:
+            The instantiated environments
+        """
+        environments: list[Environment] = []
+
+        for environment_type in environment_types:
+            environments.append(Builder.build_environment(environment_type))
+
+        return environments

porringer-0.1.0/porringer/backend/command/__init__.py

@@ -0,0 +1,5 @@
+"""Command package for Porringer backend.
+
+This package contains command modules for backend operations,
+including plugin management and self-update functionalities.
+"""

porringer-0.1.0/porringer/backend/command/plugin.py

@@ -0,0 +1,62 @@
+"""The plugin command module."""
+
+from logging import Logger
+
+from porringer.backend.builder import Builder
+from porringer.backend.resolver import resolve_list_plugins_parameters
+from porringer.schema import ListPluginResults, ListPluginsParameters
+
+
+class PluginCommands:
+    """Plugin commands"""
+
+    def __init__(self, logger: Logger) -> None:
+        """Initialize the SelfCommands class.
+
+        Args:
+            logger (Logger): Logger instance for logging actions.
+        """
+        self.logger = logger
+
+    def list(self, parameters: ListPluginsParameters) -> list[ListPluginResults]:
+        """Lists the plugins.
+
+        Args:
+            parameters: The list command parameters.
+
+        Returns:
+            A list of registered plugins.
+        """
+        self.logger.info('Listing plugins')
+
+        builder = Builder(self.logger)
+
+        environment_types = builder.find_environments()
+
+        environments = builder.build_environments(environment_types)
+
+        return resolve_list_plugins_parameters(environments)
+
+    def install(self, logger: Logger) -> None:
+        """Install a plugin"""
+        logger.info('Installing plugin')
+
+        builder = Builder(logger)
+
+        environment_types = builder.find_environments()
+
+    def uninstall(self, logger: Logger) -> None:
+        """Remove an installed plugin"""
+        logger.info('Uninstalling plugin')
+
+        builder = Builder(logger)
+
+        environment_types = builder.find_environments()
+
+    def update(self, logger: Logger) -> None:
+        """Updates the plugins.
+
+        Args:
+            logger: The logger.
+        """
+        logger.info('Updating plugins')

porringer-0.1.0/porringer/backend/command/self.py

@@ -0,0 +1,48 @@
+"""Utilities for managing and checking the Porringer installation version."""
+
+import os
+import subprocess
+import sys
+from logging import Logger
+
+
+class SelfCommands:
+    """Commands related to the Porringer installation."""
+
+    def __init__(self, logger: Logger) -> None:
+        """Initialize the SelfCommands class.
+
+        Args:
+            logger: Logger instance for logging actions.
+        """
+        self.logger = logger
+
+    def is_pipx_installation(self) -> bool:
+        """Check if Porringer is installed via pipx.
+
+        Returns:
+            bool: True if the current Python environment is a pipx-managed venv, False otherwise.
+        """
+        return sys.prefix.split(os.sep)[-3:-1] == ['pipx', 'venvs']
+
+    def update(self) -> None:
+        """Upgrade the Porringer package using pipx if installed via pipx.
+
+        Raises:
+            NotImplementedError: If Porringer is not installed via pipx.
+        """
+        if self.is_pipx_installation():
+            subprocess.run(['pipx', 'upgrade', 'porringer'], check=True)
+        else:
+            raise NotImplementedError()
+
+    def check(self) -> None:
+        """Check for updates to the Porringer package using pipx if installed via pipx.
+
+        Raises:
+            NotImplementedError: If Porringer is not installed via pipx.
+        """
+        if self.is_pipx_installation():
+            subprocess.run(['pipx', 'upgrade', 'porringer'], check=True)
+        else:
+            raise NotImplementedError()

porringer-0.1.0/porringer/backend/command/version.py

@@ -0,0 +1 @@
+"""Version utilities"""

porringer-0.1.0/porringer/backend/resolver.py

@@ -0,0 +1,50 @@
+"""Resolves"""
+
+from porringer.backend.schema import Configuration, GlobalConfiguration
+from porringer.core.plugin_schema.environment import Environment
+from porringer.schema import ListPluginResults, LocalConfiguration
+from porringer.utility.utility import canonicalize_type
+
+
+def resolve_configuration(
+    local_configuration: LocalConfiguration, global_configuration: GlobalConfiguration
+) -> Configuration:
+    """Resolves the configuration.
+
+    Args:
+        local_configuration: The local configuration.
+        global_configuration: The global configuration.
+
+    Returns:
+        The resolved configuration.
+    """
+    local_configuration.cache_directory.mkdir(parents=True, exist_ok=True)
+
+    global_configuration.config_directory.mkdir(parents=True, exist_ok=True)
+    global_configuration.data_directory.mkdir(parents=True, exist_ok=True)
+
+    return Configuration(
+        cache_directory=local_configuration.cache_directory,
+        config_directory=global_configuration.config_directory,
+        data_directory=global_configuration.data_directory,
+    )
+
+
+def resolve_list_plugins_parameters(environment: list[Environment]) -> list[ListPluginResults]:
+    """Resolves the list plugins parameters.
+
+    Args:
+        environment: The environment.
+
+    Returns:
+        A list of plugin metadata.
+    """
+    plugin_metadata: list[ListPluginResults] = []
+
+    for plugin in environment:
+        canonicalized = canonicalize_type(type(plugin))
+
+        resolved_metadata = ListPluginResults(canonicalized.name, plugin.distribution.version, False)
+        plugin_metadata.append(resolved_metadata)
+
+    return plugin_metadata

porringer-0.1.0/porringer/backend/schema.py

@@ -0,0 +1,28 @@
+"""Backend schema"""
+
+from pathlib import Path
+
+from platformdirs import user_config_dir, user_data_dir
+from pydantic import BaseModel, DirectoryPath, Field
+
+
+class GlobalConfiguration(BaseModel):
+    """Global configuration that Porringer manages"""
+
+    config_directory: Path = Field(
+        default=Path(user_config_dir('porringer', 'synodic')),
+        description='The configuration directory',
+    )
+
+    data_directory: Path = Field(
+        default=Path(user_data_dir('porringer', 'synodic')),
+        description='The data directory',
+    )
+
+
+class Configuration(BaseModel):
+    """Resolved configuration"""
+
+    cache_directory: DirectoryPath
+    config_directory: DirectoryPath
+    data_directory: DirectoryPath

porringer-0.1.0/porringer/console/__init__.py

@@ -0,0 +1,5 @@
+"""Console package for Porringer.
+
+This package contains modules and utilities for the command-line interface,
+including command definitions and configuration management.
+"""

porringer-0.1.0/porringer/console/command/__init__.py

@@ -0,0 +1 @@
+"""Commands for the Porringer console application."""

porringer-0.1.0/porringer/console/command/plugin.py

@@ -0,0 +1,66 @@
+"""Porringer CLI plugin command module"""
+
+import logging
+from typing import Annotated
+
+import typer
+
+from porringer.api import API
+from porringer.console.schema import Configuration
+from porringer.schema import APIParameters, ListPluginsParameters
+
+app = typer.Typer()
+
+
+@app.command('list')
+def plugin_list(
+    context: typer.Context,
+) -> None:
+    """Lists available plugins
+
+    Args:
+        context: The click context
+    """
+    configuration = context.ensure_object(Configuration)
+
+    api_parameters = APIParameters(logging.getLogger('porringer'))
+    api = API(configuration.local_configuration, api_parameters)
+
+    list_parameters = ListPluginsParameters()
+    results = api.plugin.list(list_parameters)
+
+    for result in results:
+        configuration.console.print(result)
+
+
+@app.command('install')
+def plugin_install(
+    context: typer.Context, plugins: Annotated[list[str], typer.Argument(help='Plugins to install')]
+) -> None:
+    """Install plugins"""
+    for plugin in plugins:
+        pass
+
+
+@app.command('update')
+def plugin_update(
+    context: typer.Context, plugins: Annotated[list[str], typer.Argument(help='Plugins to update')]
+) -> None:
+    """Update plugins"""
+    for plugin in plugins:
+        pass
+
+
+@app.command('uninstall')
+def plugin_uninstall(
+    context: typer.Context, plugins: Annotated[list[str], typer.Argument(help='Plugins to remove')]
+) -> None:
+    """Remove installed plugins"""
+    for plugin in plugins:
+        pass
+
+
+@app.callback(invoke_without_command=True, no_args_is_help=True)
+def application() -> None:
+    """Plugin management and operations"""
+    pass

porringer-0.1.0/porringer/console/command/self.py

@@ -0,0 +1,29 @@
+"""Porringer CLI self command module."""
+
+import typer
+
+app = typer.Typer()
+
+
+@app.command('update')
+def self_update() -> None:
+    """Updates the Porringer application.
+
+    Raises:
+        NotImplementedError: This functionality is not yet implemented.
+    """
+
+
+@app.command('check')
+def self_check() -> None:
+    """Checks for updates to the Porringer application.
+
+    Raises:
+        NotImplementedError: This functionality is not yet implemented.
+    """
+
+
+@app.callback(invoke_without_command=True, no_args_is_help=True)
+def application() -> None:
+    """Management of the Porringer instance running the CLI application."""
+    pass

porringer-0.1.0/porringer/console/entry.py

@@ -0,0 +1,68 @@
+"""Typer CLI Application"""
+
+import logging
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from porringer.console.command.plugin import app as plugin_app
+from porringer.console.command.self import app as self_app
+from porringer.console.schema import LOG_LEVELS, MAX_VERBOSITY_LEVEL, Configuration
+
+# TODO: Hook up version to the version in pyproject.toml
+__version__ = '0.1.0'
+
+app = typer.Typer()
+app.add_typer(plugin_app, name='plugin')
+app.add_typer(self_app, name='self')
+
+
+class TyperHandler(logging.Handler):
+    """A logging handler that outputs to typer"""
+
+    def __init__(self, console: Console) -> None:
+        """Initializes the handler"""
+        logging.Handler.__init__(self)
+
+        self.console = console
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emits the log record to typer"""
+        level = next(level for level in LOG_LEVELS if level.name == record.levelname)
+        self.console.print(record, style=level.colour)
+
+
+def version_callback(value: bool) -> None:
+    """Callback for the version option"""
+    if value:
+        print(f'Awesome CLI Version: {__version__}')
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True, no_args_is_help=True)
+def application(
+    context: typer.Context,
+    verbose: Annotated[int, typer.Option('--verbose', '-v', count=True, help='', min=0, max=MAX_VERBOSITY_LEVEL)] = 0,
+    debug: Annotated[bool, typer.Option('--debug', help='')] = False,
+    version: Annotated[
+        bool | None,
+        typer.Option('--version', callback=version_callback, is_eager=True),
+    ] = None,
+) -> None:
+    """A tool for automatic facilitation of program updates and package managers.
+
+    Args:
+        context: The click context object
+        verbose: The input verbosity level
+        debug: The debug flag
+        version: The version request
+    """
+    configuration = context.ensure_object(Configuration)
+
+    configuration.debug = debug
+    configuration.verbosity = verbose
+
+    logger = logging.getLogger('porringer')
+    handler = TyperHandler(configuration.console)
+    logger.addHandler(handler)

porringer-0.1.0/porringer/console/schema.py

@@ -0,0 +1,38 @@
+"""Data schemas for console commands"""
+
+from dataclasses import dataclass
+from typing import LiteralString
+
+from pydantic import BaseModel, ConfigDict
+from rich.console import Console
+
+from porringer.schema import LocalConfiguration
+
+MAX_VERBOSITY_LEVEL = 3
+
+
+@dataclass
+class LogLevel:
+    """Log level metadata"""
+
+    name: LiteralString
+    colour: str
+
+
+LOG_LEVELS: list[LogLevel] = [
+    LogLevel(name='ERROR', colour='red'),
+    LogLevel(name='WARNING', colour='yellow'),
+    LogLevel(name='INFO', colour='white'),
+    LogLevel(name='DEBUG', colour='bright_white'),
+]
+
+
+class Configuration(BaseModel):
+    """Configuration object for the CLI"""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    console: Console = Console()
+    local_configuration: LocalConfiguration = LocalConfiguration()
+    debug: bool = False
+    verbosity: int = 0

porringer-0.1.0/porringer/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core package for Porringer.
+
+This package contains the core schemas and base classes used throughout the Porringer application,
+including plugin definitions and shared data models.
+"""

porringer-0.1.0/porringer/core/plugin_schema/__init__.py

@@ -0,0 +1,5 @@
+"""Plugin schema package for Porringer.
+
+This package contains the schema definitions and base classes for plugins,
+including environment plugins and their parameters.
+"""