PK ǔ4AJ shrinkwrap-latest/searchindex.jsSearch.setIndex({objects:{"":{SHRINKWRAP_NEVER_SKIP:[3,0,1,"-"]},shrinkwrap:{command:[4,1,1,""],install:[4,1,1,""]},"shrinkwrap.install":{validate_installer_option:[4,5,1,""],ShrinkwrapInstall:[4,4,1,""],autoconf_install:[4,5,1,""],assert_callable:[4,5,1,""],assert_string:[4,5,1,""],SYSTEM_INCLUDE_PATHS:[4,2,1,""]},"shrinkwrap.command":{activate:[4,5,1,""],createpkg:[4,5,1,""],help:[4,5,1,""]},"shrinkwrap.install.ShrinkwrapInstall":{virtualenv:[4,6,1,""],python_libdir:[4,6,1,""],shell:[4,3,1,""],run:[4,3,1,""],cmd_output:[4,3,1,""],make:[4,3,1,""],untar:[4,3,1,""],download_url:[4,3,1,""],download_and_unpack_tarball:[4,3,1,""],ncpu:[4,6,1,""],src_dir:[4,6,1,""],env_dir:[4,6,1,""],check_header:[4,3,1,""],install_env:[4,3,1,""]}},terms:{all:[2,3,1],code:[2,3,4,1],dist:4,illustr:2,scratch:3,focus:3,prefix:2,edu:2,follow:2,disk:4,depend:[2,0,4,3],cmdclass:2,autoconf_instal:4,present:2,under:[3,4],sourc:[2,3,4],string:[2,4],fals:[2,4],to_src_dir:4,util:4,mechan:3,veri:3,cmd:4,list:[2,3,4],upload:[2,0],"try":2,shortcom:3,small:[2,3],pleas:0,natur:1,design:3,cumbersom:[],pass:[2,3,4],download:[2,0,4,3,1],further:0,index:[2,0,3],appear:0,compar:3,fine:0,section:2,find:0,current:[2,3,4],version:[2,0,5,3],"new":[2,3],ever:[2,0],method:[2,4],metadata:2,python_libdir:4,full:4,hash:1,deriv:2,gener:[2,0,4],sophist:3,shrinkwrap_source_url:2,satisfi:3,argv:4,path:[2,4],becom:3,modifi:3,sinc:3,valu:4,convenic:[],search:[0,4],cern:2,host:0,behav:0,implement:[3,4],overrid:[],via:[2,0],repositori:[2,0,3],extra:[2,3],activ:[2,3,4],modul:[0,3],apt:0,filenam:[2,4],api:[0,4],instal:[0,1,2,3,4,5],txt:[2,3],select:3,from:[2,0,4,3],describ:0,would:[2,3],two:2,"throw":3,call:[2,4,1],usr:4,autodetect:3,more:[3,5],peopl:2,warn:0,particular:3,unpack:[2,3,4],must:2,none:4,chdir:2,restor:3,setup:[2,0,4,3],work:[0,3],roof:3,can:[2,0,3],meet:2,purpos:3,root:2,def:2,boilerpl:2,control:2,tar:[2,3,4,1],process:2,sdist:4,share:2,indic:[2,0],tarbal:[2,3,4],want:2,shrinkwrap_source_dir:4,unfortun:2,alwai:3,multipl:3,goal:[2,3,1],rather:[2,3],write:[2,0,3],how:[2,0,3],env:[2,3,4],src_dir:4,config:2,gentoo:3,clone:0,variant:3,befor:[2,0,4],wrong:2,inst:2,mai:2,end:[2,3],parallel:4,mastbaum:2,github:4,attempt:3,author:2,inform:5,cannot:0,environ:[2,3,4],allow:[2,3,4],extra_opt:[2,4],callabl:4,egg:2,order:2,help:4,offici:2,becaus:3,tarfil:[2,4],paramet:4,streamlin:4,scon:2,lengthi:[],better:2,platform:3,infrastructur:1,bypass:0,bin:[2,3],might:3,easier:0,them:[2,3,4,5],"return":[2,4],thei:[2,3],python:[2,0,4,3],auto:3,mention:2,facilit:[],verifi:4,name:2,anyth:2,refresh:3,separ:[2,0],achiev:3,each:[2,0,4,3,1],found:[3,4],went:2,compil:[2,0,3],fftw:3,continu:[],shrinkwrap_pkg:2,ensur:2,our:[2,0,3],extract:4,variabl:[2,3],shown:2,content:[0,4],suitabl:2,print:4,insid:4,situat:2,given:4,free:2,standard:[3,4],ncpu:4,reason:3,base:[0,4,3],releas:[0,5],org:[2,0,3],"byte":4,precompil:3,virtual_env:[2,3,4],script:[2,3,4],thing:2,validate_installer_opt:4,place:[2,3,4],top:[2,3],first:[3,4,5],oper:2,softwar:[2,0,3],directli:[0,3],feel:2,onc:2,number:4,yourself:0,alreadi:[2,3,5],miss:4,differ:[2,3],seibert:[2,0],interact:2,return_cod:[],system:[2,0,4,5,3],wrapper:[2,0],mercuri:0,too:2,conveni:[2,4],shell:[2,3,4],option:[2,3,4,5],tool:[2,0,3],copi:[2,4],setuptool:[2,4],specifi:[2,3,4],appropri:[],than:[2,3],serv:2,wide:[0,4,3],kind:[2,3],min_vers:2,keyword:[2,3,4],provid:[2,0,4,5,3],remov:[2,3,1],project:0,abov:2,argument:[2,3,4],packag:[2,0,4,5,3],have:[2,3],tabl:0,need:[2,3,4],built:[2,3],destroi:1,self:[2,3,4],client:2,note:[2,0,4,5,3],also:[2,3],without:0,build:[2,3],which:[2,3,4,1],singl:3,simplifi:[2,0],distribut:2,deploy:[0,3],track:3,discov:2,commanderror:[],plan:2,deploi:[2,3],"class":4,don:[2,3],url:[2,3,4],upenn:2,doe:[2,0,3],yum:0,wildcard:2,newer:2,subprocess:[2,4],bring:3,trivial:1,anywai:2,onli:[2,3],locat:4,configur:2,solut:[2,3],should:0,saveto:4,local:4,nearli:3,get:2,familiar:[],pypi:[2,0],autom:[3,1],tailor:3,report:[],requir:[2,0,4,3,1],target:4,patch:3,"default":[2,3,4],common:2,contain:[2,3],userspac:3,check_head:4,where:[2,3],valid:2,forego:3,set:[2,3,4],zeroinstal:3,createpkg:[2,4],roadmap:[0,1],see:[2,3,5],result:[2,3],detect:[2,3,5,1],setup_requir:2,success_return_cod:4,shrinkwrap_skip:[2,5],"import":2,altern:3,parent:4,web:2,isol:3,source_url:2,entir:[3,4,1],here:2,check_cal:2,addit:4,both:[0,4],howev:[2,0,3],equal:4,admit:3,instanc:2,mani:[2,3],com:[2,4],simpli:2,header:4,shrinkwrap_requir:2,assum:[2,3],pip_extra_index_url:[2,3],haxx:2,shrinkwrap_instal:[2,4],three:3,been:3,mark:[2,3],interest:0,shrinkwrapinstal:[2,4],calledprocesserror:4,bzip:2,gist:4,presenc:3,great:3,ani:[2,3,4],understand:2,makedir:4,those:0,"case":3,ident:3,cmd_output:[2,4],aim:3,defin:[2,4],behavior:3,error:[],spawn:2,real:5,readi:3,non:[2,0,1],strain:3,clutter:0,lightweight:0,sever:2,develop:0,welcom:[],minim:0,perform:[2,4],suggest:3,make:[2,0,4,3],same:[2,3],handl:2,download_and_unpack_tarbal:[2,4],split:2,version_str:2,document:[0,4],complet:2,http:[2,0,4,3],itch:3,assert_cal:4,rais:4,temporari:4,user:3,loosevers:2,distutil:2,typic:3,bz2:2,task:0,framework:1,well:4,exampl:[2,3],command:[2,0,4,3],thi:[2,0,3,1],filesystem:3,everyth:0,newest:0,just:[2,0,3],bzip2_dir:2,yet:3,assert_str:4,easi:[2,0,3],mix:3,except:[2,3],shrinkwrap_never_skip:[3,4],add:[2,3],macport:3,els:2,save:4,take:4,opt:4,applic:3,around:0,format:2,swig:0,sha1:1,know:2,insert:3,like:[2,0],specif:[0,3],arbitrari:[2,3],server:2,either:[2,4],output:[2,4],install_requir:2,system_include_path:4,manag:[2,3],www:2,old:2,creation:4,some:[2,3,1],back:4,"export":[2,3],my_shrinkwrap_pkg:2,home:3,librari:[2,0,4],virtualenv:[2,0,4,3,1],avoid:[2,0],per:3,install_env:[2,4],foo:2,notabl:3,nose:3,core:4,encourag:3,run:[2,0,4],uncompress:4,importerror:2,usag:4,step:[],although:3,shrinkwrap:[2,0,4,3,1],andi:2,post:0,env_dir:4,src:4,actual:2,greatli:0,coexist:3,page:0,regular:0,disabl:[3,4],own:[2,0],basenam:4,system_vers:2,easy_instal:[0,3],automat:[2,3],due:1,extra_path:4,wrap:4,chang:3,your:[2,0,3],leverag:[],hep:2,wai:3,support:3,download_url:4,custom:2,avail:[2,0],interfac:[],includ:[2,4],suit:1,"function":[2,3,4,1],properli:[2,3],repeatedli:1,offer:2,forc:3,untar:[2,4],skip:[2,3,4,5],uninstal:[3,1],renam:4,line:[3,4],"true":[2,3,4],made:[2,3],attr:4,temp:2,whether:3,wish:2,record:1,limit:[2,0,3],mtrr:[2,3],problem:3,autoconf:[2,4],instead:[],featur:0,creat:[2,0,4,3,1],file:[2,3,4,1],guarante:2,pip:[2,0,3,1],curl:[2,3],check:[2,1],fill:4,again:3,bzip2:2,cmake:2,author_email:2,when:[2,3,1],detail:3,virtual:3,field:2,other:[2,0],futur:1,rememb:[2,4],test:[3,1],you:[2,0,3],architectur:3,intend:3,fulli:2,stan:2,bitbucket:[2,0],directori:[2,0,4,3],rule:2,emerg:3,time:3,far:1,escap:4,cpu:4,unset:3},objtypes:{"0":"std:envvar","1":"py:module","2":"py:data","3":"py:method","4":"py:class","5":"py:function","6":"py:attribute"},titles:["shrinkwrap: Python packaging for everything","Roadmap","Creating Packages","How Shrinkwrap Works","API Documentation","Release Notes"],objnames:{"0":["std","envvar","environment variable"],"1":["py","module","Python module"],"2":["py","data","Python data"],"3":["py","method","Python method"],"4":["py","class","Python class"],"5":["py","function","Python function"],"6":["py","attribute","Python attribute"]},filenames:["index","roadmap","packaging","how","api","relnotes"]})PK ǔ4A7 7 shrinkwrap-latest/index.html
Shrinkwrap provides tools to create lightweight Python package wrappers around non-Python software, and to install such software from project-specific repositories using virtualenv and pip.
A shrinkwrap package is a minimal python package that downloads, compiles and installs software to the virtualenv base directory. The shrinkwrap package behaves just like a regular python package, so both shrinkwrap and non- shrinkwrap packages can be dependencies of each other. We find that this greatly simplifies deployment of Python packages that depend on compiled libraries without requiring the use of system-wide packaging tools, like apt or yum. Shrinkwrap is not an API wrapper generator like SWIG, but does make it easier to install C libraries into a virtualenv before installing a separate Python wrapper around its API.
Warning
To avoid cluttering PyPI with non-Python software, please do not ever upload shrinkwrap-generated packages there! Hosting shrinkwrap packages yourself is easy, and described further in Running your own package index.
Shrinkwrap is available on PyPI and can be installed via pip install shrinkwrap, easy_install shrinkwrap, or by downloading the package and installing with python setup.py install.
For those interested in the newest features should use the development version of shrinkwrap, available on bitbucket:
hg clone http://bitbucket.org/seibert/shrinkwrap
Note that you cannot directly install shrinkwrap from the Mercurial repository to a virtualenv with the pip -e command, as this appears to bypass our post- installation tasks. Running python setup.py install from the cloned repository is fine, however.
Shrinkwrap was designed to scratch a particular itch: automating the installation of software in a self-contained environment.
Nearly all package managers assume they are managing software installation for the entire system, and don’t allow isolated environments. ZeroInstall is a notable exception which installs software into a user’s home directory and can manage multiple versions of a single package. However, ZeroInstall is more aimed at providing specific applications to an end user, rather than providing a shell environment with a set of packages installed and ready for use.
Python’s virtualenv and easy_install/pip tools are a great example of a userspace packaging solution that creates self-contained, easy-to-use environments. Since we work in mixed environments where C, C++ and Python software needs to coexist, shrinkwrap is our attempt to bring all that software under one roof.
Shrinkwrap achieves this goal by modifying the virtualenv in three ways:
1. It provides an alternate implementation of the python setup.py install command that makes it easy to insert an arbitrary installer function. This function typically downloads source tarballs, unpacks them, compiles and installs to the virtualenv base directory.
2. It adds new optional keyword arguments to setup() to specify the installer function, and also to list packages that are build dependencies of this package. See Package Dependencies for details.
3. It creates a new $VIRTUAL_ENV/env.d directory and patches the $VIRTUAL_ENV/bin/activate script to source any files found in that directory. This allows shrinkwrap packages to install scripts that make changes to the shell environment. Many of the software packages we work with require environment variables to function properly.
With these changes, it becomes very easy to write small Python packages that download, compile, and install software into the virtualenv environment.
Installing a shrinkwrapped package is identical to installing any package with pip. You can install the package file directly from the filesystem:
pip install curl-7.27.0.tar.gz
or from a URL:
pip install http://mtrr.org/packages/curl/curl-7.27.0.tar.gz
or set the URL of extra package repository which contains shrinkwrapped packages:
export PIP_EXTRA_INDEX_URL=http://mtrr.org/packages/
pip install curl
If the shrinkwrapped package contains the standard test for the shrinkwrap module at the top (see Built-in installers), then shrinkwrap will be automatically installed to your virtualenv.
Note that environment files in the $VIRTUAL_ENV/env.d/ directory are only sourced when the $VIRTUAL_ENV/bin/activate script is sourced. You will need to source that script again to refresh your environment if the shrinkwrapped package added new environment files.
As true Python packages, shrinkwrapped packages can be used in a requirements.txt files passed to pip. Just place the extra index URL argument at the top:
--extra-index-url http://mtrr.org/packages/
curl
fftw
nose
Some shrinkwrap packages will auto-detect whether the software is already installed system-wide. If it is, installation is skipped and the package is marked as installed since the dependency is satisfied.
To force installation into the virtual environment, this auto-detection can be disabled with an environment variable:
Set this variable to ‘1’ to forego system package detection and always install the shrinkwrap package. Unset or change to ‘0’ to restore the default behavior.
We are the first to admit that shrinkwrap is straining the intended purpose of the Python packaging tools. As a result, shrinkwrap+pip has some shortcomings compared to more sophisticated package managers:
The goal of shrinkwrap is to create Python packages for non-Python software and install them using Python package management. To this end, shrinkwrap “packages” are simply setuptools setup scripts which know how to download and install other software.
A shrinkwrap package may either use a built-in installer function (for common installation methods) or define a custom one.
An installer for software using autoconf is available to simplify things. The autoconf shrinkwrap installer assumes the tarfile unpacks to a directory with the same name as the tarfile with .tar.{gz,bz2} removed, contains a configure script, and understands the –prefix option to control where the package is installed.
For example, to package curl, one may write the following (as, e.g. curl-7.27.0.py):
try:
from shrinkwrap.install import ShrinkwrapInstall
except ImportError:
import subprocess; subprocess.check_call('pip install -b $VIRTUAL_ENV/build/build-shrinkwrap shrinkwrap', shell=True)
from shrinkwrap.install import ShrinkwrapInstall
from setuptools import setup
version = '7.27.0'
setup(
name='curl',
version=version,
author='Stan Seibert',
author_email='stan@mtrr.org',
shrinkwrap_installer='autoconf',
shrinkwrap_source_url='http://curl.haxx.se/download/curl-%s.tar.bz2' % version,
cmdclass={'install': ShrinkwrapInstall},
)
To install curl, one would simply run:
python curl-7.27.0.py install
The boilerplate at the top of the script is required to ensure that shrinkwrap is installed before setuptools is imported. The cmdclass option must be set as shown above in order to use the ShrinkwrapInstall command rather than the default install command provided by setuptools.
The filename of the python script is not used by shrinkwrap.
The following package for bzip2 illustrates a custom installer function:
try:
from shrinkwrap.install import ShrinkwrapInstall
except ImportError:
import subprocess; subprocess.check_call('pip install shrinkwrap', shell=True)
from shrinkwrap.install import ShrinkwrapInstall
import os
from setuptools import setup
version = '1.0.6'
source_url = 'http://www.bzip.org/%(version)s/bzip2-%(version)s.tar.gz' % {'version': version}
def installer(inst):
self.download_and_unpack_tarball(source_url)
bzip2_dir = 'bzip2-' + version
os.chdir(bzip2_dir)
self.make(extra_opts=['install', 'PREFIX=%s' % self.virtualenv])
setup(
name='bzip2',
version=version,
author='Andy Mastbaum',
author_email='mastbaum@hep.upenn.edu',
shrinkwrap_installer=installer,
cmdclass={'install': ShrinkwrapInstall},
)
As before, installing bzip2 simply requires:
python bzip2-1.0.6.py install
Here, the shrinkwrap_installer argument to setup() is set to our own installer function. The installer function is called with an instance of ShrinkwrapInstall as the argument, which provides several convenience functions. This installer uses two of these functions, download_and_unpack_tarball and make to download, untar, and compile the bzip2 library. See shrinkwrap.install for a complete list of available functions. By passing extra options to make, the software is installed into the root of the active virtualenv.
Note
For several examples of custom installers, see https://bitbucket.org/seibert/shrinkwrap_pkgs.
Examples include getting code from version control, installing with cmake, and customizing install paths.
In some situations, you only want to install a package if the operating system does not already provide it. The shrinkwrap_skip argument to setup() allows you to specify a function to call to check if installation is performed. If the skip function returns True, then the installer() function is skipped, but the package is marked as installed.
Here is an example of a package that installs curl only if version 7.26.0 or newer is not present:
try:
from shrinkwrap.install import ShrinkwrapInstall
except ImportError:
import subprocess; subprocess.check_call('pip install -b $VIRTUAL_ENV/build/build-shrinkwrap shrinkwrap', shell=True)
from shrinkwrap.install import ShrinkwrapInstall
from setuptools import setup
from distutils.version import LooseVersion
version = '7.27.0'
def skip(inst):
try:
output = inst.cmd_output('curl-config --version')
name, version_str = output.split()
system_version = LooseVersion(version_str)
min_version = LooseVersion('7.26.0')
if system_version > min_version:
return True # Don't install
else:
return False # Version too old
except:
return False # install package if anything went wrong
setup(
name='curl-check',
version=version,
author='Stan Seibert',
author_email='stan@mtrr.org',
shrinkwrap_installer='autoconf',
shrinkwrap_skip=skip,
shrinkwrap_source_url='http://curl.haxx.se/download/curl-%s.tar.bz2' % version,
cmdclass={'install': ShrinkwrapInstall},
)
The handling of package dependencies in pip (as of version 1.1, anyway) does not, unfortunately, meet the requirements for installing compiled software. Packages listed in the install_requires keyword argument to setup() will be discovered by pip and installed, but in an arbitrary order. Packages listed in the setup_requires keyword argument are not actually installed to the virtualenv, but rather made available in .egg files in the build directory, which also is not a solution for compiled code.
As a result, shrinkwrap adds a new keyword argument, shrinkwrap_requires, to setup(). All dependencies listed here are guaranteed to be fully installed to the virtualenv before the installer() function is run. A separate pip process is spawned to install each one, so the dependency string can include package versions, just as setup_requires and install_requires allow. The shrinkwrap dependencies can be any kind of package, so if your library uses SCons as the build system, you can list it in the shrinkwrap_requires field:
setup(
name='foo',
version=version,
author='Example Author'
author_email='author@example.com'
shrinkwrap_installer=installer,
shrinkwrap_requires=['scons'],
cmdclass={'install': ShrinkwrapInstall},
)
If your package also needs to set some shell environment variables for operation, they can be placed in the $VIRTUAL_ENV/env.d directory, and they will be sourced automatically when the $VIRTUAL_ENV/bin/activate script is sourced. See the package file for CERN’s ROOT library for an example of using the install_env() convenience function.
To share shrinkwrap packages via a package index like PyPI (remember: don’t actually upload shrinkwrap packages to PyPI), you must create distribution tarballs. Shrinkwrap includes a tool to create these automatically from wrapper setup.py files:
shrinkwrap createpkg bzip2-1.0.6.py
This will create a tarball in the current directory suitable for uploading. Wildcards are valid for generating many packages at once.
Note
You can name the python file anything you want (not just setup.py). It will be copied to setup.py in a temp directory and the name of the resulting tarball will be derived from the package metadata you specified.
As mentioned in the Limitations section, shrinkwrap packages are small and easy to deploy. It is better to have different package repositories when you want to build a source package with different options in different situations, rather than have One Repository To Rule Them All [1] .
If you wish to serve your own package index, use the -p option to place output tarballs into one properly-formatted directory:
shrinkwrap createpkg -p packages my_shrinkwrap_pkgs/*
Simply serve the packages directory on the web, and pip clients can interact with it just like PyPI:
client$ export PIP_EXTRA_INDEX_URL=http://your-server.com/packages/
client$ pip install bzip2
Extra package indices can be specified in a requirements.txt file with an option at the top:
--extra-index-url http://mtrr.org/packages/
[1] | In order to avoid creating One Repository To Rule Them All, we do not plan to ever offer a repository of “official” shrinkwrap packages. Feel free to copy other people’s package files to your repository, however. |
|
Near future goals:
Far future goals:
utilities for installing shrinkwrapped packages
Standard system-wide include paths
Base class for a setup.py “install” command that wraps a generic tarball installation.
Search for a header by filename.
Searches in standard locations defined in SYSTEM_INCLUDE_PATHS as well as any paths provided in extra_paths, returning True if the file is found and False if not.
Run command in the shell and return its output as a byte string.
If return code from command not equal to success_return_code, raises subprocess.CalledProcessError.
Based on implementation from: https://gist.github.com/1027906
Convenience method that downloads a tarball from the given URL and unpacks it. By default, the tarfile and uncompressed contents are placed in the current directory, but if to_src_dir is True, then both the tarfile and contents will be in the src/ directory under the virtualenv base.
Returns the full path to the downloaded tar file.
Downloads a file. If no saveto is specified, the basename of the URL and the current directory will be used.
Returns the full path to the saved file on disk.
Full path to shrinkwrap env directory inside virtualenv
Create an environment shell script called filename in the shrinkwrap env directory and fill it with the string contents.
Run make in current directory. If parallel is true, will run make with the -j option and the number of CPU cores. extra_opts is a list of additional options to be passed to make.
Remember to escape them for the shell, if needed!
Number of CPU cores.
Location of python library.
setuptools install command that install dependencies in before calling the installer function provided in the shrinkwrap_installer keyword argument to setup().
Disable installer skip functions by setting SHRINKWRAP_NEVER_SKIP to 1.
Runs cmd in a shell. Raises subprocess.CalledProcessError if the return code from cmd is not equal to success_return_code.
Full path to source directory inside virtualenv
Unpack tar file with filename source to directory target. If makedir is true, then the target directory will be created first, including missing parent directories.
Default is to extract to current directory.
Full path to base of virtualenv directory.
Verify that value is a callable function
Verify that value is a string
A convenience function to perform an autoconf-based installation.
Note: requires parameter “shrinkwrap_source_dir” to be set in setup() call.
Verify that value is either an allowed string or a callable function
shrinkwrap command-line utility
Print the contents of scripts in $VIRTUAL_ENV/env.d.
Take each listed file on the command line, copy to a temporary directory, rename to setup.py, run “python setup.py sdist”, and copy back the generated tar file.
Streamlines the creation of shrinkwrap packages which are entirely defined by a setup.py file.
Print usage for the shrinkwrap command-line utility.
Please activate JavaScript to enable the search functionality.
From here you can search these documents. Enter your search words into the box below and click "search". Note that the search function will automatically search for all of the words. Pages containing fewer words won't appear in the result list.