# quilt3.Package

In-memory representation of a package

## manifest

Provides a generator of the dicts that make up the serialized package.

## top\_hash

Returns the top hash of the package.

Note that physical keys are not hashed because the package has the same semantics regardless of where the bytes come from.

**Returns**

A string that represents the top hash of the package

## Package.\_\_repr\_\_(self, max\_lines=20) <a href="#package.-_-_repr-_-_" id="package.-_-_repr-_-_"></a>

String representation of the Package.

## Package.install(name, registry=None, top\_hash=None, dest=None, dest\_registry=None) <a href="#package.install" id="package.install"></a>

Installs a named package to the local registry and downloads its files.

**Arguments**

* **name(str)**:  Name of package to install.
* **registry(str)**:  Registry where package is located.

  &#x20; Defaults to the default remote registry.
* **top\_hash(str)**:  Hash of package to install. Defaults to latest.
* **dest(str)**:  Local path to download files to.
* **dest\_registry(str)**:  Registry to install package to. Defaults to local registry.

**Returns**

A new Package that points to files on your local machine.

## Package.browse(name=None, registry=None, top\_hash=None) <a href="#package.browse" id="package.browse"></a>

Load a package into memory from a registry without making a local copy of the manifest. **Arguments**

* **name(string)**:  name of package to load
* **registry(string)**:  location of registry to load package from
* **top\_hash(string)**:  top hash of package version to load

## Package.\_\_contains\_\_(self, logical\_key) <a href="#package.-_-_contains-_-_" id="package.-_-_contains-_-_"></a>

Checks whether the package contains a specified logical\_key.

**Returns**

True or False

## Package.\_\_getitem\_\_(self, logical\_key) <a href="#package.-_-_getitem-_-_" id="package.-_-_getitem-_-_"></a>

Filters the package based on prefix, and returns either a new Package or a PackageEntry.

**Arguments**

* **prefix(str)**:  prefix to filter on

**Returns**

PackageEntry if prefix matches a logical\_key exactly otherwise Package

## Package.fetch(self, dest='./') <a href="#package.fetch" id="package.fetch"></a>

Copy all descendants to `dest`. Descendants are written under their logical names *relative* to self.

**Arguments**

* **dest**:  where to put the files (locally)

**Returns**

None

## Package.keys(self) <a href="#package.keys" id="package.keys"></a>

Returns logical keys in the package.

## Package.walk(self) <a href="#package.walk" id="package.walk"></a>

Generator that traverses all entries in the package tree and returns tuples of (key, entry), with keys in alphabetical order.

## Package.load(readable\_file) <a href="#package.load" id="package.load"></a>

Loads a package from a readable file-like object.

**Arguments**

* **readable\_file**:  readable file-like object to deserialize package from

**Returns**

A new Package object

**Raises**

file not found json decode error invalid package exception

## Package.set\_dir(self, lkey, path=None, meta=None) <a href="#package.set-_dir" id="package.set-_dir"></a>

Adds all files from `path` to the package.

Recursively enumerates every file in `path`, and adds them to the package according to their relative location to `path`.

**Arguments**

* **lkey(string)**:  prefix to add to every logical key,

  &#x20; use '/' for the root of the package.
* **path(string)**:  path to scan for files to add to package.

  &#x20; If None, lkey will be substituted in as the path.
* **meta(dict)**:  user level metadata dict to attach to lkey directory entry.

**Returns**

self

**Raises**

When `path` doesn't exist

## Package.get(self, logical\_key) <a href="#package.get" id="package.get"></a>

Gets object from logical\_key and returns its physical path. Equivalent to self\[logical\_key].get().

**Arguments**

* **logical\_key(string)**:  logical key of the object to get

**Returns**

Physical path as a string.

**Raises**

* `KeyError`:  when logical\_key is not present in the package
* `ValueError`:  if the logical\_key points to a Package rather than PackageEntry.

## Package.set\_meta(self, meta) <a href="#package.set-_meta" id="package.set-_meta"></a>

Sets user metadata on this Package.

## Package.build(self, name=None, registry=None, message=None) <a href="#package.build" id="package.build"></a>

Serializes this package to a registry.

**Arguments**

* **name**:  optional name for package
* **registry**:  registry to build to

  ```
    defaults to local registry
  ```
* **message**:  the commit message of the package

**Returns**

The top hash as a string.

## Package.dump(self, writable\_file) <a href="#package.dump" id="package.dump"></a>

Serializes this package to a writable file-like object.

**Arguments**

* **writable\_file**:  file-like object to write serialized package.

**Returns**

None

**Raises**

fail to create file fail to finish write

## Package.set(self, logical\_key, entry=None, meta=None, serialization\_location=None, serialization\_format\_opts=None) <a href="#package.set" id="package.set"></a>

Returns self with the object at logical\_key set to entry.

**Arguments**

* **logical\_key(string)**:  logical key to update
* **entry(PackageEntry OR string OR object)**:  new entry to place at logical\_key in the package.

  &#x20; If entry is a string, it is treated as a URL, and an entry is created based on it.

  &#x20; If entry is None, the logical key string will be substituted as the entry value.

  &#x20; If entry is an object and quilt knows how to serialize it, it will immediately be serialized and written

  &#x20; to disk, either to serialization\_location or to a location managed by quilt. List of types that Quilt

  &#x20; can serialize is available by calling `quilt3.formats.FormatRegistry.all_supported_formats()`
* **meta(dict)**:  user level metadata dict to attach to entry
* **serialization\_format\_opts(dict)**:  Optional. If passed in, only used if entry is an object. Options to help

  &#x20; Quilt understand how the object should be serialized. Useful for underspecified file formats like csv

  &#x20; when content contains confusing characters. Will be passed as kwargs to the FormatHandler.serialize()

  &#x20; function. See docstrings for individual FormatHandlers for full list of options -
* **https**: //github.com/quiltdata/quilt/blob/master/api/python/quilt3/formats.py
* **serialization\_location(string)**:  Optional. If passed in, only used if entry is an object. Where the

  &#x20; serialized object should be written, e.g. "./mydataframe.parquet"

**Returns**

self

## Package.delete(self, logical\_key) <a href="#package.delete" id="package.delete"></a>

Returns the package with logical\_key removed.

**Returns**

self

**Raises**

* `KeyError`:  when logical\_key is not present to be deleted

## Package.push(self, name, registry=None, dest=None, message=None) <a href="#package.push" id="package.push"></a>

Copies objects to path, then creates a new package that points to those objects. Copies each object in this package to path according to logical key structure, then adds to the registry a serialized version of this package with physical keys that point to the new copies.

**Arguments**

* **name**:  name for package in registry
* **dest**:  where to copy the objects in the package
* **registry**:  registry where to create the new package
* **message**:  the commit message for the new package

**Returns**

A new package that points to the copied objects.

## Package.rollback(name, registry, top\_hash) <a href="#package.rollback" id="package.rollback"></a>

Set the "latest" version to the given hash.

**Arguments**

* **name(str)**:  Name of package to rollback.
* **registry(str)**:  Registry where package is located.
* **top\_hash(str)**:  Hash to rollback to.

## Package.diff(self, other\_pkg) <a href="#package.diff" id="package.diff"></a>

Returns three lists -- added, modified, deleted.

Added: present in other\_pkg but not in self. Modified: present in both, but different. Deleted: present in self, but not other\_pkg.

**Arguments**

* **other\_pkg**:  Package to diff

**Returns**

added, modified, deleted (all lists of logical keys)

## Package.map(self, f, include\_directories=False) <a href="#package.map" id="package.map"></a>

Performs a user-specified operation on each entry in the package.

**Arguments**

* **f(x, y)**:  function

  &#x20; The function to be applied to each package entry.

  &#x20; It should take two inputs, a logical key and a PackageEntry.
* **include\_directories**:  bool

  &#x20; Whether or not to include directory entries in the map.

Returns: list The list of results generated by the map.

## Package.filter(self, f, include\_directories=False) <a href="#package.filter" id="package.filter"></a>

Applies a user-specified operation to each entry in the package, removing results that evaluate to False from the output.

**Arguments**

* **f(x, y)**:  function

  &#x20; The function to be applied to each package entry.

  &#x20; It should take two inputs, a logical key and a PackageEntry.

  &#x20; This function should return a boolean.
* **include\_directories**:  bool

  &#x20; Whether or not to include directory entries in the map.

**Returns**

A new package with entries that evaluated to False removed


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.quilt.bio/version-3.1.6/api-reference/package.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.