pfund-kit 0.1.0__tar.gz

pfund_kit-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: pfund-kit
+Version: 0.1.0
+Summary: Configuration, CLI, and shared utilities for packages in pfund's ecosystem
+Author: Stephen Yau
+Author-email: Stephen Yau <softwareentrepreneer+pfund-kit@gmail.com>
+License-Expression: Apache-2.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: click>=8.2.1
+Requires-Dist: trogon>=0.6.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: tomlkit>=0.13.3
+Requires-Dist: packaging>=25.0
+Requires-Dist: platformdirs>=4.2.2
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: prompt-toolkit>=3.0.51
+Requires-Python: >=3.11
+Project-URL: homepage, https://pfund.ai
+Project-URL: repository, https://github.com/PFund-Software-Ltd/pfund-kit
+Description-Content-Type: text/markdown
+
+# pfund-kit
+Configuration, CLI, and shared utilities for packages in pfund's ecosystem

pfund_kit-0.1.0/README.md

@@ -0,0 +1,2 @@
+# pfund-kit
+Configuration, CLI, and shared utilities for packages in pfund's ecosystem

pfund_kit-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "pfund-kit"
+version = "0.1.0"
+description = "Configuration, CLI, and shared utilities for packages in pfund's ecosystem"
+license = "Apache-2.0"
+readme = "README.md"
+authors = [
+    { name = "Stephen Yau", email = "softwareentrepreneer+pfund-kit@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "rich>=14.2.0",
+    "tqdm>=4.67.1",
+    "click>=8.2.1",
+    "trogon>=0.6.0",
+    "pyyaml>=6.0.3",
+    "tomlkit>=0.13.3",
+    "packaging>=25.0",
+    "platformdirs>=4.2.2",
+    "python-dotenv>=1.2.1",
+    "prompt-toolkit>=3.0.51",
+]
+
+[project.scripts]
+pfund-shell = "pfund_kit.pfund_shell.main:start_shell"
+
+[project.urls]
+homepage = "https://pfund.ai"
+repository = "https://github.com/PFund-Software-Ltd/pfund-kit"
+# documentation = ""
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "pfund_kit"
+module-root = "src"

pfund_kit-0.1.0/src/pfund_kit/__init__.py

@@ -0,0 +1,5 @@
+from importlib.metadata import version
+
+
+__version__ = version("pfund-kit")
+# __all__ = ()

pfund_kit-0.1.0/src/pfund_kit/aliase.py

@@ -0,0 +1,283 @@
+# VIBE-CODED
+from __future__ import annotations
+
+from typing import Iterator
+
+
+class AliasRegistry:
+    """
+    Thread-safe bidirectional alias registry for mapping short aliases to canonical names.
+
+    Features:
+    - Bidirectional lookup (alias ↔ canonical)
+    - Case-sensitive or case-insensitive matching
+    - Conflict detection during initialization
+    - Immutable after initialization
+    - Dict-like interface for easy integration
+
+    Examples:
+        >>> registry = AliasRegistry({
+        ...     'YF': 'YAHOO_FINANCE',
+        ...     'FMP': 'FINANCIAL_MODELING_PREP',
+        ... })
+        >>> # Forward: alias → canonical
+        >>> registry.resolve('YF')
+        'YAHOO_FINANCE'
+        >>> registry.resolve('YAHOO_FINANCE')  # passthrough
+        'YAHOO_FINANCE'
+        >>>
+        >>> # Reverse: canonical → alias (two ways)
+        >>> registry('YAHOO_FINANCE')  # callable interface
+        'YF'
+        >>> registry.get_alias('YAHOO_FINANCE')  # explicit method
+        'YF'
+        >>>
+        >>> # Membership testing
+        >>> 'YF' in registry
+        True
+    """
+
+    def __init__(
+        self,
+        aliases: dict[str, str],
+        *,
+        case_sensitive: bool = True,
+        allow_conflicts: bool = False,
+    ):
+        """
+        Initialize the alias registry.
+
+        Args:
+            aliases: Dictionary mapping alias → canonical name
+            case_sensitive: If False, all lookups are case-insensitive
+            allow_conflicts: If False, raises ValueError when an alias conflicts
+                           with an existing canonical name
+
+        Raises:
+            ValueError: If conflicts detected and allow_conflicts=False
+        """
+        self._case_sensitive = case_sensitive
+        self._aliases: dict[str, str] = {}
+        self._reverse: dict[str, str] = {}
+
+        # Normalize keys if case-insensitive
+        self._normalize = (lambda x: x) if case_sensitive else (lambda x: x.lower())
+
+        # Validate and populate
+        for alias, canonical in aliases.items():
+            self._add_mapping(alias, canonical, allow_conflicts=allow_conflicts)
+
+    def _add_mapping(self, alias: str, canonical: str, allow_conflicts: bool = False) -> None:
+        """Add a single alias → canonical mapping with conflict detection."""
+        norm_alias = self._normalize(alias)
+        norm_canonical = self._normalize(canonical)
+
+        # Check for conflicts: alias colliding with another canonical name
+        if not allow_conflicts and norm_alias in self._reverse:
+            raise ValueError(
+                f"Conflict: alias '{alias}' collides with existing canonical name"
+            )
+
+        # Store normalized or original based on case sensitivity
+        key_alias = norm_alias if not self._case_sensitive else alias
+        key_canonical = norm_canonical if not self._case_sensitive else canonical
+
+        self._aliases[key_alias] = key_canonical
+        self._reverse[key_canonical] = key_alias
+
+    def resolve(self, name: str) -> str:
+        """
+        Resolve a name to its canonical form.
+
+        If the name is an alias, returns the canonical name.
+        If the name is already canonical (or unknown), returns it unchanged.
+
+        Args:
+            name: Alias or canonical name
+
+        Returns:
+            Canonical name
+
+        Examples:
+            >>> registry.resolve('YF')  # alias
+            'YAHOO_FINANCE'
+            >>> registry.resolve('YAHOO_FINANCE')  # already canonical
+            'YAHOO_FINANCE'
+            >>> registry.resolve('UNKNOWN')  # unknown, passthrough
+            'UNKNOWN'
+        """
+        norm_name = self._normalize(name)
+        return self._aliases.get(norm_name, name)
+
+    def get_alias(self, canonical: str) -> str | None:
+        """
+        Get the alias for a canonical name.
+
+        Args:
+            canonical: Canonical name
+
+        Returns:
+            Alias if exists, None otherwise
+
+        Examples:
+            >>> registry.get_alias('YAHOO_FINANCE')
+            'YF'
+            >>> registry.get_alias('UNKNOWN')
+            None
+        """
+        norm_canonical = self._normalize(canonical)
+        return self._reverse.get(norm_canonical)
+
+    def __call__(self, canonical: str) -> str | None:
+        """
+        Get the alias for a canonical name (callable interface).
+
+        This is a convenience method that calls get_alias() under the hood.
+        Provides a more intuitive API for reverse lookups.
+
+        Args:
+            canonical: Canonical name
+
+        Returns:
+            Alias if exists, None otherwise
+
+        Examples:
+            >>> registry = AliasRegistry({'YF': 'YAHOO_FINANCE'})
+            >>> registry('YAHOO_FINANCE')
+            'YF'
+            >>> registry('price')  # if no alias exists
+            None
+
+        Note:
+            For forward lookups (alias → canonical), use resolve() instead.
+        """
+        return self.get_alias(canonical)
+
+    def is_alias(self, name: str) -> bool:
+        """
+        Check if a name is an alias (not a canonical name).
+
+        Args:
+            name: Name to check
+
+        Returns:
+            True if name is an alias, False otherwise
+        """
+        norm_name = self._normalize(name)
+        return norm_name in self._aliases
+
+    def is_canonical(self, name: str) -> bool:
+        """
+        Check if a name is a canonical name.
+
+        Args:
+            name: Name to check
+
+        Returns:
+            True if name is a canonical name, False otherwise
+        """
+        norm_name = self._normalize(name)
+        return norm_name in self._reverse
+
+    def __contains__(self, name: str) -> bool:
+        """
+        Check if a name exists as either alias or canonical name.
+
+        Examples:
+            >>> 'YF' in registry
+            True
+            >>> 'YAHOO_FINANCE' in registry
+            True
+        """
+        norm_name = self._normalize(name)
+        return norm_name in self._aliases or norm_name in self._reverse
+
+    def __getitem__(self, alias: str) -> str:
+        """
+        Get canonical name for an alias (raises KeyError if not found).
+
+        Examples:
+            >>> registry['YF']
+            'YAHOO_FINANCE'
+
+        Raises:
+            KeyError: If alias not found
+        """
+        norm_alias = self._normalize(alias)
+        return self._aliases[norm_alias]
+
+    def get(self, alias: str, default: str | None = None) -> str | None:
+        """
+        Get canonical name for an alias with a default fallback.
+
+        Args:
+            alias: Alias to look up
+            default: Default value if alias not found
+
+        Returns:
+            Canonical name or default
+        """
+        norm_alias = self._normalize(alias)
+        return self._aliases.get(norm_alias, default)
+
+    def items(self) -> Iterator[tuple[str, str]]:
+        """
+        Iterate over (alias, canonical) pairs.
+
+        Examples:
+            >>> for alias, canonical in registry.items():
+            ...     print(f"{alias} -> {canonical}")
+        """
+        return iter(self._aliases.items())
+
+    def aliases(self) -> Iterator[str]:
+        """
+        Get all aliases.
+
+        Returns:
+            Iterator of alias names
+        """
+        return iter(self._aliases.keys())
+
+    def canonicals(self) -> Iterator[str]:
+        """
+        Get all canonical names.
+
+        Returns:
+            Iterator of canonical names
+        """
+        return iter(self._reverse.keys())
+
+    def to_dict(self) -> dict[str, str]:
+        """
+        Export as a plain dictionary (alias → canonical).
+
+        Returns:
+            Dictionary mapping aliases to canonical names
+        """
+        return dict(self._aliases)
+
+    def to_reverse_dict(self) -> dict[str, str]:
+        """
+        Export as a reverse dictionary (canonical → alias).
+
+        Returns:
+            Dictionary mapping canonical names to aliases
+        """
+        return dict(self._reverse)
+
+    def __len__(self) -> int:
+        """Return number of alias mappings."""
+        return len(self._aliases)
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return f"AliasRegistry({self._aliases!r})"
+
+    def __str__(self) -> str:
+        """Return human-readable string."""
+        items = [f"  {a!r} -> {c!r}" for a, c in self._aliases.items()]
+        return f"AliasRegistry({len(self)} mappings):\n" + "\n".join(items)
+
+
+__all__ = ['AliasRegistry']

pfund_kit-0.1.0/src/pfund_kit/cli/__init__.py

@@ -0,0 +1,4 @@
+from pfund_kit.cli.main import create_cli_group
+
+
+__all__ = ['create_cli_group']

pfund_kit-0.1.0/src/pfund_kit/cli/commands/__init__.py

@@ -0,0 +1,12 @@
+from pfund_kit.cli.commands.config import config
+from pfund_kit.cli.commands.docker_compose import docker_compose
+from pfund_kit.cli.commands.remove import remove
+from pfund_kit.cli.commands.doc import doc
+
+
+__all__ = [
+    'config',
+    'docker_compose',
+    'remove',
+    'doc',
+]

pfund_kit-0.1.0/src/pfund_kit/cli/commands/config.py

@@ -0,0 +1,239 @@
+import shutil
+from pathlib import Path
+
+import click
+
+
+def auto_detect_editor():
+    """Auto-detect an available code editor from popular choices."""
+    import shutil
+
+    # List of popular editors in order of preference
+    editors = ['cursor', 'code', 'zed', 'charm', 'nvim']
+
+    for cmd in editors:
+        if shutil.which(cmd):
+            return cmd
+    return None
+
+
+def open_file_with_editor(file_path: Path, editor_cmd: str):
+    """Open file with the specified editor, handling edge cases like Cursor's space bug."""
+    import subprocess
+    import platform
+
+    file_path_str = str(file_path)
+
+    try:
+        # Cursor CLI has a bug with spaces in paths, use shell mode with quotes
+        if editor_cmd == 'cursor':
+            if platform.system() != 'Windows':
+                # On macOS/Linux: escape spaces with backslashes AND wrap in quotes
+                escaped_path = file_path_str.replace(' ', r'\ ')
+                subprocess.run(f'{editor_cmd} "{escaped_path}"', shell=True, check=True)
+            else:
+                # On Windows: use quotes (standard Windows shell escaping)
+                # Note: If this doesn't work, Windows may have the same bug
+                subprocess.run(f'{editor_cmd} "{file_path_str}"', shell=True, check=True)
+        else:
+            # All other editors: use standard subprocess list approach (safest)
+            subprocess.run([editor_cmd, file_path_str], check=True)
+    except FileNotFoundError:
+        click.echo(f"Error: Editor '{editor_cmd}' not found. Please check if it's installed and in your PATH.", err=True)
+        raise
+    except subprocess.CalledProcessError as e:
+        click.echo(f"Error: Failed to open file with '{editor_cmd}': {e}", err=True)
+        raise
+
+
+@click.group()
+def config():
+    """Manage configuration settings."""
+    pass
+
+
+@config.command()
+@click.pass_context
+def where(ctx):
+    """Print the config path."""
+    config = ctx.obj['config']
+    click.echo(config.path)
+
+    
+    
+@config.command('list')
+@click.pass_context
+def list_config(ctx):
+    """Print the config file."""
+    from pprint import pformat
+    config = ctx.obj['config']
+    config_dict = config.to_dict()
+    content = click.style(pformat(config_dict), fg='green')
+    click.echo(f"File: {config.file_path}\n{content}")
+
+
+@config.command('open')
+@click.pass_context
+@click.option('--config-file', '--config', '-c', is_flag=True, help='Open the config file')
+@click.option('--docker-file', '--docker', '-d', is_flag=True, help='Open the compose.yml file')
+@click.option('--logging-file', '--logging', '-l', is_flag=True, help='Open the logging.yml file')
+@click.option('--default-editor', '-e', is_flag=True, help='Use system default editor ($VISUAL or $EDITOR)')
+@click.argument('editor', required=False)
+def open_config(ctx, config_file, logging_file, docker_file, default_editor, editor):
+    """Opens the config files, e.g. logging.yml, docker-compose.yml.
+
+    EDITOR is the optional editor command to use (e.g., "code", "vim", "subl").
+    If not specified, prints the file path.
+
+    Examples:
+        pfeed config open -l code         # Open logging file in VS Code
+        pfeed config open -c vim          # Open config file in vim
+        pfeed config open -d -E           # Open docker file in default editor
+        pfeed config open -l              # Just print the logging file path
+    """
+    import subprocess
+
+    config = ctx.obj['config']
+    paths = config._paths
+    project_name = paths.project_name
+
+    if sum([config_file, logging_file, docker_file]) > 1:
+        click.echo('Please specify only one file to open')
+        return
+
+    # Determine which file to open
+    if config_file:
+        file_path = config.file_path
+    elif logging_file:
+        file_path = config.logging_config_file_path
+    elif docker_file:
+        file_path = config.docker_compose_file_path
+    else:
+        click.echo(f'Please specify a file to open, run "{project_name} config open --help" for more info')
+        return
+    
+    # Handle opening the file
+    if default_editor:
+        # Use Click's built-in editor (respects $VISUAL/$EDITOR)
+        click.edit(filename=str(file_path))
+    else:
+        # Auto-detect editor if not specified
+        editor = editor or auto_detect_editor()
+
+        if editor:
+            try:
+                open_file_with_editor(file_path, editor)
+                # Get display name for the editor
+                editor_names = {
+                    'cursor': 'Cursor',
+                    'code': 'VS Code',
+                    'zed': 'Zed',
+                    'charm': 'PyCharm',
+                    'nvim': 'Neovim',
+                }
+                display_name = editor_names.get(editor, editor)
+                click.echo(f"Opened {project_name}'s {file_path.name} with {display_name}")
+            except (FileNotFoundError, subprocess.CalledProcessError):
+                pass  # Error already printed by open_file_with_editor
+        else:
+            # No editor found, print helpful message
+            click.echo("No code editor detected.", err=True)
+            click.echo(f"Tip: Specify an editor (e.g., '{project_name} config open -l code' to use VS Code) or use -E for system default editor", err=True)
+            click.echo(f"\nFile location: {file_path}")
+
+
+@config.command('set')
+@click.pass_context
+@click.option('--data-path', '--data', type=click.Path(resolve_path=True), help='Set the data path')
+@click.option('--log-path', '--log', type=click.Path(resolve_path=True), help='Set the log path')
+@click.option('--cache-path', '--cache', type=click.Path(resolve_path=True), help='Set the cache path')
+def set_config(ctx, data_path, log_path, cache_path):
+    """Update configuration paths.
+
+    Examples:
+        pfeed config set --data /path/to/data
+        pfeed config set --log /var/log/pfeed --cache /tmp/cache
+    """
+    config = ctx.obj['config']
+
+    # Check if at least one option is provided
+    if not any([data_path, log_path, cache_path]):
+        click.echo("Error: Please specify at least one path to update.", err=True)
+        click.echo("Run 'config set --help' for usage information.")
+        return
+
+    # Update configuration and track changes
+    updated = []
+    if data_path:
+        config.data_path = data_path
+        updated.append(f"data_path -> {data_path}")
+    if log_path:
+        config.log_path = log_path
+        updated.append(f"log_path -> {log_path}")
+    if cache_path:
+        config.cache_path = cache_path
+        updated.append(f"cache_path -> {cache_path}")
+
+    config.save()
+    click.echo(f"Updated {config.filename}:")
+    for change in updated:
+        click.echo(f"  {change}")
+
+
+@config.command()
+@click.pass_context
+@click.option('--config-file', '--config', '-c', is_flag=True, help='Reset the config file')
+@click.option('--logging-file', '--logging', '-l', is_flag=True, help='Reset the logging.yaml file')
+@click.option('--docker-file', '--docker', '-d', is_flag=True, help='Reset the compose.yml file')
+def reset(ctx, config_file, logging_file, docker_file):
+    """Reset the configuration to defaults.
+    If no flags were set, all files will be reset.
+    Args:
+        config_file: Reset the config file
+        docker_file: Reset the compose.yml file
+        logging_file: Reset the logging.yaml file for logging config
+    """
+    config = ctx.obj['config']
+    
+    # If no flags were set, set all to True
+    if not any([config_file, logging_file, docker_file]):
+        config_file = logging_file = docker_file = True
+    
+    paths = config._paths
+    project_name = paths.project_name
+    
+    def _reset_file(filename):
+        default_file = paths.package_path / filename
+        if not default_file.exists() and paths.project_root:
+            default_file = paths.project_root / filename
+        
+        user_file = config.path / filename
+        backup_file = config.path / f'{filename}.bak'
+
+        # Backup existing user file if it exists
+        if user_file.exists():
+            shutil.copy(user_file, backup_file)
+            click.echo(f"  Backed up the existing file {user_file.name} to {backup_file.name}")
+
+        # Copy default file to user location
+        if default_file.exists():
+            shutil.copy(default_file, user_file)
+            click.echo(f"  Restored from default file {default_file.name}")
+        else:
+            click.echo(f"  Warning: Default file {default_file.name} not found, skipping", err=True)
+
+    if config_file:
+        filename = config.filename
+        click.echo(f"Resetting {project_name}'s {filename}...")
+        _reset_file(filename)
+
+    if logging_file:
+        filename = config.LOGGING_CONFIG_FILENAME
+        click.echo(f"Resetting {project_name}'s {filename}...")
+        _reset_file(filename)
+
+    if docker_file:
+        filename = config.DOCKER_COMPOSE_FILENAME
+        click.echo(f"Resetting {project_name}'s {filename}...")
+        _reset_file(filename)
+

pfund_kit-0.1.0/src/pfund_kit/cli/commands/doc.py

@@ -0,0 +1,65 @@
+# FIXME: fix it when pfund/pfeed has finished the docs
+
+import subprocess
+import webbrowser
+
+import click
+
+
+# FIXME
+PFEED_DOCS_URL = 'https://pfeed-docs.pfund.ai'
+
+
+def _execute_notebooks(docs_path: str):
+    """Clear outputs and execute notebooks"""
+    find_ipynb_cmd = ["find", docs_path, "-path", f"{docs_path}/_build", "-prune", "-o", "-name", "*.ipynb", "-print"]
+    clear_output_cmd = ["-exec", "jupyter", "nbconvert", "--ClearOutputPreprocessor.enabled=True", "--inplace", "{}", ";"]
+    execute_cmd = ["-exec", "jupyter", "nbconvert", "--execute", "--inplace", "{}", ";"]
+    try:
+        subprocess.run(find_ipynb_cmd + clear_output_cmd, cwd=docs_path, check=True)
+        click.echo("Notebook outputs cleared successfully.")
+        subprocess.run(find_ipynb_cmd + execute_cmd, cwd=docs_path, check=True)
+        click.echo("Notebooks executed successfully.")
+    except subprocess.CalledProcessError as e:
+        click.echo(f"Error executing notebooks: {e}", err=True)
+        raise e
+
+
+@click.command()
+@click.option('--build', is_flag=True, is_eager=True, help='Build the docs')
+@click.option('--start', is_flag=True, is_eager=True, help='Start the docs server')
+@click.option('--execute', is_flag=True, help='If True, execute jupyter notebooks')
+def doc(build, start, execute):
+    if build and start:
+        raise click.UsageError("You can only specify either --build or --start, not both.")
+    elif not build and not start:
+        if execute:
+            raise click.UsageError("You must specify either --build or --start.")
+        else:
+            webbrowser.open(PFEED_DOCS_URL)
+            return
+            
+    docs_path = str(MAIN_PATH / 'docs')
+    
+    try:    
+        if build:
+            clean_cmd = ["myst", "clean", "--all", "--yes"]
+            subprocess.run(clean_cmd, cwd=docs_path, check=True)
+            click.echo("Docs cleaned successfully.")
+            
+            build_cmd = ["myst", "build", "--html"]
+            if execute:
+                _execute_notebooks(docs_path)
+            subprocess.run(build_cmd, cwd=docs_path, check=True)
+            click.echo("Docs built successfully.")
+            return
+        
+        if start:
+            start_cmd = ["myst", "start"]
+            if execute:
+                _execute_notebooks(docs_path)
+            subprocess.run(start_cmd, cwd=docs_path, check=True)
+            return
+    except subprocess.CalledProcessError as e:
+        click.echo(f"Error using myst: {e}", err=True)
+        raise e