Packaging implementation

Author: pipermerriam

conftest.py

@@ -155,10 +155,94 @@ def _loaded_test_contract_fixtures(populus_source_root, project_dir, request):
         shutil.copy(src_path, dst_path)
 
 
+EXAMPLE_PACKAGES_BASE_PATH = './tests/example-packages'
+
+
+@pytest.fixture()
+def _loaded_installed_dependencies(populus_source_root, project_dir, request):
+    from populus.utils.dependencies import (
+        get_installed_packages_dir,
+    )
+    from populus.utils.filesystem import (
+        find_solidity_source_files,
+    )
+    from populus.utils.packaging import (
+        load_release_lockfile,
+        extract_package_metadata,
+    )
+    from populus.utils.ipfs import (
+        generate_file_hash,
+    )
+    from populus.packages.installation import (
+        write_installed_packages,
+    )
+
+    packages_to_load_from_fn = getattr(request.function, '_populus_packages_to_load', [])
+    packages_to_load_from_module = getattr(request.module, '_populus_packages_to_load', [])
+
+    packages_to_load = itertools.chain(
+        packages_to_load_from_fn,
+        packages_to_load_from_module,
+    )
+
+    def load_example_package_data(example_package_name):
+        example_package_dir = os.path.join(
+            populus_source_root,
+            EXAMPLE_PACKAGES_BASE_PATH,
+            example_package_name,
+        )
+
+        if not os.path.exists(example_package_dir):
+            raise ValueError(
+                "Unable to load example package '{0}".format(example_package_name)
+            )
+
+        release_lockfile_path = os.path.join(example_package_dir, '1.0.0.json')
+        release_lockfile_uri = generate_file_hash(release_lockfile_path)
+        release_lockfile = load_release_lockfile(release_lockfile_path)
+        source_file_paths = find_solidity_source_files(example_package_dir)
+        source_tree = {
+            os.path.relpath(source_file_path, example_package_dir): open(source_file_path).read()
+            for source_file_path
+            in source_file_paths
+        }
+        package_meta = extract_package_metadata(
+            [
+                example_package_name,
+                "{0}==1.0.0".format(example_package_name),
+                release_lockfile_uri,
+            ],
+            release_lockfile,
+        )
+        package_dependencies = tuple(
+            load_example_package_data(dependency_name)
+            for dependency_name
+            in release_lockfile.get('build_dependencies', {}).keys()
+        )
+
+        package_data = {
+            'meta': package_meta,
+            'lockfile': release_lockfile,
+            'source_tree': source_tree,
+            'dependencies': package_dependencies,
+        }
+        return package_data
+
+    installed_packages_dir = get_installed_packages_dir(project_dir)
+
+    package_data_to_install = tuple(
+        load_example_package_data(item)
+        for item
+        in packages_to_load
+    )
+    write_installed_packages(installed_packages_dir, package_data_to_install)
+
+
 @pytest.fixture()
 def project(project_dir,
             _loaded_contract_fixtures,
-            _loaded_test_contract_fixtures):
+            _loaded_test_contract_fixtures,
+            _loaded_installed_dependencies):
     return Project()
 
 

docs/index.rst

@@ -19,6 +19,7 @@ Contents
     project
     config
     chain
+    packaging
     release
     modules
     API Documentation <populus>

docs/packaging.quickstart.rst

@@ -0,0 +1,131 @@
+Packaging Quickstart
+====================
+
+.. contents:: :local:
+
+Introduction
+------------
+
+Populus can be used as a package manager to interact with any ERC190 smart
+contract packages.
+
+
+Project Manifest
+----------------
+
+In order to take advantage of the packaging features you will first need to
+create a package manifest for your project.  This can either be done manually
+or using the command line helper ``$ populus package init`` which will present
+an interactive prompt for creating the ``ethpm.json`` file.
+
+.. code-block:: bash
+
+    $ populus package init
+    Writing new ethpm.json file.
+    Package Name: fancy-greeter
+    Author(s) [[]]: Piper Merriam <[email protected]>
+    Version [1.0.0]:
+    License [MIT]:
+    Description []: A fancy greeter contract
+    Keywords [[]]: greeter, greetings
+    Links [{}]:
+    Wrote package manifest: ethpm.json
+
+
+Installing Packages
+-------------------
+
+Packages can be installed using the ``$populus package install`` command.
+Packages may be specified in the following formats.
+
+* ``populus package install .``:
+
+    To install all of the declared dependencies found within the project's package manifest.
+
+* ``populus package install some-package-name``
+
+    To install a named package ``some-package-name`` sourced from a package index.
+
+* ``populus package install ipfs://QmUwVUMVtkVctrLDeL12SoeCPUacELBU8nAxRtHUzvtjND``
+
+    To install directly from a release lockfile via IPFS
+
+* ``populus package install /path/to/release-lockfile.json``
+
+    To install directly from a release lockfile on the local filesystem.
+
+
+Populus also supports installing packages under aliased names.  This can be
+used to allow multiple versions of the same package to be installed in tandem.
+
+* ``populus package install some-alias:some-package-name``
+
+    To install a named package ``some-package-name`` under the name
+    ``some-alias`` sourced from a package index.
+
+* ``populus package install some-alias@ipfs://QmUwVUMVtkVctrLDeL12SoeCPUacELBU8nAxRtHUzvtjND``
+
+    To install directly from a release lockfile via IPFS using the name ``some-alias``.
+
+* ``populus package install some-alias@/path/to/release-lockfile.json``
+
+    To install directly from a release lockfile on the local filesystem using
+    the name ``some-alias``
+
+
+Packages are installed in the ``./installed_packages`` directory in the root
+project directory under their aliased name, or their package name if no alias
+is used.
+
+When a package is installed it is automatically saved to the project
+dependencies within the package manifest.  This can be disabled by passing in
+the ``--no-save`` flag during installation.
+
+
+Using Contracts from Installed Packages
+---------------------------------------
+
+Importing a contract from an installed package is done by prefixing the source
+path with the name of the installed package, or the alias name if an alias was
+used.
+
+Lets use the common *owned* pattern for an example.  Suppose we have the
+``owned`` package installed in our project.  We know that this package has a
+single solidity source file that contains the ``owned`` contract located at
+``./contracts/owned.sol``.
+
+To import a contract from this file into local solidity source files you would
+simply prefix the import path with the package name.
+
+.. code-block:: solidity
+
+    pragma solidity ^0.4.0;
+
+    import "owned/contracts/owned.sol";
+
+    contract MyContract is owned {
+        ...
+    }
+
+.. note:: 
+
+    If you install a package which either has source files which do not compile
+    with the solidity compiler version you are using, or which have a ``pragma
+    solidity`` statement which is incompatable with your version of solidity
+    then compilation will fail.
+
+
+Library Linking
+---------------
+
+If you have a package installed which contains a library contract with a deployed instance of that library, populus will automatically find and link against that existing deployed library.  One of the default contract backends that populus uses will check all installed packages
+
+
+
+Building and Publishing Releases
+--------------------------------
+
+Populus can be used to build and publish packages to The Ethereum Package
+Registry or any registry which implements a compatable API.
+
+To build a release use the ``$ populus package build`` command.

docs/packaging.rst

@@ -0,0 +1,15 @@
+Packaging
+=========
+
+.. contents:: :local:
+
+.. warning:: The packaging functionality is highly experimental.  All APIs are subject to change without notice.
+
+
+Contents
+--------
+
+.. toctree::
+    :maxdepth: 1
+
+    packaging.quickstart