corio 2.3.4__tar.gz → 2.3.6__tar.gz

{corio-2.3.4 → corio-2.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: corio
-Version: 2.3.4
+Version: 2.3.6
 Summary: Collection of high-level tools to simplify everyday development tasks, with a focus on AI/ML
 Author-email: Frontmatter AI <innovative.fowler@mask.pro.fmtr.dev>
 License-Expression: Apache-2.0
@@ -90,6 +90,17 @@ Requires-Dist: pydantic; extra == "api"
 Requires-Dist: pydantic-extra-types; extra == "api"
 Requires-Dist: pycountry; extra == "api"
 Requires-Dist: logfire[fastapi]; extra == "api"
+Requires-Dist: httpx; extra == "api"
+Provides-Extra: api-mcp
+Requires-Dist: fastapi; extra == "api-mcp"
+Requires-Dist: uvicorn[standard]; extra == "api-mcp"
+Requires-Dist: logfire; extra == "api-mcp"
+Requires-Dist: pydantic; extra == "api-mcp"
+Requires-Dist: pydantic-extra-types; extra == "api-mcp"
+Requires-Dist: pycountry; extra == "api-mcp"
+Requires-Dist: logfire[fastapi]; extra == "api-mcp"
+Requires-Dist: httpx; extra == "api-mcp"
+Requires-Dist: fastmcp; extra == "api-mcp"
 Provides-Extra: dm
 Requires-Dist: pydantic; extra == "dm"
 Requires-Dist: pydantic-extra-types; extra == "dm"
@@ -342,6 +353,7 @@ Requires-Dist: contexttimer; extra == "all"
 Requires-Dist: Unidecode; extra == "all"
 Requires-Dist: tinynetrc; extra == "all"
 Requires-Dist: huggingface_hub; extra == "all"
+Requires-Dist: fastmcp; extra == "all"
 Requires-Dist: peft; extra == "all"
 Requires-Dist: transformers[sentencepiece]; extra == "all"
 Requires-Dist: torchvision; extra == "all"

corio-2.3.6/corio/api/__init__.py

@@ -0,0 +1 @@
+from corio.api.api import *

{corio-2.3.4/corio → corio-2.3.6/corio/api}/api.py

@@ -1,15 +1,22 @@
+from __future__ import annotations
+
 import logging
+from contextlib import AsyncExitStack, asynccontextmanager
 from dataclasses import dataclass
 from functools import cached_property
-from typing import Callable, List, Optional, Union, Self
+from typing import Callable, List, Optional, Union, Self, TYPE_CHECKING
 
+import httpx
 import uvicorn
 from fastapi import FastAPI, Request
 
-from corio import env
+from corio import env, strings
 from corio.iterator import enlist
 from corio.logs import logger
 
+if TYPE_CHECKING:
+    from corio.api.mcp import FastMCP
+
 for name in ["uvicorn.access", "uvicorn.error", "uvicorn"]:
     logger_uvicorn = logging.getLogger(name)
     logger_uvicorn.handlers.clear()
@@ -44,6 +51,9 @@ class Base:
     URL = None
     URL_DOCS = '/'
     URL_PREFIX = None
+    IS_MCP = False
+    MCP_PATH = '/mcp'
+
 
     def add_endpoint(self, endpoint: Endpoint):
         """
@@ -63,7 +73,13 @@ class Base:
         )(endpoint.method)
 
     def __init__(self):
-        self.app = FastAPI(title=self.TITLE, swagger_ui_parameters=self.SWAGGER_PARAMS, docs_url=self.URL_DOCS)
+        self.app = FastAPI(
+            title=self.TITLE,
+            swagger_ui_parameters=self.SWAGGER_PARAMS,
+            docs_url=self.URL_DOCS,
+            lifespan=self.lifespan,
+            description=self.description,
+        )
         logger.instrument_fastapi(self.app)
 
         for endpoint in self.get_endpoints():
@@ -75,6 +91,10 @@ class Base:
         for child in self.children:
             self.app.mount(child.url_prefix, child.app)
 
+        if self.IS_MCP:
+            self.app.mount(self.MCP_PATH, self.mcp_app)
+            self.app.router.lifespan_context = self.lifespan_mcp
+
     @cached_property
     def children(self) -> List[Self]:
         """
@@ -92,7 +112,7 @@ class Base:
 
         """
         if self.URL_PREFIX:
-            self.URL_PREFIX
+            return self.URL_PREFIX
 
         return f'/{self.__class__.__name__.lower()}'
 
@@ -137,7 +157,29 @@ class Base:
         Launch message.
 
         """
-        return f"Launching {self.TITLE} at {self.url}"
+        message = f"Launching {self.TITLE} at {self.url}"
+        if self.IS_MCP:
+            message = f"{message} (with MCP at {self.MCP_PATH})"
+        return message
+
+    @property
+    def description(self) -> str|None:
+        """
+
+        Optional OpenAPI description with immediate child API links.
+
+        """
+        if not self.children:
+            return None
+
+        lines = [f"- [{child.TITLE}]({child.url_prefix})" for child in self.children]
+        lines= "\n".join(lines)
+        description=strings.trim(f"""
+        ### APIs
+        
+        {lines}
+        """)
+        return description
 
     @property
     def config(self) -> uvicorn.Config:
@@ -178,3 +220,74 @@ class Base:
         """
         import asyncio
         return asyncio.run(cls.launch_async(*args, **kwargs))
+
+    @staticmethod
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        """
+
+        Default app lifespan.
+
+        """
+        yield
+        logger.info(f"Closing {app.title}")
+
+
+    # MCP integration methods
+
+    @cached_property
+    def mcp(self) -> FastMCP:
+        """
+
+        Build an MCP server from this API's OpenAPI schema.
+
+        """
+        from corio.api.mcp import FastMCP
+        client = httpx.AsyncClient(transport=httpx.ASGITransport(app=self.app), base_url=self.url)
+        return FastMCP.from_openapi(openapi_spec=self.app.openapi(), client=client, name=self.TITLE)
+
+    @cached_property
+    def mcp_app(self):
+        """
+
+        HTTP ASGI app for this API's MCP server.
+
+        """
+        return self.mcp.http_app(path='/')
+
+
+    @cached_property
+    def mcp_lifespans_flat(self) -> list[tuple[Callable, FastAPI]]:
+        """
+
+        Flattened MCP lifespans for this API and immediate descendants.
+
+        """
+
+        if self.IS_MCP:
+            lifespans = [(self.mcp_app.lifespan, self.mcp_app)]
+        else:
+            lifespans = []
+
+        for child in self.children:
+            lifespans.extend(child.mcp_lifespans_flat)
+        return lifespans
+
+    @cached_property
+    def lifespan_mcp(self):
+        """
+
+        Combined lifespan wrapper for FastAPI and mounted MCP apps.
+
+        """
+        original_lifespan = self.app.router.lifespan_context
+
+        @asynccontextmanager
+        async def lifespan(app):
+            async with AsyncExitStack() as stack:
+                await stack.enter_async_context(original_lifespan(app))
+                for mcp_lifespan, mcp_owner_app in self.mcp_lifespans_flat:
+                    await stack.enter_async_context(mcp_lifespan(mcp_owner_app))
+                yield
+
+        return lifespan

corio-2.3.6/corio/api/mcp.py

@@ -0,0 +1 @@
+from fastmcp import FastMCP

{corio-2.3.4 → corio-2.3.6}/corio/infra/releaser.py

@@ -228,13 +228,9 @@ class IncrementorVersion(Incrementor):
     def old(self):
         return self.paths.metadata.version_obj
 
-    @cached_property
-    def old_tag(self):
-        return self.old.tag
-
     @cached_property
     def has_old_tag(self):
-        return self.old_tag in self.repo.tags.all
+        return self.old.tag in self.repo.tags.all
 
     @cached_property
     def pinned_tag(self):
@@ -250,7 +246,7 @@ class IncrementorVersion(Incrementor):
 
         if not self.has_old_tag:
             raise RuntimeError(
-                f'Current version tag "{self.old_tag}" was not found. '
+                f'Current version tag "{self.old.tag}" was not found. '
                 f'Refusing pinned release "{new}" until the previous release state is resolved.'
             )
 
@@ -267,7 +263,7 @@ class IncrementorVersion(Incrementor):
 
         if not self.has_old_tag:
             logger.warning(
-                f'Current version tag "{self.old_tag}" was not found. '
+                f'Current version tag "{self.old.tag}" was not found. '
                 f'Assuming previous release failed and reusing version "{self.old}".'
             )
             return self.old

{corio-2.3.4 → corio-2.3.6}/corio/pyproject.package.toml

@@ -1,6 +1,6 @@
 [project]
 name = "corio"
-version = "2.3.4"
+version = "2.3.6"
 description = "Collection of high-level tools to simplify everyday development tasks, with a focus on AI/ML"
 readme = "README.md"
 dependencies = []
@@ -27,7 +27,8 @@ spaces = ["tinynetrc"]
 netrc = ["tinynetrc"]
 hfh = ["huggingface_hub"]
 merging = ["deepmerge"]
-api = ["fastapi", "uvicorn[standard]", "logfire", "pydantic", "pydantic-extra-types", "pycountry", "logfire[fastapi]"]
+api = ["fastapi", "uvicorn[standard]", "logfire", "pydantic", "pydantic-extra-types", "pycountry", "logfire[fastapi]", "httpx"]
+"api.mcp" = ["fastapi", "uvicorn[standard]", "logfire", "pydantic", "pydantic-extra-types", "pycountry", "logfire[fastapi]", "httpx", "fastmcp"]
 dm = ["pydantic", "pydantic-extra-types", "pycountry"]
 ai = ["peft", "transformers[sentencepiece]", "torchvision", "torchaudio", "pydantic", "pydantic-extra-types", "pycountry"]
 "ai.compute" = ["cuda-bindings==13.2.0", "cuda-pathfinder==1.5.4", "cuda-toolkit==13.0.2", "nvidia-cublas==13.1.0.3", "nvidia-cuda-cupti==13.0.85", "nvidia-cuda-nvrtc==13.0.88", "nvidia-cuda-runtime==13.0.96", "nvidia-cudnn-cu13==9.19.0.56", "nvidia-cufft==12.0.0.61", "nvidia-cufile==1.15.1.6", "nvidia-curand==10.4.0.35", "nvidia-cusolver==12.0.4.66", "nvidia-cusparse==12.6.3.3", "nvidia-cusparselt-cu13==0.8.0", "nvidia-nccl-cu13==2.28.9", "nvidia-nvjitlink==13.0.88", "nvidia-nvshmem-cu13==3.4.5", "nvidia-nvtx==13.0.85", "torch==2.11.0", "triton==3.6.0"]
@@ -70,7 +71,7 @@ tasmota = ["decode-config", "esptool"]
 encrypt = ["pyrage"]
 secrets = ["pyrage", "dotenv", "yamlscript", "pyyaml", "logfire", "pydantic-settings", "pydantic", "pydantic-extra-types", "pycountry", "pygit2"]
 cli = ["pydantic-settings", "pydantic", "pydantic-extra-types", "pycountry", "yamlscript", "pyyaml", "logfire"]
-all = ["logfire", "semver", "pydevd-pycharm~=251.25410.159", "pydantic-settings", "pydantic", "pydantic-extra-types", "pycountry", "yamlscript", "pyyaml", "beanie", "setuptools", "mkdocs", "mkdocs-material", "mkdocstrings[python]", "mike", "mkdocs-include-dir-to-nav", "build", "twine", "packaging", "pygit2", "python-on-whales", "deepmerge", "httpx", "httpx_retries", "logfire[httpx]", "fastapi", "uvicorn[standard]", "logfire[fastapi]", "tomlkit", "pyrage", "dotenv", "pytest", "pytest-cov", "pytest-asyncio", "dask[bag]", "distributed", "bokeh", "tokenizers", "faker", "sre_yield", "contexttimer", "Unidecode", "tinynetrc", "huggingface_hub", "peft", "transformers[sentencepiece]", "torchvision", "torchaudio", "cuda-bindings==13.2.0", "cuda-pathfinder==1.5.4", "cuda-toolkit==13.0.2", "nvidia-cublas==13.1.0.3", "nvidia-cuda-cupti==13.0.85", "nvidia-cuda-nvrtc==13.0.88", "nvidia-cuda-runtime==13.0.96", "nvidia-cudnn-cu13==9.19.0.56", "nvidia-cufft==12.0.0.61", "nvidia-cufile==1.15.1.6", "nvidia-curand==10.4.0.35", "nvidia-cusolver==12.0.4.66", "nvidia-cusparse==12.6.3.3", "nvidia-cusparselt-cu13==0.8.0", "nvidia-nccl-cu13==2.28.9", "nvidia-nvjitlink==13.0.88", "nvidia-nvshmem-cu13==3.4.5", "nvidia-nvtx==13.0.85", "torch==2.11.0", "triton==3.6.0", "openai", "pydantic-ai-slim[logfire,openai]", "ollama", "json_repair", "sentence_transformers", "pandas", "tabulate", "openpyxl", "odfpy", "deepdiff", "html2text", "flet[all] <0.80.0", "flet-video", "flet-webview", "google-auth", "google-auth-oauthlib", "google-auth-httplib2", "google-api-python-client", "diskcache", "cachetools", "pymupdf", "pymupdf4llm", "appdirs", "filetype", "dnspython[doh]", "regex", "playwright", "aiomqtt", "av", "homeassistant_api", "aiohasupervisor", "pytubefix", "decode-config", "esptool"]
+all = ["logfire", "semver", "pydevd-pycharm~=251.25410.159", "pydantic-settings", "pydantic", "pydantic-extra-types", "pycountry", "yamlscript", "pyyaml", "beanie", "setuptools", "mkdocs", "mkdocs-material", "mkdocstrings[python]", "mike", "mkdocs-include-dir-to-nav", "build", "twine", "packaging", "pygit2", "python-on-whales", "deepmerge", "httpx", "httpx_retries", "logfire[httpx]", "fastapi", "uvicorn[standard]", "logfire[fastapi]", "tomlkit", "pyrage", "dotenv", "pytest", "pytest-cov", "pytest-asyncio", "dask[bag]", "distributed", "bokeh", "tokenizers", "faker", "sre_yield", "contexttimer", "Unidecode", "tinynetrc", "huggingface_hub", "fastmcp", "peft", "transformers[sentencepiece]", "torchvision", "torchaudio", "cuda-bindings==13.2.0", "cuda-pathfinder==1.5.4", "cuda-toolkit==13.0.2", "nvidia-cublas==13.1.0.3", "nvidia-cuda-cupti==13.0.85", "nvidia-cuda-nvrtc==13.0.88", "nvidia-cuda-runtime==13.0.96", "nvidia-cudnn-cu13==9.19.0.56", "nvidia-cufft==12.0.0.61", "nvidia-cufile==1.15.1.6", "nvidia-curand==10.4.0.35", "nvidia-cusolver==12.0.4.66", "nvidia-cusparse==12.6.3.3", "nvidia-cusparselt-cu13==0.8.0", "nvidia-nccl-cu13==2.28.9", "nvidia-nvjitlink==13.0.88", "nvidia-nvshmem-cu13==3.4.5", "nvidia-nvtx==13.0.85", "torch==2.11.0", "triton==3.6.0", "openai", "pydantic-ai-slim[logfire,openai]", "ollama", "json_repair", "sentence_transformers", "pandas", "tabulate", "openpyxl", "odfpy", "deepdiff", "html2text", "flet[all] <0.80.0", "flet-video", "flet-webview", "google-auth", "google-auth-oauthlib", "google-auth-httplib2", "google-api-python-client", "diskcache", "cachetools", "pymupdf", "pymupdf4llm", "appdirs", "filetype", "dnspython[doh]", "regex", "playwright", "aiomqtt", "av", "homeassistant_api", "aiohasupervisor", "pytubefix", "decode-config", "esptool"]
 
 [[project.authors]]
 name = "Frontmatter AI"
@@ -83,7 +84,7 @@ Homepage = "https://github.com/fmtr/corio"
 corio = "corio.entrypoint:main"
 
 [tool.corio.metadata]
-version = "2.3.4"
+version = "2.3.6"
 port = 0
 base = "python"
 description = "Collection of high-level tools to simplify everyday development tasks, with a focus on AI/ML"
@@ -120,7 +121,8 @@ spaces = ["netrc"]
 netrc = ["tinynetrc"]
 hfh = ["huggingface_hub"]
 merging = ["deepmerge"]
-api = ["fastapi", "uvicorn[standard]", "logging", "dm", "logfire[fastapi]"]
+api = ["fastapi", "uvicorn[standard]", "logging", "dm", "logfire[fastapi]", "httpx"]
+"api.mcp" = ["api", "fastmcp"]
 dm = ["pydantic", "pydantic-extra-types", "pycountry"]
 ai = ["peft", "transformers[sentencepiece]", "torchvision", "torchaudio", "dm"]
 "ai.compute" = ["cuda-bindings==13.2.0", "cuda-pathfinder==1.5.4", "cuda-toolkit==13.0.2", "nvidia-cublas==13.1.0.3", "nvidia-cuda-cupti==13.0.85", "nvidia-cuda-nvrtc==13.0.88", "nvidia-cuda-runtime==13.0.96", "nvidia-cudnn-cu13==9.19.0.56", "nvidia-cufft==12.0.0.61", "nvidia-cufile==1.15.1.6", "nvidia-curand==10.4.0.35", "nvidia-cusolver==12.0.4.66", "nvidia-cusparse==12.6.3.3", "nvidia-cusparselt-cu13==0.8.0", "nvidia-nccl-cu13==2.28.9", "nvidia-nvjitlink==13.0.88", "nvidia-nvshmem-cu13==3.4.5", "nvidia-nvtx==13.0.85", "torch==2.11.0", "triton==3.6.0"]
@@ -177,7 +179,12 @@ corio = ["pyproject.package.toml"]
 
 [tool.tox]
 requires = ["tox>=4.22", "tox-uv>=1"]
-env_list = ["caching", "datatype", "dns", "dt", "encrypt", "env", "hash", "hook", "infra", "iterator", "jsn", "name", "path", "patterns", "rand", "strings", "toml", "tools", "yml"]
+env_list = ["api", "caching", "datatype", "dns", "dt", "encrypt", "env", "hash", "hook", "infra", "iterator", "jsn", "name", "path", "patterns", "rand", "shell", "strings", "toml", "tools", "yml"]
+
+[tool.tox.env.api]
+description = "Run api tests."
+deps = ["fastapi", "fastmcp", "httpx", "logfire", "logfire[fastapi]", "pycountry", "pydantic", "pydantic-extra-types", "pytest", "pytest-asyncio", "pytest-cov", "uvicorn[standard]"]
+commands = [["python", "-m", "pytest", "-q", "corio/tests/test_api.py"]]
 
 [tool.tox.env.caching]
 description = "Run caching tests."
@@ -254,6 +261,11 @@ description = "Run rand tests."
 deps = ["pytest", "pytest-asyncio", "pytest-cov"]
 commands = [["python", "-m", "pytest", "-q", "corio/tests/test_rand.py"]]
 
+[tool.tox.env.shell]
+description = "Run shell tests."
+deps = ["pytest", "pytest-asyncio", "pytest-cov"]
+commands = [["python", "-m", "pytest", "-q", "corio/tests/test_shell.py"]]
+
 [tool.tox.env.strings]
 description = "Run strings tests."
 deps = ["pytest", "pytest-asyncio", "pytest-cov"]

corio-2.3.6/corio/sandbox/__init__.py

@@ -0,0 +1 @@
+from corio.sandbox.api import SandboxApi

corio-2.3.6/corio/sandbox/api.py

@@ -0,0 +1,64 @@
+from corio import api
+from functools import cached_property
+
+
+class Child(api.Base):
+    TITLE = 'Sandbox Child API'
+    IS_MCP = True
+
+
+    def get_endpoints(self):
+        """
+
+        Sandbox child endpoints.
+
+        """
+        endpoints = [
+            api.Endpoint(method_http=self.app.get, path='/pong', method=self.pong, tags='sandbox'),
+        ]
+        return endpoints
+
+    async def pong(self, value: str = 'ok'):
+        """
+
+        Child ping variant.
+
+        """
+        return dict(child=value)
+
+
+class SandboxApi(api.Base):
+    TITLE = 'Sandbox API'
+    PORT = 8001
+    IS_MCP = True
+
+    def get_endpoints(self):
+        """
+
+        Sandbox parent endpoints.
+
+        """
+        endpoints = [
+            api.Endpoint(method_http=self.app.get, path='/ping', method=self.ping, tags='sandbox'),
+        ]
+        return endpoints
+
+    async def ping(self, name: str = 'world'):
+        """
+
+        Parent ping endpoint.
+
+        """
+        return dict(message=f'hello {name}')
+
+    @cached_property
+    def children(self):
+        """
+
+        Immediate sandbox child APIs.
+
+        """
+        return [Child()]
+
+if __name__ == '__main__':
+    SandboxApi.launch()

corio-2.3.6/corio/shell/__init__.py

@@ -0,0 +1,3 @@
+from corio.shell.dsl import Argument, Expression, Shell, Subcommand, Value
+
+__all__ = ["Argument", "Expression", "Shell", "Subcommand", "Value"]

corio-2.3.6/corio/shell/dsl.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import shlex
+import subprocess
+
+
+def _normalize(name: str) -> str:
+    return name.strip("_").replace("_", "-")
+
+
+def _to_value(item: object) -> Value:
+    if isinstance(item, Value):
+        return item
+    if isinstance(item, Argument):
+        return Value(name=item.name)
+    return Value(name=str(item))
+
+
+def _to_subcommand_part(item: object) -> Argument:
+    if isinstance(item, Argument):
+        return item
+    if isinstance(item, Value):
+        return Argument(name=item.name)
+    return Argument(name=str(item))
+
+
+def _to_expression_part(item: object) -> Subcommand | Argument:
+    if isinstance(item, Subcommand):
+        return item
+    if isinstance(item, Argument):
+        return item
+    if isinstance(item, Value):
+        return Argument(name=item.name)
+    return Argument(name=str(item))
+
+
+def _to_argument_child(item: object) -> Argument | Value:
+    if isinstance(item, Argument):
+        return item
+    if isinstance(item, Value):
+        return item
+    return Argument(name=str(item))
+
+
+def _flatten_parts(parts: list[object]) -> list[str]:
+    return [token for part in parts for token in part.tokens()]
+
+
+@dataclass
+class Value:
+    name: str = ""
+    children: list[object] = field(default_factory=list)
+
+    def __getattr__(self, name: str) -> Value:
+        return Value(name=_normalize(name))
+
+    def tokens(self) -> list[str]:
+        return [shlex.quote(self.name)]
+
+    def __str__(self) -> str:
+        return " ".join(self.tokens())
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}('{self}')"
+
+
+@dataclass
+class Argument:
+    name: str = ""
+    prefixes: str = ""
+    children: list[Argument | Value] = field(default_factory=list)
+    sep: str = " "
+
+    def __getattr__(self, name: str) -> Argument:
+        return Argument(name=_normalize(name), prefixes=self.prefixes)
+
+    def __neg__(self) -> Argument:
+        return Argument(name=self.name, prefixes=f"-{self.prefixes}", children=list(self.children), sep=self.sep)
+
+    def __pos__(self) -> Argument:
+        return Argument(name=self.name, prefixes=f"+{self.prefixes}", children=list(self.children), sep=self.sep)
+
+    def __add__(self, other: object) -> Argument:
+        child = _to_value(other)
+        return Argument(
+            name=self.name,
+            prefixes=self.prefixes,
+            children=[*self.children, child],
+            sep=self.sep,
+        )
+
+    def __call__(self, *parts: object) -> Argument:
+        return Argument(
+            name=self.name,
+            prefixes=self.prefixes,
+            children=[*self.children, *[_to_argument_child(part) for part in parts]],
+            sep=self.sep,
+        )
+
+    def __eq__(self, other: object) -> Argument:  # type: ignore[override]
+        return Argument(
+            name=self.name,
+            prefixes=self.prefixes,
+            children=[_to_value(other)],
+            sep="=",
+        )
+
+    @property
+    def token(self) -> str:
+        return f"{self.prefixes}{shlex.quote(self.name)}"
+
+    def tokens(self) -> list[str]:
+        if not self.children:
+            return [self.token]
+        if self.sep != " ":
+            first, rest = self.children[0], self.children[1:]
+            return [f"{self.token}{self.sep}{first.tokens()[0]}", *_flatten_parts(rest)]
+        return [self.token, *_flatten_parts(self.children)]
+
+    def __str__(self) -> str:
+        return " ".join(self.tokens())
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}('{self}')"
+
+
+@dataclass
+class Subcommand:
+    name: str
+    children: list[Subcommand | Argument] = field(default_factory=list)
+    active: Subcommand = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.active = self
+
+    def add_subcommand(self, name: str) -> Subcommand:
+        child = Subcommand(name=name)
+        self.active.children.append(child)
+        self.active = child
+        return child
+
+    def __call__(self, *parts: object) -> Subcommand:
+        self.active.children.extend(_to_subcommand_part(part) for part in parts)
+        return self
+
+    def tokens(self) -> list[str]:
+        return [self.name, *_flatten_parts(self.children)]
+
+    def __str__(self) -> str:
+        return " ".join(self.tokens())
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}('{self}')"
+
+
+@dataclass
+class Expression:
+    name: str
+    shell: Shell
+    children: list[Subcommand | Argument] = field(default_factory=list)
+    active: Expression | Subcommand = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.active = self
+
+    def __getattr__(self, name: str) -> Expression:
+        command = _normalize(name)
+        if self.active is self:
+            child = Subcommand(name=command)
+            self.children.append(child)
+            self.active = child
+            return self
+        self.active = self.active.add_subcommand(command)
+        return self
+
+    def __call__(self, *parts: object) -> Expression:
+        if self.active is self:
+            self.children.extend(_to_expression_part(part) for part in parts)
+            return self
+        self.active(*parts)
+        return self
+
+    def tokens(self) -> list[str]:
+        return [self.name, *_flatten_parts(self.children)]
+
+    def popen(self) -> subprocess.Popen[str]:
+        return self.shell.popen(self)
+
+    def iterate_lines(self):
+        return self.shell.iterate_lines(self)
+
+    def __iter__(self):
+        return self.iterate_lines()
+
+    def __pos__(self):
+        return self.iterate_lines()
+
+    def __str__(self) -> str:
+        return " ".join(self.tokens())
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}('{self}')"
+
+
+@dataclass
+class Shell:
+    context: str = ""
+
+    def __getattr__(self, name: str) -> Expression:
+        return Expression(name=_normalize(name), shell=self)
+
+    def popen(self, expression: Expression) -> subprocess.Popen[str]:
+        return subprocess.Popen(
+            expression.tokens(),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+
+    def iterate_lines(self, expression: Expression):
+        process = self.popen(expression)
+        if process.stdout is not None:
+            for line in process.stdout:
+                yield line.rstrip("\n")
+        process.wait()
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}('{self.context}')"