Programs and catalogues · API reference

new type

`Program`

Program = typ.NewType('Program', str)

class

`ProgramCatalogue`

cuprum/catalogue.py

class ProgramCatalogue(
    *,
    projects: cabc.Iterable[ProjectSettings],
) -> None

Catalogue of curated programs with a default allowlist.

7 members

classmethod ProgramCatalogue.from_programs

def from_programs(
    *programs: Program | str,
    name: str | None = None,
    documentation_locations: tuple[str, ...] = (),
    noise_rules: tuple[str, ...] = (),
) -> ProgramCatalogue

Build a single-project catalogue from the given programs.

Parameters

*programs Program | str: Programs to allowlist; bare names and absolute paths are accepted.
name str | None, optional: Project name, derived from the programs' base names when omitted.
documentation_locations tuple[str, ...], optional: Documentation references for the project.
noise_rules tuple[str, ...], optional: Regular expressions for output lines a logger may drop.

Returns

ProgramCatalogue: A catalogue whose sole project owns the supplied programs.

Raises

ValueError: If no programs are supplied.
DuplicateProgramError: If a program is supplied more than once.

Examples

>>> from cuprum import ProgramCatalogue
>>> catalogue = ProgramCatalogue.from_programs("git", "cargo")
>>> sorted(catalogue.allowlist)
['cargo', 'git']
>>> catalogue.lookup("git").project_name
'git-cargo'

classmethod ProgramCatalogue.from_project

def from_project(settings: ProjectSettings) -> ProgramCatalogue

Build a catalogue containing a supplied project.

Parameters

settings ProjectSettings: The sole project to register.

Returns

ProgramCatalogue: A catalogue exposing the supplied project's allowlist and metadata.

Raises

DuplicateProgramError: If settings declares a program more than once.

Examples

>>> from cuprum import Program, ProgramCatalogue, ProjectSettings
>>> settings = ProjectSettings(name="tools", programs=(Program("git"),))
>>> ProgramCatalogue.from_project(settings).is_allowed("git")
True

property ProgramCatalogue.allowlist

allowlist: frozenset[Program]

The curated allowlist of programs.

Returns

frozenset[Program]: Every program registered in the catalogue. The returned set cannot be modified.

method ProgramCatalogue.is_allowed

def is_allowed(program: Program | str) -> bool

Return True when the program is part of the default allowlist.

Parameters

program Program | str: The program to test against the curated default allowlist.

Returns

bool: True if the program is present in the curated allowlist.

method ProgramCatalogue.lookup

def lookup(program: Program | str) -> ProgramEntry

Resolve a program into its entry, blocking unknown executables.

Parameters

program Program | str: The program to resolve into its catalogue entry.

Returns

ProgramEntry: The resolved entry with its owning project metadata.

Raises

UnknownProgramError: If the program is not present in the catalogue allowlist.

method ProgramCatalogue.project_for

def project_for(program: Program | str) -> ProjectSettings

Return the owning project for the given program.

Parameters

program Program | str: The program whose owning project is returned.

Returns

ProjectSettings: The project that owns the given program.

Raises

UnknownProgramError: If the program is not present in this catalogue.

property ProgramCatalogue.visible_settings

visible_settings: _VisibleSettings

Cached, read-only settings indexed by project name.

Returns

_VisibleSettings: The same immutable mapping for the catalogue lifetime. Access it as a property; calling it remains a temporary compatibility form.

class

`ProgramEntry`

cuprum/catalogue.py

class ProgramEntry(program: Program, project: ProjectSettings)

A resolved program with its owning project metadata.

3 members

field ProgramEntry.program

program: Program

field ProgramEntry.project

project: ProjectSettings

property ProgramEntry.project_name

project_name: str

The owning project's name.

Returns

str: The name of the project that registered this program.

class

`ProjectSettings`

cuprum/catalogue.py

class ProjectSettings(
    name: str,
    programs: tuple[Program, ...],
    documentation_locations: tuple[str, ...] = (),
    noise_rules: tuple[str, ...] = (),
)

Metadata shared by a project's curated programs.

documentation_locations and noise_rules default to empty tuples so a small script can declare a project from its name and programs alone.

Attributes

name str: The project's descriptive name.
programs tuple[Program, ...]: Curated programs owned by the project.
documentation_locations tuple[str, ...]: Runbook/reference links visible through visible_settings. Empty means no documentation references are declared.
noise_rules tuple[str, ...]: Patterns a logger may drop; Cuprum stores them but does not apply them. Empty means no project output lines are marked as noise.

5 members

field ProjectSettings.name

name: str

field ProjectSettings.programs

programs: tuple[Program, ...]

field ProjectSettings.documentation_locations

documentation_locations: tuple[str, ...]

field ProjectSettings.noise_rules

noise_rules: tuple[str, ...]

method ProjectSettings.owns

def owns(program: Program) -> bool

Return True when the program belongs to this project.

Parameters

program Program: The program to test for membership in this project.

Returns

bool: True if the program is one of this project's programs.

constant

`DEFAULT_CATALOGUE`

cuprum/catalogue.py

DEFAULT_CATALOGUE = ProgramCatalogue(projects=DEFAULT_PROJECTS)

constant

`DEFAULT_PROJECTS`

cuprum/catalogue.py

DEFAULT_PROJECTS = tuple((ProjectSettings(name=name, programs=programs, documentation_locations=documentation_locations, noise_rules=noise_rules) for name, programs, documentation_locations, noise_rules in DEFAULT_PROJECT_DATA))

constant

`CORE_OPS_PROJECT`

cuprum/_catalogue_defaults.py

CORE_OPS_PROJECT = 'core-ops'

constant

`DOCUMENTATION_PROJECT`

cuprum/_catalogue_defaults.py

DOCUMENTATION_PROJECT = 'docs'

constant

`ECHO`

cuprum/_catalogue_defaults.py

ECHO = Program('echo')

constant

`GIT`

cuprum/_catalogue_defaults.py

GIT = Program('git')

constant

`LS`

cuprum/_catalogue_defaults.py

LS = Program('ls')

constant

`RSYNC`

cuprum/_catalogue_defaults.py

RSYNC = Program('rsync')

constant

`TAR`

cuprum/_catalogue_defaults.py

TAR = Program('tar')

constant

`DOC_TOOL`

cuprum/_catalogue_defaults.py

DOC_TOOL = Program('mdbook')

constant

`PACKAGE_NAME`

cuprum/_constants.py

PACKAGE_NAME = 'cuprum'

module

`cuprum.catalogue`

cuprum/catalogue.py

from cuprum import catalogue

Curated catalogue of allowed executables and their metadata.

Example: >>> from cuprum.catalogue import DEFAULT_CATALOGUE, ECHO >>> entry = DEFAULT_CATALOGUE.lookup(ECHO) >>> (entry.project_name, entry.program) ('core-ops', 'echo')

2 exports

exception cuprum.catalogue.DuplicateProgramError

class DuplicateProgramError(program: Program, owner: str) -> None

Raised when a program is claimed by more than one project.

Parameters

program Program: The contested program.
owner str: The name of the project that already owns the program.

Attributes

program Program: The contested program.
owner str: The existing owner's project name.

exception cuprum.catalogue.DuplicateProjectError

class DuplicateProjectError(project_name: str) -> None

Raised when a project name is registered more than once.

Parameters

project_name str: The duplicated project name.

Attributes

project_name str: The duplicated project name.