ghoshell-common 0.4.0.dev0__tar.gz → 0.4.0.dev1__tar.gz

{ghoshell_common-0.4.0.dev0 → ghoshell_common-0.4.0.dev1}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.1
 Name: ghoshell-common
-Version: 0.4.0.dev0
+Version: 0.4.0.dev1
 Summary: common library for GhostInShells project
 Author-Email: thirdgerb <thirdgerb@gmail.com>
 License: MIT
 Requires-Python: >=3.10
+Requires-Dist: click>=8.3.0
 Requires-Dist: ghoshell-container>=0.3.0.dev1
 Requires-Dist: pydantic<3.0.0,>=2.7.0
 Requires-Dist: pyyaml<7.0.0,>=6.0.1

{ghoshell_common-0.4.0.dev0 → ghoshell_common-0.4.0.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ghoshell-common"
-version = "0.4.0-dev"
+version = "0.4.0-dev1"
 description = "common library for GhostInShells project"
 authors = [
     { name = "thirdgerb", email = "thirdgerb@gmail.com" },
@@ -8,6 +8,7 @@ authors = [
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
+    "click>=8.3.0",
     "ghoshell-container>=0.3.0.dev1",
     "pydantic<3.0.0,>=2.7.0",
     "pyyaml<7.0.0,>=6.0.1",

ghoshell_common-0.4.0.dev1/src/ghoshell_common/cli/main.py

@@ -0,0 +1,34 @@
+import click
+import sys
+
+
+@click.group()
+def main():
+    """
+    ghoshell cli main group
+    """
+    pass
+
+
+@main.command("help")
+def main_help():
+    """Print this help message."""
+    _get_command_line_as_string()
+
+    assert len(sys.argv) == 2  # This is always true, but let's assert anyway.
+    # Pretend user typed 'streamlit --help' instead of 'streamlit help'.
+    sys.argv[1] = "--help"
+    main(prog_name="main")
+
+
+def _get_command_line_as_string() -> str | None:
+    """Print this help message."""
+    import sys
+    import subprocess
+    parent = click.get_current_context().parent
+    if parent is None:
+        return None
+
+    cmd_line_as_list = [parent.command_path]
+    cmd_line_as_list.extend(sys.argv[1:])
+    return subprocess.list2cmdline(cmd_line_as_list)

ghoshell_common-0.4.0.dev1/src/ghoshell_common/contracts/__init__.py

@@ -0,0 +1,41 @@
+from ghoshell_common.contracts.storage import (
+    Storage, FileStorage,
+    FileStorageProvider,
+    DefaultFileStorage,
+)
+
+from ghoshell_common.contracts.workspace import (
+    Workspace,
+    LocalWorkspaceProvider,
+    LocalWorkspace,
+)
+
+from ghoshell_common.contracts.configs import (
+    ConfigType, Configs,
+    YamlConfig,
+    DefaultConfigs,
+    WorkspaceConfigs, WorkspaceConfigsProvider
+)
+
+from ghoshell_common.contracts.logger import (
+    LoggerItf,
+    LoggerProvider, WorkspaceLoggerProvider,
+    get_console_logger, config_logger_from_yaml,
+)
+
+from ghoshell_common.contracts.assets import (
+    FileAsset, FileAssetRepo,
+    ImageAssetRepo, AudioAssetRepo,
+    WorkspaceAssetsRepoProvider,
+)
+
+
+def workspace_providers(workspace_dir: str = "", stub_dir: str | None = None):
+    """
+    default providers.
+    """
+    yield LocalWorkspaceProvider(workspace_dir, stub_dir)
+    yield WorkspaceConfigsProvider()
+    yield WorkspaceLoggerProvider("ghoshell")
+    yield WorkspaceAssetsRepoProvider(ImageAssetRepo, "images")
+    yield WorkspaceAssetsRepoProvider(AudioAssetRepo, "audio")

ghoshell_common-0.4.0.dev1/src/ghoshell_common/contracts/assets.py

@@ -0,0 +1,162 @@
+from abc import ABC, abstractmethod
+from typing import Optional, Tuple, Union, Type
+from mimetypes import guess_type
+from pydantic import BaseModel, Field
+from ghoshell_common.contracts.storage import Storage
+from ghoshell_common.helpers import uuid, yaml_pretty_dump
+from ghoshell_container import Provider, IoCContainer
+import yaml
+
+__all__ = [
+    'FileAsset', 'FileAssetRepo',
+    'AudioAssetRepo', 'ImageAssetRepo',
+    'StorageFileAssetRepo',
+    'WorkspaceAssetsRepoProvider',
+]
+
+
+class FileAsset(BaseModel):
+    fileid: str = Field(default_factory=uuid, description="ID of the file.")
+    filename: str = Field(description="The file name of the file.")
+    description: str = Field(default="", description="The description of the file.")
+    filetype: str = Field(default="", description="The file type of the file.")
+    summary: str = Field(default="", description="The text summary of the file.")
+    url: Optional[str] = Field(default=None, description="The URL of the file.")
+
+    def get_format(self) -> str:
+        return self.filetype.split("/")[-1]
+
+
+class FileAssetRepo(ABC):
+
+    @classmethod
+    def new_fileinfo(
+            cls,
+            fileid: str,
+            filename: str,
+            description: str = "",
+            filetype: Optional[str] = None,
+    ) -> FileAsset:
+        if filetype is None:
+            filetype, _ = guess_type(filename)
+        fileinfo = FileAsset(
+            fileid=fileid,
+            filename=filename,
+            description=description,
+            filetype=filetype,
+        )
+        return fileinfo
+
+    @abstractmethod
+    def save(self, file: FileAsset, binary: Optional[bytes]) -> str:
+        """
+        save file info and binary data to storage
+        :param file: the file info
+        :param binary: binary data of the file. if None, the url must be provided
+        :return: relative file path of the saved file
+        """
+        pass
+
+    @abstractmethod
+    def get_binary(self, filename: str) -> Optional[bytes]:
+        """
+        get binary data of the file
+        :param filename: the relative filename of the file
+        :return: binary data of the file, None if binary data is not available
+        """
+        pass
+
+    @abstractmethod
+    def get_fileinfo(self, fileid: str) -> Optional[FileAsset]:
+        """
+        get file info from storage
+        :param fileid: the file id
+        :return: None if no file info is available
+        """
+        pass
+
+    @abstractmethod
+    def has_binary(self, fileid: str) -> bool:
+        pass
+
+    def get_file_and_binary_by_id(self, fileid: str) -> Tuple[Union[FileAsset, None], Union[bytes, None]]:
+        """
+        get binary data by file id
+        :param fileid: the file info id.
+        :return: file info and binary data, if binary data is None, means the file has url.
+        """
+        file_info = self.get_fileinfo(fileid)
+        if file_info is None:
+            return None, None
+        return file_info, self.get_binary(file_info.filename)
+
+
+class ImageAssetRepo(FileAssetRepo, ABC):
+    pass
+
+
+class AudioAssetRepo(FileAssetRepo, ABC):
+    pass
+
+
+class StorageFileAssetRepo(FileAssetRepo):
+    """
+    simple implementation of FileAssets
+    """
+
+    def __init__(self, storage: Storage):
+        self._storage = storage
+
+    @staticmethod
+    def _get_fileinfo_filename(fileid: str) -> str:
+        return f"{fileid}.yml"
+
+    def save(self, file: FileAsset, binary: Optional[bytes]) -> str:
+        if binary is None and file.url is None:
+            raise AttributeError("failed to save image: binary is None and image info is not from url.")
+        fileinfo_filename = self._get_fileinfo_filename(file.fileid)
+        data = file.model_dump(exclude_none=True)
+        content = yaml_pretty_dump(data)
+        self._storage.put(fileinfo_filename, content.encode())
+        if binary:
+            self._storage.put(file.filename, binary)
+        return file.filename
+
+    def get_binary(self, filename: str) -> Optional[bytes]:
+        if self._storage.exists(filename):
+            return self._storage.get(filename)
+        return None
+
+    def has_binary(self, fileid: str) -> bool:
+        fileinfo = self.get_fileinfo(fileid)
+        if fileinfo is None:
+            return False
+        filename = fileinfo.filename
+        return self._storage.exists(filename)
+
+    def get_fileinfo(self, fileid: str) -> Optional[FileAsset]:
+        fileinfo_filename = self._get_fileinfo_filename(fileid)
+        if not self._storage.exists(fileinfo_filename):
+            return None
+        content = self._storage.get(fileinfo_filename)
+        data = yaml.safe_load(content)
+        return FileAsset(**data)
+
+
+class WorkspaceAssetsRepoProvider(Provider):
+
+    def __init__(self, assets_type: Type[FileAssetRepo], relative_path: str):
+        self._assets_type = assets_type
+        self._relative_path = relative_path
+
+    def singleton(self) -> bool:
+        return True
+
+    def contract(self) -> Type[FileAssetRepo]:
+        return self._assets_type
+
+    def factory(self, con: IoCContainer) -> FileAssetRepo:
+        from ghoshell_common.contracts.workspace import Workspace
+        ws = con.force_fetch(Workspace)
+        repo = StorageFileAssetRepo(ws.assets().sub_storage(self._relative_path))
+        return repo

ghoshell_common-0.4.0.dev1/src/ghoshell_common/contracts/configs.py

@@ -0,0 +1,200 @@
+import yaml
+from abc import ABC, abstractmethod
+from typing import ClassVar, TypeVar, Type, Optional, List
+from typing_extensions import Self
+from pydantic import BaseModel
+from ghoshell_common.helpers import generate_import_path
+from ghoshell_common.contracts.storage import FileStorage
+from ghoshell_container import Container, Provider
+from os.path import join, abspath, exists
+
+__all__ = [
+    'ConfigType', 'Configs', 'YamlConfig',
+    'WorkspaceConfigs', 'WorkspaceConfigsProvider',
+    'DefaultConfigs',
+]
+
+
+class ConfigType(ABC):
+    """
+    从 workspace 中获取配置文件, 基于 Pydantic + Yaml 或 toml 定义配置.
+    """
+
+    @classmethod
+    @abstractmethod
+    def conf_path(cls) -> str:
+        """
+        当前 Config 存储时对于 configs 目录的相对路径.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def unmarshal(cls, content: bytes) -> Self:
+        """
+        反序列化存储数据的方法.
+        """
+        pass
+
+    def marshal(self) -> bytes:
+        """
+        生成自己存储数据的方法.
+        """
+        pass
+
+
+CONF_TYPE = TypeVar('CONF_TYPE', bound=ConfigType)
+
+
+class Configs(ABC):
+    """
+    存储所有 Config 对象的仓库.
+    """
+
+    @abstractmethod
+    def get(self, conf_type: Type[CONF_TYPE], relative_path: Optional[str] = None) -> CONF_TYPE:
+        """
+        从仓库中读取一个配置对象.
+        :param conf_type: C 类型配置对象的类.
+        :param relative_path: 默认不需要填. 如果读取路径不是 C 类型默认的, 才需要传入.
+        :return: C 类型的实例.
+        :exception: FileNotFoundError
+        """
+        pass
+
+    @abstractmethod
+    def get_or_create(self, conf: CONF_TYPE) -> CONF_TYPE:
+        """
+        如果配置对象不存在, 则创建一个.
+        """
+        pass
+
+    @abstractmethod
+    def save(self, conf: ConfigType, relative_path: Optional[str] = None) -> None:
+        """
+        保存一个 Config 对象.
+        :param conf: the conf object
+        :param relative_path: if pass, override the conf_type default path.
+        """
+        pass
+
+
+class YamlConfig(ConfigType, BaseModel):
+    """
+    基于 Yaml + BaseModel 实现的配置文件.
+    """
+
+    relative_path: ClassVar[str]
+    """定义默认的相对存储路径. 通常存储在 workspace/configs/relative_path"""
+
+    @classmethod
+    def conf_path(cls) -> str:
+        return cls.relative_path
+
+    @classmethod
+    def unmarshal(cls, content: str) -> "ConfigType":
+        value = yaml.safe_load(content)
+        return cls(**value)
+
+    def marshal(self) -> bytes:
+        value = self.model_dump()
+        comment = f"# from class: {generate_import_path(self.__class__)}"
+        result = yaml.safe_dump(value)
+        return "\n".join([comment, result]).encode()
+
+
+class BasicConfigs(Configs, ABC):
+    """
+    A Configs(repository) based on Storage, no matter what the Storage is.
+    """
+
+    def get(self, conf_type: Type[CONF_TYPE], relative_path: Optional[str] = None) -> CONF_TYPE:
+        path = conf_type.conf_path()
+        relative_path = relative_path if relative_path else path
+        content = self._get(relative_path)
+        return conf_type.unmarshal(content)
+
+    def get_or_create(self, conf: CONF_TYPE) -> CONF_TYPE:
+        path = conf.conf_path()
+        if not self._exists(path):
+            self._put(path, conf.marshal())
+            return conf
+        return self.get(type(conf))
+
+    @abstractmethod
+    def _get(self, relative_path: str) -> bytes:
+        pass
+
+    @abstractmethod
+    def _put(self, relative_path: str, content: bytes) -> None:
+        pass
+
+    @abstractmethod
+    def _exists(self, relative_path: str) -> bool:
+        pass
+
+    def save(self, conf: ConfigType, relative_path: Optional[str] = None) -> None:
+        marshaled = conf.marshal()
+        relative_path = relative_path if relative_path else conf.conf_path()
+        self._put(relative_path, marshaled)
+
+
+class DefaultConfigs(BasicConfigs):
+    """
+    A Configs(repository) based on Storage, no matter what the Storage is.
+    """
+
+    def __init__(self, configs_dir: str):
+        self._configs_dir = configs_dir
+
+    def _get(self, relative_path: str) -> bytes:
+        abs_path = abspath(join(self._configs_dir, relative_path))
+        with open(abs_path, 'rb') as f:
+            return f.read()
+
+    def _put(self, relative_path: str, content: bytes) -> None:
+        abs_path = abspath(join(self._configs_dir, relative_path))
+        with open(abs_path, 'wb') as f:
+            f.write(content)
+
+    def _exists(self, relative_path: str) -> bool:
+        abs_path = abspath(join(self._configs_dir, relative_path))
+        return exists(abs_path)
+
+
+class WorkspaceConfigs(BasicConfigs):
+
+    def __init__(self, storage: FileStorage):
+        self._storage = storage
+
+    def _get(self, relative_path: str) -> bytes:
+        return self._storage.get(relative_path)
+
+    def _put(self, relative_path: str, content: bytes) -> None:
+        self._storage.put(relative_path, content)
+
+    def _exists(self, relative_path: str) -> bool:
+        return self._storage.exists(relative_path)
+
+
+class WorkspaceConfigsProvider(Provider[Configs]):
+    """
+    默认的 configs 实现.
+    """
+
+    def __init__(self, default_configs: List[ConfigType] | None = None):
+        self._create_default_configs = default_configs
+
+    def singleton(self) -> bool:
+        return True
+
+    def factory(self, con: Container) -> Optional[Configs]:
+        from ghoshell_common.contracts.workspace import Workspace
+        ws = con.force_fetch(Workspace)
+
+        configs = WorkspaceConfigs(ws.configs())
+        # 创建默认的配置文件
+        if self._create_default_configs:
+            for default_config in self._create_default_configs:
+                configs.get_or_create(default_config)
+        return configs

ghoshell_common-0.4.0.dev1/src/ghoshell_common/contracts/logger.py

@@ -0,0 +1,239 @@
+import logging
+import warnings
+from abc import abstractmethod
+from typing import Optional, Protocol
+from logging import getLogger
+from logging.config import dictConfig
+from ghoshell_container import Container, Provider, INSTANCE, IoCContainer
+from os import path
+import yaml
+
+__all__ = [
+    'LoggerItf',
+    'WorkspaceLoggerProvider', 'LoggerProvider',
+    'config_workspace_logger', 'get_console_logger', 'config_logger_from_yaml', 'get_logger_with_extra',
+]
+
+
+class LoggerItf(Protocol):
+    """
+    """
+
+    @abstractmethod
+    def debug(self, msg, *args, **kwargs):
+        """
+        Log 'msg % args' with severity 'DEBUG'.
+
+        To pass exception information, use the keyword argument exc_info with
+        a true value, e.g.
+
+        logger.debug("Houston, we have a %s", "thorny problem", exc_info=True)
+        """
+        pass
+
+    @abstractmethod
+    def info(self, msg, *args, **kwargs):
+        """
+        Log 'msg % args' with severity 'INFO'.
+
+        To pass exception information, use the keyword argument exc_info with
+        a true value, e.g.
+
+        logger.debug("Houston, we have a %s", "notable problem", exc_info=True)
+        """
+        pass
+
+    @abstractmethod
+    def warning(self, msg, *args, **kwargs):
+        """
+        Log 'msg % args' with severity 'WARNING'.
+
+        To pass exception information, use the keyword argument exc_info with
+        a true value, e.g.
+
+        logger.warning("Houston, we have a %s", "bit of a problem", exc_info=True)
+        """
+        pass
+
+    @abstractmethod
+    def error(self, msg, *args, **kwargs):
+        """
+        Log 'msg % args' with severity 'ERROR'.
+
+        To pass exception information, use the keyword argument exc_info with
+        a true value, e.g.
+
+        logger.error("Houston, we have a %s", "major problem", exc_info=True)
+        """
+        pass
+
+    @abstractmethod
+    def exception(self, msg, *args, exc_info=True, **kwargs):
+        """
+        Convenience method for logging an ERROR with exception information.
+        """
+        pass
+
+    @abstractmethod
+    def critical(self, msg, *args, **kwargs):
+        """
+        Log 'msg % args' with severity 'CRITICAL'.
+
+        To pass exception information, use the keyword argument exc_info with
+        a true value, e.g.
+
+        logger.critical("Houston, we have a %s", "major disaster", exc_info=True)
+        """
+        pass
+
+    @abstractmethod
+    def log(self, level, msg, *args, **kwargs):
+        """
+        Log 'msg % args' with the integer severity 'level'.
+
+        To pass exception information, use the keyword argument exc_info with
+        a true value, e.g.
+
+        logger.log(level, "We have a %s", "mysterious problem", exc_info=True)
+        """
+        pass
+
+
+class PleshakovFormatter(logging.Formatter):
+    # copy from
+    # https://stackoverflow.com/questions/384076/how-can-i-color-python-logging-output
+    grey = "\x1b[37;20m"
+    yellow = "\x1b[33;20m"
+    red = "\x1b[31;20m"
+    green = "\x1b[32;20m"
+    bold_red = "\x1b[31;1m"
+    reset = "\x1b[0m"
+    format = "%(asctime)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)"
+
+    FORMATS = {
+        logging.DEBUG: grey + format + reset,
+        logging.INFO: green + format + reset,
+        logging.WARNING: yellow + format + reset,
+        logging.ERROR: red + format + reset,
+        logging.CRITICAL: bold_red + format + reset
+    }
+
+    def format(self, record):
+        log_fmt = self.FORMATS.get(record.levelno)
+        formatter = logging.Formatter(log_fmt)
+        return formatter.format(record)
+
+
+class FakeLogger(LoggerItf):
+    def debug(self, msg, *args, **kwargs):
+        pass
+
+    def info(self, msg, *args, **kwargs):
+        pass
+
+    def warning(self, msg, *args, **kwargs):
+        pass
+
+    def error(self, msg, *args, **kwargs):
+        pass
+
+    def exception(self, msg, *args, exc_info=True, **kwargs):
+        pass
+
+    def critical(self, msg, *args, **kwargs):
+        pass
+
+    def log(self, level, msg, *args, **kwargs):
+        pass
+
+
+def get_logger_with_extra(name: Optional[str] = None, extra: Optional[dict] = None) -> LoggerItf:
+    return logging.LoggerAdapter(getLogger(name), extra=extra)
+
+
+def config_logger_from_yaml(yaml_conf_path: str) -> None:
+    """
+    configurate logging by yaml config
+    :param yaml_conf_path: absolute path of yaml config file
+    """
+    if not path.exists(yaml_conf_path):
+        return
+
+    with open(yaml_conf_path) as f:
+        content = f.read()
+    data = yaml.safe_load(content)
+    dictConfig(data)
+
+
+def config_workspace_logger(workspace_dir: str) -> None:
+    from os.path import join, exists
+    logger_path = join(workspace_dir, "logging.yml")
+    if not exists(logger_path):
+        warnings.warn("Coco logger not found at '{}'".format(logger_path))
+    else:
+        config_logger_from_yaml(logger_path)
+
+
+def get_console_logger(
+        name: str,
+        extra: Optional[dict] = None,
+        debug: bool = False,
+) -> LoggerItf:
+    logger = getLogger(name)
+    if not logger.hasHandlers():
+        _console_handler = logging.StreamHandler()
+        _console_formatter = PleshakovFormatter()
+        _console_handler.setFormatter(_console_formatter)
+        logger.addHandler(_console_handler)
+
+    if debug:
+        logger.setLevel(logging.DEBUG)
+    return logging.LoggerAdapter(logger, extra=extra)
+
+
+class LoggerProvider(Provider[LoggerItf]):
+    """
+    注册日志服务, 方便从容器中获取日志实例.
+    """
+
+    def __init__(
+            self,
+            name: str = "ghoshell",
+            level: Optional[int] = None,
+            extra: Optional[dict] = None,
+    ):
+        self.name = name
+        self.level = level
+        self.extra = extra
+
+    def singleton(self) -> bool:
+        return True
+
+    def contract(self):
+        return LoggerItf
+
+    def factory(self, con: Container) -> Optional[LoggerItf]:
+        logger = logging.getLogger(self.name)
+        return logging.LoggerAdapter(logger, self.extra)
+
+
+class WorkspaceLoggerProvider(Provider[LoggerItf]):
+    """
+    logger from workspace.
+    """
+
+    def __init__(self, name: str):
+        self.name = name
+
+    def singleton(self) -> bool:
+        return True
+
+    def factory(self, con: IoCContainer) -> INSTANCE:
+        from ghoshell_common.contracts.workspace import Workspace
+        ws = con.force_fetch(Workspace)
+        if not ws.configs().exists("logging.yml"):
+            return get_console_logger(self.name)
+        else:
+            logging_config_path = ws.configs().abspath().join("logging.yml")
+            config_logger_from_yaml(logging_config_path)
+            return logging.getLogger(self.name)

ghoshell_common-0.4.0.dev1/src/ghoshell_common/contracts/storage.py

@@ -0,0 +1,170 @@
+from abc import abstractmethod
+from typing import Optional, Iterable, Protocol
+import os
+from ghoshell_container import Container, Provider
+import fnmatch
+
+__all__ = ['Storage', 'FileStorage', 'DefaultFileStorage', 'FileStorageProvider']
+
+
+class Storage(Protocol):
+
+    @abstractmethod
+    def sub_storage(self, relative_path: str) -> "Storage":
+        """
+        生成一个次级目录下的 storage.
+        :param relative_path:
+        :return:
+        """
+        pass
+
+    @abstractmethod
+    def get(self, file_path: str) -> bytes:
+        """
+        获取一个 Storage 路径下一个文件的内容.
+        :param file_path: storage 下的一个相对路径.
+        """
+        pass
+
+    @abstractmethod
+    def remove(self, file_path: str) -> None:
+        pass
+
+    @abstractmethod
+    def exists(self, file_path: str) -> bool:
+        """
+        if the object exists
+        :param file_path: file_path or directory path
+        """
+        pass
+
+    @abstractmethod
+    def put(self, file_path: str, content: bytes) -> None:
+        """
+        保存一个文件的内容到 file_path .
+        :param file_path: storage 下的一个相对路径.
+        :param content: 文件的内容.
+        """
+        pass
+
+    @abstractmethod
+    def dir(self, prefix_dir: str, recursive: bool, patten: Optional[str] = None) -> Iterable[str]:
+        """
+        遍历一个路径下的文件, 返回相对的文件名.
+        :param prefix_dir: 目录的相对路径位置.
+        :param recursive: 是否递归查找.
+        :param patten: 文件的正则规范.
+        :return: 多个文件路径名.
+        """
+        pass
+
+
+class FileStorage(Storage, Protocol):
+    """
+    Storage Based on FileSystem.
+    """
+
+    @abstractmethod
+    def abspath(self) -> str:
+        """
+        storage root directory's absolute path
+        """
+        pass
+
+    @abstractmethod
+    def sub_storage(self, relative_path: str) -> "FileStorage":
+        """
+        FileStorage's sub storage is still FileStorage
+        """
+        pass
+
+
+class DefaultFileStorage(FileStorage):
+    """
+    FileStorage implementation based on python filesystem.
+    Simplest implementation.
+    """
+
+    def __init__(self, dir_: str):
+        self._dir: str = os.path.abspath(dir_)
+
+    def abspath(self) -> str:
+        return self._dir
+
+    def get(self, file_path: str) -> bytes:
+        file_path = self._join_file_path(file_path)
+        with open(file_path, 'rb') as f:
+            return f.read()
+
+    def remove(self, file_path: str) -> None:
+        file_path = self._join_file_path(file_path)
+        os.remove(file_path)
+
+    def exists(self, file_path: str) -> bool:
+        file_path = self._join_file_path(file_path)
+        return os.path.exists(file_path)
+
+    def _join_file_path(self, path: str) -> str:
+        file_path = os.path.join(self._dir, path)
+        file_path = os.path.abspath(file_path)
+        if not file_path.startswith(self._dir):
+            raise FileNotFoundError(f"file path {path} is not allowed")
+        return file_path
+
+    def put(self, file_path: str, content: bytes) -> None:
+        file_path = self._join_file_path(file_path)
+        if not file_path.startswith(self._dir):
+            raise FileNotFoundError(f"file path {file_path} is not allowed")
+        file_dir = os.path.dirname(file_path)
+        if not os.path.exists(file_dir):
+            os.makedirs(file_dir)
+        with open(file_path, 'wb') as f:
+            f.write(content)
+
+    def sub_storage(self, relative_path: str) -> "FileStorage":
+        if not relative_path:
+            return self
+        dir_path = self._join_file_path(relative_path)
+        return DefaultFileStorage(dir_path)
+
+    def dir(self, prefix_dir: str, recursive: bool, patten: Optional[str] = None) -> Iterable[str]:
+        dir_path = self._join_file_path(prefix_dir)
+        for root, ds, fs in os.walk(dir_path):
+            # 遍历单层的文件名.
+            for filename in fs:
+                if self._match_file_pattern(filename, patten):
+                    yield filename
+
+            # 深入遍历目录.
+            if recursive and ds:
+                for _dir in ds:
+                    sub_dir_iterator = self.dir(_dir, recursive, patten)
+                    for filename in sub_dir_iterator:
+                        yield filename
+
+    @staticmethod
+    def _match_file_pattern(filename: str, pattern: Optional[str]) -> bool:
+        if pattern is None:
+            return True
+        matched = True
+        if pattern.startswith('!'):
+            matched = False
+            pattern = pattern[1:]
+        if pattern and fnmatch.fnmatch(filename, pattern):
+            return matched
+        return not matched
+
+
+class FileStorageProvider(Provider[FileStorage]):
+
+    def __init__(self, dir_: str):
+        self._dir: str = dir_
+
+    def singleton(self) -> bool:
+        return True
+
+    def aliases(self) -> Iterable[Storage]:
+        yield Storage
+
+    def factory(self, con: Container) -> Optional[Storage]:
+        return DefaultFileStorage(self._dir)

ghoshell_common-0.4.0.dev1/src/ghoshell_common/contracts/workspace.py

@@ -0,0 +1,88 @@
+import os
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from ghoshell_common.contracts.storage import FileStorage, DefaultFileStorage
+from ghoshell_container import Container, Provider
+from os.path import abspath
+import shutil
+
+__all__ = ['Workspace', 'LocalWorkspace', 'LocalWorkspaceProvider']
+
+
+class Workspace(ABC):
+    """
+    workspace 目录文件管理.
+    用于管理一个项目的本地文件存储.
+    """
+
+    @abstractmethod
+    def root(self) -> FileStorage:
+        """
+        workspace 根 storage.
+        """
+        pass
+
+    @abstractmethod
+    def configs(self) -> FileStorage:
+        """
+        配置文件存储路径.
+        """
+        pass
+
+    @abstractmethod
+    def runtime(self) -> FileStorage:
+        """
+        运行时数据存储路径.
+        """
+        pass
+
+    @abstractmethod
+    def assets(self) -> FileStorage:
+        """
+        数据资产存储路径.
+        """
+        pass
+
+
+class LocalWorkspace(Workspace):
+
+    def __init__(self, workspace_dir: str):
+        workspace_dir = abspath(workspace_dir)
+        self._ws_root_dir = workspace_dir
+        self._root = DefaultFileStorage(workspace_dir)
+
+    def root(self) -> FileStorage:
+        return self._root
+
+    def configs(self) -> FileStorage:
+        return self._root.sub_storage("configs")
+
+    def runtime(self) -> FileStorage:
+        return self._root.sub_storage("runtime")
+
+    def assets(self) -> FileStorage:
+        return self._root.sub_storage("assets")
+
+
+class LocalWorkspaceProvider(Provider[Workspace]):
+
+    def __init__(
+            self,
+            workspace_dir: str = "",
+            stub_dir: Optional[str] = None,
+    ):
+        if workspace_dir == "":
+            # 使用脚本运行的路径作为 workspace.
+            workspace_dir = os.path.join(abspath(os.getcwd()), ".ghoshell_ws/")
+        self._ws_dir = abspath(workspace_dir)
+        self._stub_dir = abspath(stub_dir) if stub_dir else None
+
+    def singleton(self) -> bool:
+        return True
+
+    def factory(self, con: Container) -> Optional[Workspace]:
+        if self._stub_dir and not os.path.exists(self._stub_dir):
+            os.makedirs(self._stub_dir)
+            shutil.copytree(self._stub_dir, self._ws_dir)
+        return LocalWorkspace(self._ws_dir)