Traceback#

Description#

Build a traceback tree for a wrapp file, following both source and repository paths.

Package Ancestry#

Each package records two pointers to trace its ancestry:

  1. The source pointer is set on create to point to the root directory of the create operation.

  2. The repository pointer is set on create to point to the target repository, updated on install to point to the source repository, and updated on mirror to point to the source repository.

This allows tracing the origin of an install or mirror operation via the repository pointer, and finding the original source directory via the source pointer. Repeated install/create cycles can be traced back through multiple repositories as long as no intermediate packages are deleted.

The traceback command produces a user-friendly inheritance tree by following these pointers.

Reported Cases#

The following cases can be reported by traceback:

  • Primary source at {wrapp_file}.

  • Primary source folder (no package file) {wrapp_dir}.

  • Intermediate source installed at {wrapp_file}.

  • Primary repository at {wrapp_file}.

  • Mirror repository at {wrapp_file}.

  • Source without repository pointer at {wrapp_file}. This is considered a data error.

  • Could not find wrapp file in repository at {wrapp_file}. This is flagged as an error.

  • Source package missing: Could not find wrapp file at {wrapp_file}. This is flagged as an error.

  • Circular reference detected: {wrapp_file} has already been visited. This is considered a data error.

For CLI options, run wrapp traceback --help.

Python API Reference#

wrapp.traceback#

async wrapp.traceback(
wrapp_file: str,
visited_paths: Set[str] | None = None,
) → TracebackNode

Build a traceback tree for a wrapp file, following both source and repository paths.

Parameters:

  • wrapp_file – Path to the wrapp file to traceback

  • visited_paths – Set of already visited paths to prevent circular references

Returns:

A TracebackNode representing the root of the traceback tree

wrapp.TracebackNode#

The traceback function returns a tree of wrapp.TracebackNode objects:

class wrapp.TracebackNode(
package_location_type: PackageLocationType,
path: str,
message: str = '',
source: TracebackNode | None = None,
repository: TracebackNode | None = None,
is_error=False,
)

Represents a node in the traceback tree.

package_location_type

The type of package location, defined by the PackageLocationType enum

path

The path to the wrapp file

message

Human readable description of the wrapp file location found

source

Optional pointer to the TracebackNode pointed to by the source field

repository

Optional pointer to the TracebackNode pointed to by the repository field

wrapp.PackageLocationType#

Each node contains a location type:

class wrapp.PackageLocationType(
value,
names=None,
*,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)

Enum to classify the location of the wrapp file in a traceback chain

Values:

REPOSITORY - the wrapp file is located in a repository (a subfolder with version and package name within a .packages hierarchy) SOURCE - the wrapp file is located in a non-repository folder ERROR - the data contains a validation error, and it can not be correctly classified