flowshow 项目启动与配置教程

flowshow 项目启动与配置教程

flowshow Just a super thin wrapper for Python tasks that form a flow. 项目地址: https://gitcode.com/gh_mirrors/fl/flowshow

1. 项目目录结构及介绍

flowshow 项目是一个用于创建和管理 Python 任务流的轻量级包装器。以下是项目的目录结构及其说明：

flowshow/
├── .github/          # GitHub 工作流文件
│   └── workflows/
├── docs/             # 文档目录
├── flowshow/         # 包含 flowshow 的核心代码
├── imgs/             # 存储图像资源
├── tests/            # 测试代码目录
├── .gitignore        # 指定 Git 忽略的文件
├── LICENSE           # MIT 许可证文件
├── Makefile          # Makefile 文件，用于构建和测试项目
├── README.md         # 项目自述文件
├── demo.py           # 演示如何使用 flowshow 的示例脚本
├── pyproject.toml    # 项目元数据文件
└── uv.lock           # 用于缓存依赖的文件

• .github/workflows/：存放 GitHub Actions 的配置文件，用于自动化项目的一些流程，例如自动运行测试。
• docs/：存放项目的文档。
• flowshow/：包含项目的主要代码。
• imgs/：存放项目所需的图像资源。
• tests/：存放测试代码，用于验证项目功能的正确性。
• .gitignore：定义了哪些文件和目录应该被 Git 忽略。
• LICENSE：项目的 MIT 许可证。
• Makefile：可以包含构建项目或运行测试的命令。
• README.md：项目的说明文档，介绍了项目的基本信息和如何使用。
• demo.py：一个示例脚本，展示了如何使用 flowshow。
• pyproject.toml：包含项目元数据，如项目名称、版本和依赖。
• uv.lock：用于缓存项目依赖。

2. 项目的启动文件介绍

项目的启动主要是通过运行 demo.py 脚本来完成的。以下是 demo.py 的基本内容：

import time
import random
from pydantic import BaseModel
from typing import List
from flowshow import task, add_artifacts, info, debug, warning, error, span

# 定义一些模型
class Foobar(BaseModel):
    x: int
    y: int
    saying: str

class ManyBar(BaseModel):
    desc: str
    stuff: List[Foobar]

# 定义一些任务
@task
def my_function(x):
    info("This function should always run")
    time.sleep(0.2)
    add_artifacts(foo=1, bar=2, buz={"hello": "there"})
    return x * 2

@task(retry_on=ValueError, retry_attempts=5)
def might_fail():
    info("This function call might fail")
    time.sleep(0.2)
    my_function(2)
    # raise ValueError("oh noes")
    debug("The function has passed! Yay!")
    return "done"

@task
def main_job():
    info("This output will be captured by the task")
    add_artifacts(manybar=ManyBar(desc="hello", stuff=[Foobar(x=1, y=2, saying="ohyes")]))

    with span("hello") as s:
        info("test test")

    with span("foobar") as f:
        info("whoa whoa")

    for i in range(3):
        my_function(10)
        might_fail()

    return "done"

# 运行主任务
_ = main_job()

在终端中，可以通过以下命令运行 demo.py：

python demo.py

这将会执行定义的任务，并在终端中显示相关的日志信息。

3. 项目的配置文件介绍

flowshow 项目的配置主要通过 pyproject.toml 文件进行。以下是 pyproject.toml 的一个示例：

[build-system]
requires = ["setuptools", "wheel"]

[tool.setuptools]
packages = find:
python_requires = ">=3.7"

在这个配置文件中，我们定义了以下内容：

• build-system：指定构建系统需要的依赖，这里是 setuptools 和 wheel。
• tool.setuptools：指定打包工具的配置，例如自动查找包和指定 Python 版本要求。

如果需要安装项目依赖，可以使用以下命令：

pip install .

这将安装 pyproject.toml 文件中指定的所有依赖项。

flowshow Just a super thin wrapper for Python tasks that form a flow. 项目地址: https://gitcode.com/gh_mirrors/fl/flowshow