ckanext-flakes

用于创建和管理独立数据块的工具。

此扩展提供了一个用于存储任意数据的基实体。它可以用在多种情况下，特别是如果您还没有创建全新的模型、数据库迁移和表，但又没有其他选择。

ckanext-flakes 为您提供了一组创建和管理小型字典样对象（任何可以序列化为JSON的东西）的操作。如果您正在使用它并想添加额外的操作，请随意创建一个带有您的建议的PR或问题。

结构

• 示例
• 示例插件
• 要求
• 安装
• 配置
• 接口
• API
  • flakes_flake_create
  • flakes_flake_show
  • flakes_flake_list
  • flakes_flake_update
  • flakes_flake_override
  • flakes_flake_delete
  • flakes_flake_lookup
  • flakes_flake_validate
  • flakes_data_validate
  • flakes_data_example
  • flakes_flake_materialize
  • flakes_flake_combine
  • flakes_flake_merge
  • flakes_data_patch
  • flakes_extras_patch

示例

创建记录集合

场景：用户需要一个待办事项列表

任何用户创建的Flakes只能被此用户看到，因此Flakes可以用作私有数据的存储。

雪花可以有额外信息，这些信息充当标签的角色。额外信息由字典表示，当用户列出他的雪花时，他可以选择只查看包含特定数据的雪花。

flake_create = tk.get_action("flakes_flake_create")
flake_list = tk.get_action("flakes_flake_create")

# create an urgent taks
flake_create(
    {"user": "john"},
    {"data": {"task": "feed the cat"}, "extras": {"when": "today", "type": "task"}}
)

# create a couple of tasks that can wait
flake_create(
    {"user": "john"},
    {"data": {"task": "buy food"}, "extras": {"when": "tomorrow", "type": "task"}}
)
flake_create(
    {"user": "john"},
    {"data": {"task": "update documentation"}, "extras": {"when": "tomorrow", "type": "task"}}
)

# list all the tasks
flake_list(
    {"user": "john"},
    {"extras": {"type": "task"}}
)

# list all the urgent tasks
flake_list(
    {"user": "john"},
    {"extras": {"type": "task", "when": "today"}}
)

# list all the tasks for tomorrow
flake_list(
    {"user": "john"},
    {"extras": {"type": "task", "when": "tomorrow"}}
)

为每个用户单独保存选项的值

场景：每个用户都可以设置应用程序的主题，并且该主题只会应用于当前用户。

用户A的雪花是从上下文中创建的，用户A的雪花只能被用户A看到；用户B的雪花存在于不同的命名空间中，并且只能被用户B看到。

每个雪花可以有一个名称。名称必须在用户的所有雪花中是唯一的。但不同的用户可以为他们的雪花使用相同的名称，因为每个用户都有自己的雪花命名空间。

雪花可以通过flakes_flake_create操作（接受可选的名称，如果名称不唯一则引发异常）或flakes_flake_override（需要一个名称，如果名称未被占用则创建新的雪花，如果已被某些雪花使用则更新现有雪花）来创建。

要获取雪花，请使用带有雪花id的flakes_flake_show或带有雪花名称的flakes_flake_lookup。

# set a theme for John
tk.get_action("flakes_flake_override")(
    {"user": "john"},
    {"name": "application:theme", "data": {"theme": "dark"}}
)

# set a theme for Mary
tk.get_action("flakes_flake_override")(
    {"user": "mary"},
    {"name": "application:theme", "data": {"theme": "light"}}
)


# get the value from the flake
john_theme = tk.get_action("flakes_flake_lookup")(
    {"user": "john"},
    {"name": "application:theme"}
)["data"]["theme"]

mary_theme = tk.get_action("flakes_flake_lookup")(
    {"user": "mary"},
    {"name": "application:theme"}
)["data"]["theme"]

assert john_theme == "dark"
assert mary_theme == "light"

创建和获取全局变量

场景：应用程序需要全局选项，该选项可以在运行时更改。

默认情况下，雪花是在当前用户的“命名空间”中创建的。只有作者可以看到并修改他自己的雪花。

全局值不应归任何人所有，因此这里需要一个“无主”雪花——即不与特定用户关联的雪花。只有系统管理员可以创建这样的雪花，因此我们将使用上下文的ignore_auth=True属性。

我们将使用flakes_flake_override操作，它接受雪花的名称，要么更新具有此名称的现有雪花，要么在名称空闲时创建新的雪花。这样我们可以避免全局雪花的重复。

# create a flake
tk.get_action("flakes_flake_override")(
    {"ignore_auth": True}, # only syadmin allowed to create unowned flakes with empty author id
    {"name": "global:config:value", "data": {"value": 1}, "author_id": None}
)

# get the value from the flake
value = tk.get_action("flakes_flake_lookup")(
    {"ignore_auth": True},
    {"name": "global:config:value", "author_id": None}
)["data"]["value"]

示例插件

这些插件实现了基本功能，可以用作ckanext-flakes使用的真实示例。

flakes_rating

用户可以通过API操作对包进行评分。将ckanext.flakes_rating.show_package_widget = true添加到配置中，默认小部件将添加到dataset.read页面侧边栏。

flakes_feedback

用户可以通过API操作为包留下反馈。将ckanext.flakes_feedback.enable_views = true添加到配置中，默认页面将添加到dataset.read页面的导航标签中。

要求

需要Python 3.7或更高版本。Python 2的支持不需要太多努力，但它既不值得你花费的时间。

与核心CKAN版本兼容性

安装

安装ckanext-flakes

1. 通过pip安装

   pip install ckanext-flakes
   

2. 将flakes添加到CKAN配置文件中的ckan.plugins设置。
3. 运行数据库迁移

   ckan db upgrade -p flakes
   

配置

# Any user can create a new flake.
# (optional, default: true)
ckanext.flakes.creation.allowed = false

# Any user can validate flake or plain data.
# (optional, default: false)
ckanext.flakes.validation.allowed = true

接口

提供ckanext.flakes.interfaces.IFlakes接口。实现时始终使用inherit=True，因为它可能在将来发生变化。

目前它提供了以下钩子

class IFlakes(Interface):
    """Extend functionality of ckanext-flakes"""

    def get_flake_schemas(self) -> dict[str, dict[str, Any]]:
        """Register named validation schemas.

        Used by `flakes_flake_validate` and `flakes_data_validate` actions.

        Returns:
            Mapping of names and corresponding validation schemas.

        Example:
            def get_flake_schemas(self) -> dict[str, dict[str, Any]]:
                return {
                    "schema-that-requires-name": {"name": [not_missing]}
                }
        """
        return {}

    def get_flake_factories(self) -> dict[str, Callable[[dict[str, Any]], dict[str, Any]]]:
        """Register named example factories.

        Used by `flakes_data_example` action.

        Returns:
            Mapping of names and corresponding example factories.

        Example:
            def get_flake_factories(self) -> dict[str, dict[str, Any]]:
                def factory(payload: dict[str, Any]):
                    return {"field": "value"}

                return {
                    "test-factory": factory
                }
        """
        return {}

API

flakes_flake_create

创建一个雪花。

参数

name (str, optional): name of the flake
data (dict): flake's data
parent_id (str, optional): ID of flake to extend
author_id (str, optional): author ID(can be set only by sysadmin)
extras (dict): flake's extra details

flakes_flake_show

显示现有雪花

参数

id (str): ID of flake to display
expand (bool, optional): Extend flake using data from the parent flakes

flakes_flake_list

显示用户的所有雪花。

如果传递了额外信息字典，则只显示包含给定额外信息的雪花。示例

first_flake = Flake(extras={"xxx": {"yyy": "hello"}})
second_flake = Flake(extras={"xxx": {"yyy": "world"}})

flake_list(context, {"extras": {"xxx": {"yyy": "hello"}})
>>> first_flake

参数

expand (bool, optional): Extend flake using data from the parent flakes
extras (dict, optional): Show only flakes whose extras contains passed dict
author_id (str, optional): author ID(can be set only by sysadmin)

flakes_flake_update

更新现有雪花

参数

id (str): ID of flake to update
data (dict): flake's data
parent_id (str, optional): ID of flake to extend
extras (dict): flake's extra details

flakes_flake_override

通过名称更新现有雪花或创建一个新的雪花。

参数

name (str): Name flake to override
data (dict): template itself
parent_id (str, optional): ID of flake to extend
author_id (str, optional): author ID(can be set only by sysadmin if flake does not exist)
extras (dict): flake's extra details

flakes_flake_delete

删除现有雪花

参数

id (str): ID of flake to delete

flakes_flake_lookup

使用名称显示雪花。

参数

name (str): Name of the flake
expand (bool, optional): Extend flake using data from the parent flakes
author_id (str, optional): author ID(can be set only by sysadmin)

flakes_flake_validate

验证现有雪花

必须通过IFlakes接口注册模式。

参数

id (str): ID of flake to validate
expand (bool, optional): Extend flake using data from the parent flakes
schema(str): validation schema for the flake's data

flakes_data_validate

验证与命名模式（通过IFlakes注册）的任意数据。

参数

data (dict): data that needs to be validated
schema(str): validation schema for the data

flakes_data_example

使用命名工厂（通过IFlakes注册）生成雪花的示例数据。

必须通过IFlakes接口注册工厂。

参数

factory(str): example factory
data (dict, optional): payload for the example factory

flakes_flake_materialize

将雪花的数据发送到API操作。

参数

id (str): ID of flake to materialize
expand (bool, optional): Extend flake using data from the parent flakes
remove (bool, optional): Remove flake after materialization
action (str): API action to use for materialization

flakes_flake_combine

组合多个雪花的从数据。

id 参数指定必须组合的所有碎片。所有碎片都必须存在，否则会引发 NotFound 错误。列表开头的 ID 具有更高的优先级（会覆盖匹配的键）。列表末尾的 ID 具有较低的优先级（可以被前面的碎片覆盖）。

expand 必须是 dict[str, bool] 类型。键是碎片的 ID，值是对应碎片的展开标志。

参数

id (list): IDs of flakes.
expand (dict, optional): Extend flake using data from the parent flakes

flakes_flake_merge

组合多个碎片并保存结果。

参数

id (list): IDs of flakes.
expand (dict, optional): Extend flake using data from the parent flakes
remove (bool, optional): Remove flakes after the operation.
destination (str, optional): Save data into the specified flake instead of a new one

flakes_data_patch

部分覆盖数据，保留其他字段。

参数

id (str): ID of flake
data (dict): patch for data

flakes_extras_patch

部分覆盖额外信息，保留其他字段。

参数

id (str): ID of flake
extras (dict): patch for extras

开发者安装

为了开发安装 ckanext-flakes，激活您的 CKAN 虚拟环境并执行

git clone https://github.com/DataShades/ckanext-flakes.git
cd ckanext-flakes
python setup.py develop

测试

要运行测试，请执行

pytest

许可证

AGPL