Skip to content

trudag.dotstop.core.reference.references

Extensible classes for storing References to Artifacts

ArtifactReference 

ArtifactReference(path: str, roots: list[str])

Bases: BaseReference

An ArtifactReference references a subgraph of another Trustable project through the artifact. When publishing, an additional report will be published from this artifact, which the rendered reference will link to.

Parameters:

Name Type Description Default
path str

path of artifact file

 required
roots list[str]

roots of the subgraph

 required

BaseReference

Bases: ABC

Abstract base class for defining References to Artifacts.

Concrete subclasses of BaseReference are identified by their type property and:

  • Are expressible as a string of valid markdown using as_markdown()
  • Have a persistent sha256 checksum sha
  • Express a relationship to a specific sequence of bytes, content

content abstractmethod cached property 

content: bytes

The content of the Referenced Artifact as bytes.

sha property 

sha: str

The content of the Referenced Artifact as a sha256 checksum, formatted as a hexadecimal str.

Raises a ReferenceError if the content cannot accessed.

as_markdown abstractmethod 

as_markdown(filepath: Path | None = None) -> str

The content of the Referenced Artifact as a string of valid markdown.

The optional argument filepath is provided to allow subclasses of BaseReference to express links to other documentation or data. This is required as markdown links are always relative.

Parameters:

Name Type Description Default
filepath Path | None

Path to markdown file being written to. Defaults to None.

 None

from_dict classmethod 

from_dict(
    reference_dict: dict[str, bool | int | float | str],
) -> BaseReference

Construct a BaseReference from a dictionary with the appropriate type value.

Raises a ReferenceError if the object cannot be built.

Parameters:

Name Type Description Default
reference_dict dict[str, bool | int | float | str]

Dictionary used to construct BaseReference instance.

 required

type abstractmethod classmethod 

type() -> str

A unique human-readable identifier for the Reference.

This identifier is used by ReferenceBuilder to select the appropriate reference type. This type is usually specified in non-python contexts, such as markdown frontmatter.

FileReference

Bases: BaseReference, ABC

Abstract base class for References to Artifacts that are regular files.

Provides a concrete implementation of as_markdown().

FILE_EXTENSION_ALIASES class-attribute instance-attribute 

FILE_EXTENSION_ALIASES = {
    ".yml": ".yaml",
    ".bst": ".yaml",
    ".conf": ".txt",
}

Aliases for unusual file formats.

Each key-value pair expresses a mapping from a non-standard file extension (the key) to an extension supported by pygments (the value). This allows unusual files to be formatted correctly in a fenced markdown block.

extension abstractmethod property 

extension: str

File extension of Referenced Artifact.

as_markdown 

as_markdown(filepath: Path | None = None) -> str

The content of the Referenced Artifact as a string of valid markdown.

Supports all file formats that are supported by pygments.

Note

.csv format files are always assumed to use a comma delimiter, as the delimiter of a csv file cannot be reliably determined.

Parameters:

Name Type Description Default
filepath Path | None

Path to markdown file being written to. Defaults to None.

 None

GitlabFileReference 

GitlabFileReference(
    url: str,
    id: int | str,
    path: str,
    ref: str,
    token: str = "GITLAB_CI_TOKEN",
    public: bool = False,
    retries: int = 3,
    **kwargs,
)

Bases: FileReference

References to Artifacts that are regular files in a remote GitLab repository.

A valid gitlab access token with sufficient read permissions must be available in the current environment. Several attempts are made to get a token, with the following precedence:

  1. User-specified token argument
  2. $GITLAB_CI_TOKEN
  3. $CI_JOB_TOKEN

Parameters:

Name Type Description Default
url str

Url of gitlab instance (e.g. "gitlab.com")

 required
id int

Repository/project id (this is an integer value, unique to repository)

 required
path str

Path to the Artifact, relative to the root of the repository

 required
ref str

Tag, branch or sha

 required
token str

Environmental variable containing a suitable access token. Defaults to "GITLAB_CI_TOKEN".

 'GITLAB_CI_TOKEN'
retries int

Specify max amount of retries for request.

 3

LocalFileReference 

LocalFileReference(
    path: str, rendering: str | None = None, **kwargs
)

Bases: FileReference

References to Artifacts that are regular local files, in the git sense.

This means any regular file that is present in the git tree for the current commit of the local repository.

Parameters:

Name Type Description Default
path str

Path to the Artifact, relative to the root of the repository.

 required
rendering str

optional 'inline-{expanded,collapsible}' or codeblock-{expanded,collapsible} rendering default: 'inline-collapsible'

 None

ResolvedReference dataclass 

ResolvedReference(
    type_: str,
    sha: str | None,
    origin: str,
    text_content: str,
    metadata: dict,
    logs: list[str] = list(),
)

An immutable data structure for a reference that has been resolved.

SourceSpanReference 

SourceSpanReference(path: str, span: list[tuple[int, int]])

Bases: BaseReference, ABC

References to a span of source code in the repository.

Should be used as the base class for your own reference types that find the span of the references source code at reference-time - say, by looking up a function name.

Parameters:

Name Type Description Default
path str

Path to the source file, relative to the root of the repository.

 required
span list[tuple[int, int]]

list of two 2-tuples. The tuples are the start and end [line, character] positions spanning the code we wish to reference.

 required

language abstractmethod classmethod 

language() -> str

The markdown name of the language of the source code you are referencing.

csv_to_markdown_table 

csv_to_markdown_table(
    csv: str, delimiter: str = ","
) -> str

Given a string in csv format, return the data formatted as a GitLab-flavoured-markdown table.

Parameters:

Name Type Description Default
csv str

Data to write as a table.

 required
delimiter str

Character used as the column delimiter. Defaults to ",".

 ','