Package Manager API

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

  • To learn more about the EthPM spec, visit the documentation.
  • To learn more about the Py-EthPM library used in this module, visit the documentation.

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.auto import w3
>>> w3.pm
...
AttributeError: The Package Management feature is disabled by default ...

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

>>> web3.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(web3)

By default, the PM module uses the Vyper Reference Registry implementation. However, it will work with any subclass of ERCRegistry, tailored to a particular implementation of ERC1319, set as its registry attribute.

get_package_from_manifest(manifest: NewType.<locals>.new_type) → ethpm.package.Package

Returns a Package instance built with the given manifest.

  • Parameters:
    • manifest: A dict representing a valid manifest
get_package_from_uri(manifest_uri: NewType.<locals>.new_type) → ethpm.package.Package

Returns a Package 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
set_registry(address: NewType.<locals>.new_type) → 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 instance of the Vyper Reference Registry implementation. If you want to use a different registry implementation with web3.pm, manually set the web3.pm.registry attribute to any subclass of ERCRegistry.

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

  • Parameters:
    • address: Address of on-chain Vyper Reference Registry.
deploy_and_set_registry() → NewType.<locals>.new_type

Returns the address of a freshly deployed instance of the vyper registry, 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: str) → 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.defaultAccount 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) → Tuple[str, str, str]

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) → Tuple[str, str, str]

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) → ethpm.package.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.ERCRegistry(address: NewType.<locals>.new_type, w3: web3.main.Web3)

The ERCRegistry 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 ERCRegistry subclass in order to be compatible with the PM module. Any custom methods (eg. not definied 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.

__init__(address: NewType.<locals>.new_type, w3: web3.main.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.
_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
_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.
_get_all_package_ids() → Tuple[bytes]

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

_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.
_get_all_release_ids(package_name: str) → Tuple[bytes]

Returns a tuple containg 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.
_get_release_data(release_id: bytes) → Tuple[str, str, str]

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.
_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.
_num_package_ids() → int

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

_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.
class web3.pm.VyperReferenceRegistry(address: NewType.<locals>.new_type, w3: web3.main.Web3)

The VyperReferenceRegistry class implements all of the methods found in ERCRegistry, along with some custom methods included in the implementation.

classmethod deploy_new_instance(w3: web3.main.Web3) → web3.pm.VyperReferenceRegistry

Returns a new instance of `VyperReferenceRegistry representing a freshly deployed instance on the given web3 instance of the Vyper Reference Registry implementation.

owner() → NewType.<locals>.new_type

Returns the address of the owner of this registry instance. Only the owner is allowed to add releases to the Vyper Reference Registry implementation.

transfer_owner(new_owner: NewType.<locals>.new_type) → NewType.<locals>.new_type

Transfers ownership of this registry instance to the given new_owner. Only the owner is allowed to transfer ownership.

  • Parameters:
    • new_owner: The address of the new owner.
class web3.pm.SolidityReferenceRegistry(address: NewType.<locals>.new_type, w3: web3.main.Web3)

This class represents an instance of the Solidity Reference Registry implementation. To use this subclass, you must manually set an instance of this class to the registry attribute on web3.pm.

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 ERCRegistry, and implements all the ERC 1319 standard methods prefixed with an underscore in ERCRegistry. 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 ERCRegistry subclass to easily call both the standard & custom methods.

The VyperReferenceRegistry class is an example of this, as it contains all of the ERC 1319 defined functions (prefixed with an underscore, eg _get_package_name) but also contains functions that are unique to the Vyper Registry reference implementation (eg transfer_owner).