Project Metadata

Overview

cikit provides a compact project metadata model for values that are needed consistently across CI commands, generated files, and documentation.

The resolved metadata combines two sources:

• static project information from pyproject.toml

• runtime CI and Git information from the active CiEnvironment

The result is represented by ProjectMeta.

Typical resolved values include:

• project name and description

• project version

• author and license

• pipeline and provider information

• branch and commit metadata

• normalized version components

• build date information

• revision and release strings

Project File

The currently supported project metadata file is:

pyproject.toml

find_project_file() searches from the given path, or the current working directory, upwards through its parent directories until it finds the nearest pyproject.toml.

If no supported project file can be found, cikit raises an error.

The detected path is also exposed by the environment as:

env["PROJECT_FILE"]

Project Root

The project root is defined as the directory containing the detected pyproject.toml.

This keeps project metadata discovery and PROJECT_ROOT resolution based on the same source.

For details of environment path handling, see Environment.

pyproject.toml Metadata

cikit reads its base metadata from the standard [project] table.

For example:

[project]
name = "demo"
version = "1.2.3"
description = "Example project"
authors = [
    { name = "Sven", email = "sven@example.com" }
]
license = "GPL-3.0-or-later"

The project.name field is required.

The following values are currently extracted:

Metadata key	Source
project_name	project.name
description	project.description
version	project.version
license	project.license
project_author	Name of the first entry in project.authors
project_author_email	Email of the first entry in project.authors
project_file	Project file path used for loading
project_file_type	pyproject

Only the first author entry is currently used by ProjectMeta.

Dynamic Version

PEP 621 allows project metadata such as version to be declared as dynamic:

[project]
name = "demo"
dynamic = ["version"]

In this case the version is expected to be provided by another build or packaging mechanism.

cikit currently does not resolve such dynamically provided versions. If version is listed in project.dynamic, the resolved ProjectMeta contains an empty version value.

Without an explicit tool.cikit.revision_name, revision resolution then falls back to the short commit hash.

The numeric version components also default to zero unless they are supplied through explicit metadata overrides.

cikit-specific Metadata

Additional metadata can be configured in [tool.cikit].

The currently supported values are:

[tool.cikit]
data_scope = "svesch"
revision_name = "rev-1"
build_number = 42

data_scope optionally prefixes the cikit data project key. With project.name = "cikit" and data_scope = "svesch", the resulting key is svesch/cikit. Without a scope, the key remains cikit.

revision_name provides an explicit human-readable revision identifier.

build_number provides an explicit numeric build value and also becomes the fourth component of release_string.

Runtime Metadata

build_project_meta() combines project metadata with information from the active environment.

Example:

from cikit import build_project_meta

meta = build_project_meta(env)

The following runtime values are added:

Metadata key	Environment source
pipeline_id	env.pipeline_id
pipeline_alias	env.pipeline_alias
project_root	env["PROJECT_ROOT"]
ci_provider	str(env.provider)
branch_name	env.branch_name
commit_hash	env.commit_sha
commit_short_hash	env.commit_short_sha
commit_title	env.commit_title
commit_message	env.commit_message
commit_author	env.commit_author
commit_timestamp	env.commit_timestamp

Provider-specific details are described in Providers.

Version Components

The configured project version is parsed into four numeric components:

major
minor
patch
build

For example:

version = 1.2.3
-> major = 1
-> minor = 2
-> patch = 3
-> build = 0

The parser extracts numeric components from the version string and uses the first four numbers it finds.

Missing components default to 0.

For example:

1.2
-> 1.2.0.0

1.2.3.4
-> 1.2.3.4

The original version string is preserved separately as version.

Build Number

build_number is a normalized integer used as CI/build metadata.

Its resolution follows this order:

1. Use tool.cikit.build_number when it is configured and non-zero.

2. Otherwise derive build_number from pipeline_id.

3. Values that cannot be converted to an integer become 0.

For example, with:

version = 1.2.3
pipeline_id = 123

the resolved values are:

build_number = 123
release_string = 1.2.3.0

The pipeline-derived build_number does not automatically replace the build component parsed from the project version.

An explicit cikit build number does:

[project]
version = "1.2.3"

[tool.cikit]
build_number = 42

This results in:

build_number = 42
release_string = 1.2.3.42

Revision Name

revision_name is resolved in this order:

1. tool.cikit.revision_name

2. project version

3. commit_short_hash

Release String

release_string is the normalized four-component numeric version:

major.minor.patch.build

For example:

1.2.3.0
1.2.3.42

Revision String

revision_string is assembled from:

• project name

• revision name

• short commit hash

• build date

Conceptually:

<project_name> <revision_name>, <commit_short_hash> <build_date>

Empty components are omitted.

Build Date Metadata

Metadata resolution adds:

Key	Meaning
build_date	Compact date in YYMMDD form.
build_year	Four-digit year.
build_month	Numeric month.
build_day	Numeric day.

ProjectMeta

ProjectMeta provides properties for commonly used values:

meta.project_name
meta.description
meta.version
meta.revision_name
meta.revision_string
meta.release_string
meta.commit_short_hash
meta.build_number
meta.project_author
meta.license

Additional metadata is available through:

value = meta.get("pipeline_alias")

The complete mapping can be obtained with:

data = meta.as_dict()

as_dict() returns a copy.

Overrides

build_project_meta() accepts explicit overrides:

meta = build_project_meta(
    env,
    {
        "revision_name": "manual",
        "build": 9,
    },
)

Overrides are applied after project and environment metadata have been resolved.

If build is overridden without build_number, cikit synchronizes both values. An explicit build_number override also updates the numeric build component.

Template Rendering

ProjectMeta renders ${name} placeholders:

text = meta.render(
    "Project ${project_name} ${release_string}"
)

Unknown placeholders raise an error instead of remaining unresolved.

Generating Files

Rendered metadata can be written directly:

meta.render_to_file(
    env,
    output_file,
    '#define PROJECT_NAME "${project_name}"',
)

A template file can also be used:

meta.render_to_file_from_template_file(
    env,
    output_file,
    template_file,
)

Parent directories are created automatically.

The implementation is intended to register generated files as METADATA artifacts so they can participate in the common artifact mechanism.

For artifact storage and lookup semantics, see Artifacts.

Sphinx Integration

The cikit documentation uses ProjectMeta in docs/conf.py:

from cikit import build_project_meta
from cikit.macros import init_env

env = init_env()
meta = build_project_meta(env)

project = meta.project_name
author = meta.project_author
release = meta.release_string
version = meta.version or meta.release_string

The resolved metadata is also used for substitutions such as:

|project|
|version|
|author|
|license|
|commit|

Metadata Responsibilities

Layer	Examples	Source
Project metadata	Name, version, author, license	pyproject.toml
cikit metadata	Revision name, build number	[tool.cikit]
CI metadata	Pipeline id and alias	Active provider
Git metadata	Branch, commit hash, author	Active provider
Derived metadata	Release string, revision string, build date	build_project_meta()

See Also

• Environment

• Providers

• Artifacts