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 spec or 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 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 itsregistry
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. Requiresweb3.eth.default_account
to be the registry owner.- Parameters:
package_name
: Must be a valid package name, matching thegiven 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_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 themanifest_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 theregistry 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 toany versioning scheme.
manifest_uri
: URI location of a manifest which details therelease 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 toany 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 toany versioning scheme.
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.