Package Manager API

The web3.pm object exposes methods to interact with Packages as defined by ERC 1123.

Warning

The web3.pm API is still under development and likely to change quickly.

Now is a great time to get familiar with the API, and test out writing code that uses some of the great upcoming features.

By default, access to this module has been turned off in the stable version of web3.py:

>>> from web3 import Web3, IPCProvider
>>> w3 = Web3(IPCProvider(...))
>>> w3.pm
...
AttributeError: The Package Management feature is disabled by default ...

In order to access these features, you can turn it on with…

>>> w3.enable_unstable_package_management_api()
>>> w3.pm
<web3.pm.PM at 0x....>

Methods

The following methods are available on the web3.pm namespace.

class web3.pm.PM(w3: AsyncWeb3 | Web3)

The PM module will work with any subclass of ERC1319Registry, tailored to a particular implementation of ERC1319, set as its registry attribute.

get_package_from_manifest(manifest: Manifest) Package

Returns a Package # noqa: E501 instance built with the given manifest.

  • Parameters:
    • manifest: A dict representing a valid manifest

get_package_from_uri(manifest_uri: URI) Package

Returns a Package # noqa: E501 instance built with the Manifest stored at the URI. If you want to use a specific IPFS backend, set ETHPM_IPFS_BACKEND_CLASS to your desired backend. Defaults to Infura IPFS backend.

  • Parameters:
    • uri: Must be a valid content-addressed URI

get_local_package(package_name: str, ethpm_dir: Path | None = None) Package

Returns a Package # noqa: E501 instance built with the Manifest found at the package name in your local ethpm_dir.

  • Parameters:
    • package_name: Must be the name of a package installed locally.

    • ethpm_dir: Path pointing to the target ethpm directory (optional).

set_registry(address: Address | ChecksumAddress | ENS) None

Sets the current registry used in web3.pm functions that read/write to an on-chain registry. This method accepts checksummed/canonical addresses or ENS names. Addresses must point to an on-chain instance of an ERC1319 registry implementation.

To use an ENS domain as the address, make sure a valid ENS instance set as web3.ens.

  • Parameters:
    • address: Address of on-chain Registry.

deploy_and_set_registry() ChecksumAddress

Returns the address of a freshly deployed instance of SimpleRegistry and sets the newly deployed registry as the active registry on web3.pm.registry.

To tie your registry to an ENS name, use web3’s ENS module, ie.

w3.ens.setup_address(ens_name, w3.pm.registry.address)
release_package(package_name: str, version: str, manifest_uri: URI) bytes

Returns the release id generated by releasing a package on the current registry. Requires web3.PM to have a registry set. Requires web3.eth.default_account to be the registry owner.

  • Parameters:
    • package_name: Must be a valid package name, matching the

      given manifest.

    • version: Must be a valid package version, matching the given manifest.

    • manifest_uri: Must be a valid content-addressed URI. Currently,

      only IPFS and Github content-addressed URIs are supported.

get_all_package_names() Iterable[str]

Returns a tuple containing all the package names available on the current registry.

get_package_count() int

Returns the number of packages available on the current registry.

get_release_count(package_name: str) int

Returns the number of releases of the given package name available on the current registry.

get_release_id(package_name: str, version: str) bytes

Returns the 32 byte identifier of a release for the given package name and version, if they are available on the current registry.

get_all_package_releases(package_name: str) Iterable[Tuple[str, str]]

Returns a tuple of release data (version, manifest_ur) for every release of the given package name available on the current registry.

get_release_id_data(release_id: bytes) ReleaseData

Returns (package_name, version, manifest_uri) associated with the given release id, if it is available on the current registry.

  • Parameters:
    • release_id: 32 byte release identifier

get_release_data(package_name: str, version: str) ReleaseData

Returns (package_name, version, manifest_uri) associated with the given package name and version, if they are published to the currently set registry.

  • Parameters:
    • name: Must be a valid package name.

    • version: Must be a valid package version.

get_package(package_name: str, version: str) Package

Returns a Package instance, generated by the manifest_uri associated with the given package name and version, if they are published to the currently set registry.

  • Parameters:
    • name: Must be a valid package name.

    • version: Must be a valid package version.

class web3.pm.ERC1319Registry(address: Address, w3: Web3)

The ERC1319Registry class is a base class for all registry implementations to inherit from. It defines the methods specified in ERC 1319. All of these methods are prefixed with an underscore, since they are not intended to be accessed directly, but rather through the methods on web3.pm. They are unlikely to change, but must be implemented in a ERC1319Registry subclass in order to be compatible with the PM module. Any custom methods (eg. not defined in ERC1319) in a subclass should not be prefixed with an underscore.

All of these methods must be implemented in any subclass in order to work with web3.pm.PM. Any implementation specific logic should be handled in a subclass.

abstract __init__(address: Address, w3: Web3) None

Initializes the class with the on-chain address of the registry, and a web3 instance connected to the chain where the registry can be found.

Must set the following properties…

  • self.registry: A web3.contract instance of the target registry.

  • self.address: The address of the target registry.

  • self.w3: The web3 instance connected to the chain where the

    registry can be found.

abstract _release(package_name: str, version: str, manifest_uri: str) bytes

Returns the releaseId created by successfully adding a release to the registry.

  • Parameters:
    • package_name: Valid package name according the spec.

    • version: Version identifier string, can conform to

      any versioning scheme.

    • manifest_uri: URI location of a manifest which details the

      release contents

abstract _get_package_name(package_id: bytes) str

Returns the package name associated with the given package id, if the package id exists on the connected registry.

  • Parameters:
    • package_id: 32 byte package identifier.

abstract _get_all_package_ids() Iterable[bytes]

Returns a tuple containing all of the package ids found on the connected registry.

abstract _get_release_id(package_name: str, version: str) bytes

Returns the 32 bytes release id associated with the given package name and version, if the release exists on the connected registry.

  • Parameters:
    • package_name: Valid package name according the spec.

    • version: Version identifier string, can conform to

      any versioning scheme.

abstract _get_all_release_ids(package_name: str) Iterable[bytes]

Returns a tuple containing all of the release ids belonging to the given package name, if the package has releases on the connected registry.

  • Parameters:
    • package_name: Valid package name according the spec.

abstract _get_release_data(release_id: bytes) ReleaseData

Returns a tuple containing (package_name, version, manifest_uri) for the given release id, if the release exists on the connected registry.

  • Parameters:
    • release_id: 32 byte release identifier.

abstract _generate_release_id(package_name: str, version: str) bytes

Returns the 32 byte release identifier that would be associated with the given package name and version according to the registry’s hashing mechanism. The release does not have to exist on the connected registry.

  • Parameters:
    • package_name: Valid package name according the spec.

    • version: Version identifier string, can conform to

      any versioning scheme.

abstract _num_package_ids() int

Returns the number of packages that exist on the connected registry.

abstract _num_release_ids(package_name: str) int

Returns the number of releases found on the connected registry, that belong to the given package name.

  • Parameters:
    • package_name: Valid package name according the spec.

Creating your own Registry class

If you want to implement your own registry and use it with web3.pm, you must create a subclass that inherits from ERC1319Registry, and implements all the ERC 1319 standard methods prefixed with an underscore in ERC1319Registry. Then, you have to manually set it as the registry attribute on web3.pm.

custom_registry = CustomRegistryClass(address, w3)
w3.pm.registry = custom_registry

One reason a user might want to create their own Registry class is if they build a custom Package Registry smart contract that has features beyond those specified in ERC 1319. For example, the ability to delete a release or some micropayment feature. Rather than accessing those functions directly on the contract instance, they can create a custom ERC1319Registry subclass to easily call both the standard & custom methods.