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