Package

Load, inspect, and test conda packages.

You can import the package classes from rattler_build:

from rattler_build import Package, PythonTest, CommandsTest, PackageContentsTest, TestResult

The tests property returns a list of test objects that can be pattern matched (Python 3.10+):

for test in pkg.tests:
    match test:
        case PythonTest() as py_test:
            print(f"Python imports: {py_test.imports}")
        case CommandsTest() as cmd_test:
            print(f"Commands: {cmd_test.script}")
        case PackageContentsTest() as pc_test:
            print(f"Package contents check, strict={pc_test.strict}")

Package

A loaded conda package for inspection and testing.

This class provides access to package metadata, file contents, and embedded tests. The package is lazily extracted when needed (e.g., when accessing files or tests).

Attributes:

Name	Type	Description
name	str	Package name (e.g., "numpy")
version	str	Package version (e.g., "1.26.0")
build_string	str	Build string (e.g., "py312_0")
build_number	int	Build number
subdir	str | None	Target platform subdirectory (e.g., "linux-64", "noarch")
noarch	str | None	NoArch type (None, "python", or "generic")
depends	list[str]	List of runtime dependencies
constrains	list[str]	List of dependency constraints
license	str | None	Package license
license_family	str | None	License family
timestamp	datetime | None	Build timestamp as a datetime object
arch	str | None	Architecture (e.g., "x86_64")
platform	str | None	Platform (e.g., "linux")
path	Path	Path to the package file
archive_type	str	Archive format ("conda" or "tar.bz2")
filename	str	Filename of the package
files	list[str]	List of all files in the package
tests	list[PackageTestType]	List of tests embedded in the package

name property

name

Package name.

version property

version

Package version.

build_string property

build_string

Build string (e.g., "py312_0").

build_number property

build_number

Build number.

subdir property

subdir

Target platform subdirectory (e.g., "linux-64", "noarch").

noarch property

noarch

NoArch type (None, "python", or "generic").

depends property

depends

List of runtime dependencies.

constrains property

constrains

List of dependency constraints.

license property

license

Package license.

license_family property

license_family

License family.

timestamp property

timestamp

Build timestamp as a datetime object (UTC timezone-aware).

arch property

arch

Architecture (e.g., "x86_64").

platform property

platform

Platform (e.g., "linux").

path property

path

Path to the package file.

archive_type property

archive_type

Archive format ("conda" or "tar.bz2").

filename property

filename

Filename of the package (e.g., "numpy-1.26.0-py312_0.conda").

files property

files

List of all files in the package.

tests property

tests

List of tests embedded in the package.

Returns a list of test objects that can be pattern matched:

for test in pkg.tests:
    match test:
        case PythonTest() as py_test:
            print(f"imports: {py_test.imports}")
        case CommandsTest() as cmd_test:
            print(f"script: {cmd_test.script}")
        case PackageContentsTest() as pc_test:
            print(f"strict: {pc_test.strict}")

test_count property

test_count

Get the number of tests in the package.

from_file classmethod

from_file(path)

Load a package from a .conda or .tar.bz2 file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the package file	required

Returns:

Type	Description
Package	A Package object for inspection and testing

Raises:

Type	Description
RattlerBuildError	If the package cannot be loaded or parsed

Example

pkg = Package.from_file("numpy-1.26.0-py312_0.conda")
print(pkg.name)
# numpy

run_test

run_test(
    index,
    *,
    channel=None,
    channel_priority=None,
    debug=False,
    auth_file=None,
    allow_insecure_host=None,
    compression_threads=None,
    use_bz2=True,
    use_zstd=True,
    use_sharded=True,
)

Run a specific test by index.

Parameters:

Name	Type	Description	Default
index	int	Index of the test to run (0-based)	required
channel	Sequence[str] | None	List of channels to use for dependencies	None
channel_priority	Literal['disabled', 'strict', 'flexible'] | None	Channel priority ("disabled", "strict", or "flexible")	None
debug	bool	Enable debug mode (keeps test environment)	False
auth_file	str | Path | None	Path to authentication file	None
allow_insecure_host	Sequence[str] | None	List of hosts to allow insecure connections	None
compression_threads	int | None	Number of compression threads	None
use_bz2	bool	Enable bz2 repodata	True
use_zstd	bool	Enable zstd repodata	True
use_sharded	bool	Enable sharded repodata	True

Returns:

Type	Description
TestResult	TestResult with success status and output

Raises:

Type	Description
RattlerBuildError	If the test index is out of range or test execution fails

Example

result = pkg.run_test(0, channel=["conda-forge"])
if result.success:
    print("Test passed!")

run_tests

run_tests(
    *,
    channel=None,
    channel_priority=None,
    debug=False,
    auth_file=None,
    allow_insecure_host=None,
    compression_threads=None,
    use_bz2=True,
    use_zstd=True,
    use_sharded=True,
)

Run all tests in the package.

Parameters:

Name	Type	Description	Default
channel	Sequence[str] | None	List of channels to use for dependencies	None
channel_priority	Literal['disabled', 'strict', 'flexible'] | None	Channel priority ("disabled", "strict", or "flexible")	None
debug	bool	Enable debug mode (keeps test environment)	False
auth_file	str | Path | None	Path to authentication file	None
allow_insecure_host	Sequence[str] | None	List of hosts to allow insecure connections	None
compression_threads	int | None	Number of compression threads	None
use_bz2	bool	Enable bz2 repodata	True
use_zstd	bool	Enable zstd repodata	True
use_sharded	bool	Enable sharded repodata	True

Returns:

Type	Description
list[TestResult]	List of TestResult objects, one per test

Example

results = pkg.run_tests(channel=["conda-forge"])
for r in results:
    status = "PASS" if r.success else "FAIL"
    print(f"Test {r.test_index}: {status}")

to_dict

to_dict()

Convert package metadata to a dictionary.

TestResult

Result of running a test.

Attributes:

Name	Type	Description
success	bool	Whether the test passed
output	list[str]	Test output/logs
test_index	int	Index of the test that was run

success property

success

Whether the test passed.

output property

output

Test output/logs.

test_index property

test_index

Index of the test that was run.

Test Types

PythonTest

Python test - imports modules and optionally runs pip check.

Attributes:

Name	Type	Description
index	int	Index of this test in the package's test list
imports	list[str]	List of modules to import
pip_check	bool	Whether to run pip check (default: True)
python_version	PythonVersion | None	Python version specification

index property

index

Index of this test in the package's test list.

imports property

imports

List of modules to import.

pip_check property

pip_check

Whether to run pip check (default: True).

python_version property

python_version

Python version specification.

to_dict

to_dict()

Convert to a dictionary.

PythonVersion

Python version specification for tests.

Can be a single version, multiple versions, or unspecified (None).

as_single

as_single()

Get the version as a single string (if single version).

as_multiple

as_multiple()

Get the versions as a list (if multiple versions).

is_none

is_none()

Check if no specific version is set.

CommandsTest

Commands test - runs arbitrary shell commands.

Attributes:

Name	Type	Description
index	int	Index of this test in the package's test list
script	dict[str, Any]	The script content (as dict)
requirements_run	list[str]	Extra runtime requirements for the test
requirements_build	list[str]	Extra build requirements for the test (e.g., emulators)

index property

index

Index of this test in the package's test list.

script property

script

The script content.

requirements_run property

requirements_run

Extra runtime requirements for the test.

requirements_build property

requirements_build

Extra build requirements for the test (e.g., emulators).

to_dict

to_dict()

Convert to a dictionary.

PerlTest

Perl test - tests Perl modules.

Attributes:

Name	Type	Description
index	int	Index of this test in the package's test list
uses	list[str]	List of Perl modules to load with 'use'

index property

index

Index of this test in the package's test list.

uses property

uses

List of Perl modules to load with 'use'.

to_dict

to_dict()

Convert to a dictionary.

RTest

R test - tests R libraries.

Attributes:

Name	Type	Description
index	int	Index of this test in the package's test list
libraries	list[str]	List of R libraries to load with library()

index property

index

Index of this test in the package's test list.

libraries property

libraries

List of R libraries to load with library().

to_dict

to_dict()

Convert to a dictionary.

RubyTest

Ruby test - tests Ruby modules.

Attributes:

Name	Type	Description
index	int	Index of this test in the package's test list
requires	list[str]	List of Ruby modules to require

index property

index

Index of this test in the package's test list.

requires property

requires

List of Ruby modules to require.

to_dict

to_dict()

Convert to a dictionary.

DownstreamTest

Downstream test - tests a downstream package that depends on this package.

Attributes:

Name	Type	Description
index	int	Index of this test in the package's test list
downstream	str	Name of the downstream package to test

index property

index

Index of this test in the package's test list.

downstream property

downstream

Name of the downstream package to test.

to_dict

to_dict()

Convert to a dictionary.

PackageContentsTest

Package contents test - checks that files exist or don't exist in the package.

Attributes:

Name	Type	Description
index	int	Index of this test in the package's test list
files	FileChecks	File checks for all files
site_packages	FileChecks	File checks for Python site-packages
bin	FileChecks	File checks for binaries in bin/
lib	FileChecks	File checks for libraries
include	FileChecks	File checks for include headers
strict	bool	Whether to fail on non-matched glob patterns (strict mode)

index property

index

Index of this test in the package's test list.

files property

files

File checks for all files.

site_packages property

site_packages

File checks for Python site-packages.

bin property

bin

File checks for binaries in bin/.

lib property

lib

File checks for libraries.

include property

include

File checks for include headers.

strict property

strict

Whether to fail on non-matched glob patterns (strict mode).

to_dict

to_dict()

Convert to a dictionary.

FileChecks

File existence checks (glob patterns).

Attributes:

Name	Type	Description
exists	list[str]	Glob patterns that must match at least one file
not_exists	list[str]	Glob patterns that must NOT match any file

exists property

exists

Glob patterns that must match at least one file.

not_exists property

not_exists

Glob patterns that must NOT match any file.

PathEntry

Path entry from paths.json.

Attributes:

Name	Type	Description
relative_path	str	Relative path of the file in the package
no_link	bool	Whether to skip linking this file
path_type	str	Path type ("hardlink", "softlink", or "directory")
size_in_bytes	int | None	Size of the file in bytes (if available)
sha256	str | None	SHA256 hash of the file (if available)

relative_path property

relative_path

Relative path of the file in the package.

no_link property

no_link

Whether to skip linking this file.

path_type property

path_type

Path type: "hardlink", "softlink", or "directory".

size_in_bytes property

size_in_bytes

Size of the file in bytes (if available).

sha256 property

sha256

SHA256 hash of the file (if available).