archive-com.com » COM » T » TELECOMMUNITY.COM

Total: 388

Choose link from "Titles, links and description words view":

Or switch to "Titles and links view".
  • setuptools - The PEAK Developers' Center
    t It s really intended to support projects with lots of non Python dependencies and as a last resort for crufty projects that can t otherwise handle being compressed If your package is pure Python Python plus data files or Python plus C you really don t need this You ve got to be using either C or an external program that needs real files in your project before there s any possibility of eager resources being relevant to your project Extensible Applications and Frameworks Dynamic Discovery of Services and Plugins setuptools supports creating libraries that plug in to extensible applications and frameworks by letting you register entry points in your project that can be imported by the application or framework For example suppose that a blogging tool wants to support plugins that provide translation for various file types to the blog s output format The framework might define an entry point group called blogtool parsers and then allow plugins to register entry points for the file extensions they support This would allow people to create distributions that contain one or more parsers for different file types and then the blogging tool would be able to find the parsers at runtime by looking up an entry point for the file extension or mime type or however it wants to Note that if the blogging tool includes parsers for certain file formats it can register these as entry points in its own setup script which means it doesn t have to special case its built in formats They can just be treated the same as any other plugin s entry points would be If you re creating a project that plugs in to an existing application or framework you ll need to know what entry points or entry point groups are defined by that application or framework Then you can register entry points in your setup script Here are a few examples of ways you might register an rst file parser entry point in the blogtool parsers entry point group for our hypothetical blogging tool setup entry points blogtool parsers rst some module SomeClass setup entry points blogtool parsers rst some module a func setup entry points blogtool parsers rst some nested module SomeClass some classmethod reST extras require dict reST Docutils 0 3 5 The entry points argument to setup accepts either a string with ini style sections or a dictionary mapping entry point group names to either strings or lists of strings containing entry point specifiers An entry point specifier consists of a name and value separated by an sign The value consists of a dotted module name optionally followed by a and a dotted identifier naming an object within the module It can also include a bracketed list of extras that are required for the entry point to be used When the invoking application or framework requests loading of an entry point any requirements implied by the associated extras will be passed to pkg resources require so that an appropriate error message can be displayed if the needed package s are missing Of course the invoking app or framework can ignore such errors if it wants to make an entry point optional if a requirement isn t installed Defining Additional Metadata Some extensible applications and frameworks may need to define their own kinds of metadata to include in eggs which they can then access using the pkg resources metadata APIs Ordinarily this is done by having plugin developers include additional files in their ProjectName egg info directory However since it can be tedious to create such files by hand you may want to create a distutils extension that will create the necessary files from arguments to setup in much the same way that setuptools does for many of the setup arguments it adds See the section below on Creating distutils Extensions for more details especially the subsection on Adding new EGG INFO Files Development Mode Under normal circumstances the distutils assume that you are going to build a distribution of your project not use it in its raw or unbuilt form If you were to use the distutils that way you would have to rebuild and reinstall your project every time you made a change to it during development Another problem that sometimes comes up with the distutils is that you may need to do development on two related projects at the same time You may need to put both projects packages in the same directory to run them but need to keep them separate for revision control purposes How can you do this Setuptools allows you to deploy your projects for use in a common directory or staging area but without copying any files Thus you can edit each project s code in its checkout directory and only need to run build commands when you change a project s C extensions or similarly compiled files You can even deploy a project into another project s checkout directory if that s your preferred way of working as opposed to using a common independent staging area or the site packages directory To do this use the setup py develop command It works very similarly to setup py install or the EasyInstall tool except that it doesn t actually install anything Instead it creates a special egg link file in the deployment directory that links to your project s source code And if your deployment directory is Python s site packages directory it will also update the easy install pth file to include your project s source code thereby making it available on sys path for all programs using that Python installation In addition the develop command creates wrapper scripts in the target script directory that will run your in development scripts after ensuring that all your install requires packages are available on sys path You can deploy the same project to multiple staging areas e g if you have multiple projects on the same machine that are sharing the same project you re doing development work When you re done with a given development task you can remove the project source from a staging area using setup py develop uninstall specifying the desired staging area if it s not the default There are several options to control the precise behavior of the develop command see the section on the develop command below for more details Distributing a setuptools based package Using setuptools Without bundling it Your users might not have setuptools installed on their machines or even if they do it might not be the right version Fixing this is easy just download ez setup py and put it in the same directory as your setup py script Be sure to add it to your revision control system too Then add these two lines to the very top of your setup script before the script imports anything from setuptools import ez setup ez setup use setuptools That s it The ez setup module will automatically download a matching version of setuptools from PyPI if it isn t present on the target system Whenever you install an updated version of setuptools you should also update your projects ez setup py files so that a matching version gets installed on the target machine s By the way setuptools supports the new PyPI upload command so you can use setup py sdist upload or setup py bdist egg upload to upload your source or egg distributions respectively Your project s current version must be registered with PyPI first of course you can use setup py register to do that Or you can do it all in one step e g setup py register sdist bdist egg upload will register the package build source and egg distributions and then upload them both to PyPI where they ll be easily found by other projects that depend on them Managing Multiple Projects If you re managing several projects that need to use ez setup and you are using Subversion as your revision control system you can use the svn externals property to share a single copy of ez setup between projects so that it will always be up to date whenever you check out or update an individual project without having to manually update each project to use a new version However because Subversion only supports using directories as externals you have to turn ez setup py into ez setup init py in order to do this then create externals definitions that map the ez setup directory into each project Also if any of your projects use find packages on their setup directory you will need to exclude the resulting ez setup package to keep it from being included in your distributions e g setup packages find packages exclude ez setup Of course the ez setup package will still be included in your packages source distributions as it needs to be For your convenience you may use the following external definition which will track the latest version of setuptools ez setup svn svn eby sarna com svnroot ez setup You can set this by executing this command in your project directory svn propedit svn externals And then adding the line shown above to the file that comes up for editing Setting the zip safe flag For maximum performance Python packages are best installed as zip files Not all packages however are capable of running in compressed form because they may expect to be able to access either source code or data files as normal operating system files So setuptools can install your project as a zipfile or a directory and its default choice is determined by the project s zip safe flag You can pass a True or False value for the zip safe argument to the setup function or you can omit it If you omit it the bdist egg command will analyze your project s contents to see if it can detect any conditions that would prevent it from working in a zipfile It will output notices to the console about any such conditions that it finds Currently this analysis is extremely conservative it will consider the project unsafe if it contains any C extensions or datafiles whatsoever This does not mean that the project can t or won t work as a zipfile It just means that the bdist egg authors aren t yet comfortable asserting that the project will work If the project contains no C or data files and does no file or path introspection or source code manipulation then there is an extremely solid chance the project will work when installed as a zipfile And if the project uses pkg resources for all its data file access then C extensions and other data files shouldn t be a problem at all See the Accessing Data Files at Runtime section above for more information However if bdist egg can t be sure that your package will work but you ve checked over all the warnings it issued and you are either satisfied it will work or if you want to try it for yourself then you should set zip safe to True in your setup call If it turns out that it doesn t work you can always change it to False which will force setuptools to install your project as a directory rather than as a zipfile Of course the end user can still override either decision if they are using EasyInstall to install your package And if you want to override for testing purposes you can just run setup py easy install zip ok or setup py easy install always unzip in your project directory to install the package as a zipfile or directory respectively In the future as we gain more experience with different packages and become more satisfied with the robustness of the pkg resources runtime the zip safety analysis may become less conservative However we strongly recommend that you determine for yourself whether your project functions correctly when installed as a zipfile correct any problems if you can and then make an explicit declaration of True or False for the zip safe flag so that it will not be necessary for bdist egg or EasyInstall to try to guess whether your project can work as a zipfile Namespace Packages Sometimes a large package is more useful if distributed as a collection of smaller eggs However Python does not normally allow the contents of a package to be retrieved from more than one location Namespace packages are a solution for this problem When you declare a package to be a namespace package it means that the package has no meaningful contents in its init py and that it is merely a container for modules and subpackages The pkg resources runtime will automatically ensure that the contents of namespace packages that are spread over multiple eggs or directories are combined into a single virtual package The namespace packages argument to setup lets you declare your project s namespace packages so that they will be included in your project s metadata Then the runtime will automatically detect this when it adds the distribution to sys path and ensure that the packages are properly merged The argument should list the namespace packages that the egg participates in For example the ZopeInterface project might do this setup namespace packages zope because it contains a zope interface package that lives in the zope namespace package Similarly a project for a standalone zope publisher would also declare the zope namespace package Namespace packages don t have to be top level packages For example Zope 3 s zope app package is a namespace package and in the future PEAK s peak util package will be too Note by the way that your project s source tree must include the namespace packages init py files and the init py of any parent packages in a normal Python package layout These init py files should not contain any code or data because only one egg s init py files will be used to construct the parent packages in memory at runtime and there is no guarantee which egg will be used For example if both zope interface and zope publisher have been installed from separate distributions it is unspecified which of the two distributions zope init py files will be used to create the zope package in memory Therefore it is better not to have any code or data in a namespace package s init module so as to prevent any complications This is one reason the concept is called a namespace package it is a package that exists only to provide a namespace under which other modules or packages are gathered In Java for example namespace packages are often used just to avoid naming collisions between different projects using package names like org apache as a namespace for packages that are part of apache org projects Tagging and Daily Build or Snapshot Releases When a set of related projects are under development it may be important to track finer grained version increments than you would normally use for e g stable releases While stable releases might be measured in dotted numbers with alpha beta etc status codes development versions of a project often need to be tracked by revision or build number or even build date This is especially true when projects in development need to refer to one another and therefore may literally need an up to the minute version of something To support these scenarios setuptools allows you to tag your source and egg distributions by adding one or more of the following to the project s official version identifier An identifying string such as build or dev or a manually tracked build or revision number tag build STRING bSTRING A last modified revision number string generated automatically from Subversion s metadata assuming your project is being built from a Subversion working copy tag svn revision r An 8 character representation of the build date tag date d You can add these tags by adding egg info and the desired options to the command line ahead of the sdist or bdist commands that you want to generate a daily build or snapshot for See the section below on the egg info command for more details Also if you are creating builds frequently and either building them in a downloadable location or are copying them to a distribution server you should probably also check out the rotate command which lets you automatically delete all but the N most recently modified distributions matching a glob pattern So you can use a command line like setup py egg info rbDEV bdist egg rotate m egg k3 to build an egg whose version info includes DEV rNNNN where NNNN is the most recent Subversion revision that affected the source tree and then delete any egg files from the distribution directory except for the three that were built most recently If you have to manage automated builds for multiple packages each with different tagging and rotation policies you may also want to check out the alias command which would let each package define an alias like daily that would perform the necessary tag build and rotate commands Then a simpler script or cron job could just run setup py daily in each project directory And you could also define sitewide or per user default versions of the daily alias so that projects that didn t define their own would use the appropriate defaults Generating Source Distributions setuptools enhances the distutils default algorithm for source file selection so that all files managed by CVS or Subversion in your project tree are included in any source distribution you build This is a big improvement over having to manually write a MANIFEST in file and try to keep it in sync with your project So if you are using CVS or Subversion and your source distributions only need to include files that you re tracking in revision control don t create a a MANIFEST in file for your project And if you already have one you might consider deleting it the next time you would otherwise have to change it Unlike the distutils setuptools regenerates the source distribution MANIFEST file every time you build a source distribution as long as you don t have a MANIFEST in file If you do have a MANIFEST in e g because you aren t using CVS or Subversion then you ll have to follow the normal distutils procedures for managing what files get included in a source distribution and setuptools enhanced algorithms will not be used Note by the way that if you re using some other revision control system you might consider submitting a patch to the setuptools command sdist module so we can include support for it too Making your package available for EasyInstall If you use the register command setup py register to register your package with PyPI that s most of the battle right there See the docs for the register command for more details If you also use the upload command to upload actual distributions of your package that s even better because EasyInstall will be able to find and download them directly from your project s PyPI page However there may be reasons why you don t want to upload distributions to PyPI and just want your existing distributions or perhaps a Subversion checkout to be used instead So here s what you need to do before running the register command There are three setup arguments that affect EasyInstall url and download url These become links on your project s PyPI page EasyInstall will examine them to see if they link to a package primary links or whether they are HTML pages If they re HTML pages EasyInstall scans all HREF s on the page for primary links long description EasyInstall will check any URLs contained in this argument to see if they are primary links A URL is considered a primary link if it is a link to a tar gz tgz zip egg egg zip tar bz2 or exe file or if it has an egg project or egg project version fragment identifier attached to it EasyInstall attempts to determine a project name and optional version number from the text of a primary link without downloading it When it has found all the primary links EasyInstall will select the best match based on requested version platform compatibility and other criteria So if your url or download url point either directly to a downloadable source distribution or to HTML page s that have direct links to such then EasyInstall will be able to locate downloads automatically If you want to make Subversion checkouts available then you should create links with either egg project or egg project version added to the URL You should replace project and version with the values they would have in an egg filename Be sure to actually generate an egg and then use the initial part of the filename rather than trying to guess what the escaped form of the project name and version number will be Note that Subversion checkout links are of lower precedence than other kinds of distributions so EasyInstall will not select a Subversion checkout for downloading unless it has a version included in the egg suffix and it s a higher version than EasyInstall has seen in any other links for your project As a result it s a common practice to use mark checkout URLs with a version of dev i e egg projectname dev so that users can do something like this easy install editable projectname dev in order to check out the in development version of projectname Distributing Extensions compiled with Pyrex setuptools includes transparent support for building Pyrex extensions as long as you define your extensions using setuptools Extension not distutils Extension You must also not import anything from Pyrex in your setup script If you follow these rules you can safely list pyx files as the source of your Extension objects in the setup script setuptools will detect at build time whether Pyrex is installed or not If it is then setuptools will use it If not then setuptools will silently change the Extension objects to refer to the c counterparts of the pyx files so that the normal distutils C compilation process will occur Of course for this to work your source distributions must include the C code generated by Pyrex as well as your original pyx files This means that you will probably want to include current c files in your revision control system rebuilding them whenever you check changes in for the pyx source files This will ensure that people tracking your project in CVS or Subversion will be able to build it even if they don t have Pyrex installed and that your source releases will be similarly usable with or without Pyrex Command Reference alias Define shortcuts for commonly used commands Sometimes you need to use the same commands over and over but you can t necessarily set them as defaults For example if you produce both development snapshot releases and stable releases of a project you may want to put the distributions in different places or use different egg info tagging options etc In these cases it doesn t make sense to set the options in a distutils configuration file because the values of the options changed based on what you re trying to do Setuptools therefore allows you to define aliases shortcut names for an arbitrary string of commands and options using setup py alias aliasname expansion where aliasname is the name of the new alias and the remainder of the command line supplies its expansion For example this command defines a sitewide alias called daily that sets various egg info tagging options setup py alias global config daily egg info tag svn revision tag build development Once the alias is defined it can then be used with other setup commands e g setup py daily bdist egg generate a daily build egg file setup py daily sdist generate a daily build source distro setup py daily sdist bdist egg generate both The above commands are interpreted as if the word daily were replaced with egg info tag svn revision tag build development Note that setuptools will expand each alias at most once in a given command line This serves two purposes First if you accidentally create an alias loop it will have no effect you ll instead get an error message about an unknown command Second it allows you to define an alias for a command that uses that command For example this project local alias setup py alias bdist egg bdist egg rotate k1 m egg redefines the bdist egg command so that it always runs the rotate command afterwards to delete all but the newest egg file It doesn t loop indefinitely on bdist egg because the alias is only expanded once when used You can remove a defined alias with the remove or r option e g setup py alias global config remove daily would delete the daily alias we defined above Aliases can be defined on a project specific per user or sitewide basis The default is to define or remove a project specific alias but you can use any of the configuration file options listed under the saveopts command below to determine which distutils configuration file an aliases will be added to or removed from Note that if you omit the expansion argument to the alias command you ll get output showing that alias current definition and what configuration file it s defined in If you omit the alias name as well you ll get a listing of all current aliases along with their configuration file locations bdist egg Create a Python Egg for the project This command generates a Python Egg egg file for the project Python Eggs are the preferred binary distribution format for EasyInstall because they are cross platform for pure packages directly importable and contain project metadata including scripts and information about the project s dependencies They can be simply downloaded and added to sys path directly or they can be placed in a directory on sys path and then automatically discovered by the egg runtime system This command runs the egg info command if it hasn t already run to update the project s metadata egg info directory If you have added any extra metadata files to the egg info directory those files will be included in the new egg file s metadata directory for use by the egg runtime system or by any applications or frameworks that use that metadata You won t usually need to specify any special options for this command just use bdist egg and you re done But there are a few options that may be occasionally useful dist dir DIR d DIR Set the directory where the egg file will be placed If you don t supply this then the dist dir setting of the bdist command will be used which is usually a directory named dist in the project directory plat name PLATFORM p PLATFORM Set the platform name string that will be embedded in the egg s filename assuming the egg contains C extensions This can be used to override the distutils default platform name with something more meaningful Keep in mind however that the egg runtime system expects to see eggs with distutils platform names so it may ignore or reject eggs with non standard platform names Similarly the EasyInstall program may ignore them when searching web pages for download links However if you are cross compiling or doing some other unusual things you might find a use for this option exclude source files Don t include any modules py files in the egg just compiled Python C and data files Note that this doesn t affect any py files in the EGG INFO directory or its subdirectories since for example there may be scripts with a py extension which must still be retained We don t recommend that you use this option except for packages that are being bundled for proprietary end user applications or for embedded scenarios where space is at an absolute premium On the other hand if your package is going to be installed and used in compressed form you might as well exclude the source because Python s traceback module doesn t currently understand how to display zipped source code anyway or how to deal with files that are in a different place from where their code was compiled There are also some options you will probably never need but which are there because they were copied from similar bdist commands used as an example for creating this one They may be useful for testing and debugging however which is why we kept them keep temp k Keep the contents of the bdist dir tree around after creating the egg file bdist dir DIR b DIR Set the temporary directory for creating the distribution The entire contents of this directory are zipped to create the egg file after running various installation commands to copy the package s modules data and extensions here skip build Skip doing any build commands just go straight to the install and compress phases develop Deploy the project source in Development Mode This command allows you to deploy your project s source for use in one or more staging areas where it will be available for importing This deployment is done in such a way that changes to the project source are immediately available in the staging area s without needing to run a build or install step after each change The develop command works by creating an egg link file named for the project in the given staging area If the staging area is Python s site packages directory it also updates an easy install pth file so that the project is on sys path by default for all programs run using that Python installation The develop command also installs wrapper scripts in the staging area or a separate directory as specified that will ensure the project s dependencies are available on sys path before running the project s source scripts And it ensures that any missing project dependencies are available in the staging area by downloading and installing them if necessary Last but not least the develop command invokes the build ext i command to ensure any C extensions in the project have been built and are up to date and the egg info command to ensure the project s metadata is updated so that the runtime and wrappers know what the project s dependencies are If you make any changes to the project s setup script or C extensions you should rerun the develop command against all relevant staging areas to keep the project s scripts metadata and extensions up to date Most other kinds of changes to your project should not require any build operations or rerunning develop but keep in mind that even minor changes to the setup script e g changing an entry point definition require you to re run the develop or test commands to keep the distribution updated Here are the options that the develop command accepts Note that they affect the project s dependencies as well as the project itself so if you have dependencies that need to be installed and you use exclude scripts for example the dependencies scripts will not be installed either For this reason you may want to use EasyInstall to install the project s dependencies before using the develop command if you need finer control over the installation options for dependencies uninstall u Un deploy the current project You may use the install dir or d option to designate the staging area The created egg link file will be removed if present and it is still pointing to the project directory The project directory will be removed from easy install pth if the staging area is Python s site packages directory Note that this option currently does not uninstall script wrappers You must uninstall them yourself or overwrite them by using EasyInstall to activate a different version of the package You can also avoid installing script wrappers in the first place if you use the exclude scripts aka x option when you run develop to deploy the project multi version m Multi version mode Specifying this option prevents develop from adding an easy install pth entry for the project s being deployed and if an entry for any version of a project already exists the entry will be removed upon successful deployment In multi version mode no specific version of the package is available for importing unless you use pkg resources require to put it on sys path or you are running a wrapper script generated by setuptools or EasyInstall In which case the wrapper script calls require for you Note that if you install to a directory other than site packages this option is automatically in effect because pth files can only be used in site packages at least in Python 2 3 and 2 4 So if you use the install dir or d option or they are set via configuration file s your project and its dependencies will be deployed in multi version mode install dir DIR d DIR Set the installation directory staging area If this option is not directly specified on the command line or in a distutils configuration file the distutils default installation location is used Normally this will be the site packages directory but if you are using distutils configuration files setting things like prefix or install lib then those settings are taken into account when computing the default staging area script dir DIR s DIR Set the script installation directory If you don t supply this option via the command line or a configuration file but you have supplied an install dir via command line or config file then this option defaults to the same directory so that the scripts will be able to find their associated package installation Otherwise this setting defaults to the location where the distutils would normally install scripts taking any distutils configuration file settings into account exclude scripts x Don t deploy script wrappers This is useful if you don t want to disturb existing versions of the scripts in the staging area always copy a Copy all needed distributions to the staging area even if they are already present in another directory on sys path By default if a requirement can be met using a distribution that is already available in a directory on sys path it will not be copied to the staging area egg info Create egg metadata and set build tags This command performs two operations it updates a project s egg info metadata directory used by the bdist egg develop and test commands and it allows you to temporarily change a project s version string to support daily builds or snapshot releases It is run automatically by the sdist bdist egg develop and test commands in order to update the project s metadata but you can also specify it explicitly in order to temporarily change the project s version string The following options can be used to modify the project s version string for all remaining commands on the setup command line The options are processed in the order shown so if you use more than one the requested tags will be added in the following order tag build NAME b NAME Append NAME to the project s version string Due to the way setuptools processes pre release version suffixes beginning with the letters a through e like alpha beta and candidate you will usually want to use a tag like build or dev

    Original URL path: http://peak.telecommunity.com/DevCenter/setuptools?action=recall&date=1130010816 (2016-04-24)
    Open archived version from archive


  • Diff for "setuptools" - The PEAK Developers' Center
    dependency links http peak telecommunity com snapshots Declaring Extras The distutils have traditionally allowed installation of data files which are placed in a platform specific location However the most common use case for data files distributed with a package is for use by the package usually by including the data files in the package directory Setuptools supports this by allowing a package data argument to setup e g by including the data files in the package directory Setuptools offers three ways to specify data files to be included in your packages First you can simply use the include package data keyword e g from setuptools import setup find packages setup include package data True This tells setuptools to install any data files it finds in your packages The data files must be under CVS or Subversion control or else they must be specified via the distutils MANIFEST in file They can also be tracked by another revision control system using an appropriate plugin See the section below on Adding Support for Other Revision Control Systems for information on how to write such plugins If you want finer grained control over what files are included for example if you have documentation files in your package directories and want to exclude them from installation then you can also use the package data keyword e g from setuptools import setup find packages setup packages find packages src include all packages under src package dir src tell distutils packages are under src package data If any package contains txt files include them txt Python 2 4 there is some documentation for the feature available on the python org website http docs python org dist node11 html http docs python org dist node11 html Sometimes the include package data or package data options alone aren t sufficient to precisely define what files you want included For example you may want to include package README files in your revision control system and source distributions but exclude them from being installed So setuptools offers an exclude package data option as well that allows you to do things like this from setuptools import setup find packages setup packages find packages src include all packages under src package dir src tell distutils packages are under src include package data True include everything in source control but exclude README txt from all packages exclude package data README txt The exclude package data option is a dictionary mapping package names to lists of wildcard patterns just like the package data option And just as with that option a key of will apply the given pattern s to all packages However any files that match these patterns will be excluded from installation even if they were listed in package data or were included as a result of using include package data In summary the three options allow you to include package data Accept all data files and directories matched by MANIFEST in or found in source control package data Specify additional patterns to match files and directories that may or may not be matched by MANIFEST in or found in source control exclude package data Specify patterns for data files and directories that should not be included when a package is installed even if they would otherwise have been included due to the use of the preceding options NOTE Due to the way the distutils build process works a data file that you include in your project and then stop including may be orphaned in your project s build directories requiring you to run setup py clean all to fully remove them This may also be important for your users and contributors if they track intermediate revisions of your project using Subversion be sure to let them know when you make changes that remove files from inclusion so they can run setup py clean all Accessing Data Files at Runtime project includes non extension native libraries or other files that your C extensions expect to be able to access you may need to list those files in the eager resources argument to setup so that the files will be extracted together whenever a C extension in the project is imported This is especially important if your project includes shared libraries other than distutils built C extensions Those shared libraries should be listed as eager resources because they need to be present in the filesystem when the C extensions that link to them are used extracted together whenever a C extension in the project is imported This is especially important if your project includes shared libraries other than distutils built C extensions and those shared libraries use file extensions other than dll so or dylib which are the extensions that setuptools 0 6a8 and higher automatically detects as shared libraries and adds to the native libs txt file for you Any shared libraries whose names do not end with one of those extensions should be listed as eager resources because they need to be present in the filesystem when he C extensions that link to them are used The pkg resources runtime for compressed packages will automatically extract all C extensions and eager resources at the same time whenever There are several options to control the precise behavior of the develop command see the section on the develop command below for more details Note that you can also apply setuptools commands to non setuptools projects using commands like this Distributing a setuptools based package python c import setuptools execfile setup py develop That is you can simply list the normal setup commands and options following the quoted part Distributing a setuptools based project Using setuptools Without bundling it distributions and then upload them both to PyPI where they ll be easily found by other projects that depend on them By the way if you need to distribute a specific version of setuptools you can specify the exact version and base download URL as parameters to the use setuptools function See the function s docstring for details What Your Users Should Know In general a setuptools based project looks just like any distutils based project as long as your users have an internet connection and are installing to site packages that is But for some users these conditions don t apply and they may become frustrated if this is their first encounter with a setuptools based project To keep these users happy you should review the following topics in your project s installation instructions if they are relevant to your project and your target audience isn t already familiar with setuptools and easy install Network Access If your project is using ez setup you should inform users of the need to either have network access or to preinstall the correct version of setuptools using the EasyInstall installation instructions Those instructions also have tips for dealing with firewalls as well as how to manually download and install setuptools Custom Installation Locations You should inform your users that if they are installing your project to somewhere other than the main site packages directory they should first install setuptools using the instructions for Custom Installation Locations before installing your project Your Project s Dependencies If your project depends on other projects that may need to be downloaded from PyPI or elsewhere you should list them in your installation instructions or tell users how to find out what they are While most users will not need this information any users who don t have unrestricted internet access may have to find download and install the other projects manually Note however that they must still install those projects using easy install or your project will not know they are installed and your setup script will try to download them again If you want to be especially friendly to users with limited network access you may wish to build eggs for your project and its dependencies making them all available for download from your site or at least create a page with links to all of the needed eggs In this way users with limited network access can manually download all the eggs to a single directory then use the f option of easy install to specify the directory to find eggs in Users who have full network access can just use f with the URL of your download page and easy install will find all the needed eggs using your links directly This is also useful when your target audience isn t able to compile packages e g most Windows users and your package or some of its dependencies include C code Subversion or CVS Users and Co Developers Users and co developers who are tracking your in development code using CVS Subversion or some other revision control system should probably read this manual s sections regarding such development Alternately you may wish to create a quick reference guide containing the tips from this manual that apply to your particular situation For example if you recommend that people use setup py develop when tracking your in development code you should let them know that this needs to be run after every update or commit Similarly if you remove modules or data files from your project you should remind them to run setup py clean all and delete any obsolete pyc or pyo This tip applies to the distutils in general not just setuptools but not everybody knows about them be kind to your users by spelling out your project s best practices rather than leaving them guessing Creating System Packages Some users want to manage all Python packages using a single package manager and sometimes that package manager isn t easy install Setuptools currently supports bdist rpm bdist wininst and bdist dumb formats for system packaging If a user has a locally installed bdist packaging tool that internally uses the distutils install command it should be able to work with setuptools Some examples of bdist formats that this should work with include the bdist nsi and bdist msi formats for Windows However packaging tools that build binary distributions by running setup py install on the command line or as a subprocess will require modification to work with setuptools They should use the single version externally managed option to the install command combined with the standard root or record options See the install command documentation below for more details The bdist deb command is an example of a command that currently requires this kind of patching to work with setuptools If you or your users have a problem building a usable system package for your project please report the problem via the mailing list so that either the bdist tool in question or setuptools can be modified to resolve the issue Managing Multiple Projects package it means that the package has no meaningful contents in its init py and that it is merely a container for modules and subpackages The pkg resources runtime will automatically ensure that the contents of namespace packages that are spread over multiple eggs or directories are combined into a single virtual package The pkg resources runtime will then automatically ensure that the contents of namespace packages that are spread over multiple eggs or directories are combined into a single virtual package The namespace packages argument to setup lets you declare your project s namespace packages so that they will be included in your project s metadata Then the runtime will automatically detect this when it adds the distribution to sys path and ensure that the packages are properly merged The argument should list the namespace packages that the egg participates in For example the ZopeInterface project might do this metadata The argument should list the namespace packages that the egg participates in For example the ZopeInterface project might do this setup because it contains a zope interface package that lives in the zope namespace package Similarly a project for a standalone zope publisher would also declare the zope namespace package would also declare the zope namespace package When these projects are installed and used Python will see them both as part of a virtual zope package even though they will be installed in different locations Namespace packages don t have to be top level packages For example Zope 3 s zope app package is a namespace package and in the future PEAK s Note by the way that your project s source tree must include the namespace packages init py files and the init py of any parent packages in a normal Python package layout These init py files should not contain any code or data because only one egg s init py files will be used to construct the parent packages in memory at runtime and there is no guarantee which egg will be used For example if both zope interface and zope publisher have been installed from separate distributions it is unspecified which of the two distributions zope init py files will be used to create the zope package in memory Therefore it is better not to have any code or data in a namespace package s init module so as to prevent any complications This is one reason the concept is called a namespace package it is a package that exists only to provide a namespace under which other modules or packages are gathered In Java for example namespace packages are often used just to avoid naming collisions between different projects using package names like org apache as a namespace for packages that are part of apache org projects must contain the line import pkg resources declare namespace name This code ensures that the namespace package machinery is operating and that the current package is registered as a namespace package You must NOT include any other code and data in a namespace package s init py Even though it may appear to work during development or when projects are installed as egg files it will not work when the projects are installed using system packaging tools in such cases the init py files will not be installed let alone executed You must include the declare namespace line in the init py of every project that has contents for the namespace package in question in order to ensure that the namespace will be declared regardless of which project s copy of init py is loaded first If the first loaded init py doesn t declare it it will never be declared because no other copies will ever be loaded TRANSITIONAL NOTE Setuptools 0 6a automatically calls declare namespace for you at runtime but the 0 7a versions will not This is because the automatic declaration feature has some negative side effects such as needing to import all namespace packages during the initialization of the pkg resources runtime and also the need for pkg resources to be explicitly imported before any namespace packages work at all Beginning with the 0 7a releases you ll be responsible for including your own declaration lines and the automatic declaration feature will be dropped to get rid of the negative side effects During the remainder of the 0 6 development cycle therefore setuptools will warn you about missing declare namespace calls in your init py files and you should correct these as soon as possible before setuptools 0 7a1 is released Namespace packages without declaration lines will not work correctly once a user has upgraded to setuptools 0 7a1 so it s important that you make this change now in order to avoid having your code break in the field Our apologies for the inconvenience and thank you for your patience Tagging and Daily Build or Snapshot Releases egg distributions by adding one or more of the following to the project s official version identifier An identifying string such as build or dev or a manually tracked build or revision number tag build STRING bSTRING A manually specified pre release tag such as build or dev or a manually specified post release tag such as a build or revision number tag build STRING bSTRING A last modified revision number string generated automatically from A last modified revision number string generated automatically from Subversion s metadata assuming your project is being built from a Subversion working copy tag svn revision r An 8 character representation of the build date tag date d An 8 character representation of the build date tag date d as a postrelease tag You can add these tags by adding egg info and the desired options to the command line ahead of the sdist or bdist commands that you want to generate a daily build or snapshot for See the section below on the egg info command for more details Also if you are creating builds frequently and either building them in a Also before you release your project be sure to see the section above on Specifying Your Project s Version for more information about how pre and post release tags affect how setuptools and EasyInstall interpret version numbers This is important in order to make sure that dependency processing tools will know which versions of your project are newer than others Finally if you are creating builds frequently and either building them in a downloadable location or are copying them to a distribution server you should probably also check out the rotate command which lets you automatically delete all but the N most recently modified distributions matching a glob And if you already have one you might consider deleting it the next time you would otherwise have to change it Unlike the distutils setuptools regenerates the source distribution MANIFEST file every time you build a source distribution as long as you don t have a MANIFEST in file If you do have a MANIFEST in e g because you aren t using CVS or Subversion then you ll have to follow the normal distutils procedures for managing what files get included in a source distribution and setuptools enhanced algorithms will not be used Note by the way that if you re using some other revision control system you might consider submitting a patch to the setuptools command sdist module so we can include support for it too NOTE other revision control systems besides CVS and Subversion can be supported using plugins see the section below on Adding Support for Other Revision Control Systems for information on how to write such plugins If you need to include automatically generated files or files that are kept in an unsupported revision control system you ll need to create a MANIFEST in file to specify any files that the default file location algorithm doesn t catch See the distutils documentation for more information on the format of the MANIFEST in file But be sure to ignore any part of the distutils documentation that deals with MANIFEST or how it s generated from MANIFEST in setuptools shields you from these issues and doesn t work the same way in any case Unlike the distutils setuptools regenerates the source distribution manifest file every time you build a source distribution and it builds it inside the project s egg info directory out of the way of your main project directory You therefore need not worry about whether it is up to date or not Indeed because setuptools approach to determining the contents of a source distribution is so much simpler its sdist command omits nearly all of the options that the distutils more complex sdist process requires For all practical purposes you ll probably use only the formats option if you use any option at all By the way if you re using some other revision control system you might consider creating and publishing a revision control plugin for setuptools revision control plugin for setuptools Adding Support for Other Revision Control Systems Making your package available for EasyInstall in order to check out the in development version of projectname Managing Continuous Releases Using Subversion If you expect your users to track in development versions of your project via Subversion there are a few additional steps you should take to ensure that things work smoothly with EasyInstall First you should add the following to your project s setup cfg file egg info tag build dev tag svn revision 1 This will tell setuptools to generate package version numbers like 1 0a1 dev r1263 which will be considered to be an older release than 1 0a1 Thus when you actually release 1 0a1 the entire egg infrastructure including setuptools pkg resources and EasyInstall will know that 1 0a1 supersedes any interim snapshots from Subversion and handle upgrades accordingly Note the project version number you specify in setup py should always be the next version of your software not the last released version Alternately you can leave out the tag build dev and always use the last release as a version number so that your post 1 0 builds are labelled 1 0 r1263 indicating a post 1 0 patchlevel Most projects so far however seem to prefer to think of their project as being a future version still under development rather than a past version being patched It is of course possible for a single project to have both situations using post release numbering on release branches and pre release numbering on the trunk But you don t have to make things this complex if you don t want to Commonly projects releasing code from Subversion will include a PyPI link to their checkout URL as described in the previous section with an egg projectname dev suffix This allows users to request EasyInstall to download projectname dev in order to get the latest in development code Note that if your project depends on such in progress code you may wish to specify your install requires or other requirements to include dev e g install requires OtherProject 0 2a1 dev r143 dev The above example says I really want at least this particular development revision number but feel free to follow and use an egg OtherProject dev link if you find one This avoids the need to have actual source or binary distribution snapshots of in development code available just to be able to depend on the latest and greatest a project has to offer A final note for Subversion development if you are using SVN revision tags as described in this section it s a good idea to run setup py develop after each Subversion checkin or update because your project s version number will be changing and your script wrappers need to be updated accordingly Also if the project s requirements have changed the develop command will take care of fetching the updated dependencies building changed extensions etc Be sure to also remind any of your users who check out your project from Subversion that they need to run setup py develop after every update in order to keep their checkout completely in sync Making Official Non Snapshot Releases When you make an official release creating source or binary distributions you will need to override the tag settings from setup cfg so that you don t end up registering versions like foobar 0 7a1 dev r34832 This is easy to do if you are developing on the trunk and using tags or branches for your releases just make the change to setup cfg after branching or tagging the release so the trunk will still produce development snapshots Alternately if you are not branching for releases you can override the default version options on the command line using something like python setup py egg info RDb sdist bdist egg register upload The first part of this command egg info RDb will override the configured tag information before creating source and binary eggs registering the project with PyPI and uploading the files Thus these commands will use the plain version from your setup py without adding the Subversion revision number or build designation string Of course if you will be doing this a lot you may wish to create a personal alias for this operation e g python setup py alias u release egg info RDb You can then use it like this python setup py release sdist bdist egg register upload Or of course you can create more elaborate aliases that do all of the above See the sections below on the egg info and alias commands for more ideas Distributing Extensions compiled with Pyrex and that your source releases will be similarly usable with or without Pyrex Command Reference script e g changing an entry point definition require you to re run the develop or test commands to keep the distribution updated Here are the options that the develop command accepts Note that they affect the project s dependencies as well as the project itself so if you have dependencies that need to be installed and you use exclude scripts for example the dependencies scripts will not be installed either For this reason you may want to use EasyInstall to install the project s dependencies before using the develop command if you need finer control over the installation options for dependencies Here are some of the options that the develop command accepts Note that they affect the project s dependencies as well as the project itself so if you have dependencies that need to be installed and you use exclude scripts for example the dependencies scripts will not be installed either For this reason you may want to use EasyInstall to install the project s dependencies before using the develop command if you need finer control over the installation options for dependencies uninstall u Un deploy the current project You may use the install dir or d a requirement can be met using a distribution that is already available in a directory on sys path it will not be copied to the staging area egg path DIR Force the generated egg link file to use a specified relative path to the source directory This can be useful in circumstances where your installation directory is being shared by code running under multiple platforms e g Mac and Windows which have different absolute locations for the code under development but the same relative locations with respect to the installation directory If you use this option when installing you must supply the same relative path when uninstalling In addition to the above options the develop command also accepts all of the same options accepted by easy install If you ve configured any easy install settings in your setup cfg or other distutils config files the develop command will use them as defaults unless you override them in a develop section or on the command line easy install Find and install packages This command runs the EasyInstall tool http peak telecommunity com DevCenter EasyInstall for you It is exactly equivalent to running the easy install command All command line arguments following this command are consumed and not processed further by the distutils so this must be the last command listed on the command line Please see the EasyInstall documentation for the options reference and usage examples Normally there is no reason to use this command via the command line as you can just use easy install directly It s only listed here so that you know it s a distutils command which means that you can create command aliases that use it create distutils extensions that invoke it as a subcommand and configure options for it in your setup cfg or other distutils config files egg info metadata directory used by the bdist egg develop and test commands and it allows you to temporarily change a project s version string to support daily builds or snapshot releases It is run automatically by the sdist bdist egg develop and test commands in order to update the project s metadata but you can also specify it explicitly in order to temporarily change the project s version string the sdist bdist egg develop register and test commands in order to update the project s metadata but you can also specify it explicitly in order to temporarily change the project s version string while executing other commands It also generates the egg info SOURCES txt manifest file which is used when you are building source distributions In addition to writing the core egg metadata defined by setuptools and required by pkg resources this command can be extended to write other metadata files as well by defining entry points in the egg info writers group See the section on Adding new EGG INFO Files below for more details Note that using additional metadata writers may require you to include a setup requires argument to setup in order to ensure that the desired writers are available on sys path Release Tagging Options The following options can be used to modify the project s version string for all remaining commands on the setup command line The options are processed Append NAME to the project s version string Due to the way setuptools processes pre release version suffixes beginning with the letters a through e like alpha beta and candidate you will usually want to use a tag like build or dev as this will cause the version number to use a tag like build or dev as this will cause the version number to be considered lower than the project s default version If you want to make the version number higher than the default version you can always leave off tag build and use one or both of the following options always leave off tag build and then use one or both of the following options If you have a default build tag set in your setup cfg you can suppress it on the command line using b or tag build as an argument to the egg info command tag svn revision r If the current directory is a Subversion checkout i e has a svn modification to the current directory as obtained from the svn info command If the current directory is not a Subversion checkout the command will look for a PKG INFO file instead and try to find the revision number from that by looking for a rNNNN string at the end of the version number This is so that building a package from a source distribution of a Subversion snapshot will produce a binary with the correct version number If there is no PKG INFO file or the version number contained therein does not end with r and a number then r0 is used no svn revision R Don t include the Subversion revision in the version number This option is included so you can override a default setting put in setup cfg tag date d Add a date stamp of the form YYYYMMDD e g 20050528 to the project s version number no date D Don t include a date stamp in the version number This option is included so you can override a default setting in setup cfg Note Because these options modify the version number used for source and binary distributions of your project you should first make sure that you know how the resulting version numbers will be interpreted by automated tools like EasyInstall See the section above on Specifying Your Project s Version for an explanation of pre and post release tags as well as tips on how to choose and verify a versioning scheme for your your project For advanced uses there is one other option that can be set to change the location of the project s egg info directory Commands that need to find the project s source directory or metadata should get it from this setting Other egg info Options egg base SOURCEDIR e SOURCEDIR Specify the directory that should contain the egg info directory This should normally be the root of your project s source tree which is not package dir argument to the setup function if any If there is no package dir set this option defaults to the current directory In addition to writing the core egg metadata defined by setuptools and required by pkg resources this command can be extended to write other metadata files as well by defining entry points in the egg info writers group See the section on Adding new EGG INFO Files below for more details Note that using additional metadata writers may require you to include a setup requires argument to setup in order to ensure that the desired writers are available on sys path egg info Examples Creating a dated nightly build snapshot egg python setup py egg info tag date tag build DEV bdist egg Creating and uploading a release with no version tags even if some default tags are specified in setup cfg python setup py egg info RDb sdist bdist egg register upload Notice that egg info must always appear on the command line before any commands that you want the version changes to apply to install command install Run easy install or old style installation The setuptools install command is basically a shortcut to run the easy install command on the current project However for convenience in creating system packages of setuptools based projects you can also use this option single version externally managed This boolean option tells the install command to perform an old style installation with the addition of an egg info directory so that the installed project will still have its metadata available and operate normally If you use this option you must also specify the root or record options or both because otherwise you will have no way to identify and remove the installed files This option is automatically in effect when install is invoked by another distutils command so that commands like bdist wininst and bdist rpm will create system packages of eggs It is also automatically in effect if you specify the root option install egg info Install an egg info directory in site packages Setuptools runs this command as part of install operations that use the single version externally managed options You should not invoke it directly it is documented here for completeness and so that distutils extensions such as system package builders can make use of it This command has only one option install dir DIR d DIR The parent directory where the egg info directory will be placed Defaults to the same as the install dir option specified for the install lib command which is usually the system site packages directory This command assumes that the egg info command has been given valid options via the command line or setup cfg as it will invoke the egg info command and use its options to locate the project s source egg info directory rotate you will use a glob pattern like zip or egg to match files of the specified type Note that each supplied pattern is treated as a distinct group of files for purposes of selecting files to delete keep COUNT k COUNT Number of matching distributions to keep For each group of files identified by a pattern specified with the match option delete all the configuration file options to change where the options are saved For example this command does the same as above but saves the compiler setting to the site wide global distutils configuration setup py build compiler mingw32 saveopts g Note that it doesn t matter where you place the saveopts command on the command line it will still save all the options specified for all commands For example this is another valid way to spell the last example setup py saveopts g build compiler mingw32 setup py saveopts g build compiler mingw32 Note however that all of the commands specified are always run regardless of where saveopts is placed on the command line Save settings to the global distutils cfg file inside the distutils package directory You must have write access to that directory to use this option You

    Original URL path: http://peak.telecommunity.com/DevCenter/setuptools?action=diff&date=1130010816 (2016-04-24)
    Open archived version from archive

  • setuptools - The PEAK Developers' Center
    otherwise handle being compressed If your package is pure Python Python plus data files or Python plus C you really don t need this You ve got to be using either C or an external program that needs real files in your project before there s any possibility of eager resources being relevant to your project Extensible Applications and Frameworks Dynamic Discovery of Services and Plugins setuptools supports creating libraries that plug in to extensible applications and frameworks by letting you register entry points in your project that can be imported by the application or framework For example suppose that a blogging tool wants to support plugins that provide translation for various file types to the blog s output format The framework might define an entry point group called blogtool parsers and then allow plugins to register entry points for the file extensions they support This would allow people to create distributions that contain one or more parsers for different file types and then the blogging tool would be able to find the parsers at runtime by looking up an entry point for the file extension or mime type or however it wants to Note that if the blogging tool includes parsers for certain file formats it can register these as entry points in its own setup script which means it doesn t have to special case its built in formats They can just be treated the same as any other plugin s entry points would be If you re creating a project that plugs in to an existing application or framework you ll need to know what entry points or entry point groups are defined by that application or framework Then you can register entry points in your setup script Here are a few examples of ways you might register an rst file parser entry point in the blogtool parsers entry point group for our hypothetical blogging tool setup entry points blogtool parsers rst some module SomeClass setup entry points blogtool parsers rst some module a func setup entry points blogtool parsers rst some nested module SomeClass some classmethod reST extras require dict reST Docutils 0 3 5 The entry points argument to setup accepts either a string with ini style sections or a dictionary mapping entry point group names to either strings or lists of strings containing entry point specifiers An entry point specifier consists of a name and value separated by an sign The value consists of a dotted module name optionally followed by a and a dotted identifier naming an object within the module It can also include a bracketed list of extras that are required for the entry point to be used When the invoking application or framework requests loading of an entry point any requirements implied by the associated extras will be passed to pkg resources require so that an appropriate error message can be displayed if the needed package s are missing Of course the invoking app or framework can ignore such errors if it wants to make an entry point optional if a requirement isn t installed Defining Additional Metadata Some extensible applications and frameworks may need to define their own kinds of metadata to include in eggs which they can then access using the pkg resources metadata APIs Ordinarily this is done by having plugin developers include additional files in their ProjectName egg info directory However since it can be tedious to create such files by hand you may want to create a distutils extension that will create the necessary files from arguments to setup in much the same way that setuptools does for many of the setup arguments it adds See the section below on Creating distutils Extensions for more details especially the subsection on Adding new EGG INFO Files Development Mode Under normal circumstances the distutils assume that you are going to build a distribution of your project not use it in its raw or unbuilt form If you were to use the distutils that way you would have to rebuild and reinstall your project every time you made a change to it during development Another problem that sometimes comes up with the distutils is that you may need to do development on two related projects at the same time You may need to put both projects packages in the same directory to run them but need to keep them separate for revision control purposes How can you do this Setuptools allows you to deploy your projects for use in a common directory or staging area but without copying any files Thus you can edit each project s code in its checkout directory and only need to run build commands when you change a project s C extensions or similarly compiled files You can even deploy a project into another project s checkout directory if that s your preferred way of working as opposed to using a common independent staging area or the site packages directory To do this use the setup py develop command It works very similarly to setup py install or the EasyInstall tool except that it doesn t actually install anything Instead it creates a special egg link file in the deployment directory that links to your project s source code And if your deployment directory is Python s site packages directory it will also update the easy install pth file to include your project s source code thereby making it available on sys path for all programs using that Python installation In addition the develop command creates wrapper scripts in the target script directory that will run your in development scripts after ensuring that all your install requires packages are available on sys path You can deploy the same project to multiple staging areas e g if you have multiple projects on the same machine that are sharing the same project you re doing development work When you re done with a given development task you can remove the project source from a staging area using setup py develop uninstall specifying the desired staging area if it s not the default There are several options to control the precise behavior of the develop command see the section on the develop command below for more details Distributing a setuptools based package Using setuptools Without bundling it Your users might not have setuptools installed on their machines or even if they do it might not be the right version Fixing this is easy just download ez setup py and put it in the same directory as your setup py script Be sure to add it to your revision control system too Then add these two lines to the very top of your setup script before the script imports anything from setuptools import ez setup ez setup use setuptools That s it The ez setup module will automatically download a matching version of setuptools from PyPI if it isn t present on the target system Whenever you install an updated version of setuptools you should also update your projects ez setup py files so that a matching version gets installed on the target machine s By the way setuptools supports the new PyPI upload command so you can use setup py sdist upload or setup py bdist egg upload to upload your source or egg distributions respectively Your project s current version must be registered with PyPI first of course you can use setup py register to do that Or you can do it all in one step e g setup py register sdist bdist egg upload will register the package build source and egg distributions and then upload them both to PyPI where they ll be easily found by other projects that depend on them Managing Multiple Projects If you re managing several projects that need to use ez setup and you are using Subversion as your revision control system you can use the svn externals property to share a single copy of ez setup between projects so that it will always be up to date whenever you check out or update an individual project without having to manually update each project to use a new version However because Subversion only supports using directories as externals you have to turn ez setup py into ez setup init py in order to do this then create externals definitions that map the ez setup directory into each project Also if any of your projects use find packages on their setup directory you will need to exclude the resulting ez setup package to keep it from being included in your distributions e g setup packages find packages exclude ez setup Of course the ez setup package will still be included in your packages source distributions as it needs to be For your convenience you may use the following external definition which will track the latest version of setuptools ez setup svn svn eby sarna com svnroot ez setup You can set this by executing this command in your project directory svn propedit svn externals And then adding the line shown above to the file that comes up for editing Setting the zip safe flag For maximum performance Python packages are best installed as zip files Not all packages however are capable of running in compressed form because they may expect to be able to access either source code or data files as normal operating system files So setuptools can install your project as a zipfile or a directory and its default choice is determined by the project s zip safe flag You can pass a True or False value for the zip safe argument to the setup function or you can omit it If you omit it the bdist egg command will analyze your project s contents to see if it can detect any conditions that would prevent it from working in a zipfile It will output notices to the console about any such conditions that it finds Currently this analysis is extremely conservative it will consider the project unsafe if it contains any C extensions or datafiles whatsoever This does not mean that the project can t or won t work as a zipfile It just means that the bdist egg authors aren t yet comfortable asserting that the project will work If the project contains no C or data files and does no file or path introspection or source code manipulation then there is an extremely solid chance the project will work when installed as a zipfile And if the project uses pkg resources for all its data file access then C extensions and other data files shouldn t be a problem at all See the Accessing Data Files at Runtime section above for more information However if bdist egg can t be sure that your package will work but you ve checked over all the warnings it issued and you are either satisfied it will work or if you want to try it for yourself then you should set zip safe to True in your setup call If it turns out that it doesn t work you can always change it to False which will force setuptools to install your project as a directory rather than as a zipfile Of course the end user can still override either decision if they are using EasyInstall to install your package And if you want to override for testing purposes you can just run setup py easy install zip ok or setup py easy install always unzip in your project directory to install the package as a zipfile or directory respectively In the future as we gain more experience with different packages and become more satisfied with the robustness of the pkg resources runtime the zip safety analysis may become less conservative However we strongly recommend that you determine for yourself whether your project functions correctly when installed as a zipfile correct any problems if you can and then make an explicit declaration of True or False for the zip safe flag so that it will not be necessary for bdist egg or EasyInstall to try to guess whether your project can work as a zipfile Namespace Packages Sometimes a large package is more useful if distributed as a collection of smaller eggs However Python does not normally allow the contents of a package to be retrieved from more than one location Namespace packages are a solution for this problem When you declare a package to be a namespace package it means that the package has no meaningful contents in its init py and that it is merely a container for modules and subpackages The pkg resources runtime will automatically ensure that the contents of namespace packages that are spread over multiple eggs or directories are combined into a single virtual package The namespace packages argument to setup lets you declare your project s namespace packages so that they will be included in your project s metadata Then the runtime will automatically detect this when it adds the distribution to sys path and ensure that the packages are properly merged The argument should list the namespace packages that the egg participates in For example the ZopeInterface project might do this setup namespace packages zope because it contains a zope interface package that lives in the zope namespace package Similarly a project for a standalone zope publisher would also declare the zope namespace package Namespace packages don t have to be top level packages For example Zope 3 s zope app package is a namespace package and in the future PEAK s peak util package will be too Note by the way that your project s source tree must include the namespace packages init py files and the init py of any parent packages in a normal Python package layout These init py files should not contain any code or data because only one egg s init py files will be used to construct the parent packages in memory at runtime and there is no guarantee which egg will be used For example if both zope interface and zope publisher have been installed from separate distributions it is unspecified which of the two distributions zope init py files will be used to create the zope package in memory Therefore it is better not to have any code or data in a namespace package s init module so as to prevent any complications This is one reason the concept is called a namespace package it is a package that exists only to provide a namespace under which other modules or packages are gathered In Java for example namespace packages are often used just to avoid naming collisions between different projects using package names like org apache as a namespace for packages that are part of apache org projects Tagging and Daily Build or Snapshot Releases When a set of related projects are under development it may be important to track finer grained version increments than you would normally use for e g stable releases While stable releases might be measured in dotted numbers with alpha beta etc status codes development versions of a project often need to be tracked by revision or build number or even build date This is especially true when projects in development need to refer to one another and therefore may literally need an up to the minute version of something To support these scenarios setuptools allows you to tag your source and egg distributions by adding one or more of the following to the project s official version identifier An identifying string such as build or dev or a manually tracked build or revision number tag build STRING bSTRING A last modified revision number string generated automatically from Subversion s metadata assuming your project is being built from a Subversion working copy tag svn revision r An 8 character representation of the build date tag date d You can add these tags by adding egg info and the desired options to the command line ahead of the sdist or bdist commands that you want to generate a daily build or snapshot for See the section below on the egg info command for more details Also if you are creating builds frequently and either building them in a downloadable location or are copying them to a distribution server you should probably also check out the rotate command which lets you automatically delete all but the N most recently modified distributions matching a glob pattern So you can use a command line like setup py egg info rbDEV bdist egg rotate m egg k3 to build an egg whose version info includes DEV rNNNN where NNNN is the most recent Subversion revision that affected the source tree and then delete any egg files from the distribution directory except for the three that were built most recently If you have to manage automated builds for multiple packages each with different tagging and rotation policies you may also want to check out the alias command which would let each package define an alias like daily that would perform the necessary tag build and rotate commands Then a simpler script or cron job could just run setup py daily in each project directory And you could also define sitewide or per user default versions of the daily alias so that projects that didn t define their own would use the appropriate defaults Generating Source Distributions setuptools enhances the distutils default algorithm for source file selection so that all files managed by CVS or Subversion in your project tree are included in any source distribution you build This is a big improvement over having to manually write a MANIFEST in file and try to keep it in sync with your project So if you are using CVS or Subversion and your source distributions only need to include files that you re tracking in revision control don t create a a MANIFEST in file for your project And if you already have one you might consider deleting it the next time you would otherwise have to change it Unlike the distutils setuptools regenerates the source distribution MANIFEST file every time you build a source distribution as long as you don t have a MANIFEST in file If you do have a MANIFEST in e g because you aren t using CVS or Subversion then you ll have to follow the normal distutils procedures for managing what files get included in a source distribution and setuptools enhanced algorithms will not be used Note by the way that if you re using some other revision control system you might consider submitting a patch to the setuptools command sdist module so we can include support for it too Making your package available for EasyInstall If you use the register command setup py register to register your package with PyPI that s most of the battle right there See the docs for the register command for more details If you also use the upload command to upload actual distributions of your package that s even better because EasyInstall will be able to find and download them directly from your project s PyPI page However there may be reasons why you don t want to upload distributions to PyPI and just want your existing distributions or perhaps a Subversion checkout to be used instead So here s what you need to do before running the register command There are three setup arguments that affect EasyInstall url and download url These become links on your project s PyPI page EasyInstall will examine them to see if they link to a package primary links or whether they are HTML pages If they re HTML pages EasyInstall scans all HREF s on the page for primary links long description EasyInstall will check any URLs contained in this argument to see if they are primary links A URL is considered a primary link if it is a link to a tar gz tgz zip egg egg zip tar bz2 or exe file or if it has an egg project or egg project version fragment identifier attached to it EasyInstall attempts to determine a project name and optional version number from the text of a primary link without downloading it When it has found all the primary links EasyInstall will select the best match based on requested version platform compatibility and other criteria So if your url or download url point either directly to a downloadable source distribution or to HTML page s that have direct links to such then EasyInstall will be able to locate downloads automatically If you want to make Subversion checkouts available then you should create links with either egg project or egg project version added to the URL You should replace project and version with the values they would have in an egg filename Be sure to actually generate an egg and then use the initial part of the filename rather than trying to guess what the escaped form of the project name and version number will be Note that Subversion checkout links are of lower precedence than other kinds of distributions so EasyInstall will not select a Subversion checkout for downloading unless it has a version included in the egg suffix and it s a higher version than EasyInstall has seen in any other links for your project As a result it s a common practice to use mark checkout URLs with a version of dev i e egg projectname dev so that users can do something like this easy install editable projectname dev in order to check out the in development version of projectname Distributing Extensions compiled with Pyrex setuptools includes transparent support for building Pyrex extensions as long as you define your extensions using setuptools Extension not distutils Extension You must also not import anything from Pyrex in your setup script If you follow these rules you can safely list pyx files as the source of your Extension objects in the setup script setuptools will detect at build time whether Pyrex is installed or not If it is then setuptools will use it If not then setuptools will silently change the Extension objects to refer to the c counterparts of the pyx files so that the normal distutils C compilation process will occur Of course for this to work your source distributions must include the C code generated by Pyrex as well as your original pyx files This means that you will probably want to include current c files in your revision control system rebuilding them whenever you check changes in for the pyx source files This will ensure that people tracking your project in CVS or Subversion will be able to build it even if they don t have Pyrex installed and that your source releases will be similarly usable with or without Pyrex Command Reference alias Define shortcuts for commonly used commands Sometimes you need to use the same commands over and over but you can t necessarily set them as defaults For example if you produce both development snapshot releases and stable releases of a project you may want to put the distributions in different places or use different egg info tagging options etc In these cases it doesn t make sense to set the options in a distutils configuration file because the values of the options changed based on what you re trying to do Setuptools therefore allows you to define aliases shortcut names for an arbitrary string of commands and options using setup py alias aliasname expansion where aliasname is the name of the new alias and the remainder of the command line supplies its expansion For example this command defines a sitewide alias called daily that sets various egg info tagging options setup py alias global config daily egg info tag svn revision tag build development Once the alias is defined it can then be used with other setup commands e g setup py daily bdist egg generate a daily build egg file setup py daily sdist generate a daily build source distro setup py daily sdist bdist egg generate both The above commands are interpreted as if the word daily were replaced with egg info tag svn revision tag build development Note that setuptools will expand each alias at most once in a given command line This serves two purposes First if you accidentally create an alias loop it will have no effect you ll instead get an error message about an unknown command Second it allows you to define an alias for a command that uses that command For example this project local alias setup py alias bdist egg bdist egg rotate k1 m egg redefines the bdist egg command so that it always runs the rotate command afterwards to delete all but the newest egg file It doesn t loop indefinitely on bdist egg because the alias is only expanded once when used You can remove a defined alias with the remove or r option e g setup py alias global config remove daily would delete the daily alias we defined above Aliases can be defined on a project specific per user or sitewide basis The default is to define or remove a project specific alias but you can use any of the configuration file options listed under the saveopts command below to determine which distutils configuration file an aliases will be added to or removed from Note that if you omit the expansion argument to the alias command you ll get output showing that alias current definition and what configuration file it s defined in If you omit the alias name as well you ll get a listing of all current aliases along with their configuration file locations bdist egg Create a Python Egg for the project This command generates a Python Egg egg file for the project Python Eggs are the preferred binary distribution format for EasyInstall because they are cross platform for pure packages directly importable and contain project metadata including scripts and information about the project s dependencies They can be simply downloaded and added to sys path directly or they can be placed in a directory on sys path and then automatically discovered by the egg runtime system This command runs the egg info command if it hasn t already run to update the project s metadata egg info directory If you have added any extra metadata files to the egg info directory those files will be included in the new egg file s metadata directory for use by the egg runtime system or by any applications or frameworks that use that metadata You won t usually need to specify any special options for this command just use bdist egg and you re done But there are a few options that may be occasionally useful dist dir DIR d DIR Set the directory where the egg file will be placed If you don t supply this then the dist dir setting of the bdist command will be used which is usually a directory named dist in the project directory plat name PLATFORM p PLATFORM Set the platform name string that will be embedded in the egg s filename assuming the egg contains C extensions This can be used to override the distutils default platform name with something more meaningful Keep in mind however that the egg runtime system expects to see eggs with distutils platform names so it may ignore or reject eggs with non standard platform names Similarly the EasyInstall program may ignore them when searching web pages for download links However if you are cross compiling or doing some other unusual things you might find a use for this option exclude source files Don t include any modules py files in the egg just compiled Python C and data files Note that this doesn t affect any py files in the EGG INFO directory or its subdirectories since for example there may be scripts with a py extension which must still be retained We don t recommend that you use this option except for packages that are being bundled for proprietary end user applications or for embedded scenarios where space is at an absolute premium On the other hand if your package is going to be installed and used in compressed form you might as well exclude the source because Python s traceback module doesn t currently understand how to display zipped source code anyway or how to deal with files that are in a different place from where their code was compiled There are also some options you will probably never need but which are there because they were copied from similar bdist commands used as an example for creating this one They may be useful for testing and debugging however which is why we kept them keep temp k Keep the contents of the bdist dir tree around after creating the egg file bdist dir DIR b DIR Set the temporary directory for creating the distribution The entire contents of this directory are zipped to create the egg file after running various installation commands to copy the package s modules data and extensions here skip build Skip doing any build commands just go straight to the install and compress phases develop Deploy the project source in Development Mode This command allows you to deploy your project s source for use in one or more staging areas where it will be available for importing This deployment is done in such a way that changes to the project source are immediately available in the staging area s without needing to run a build or install step after each change The develop command works by creating an egg link file named for the project in the given staging area If the staging area is Python s site packages directory it also updates an easy install pth file so that the project is on sys path by default for all programs run using that Python installation The develop command also installs wrapper scripts in the staging area or a separate directory as specified that will ensure the project s dependencies are available on sys path before running the project s source scripts And it ensures that any missing project dependencies are available in the staging area by downloading and installing them if necessary Last but not least the develop command invokes the build ext i command to ensure any C extensions in the project have been built and are up to date and the egg info command to ensure the project s metadata is updated so that the runtime and wrappers know what the project s dependencies are If you make any changes to the project s setup script or C extensions you should rerun the develop command against all relevant staging areas to keep the project s scripts metadata and extensions up to date Most other kinds of changes to your project should not require any build operations or rerunning develop but keep in mind that even minor changes to the setup script e g changing an entry point definition require you to re run the develop or test commands to keep the distribution updated Here are the options that the develop command accepts Note that they affect the project s dependencies as well as the project itself so if you have dependencies that need to be installed and you use exclude scripts for example the dependencies scripts will not be installed either For this reason you may want to use EasyInstall to install the project s dependencies before using the develop command if you need finer control over the installation options for dependencies uninstall u Un deploy the current project You may use the install dir or d option to designate the staging area The created egg link file will be removed if present and it is still pointing to the project directory The project directory will be removed from easy install pth if the staging area is Python s site packages directory Note that this option currently does not uninstall script wrappers You must uninstall them yourself or overwrite them by using EasyInstall to activate a different version of the package You can also avoid installing script wrappers in the first place if you use the exclude scripts aka x option when you run develop to deploy the project multi version m Multi version mode Specifying this option prevents develop from adding an easy install pth entry for the project s being deployed and if an entry for any version of a project already exists the entry will be removed upon successful deployment In multi version mode no specific version of the package is available for importing unless you use pkg resources require to put it on sys path or you are running a wrapper script generated by setuptools or EasyInstall In which case the wrapper script calls require for you Note that if you install to a directory other than site packages this option is automatically in effect because pth files can only be used in site packages at least in Python 2 3 and 2 4 So if you use the install dir or d option or they are set via configuration file s your project and its dependencies will be deployed in multi version mode install dir DIR d DIR Set the installation directory staging area If this option is not directly specified on the command line or in a distutils configuration file the distutils default installation location is used Normally this will be the site packages directory but if you are using distutils configuration files setting things like prefix or install lib then those settings are taken into account when computing the default staging area script dir DIR s DIR Set the script installation directory If you don t supply this option via the command line or a configuration file but you have supplied an install dir via command line or config file then this option defaults to the same directory so that the scripts will be able to find their associated package installation Otherwise this setting defaults to the location where the distutils would normally install scripts taking any distutils configuration file settings into account exclude scripts x Don t deploy script wrappers This is useful if you don t want to disturb existing versions of the scripts in the staging area always copy a Copy all needed distributions to the staging area even if they are already present in another directory on sys path By default if a requirement can be met using a distribution that is already available in a directory on sys path it will not be copied to the staging area egg info Create egg metadata and set build tags This command performs two operations it updates a project s egg info metadata directory used by the bdist egg develop and test commands and it allows you to temporarily change a project s version string to support daily builds or snapshot releases It is run automatically by the sdist bdist egg develop and test commands in order to update the project s metadata but you can also specify it explicitly in order to temporarily change the project s version string The following options can be used to modify the project s version string for all remaining commands on the setup command line The options are processed in the order shown so if you use more than one the requested tags will be added in the following order tag build NAME b NAME Append NAME to the project s version string Due to the way setuptools processes pre release version suffixes beginning with the letters a through e like alpha beta and candidate you will usually want to use a tag like build or dev as this will cause the version number to be considered lower than the project s default version If you want to make the version number

    Original URL path: http://peak.telecommunity.com/DevCenter/setuptools?action=recall&date=1128902524 (2016-04-24)
    Open archived version from archive

  • Diff for "setuptools" - The PEAK Developers' Center
    of a list of URL strings For example the below will cause EasyInstall to search the specified page for eggs or source distributions if the package s dependencies aren t already installed setup dependency links http peak telecommunity com snapshots Declaring Extras The distutils have traditionally allowed installation of data files which are placed in a platform specific location However the most common use case for data files distributed with a package is for use by the package usually by including the data files in the package directory Setuptools supports this by allowing a package data argument to setup e g by including the data files in the package directory Setuptools offers three ways to specify data files to be included in your packages First you can simply use the include package data keyword e g from setuptools import setup find packages setup include package data True This tells setuptools to install any data files it finds in your packages The data files must be under CVS or Subversion control or else they must be specified via the distutils MANIFEST in file They can also be tracked by another revision control system using an appropriate plugin See the section below on Adding Support for Other Revision Control Systems for information on how to write such plugins If you want finer grained control over what files are included for example if you have documentation files in your package directories and want to exclude them from installation then you can also use the package data keyword e g from setuptools import setup find packages setup packages find packages src include all packages under src package dir src tell distutils packages are under src package data If any package contains txt files include them txt Python 2 4 there is some documentation for the feature available on the python org website http docs python org dist node11 html http docs python org dist node11 html Sometimes the include package data or package data options alone aren t sufficient to precisely define what files you want included For example you may want to include package README files in your revision control system and source distributions but exclude them from being installed So setuptools offers an exclude package data option as well that allows you to do things like this from setuptools import setup find packages setup packages find packages src include all packages under src package dir src tell distutils packages are under src include package data True include everything in source control but exclude README txt from all packages exclude package data README txt The exclude package data option is a dictionary mapping package names to lists of wildcard patterns just like the package data option And just as with that option a key of will apply the given pattern s to all packages However any files that match these patterns will be excluded from installation even if they were listed in package data or were included as a result of using include package data In summary the three options allow you to include package data Accept all data files and directories matched by MANIFEST in or found in source control package data Specify additional patterns to match files and directories that may or may not be matched by MANIFEST in or found in source control exclude package data Specify patterns for data files and directories that should not be included when a package is installed even if they would otherwise have been included due to the use of the preceding options NOTE Due to the way the distutils build process works a data file that you include in your project and then stop including may be orphaned in your project s build directories requiring you to run setup py clean all to fully remove them This may also be important for your users and contributors if they track intermediate revisions of your project using Subversion be sure to let them know when you make changes that remove files from inclusion so they can run setup py clean all Accessing Data Files at Runtime project includes non extension native libraries or other files that your C extensions expect to be able to access you may need to list those files in the eager resources argument to setup so that the files will be extracted together whenever a C extension in the project is imported This is especially important if your project includes shared libraries other than distutils built C extensions Those shared libraries should be listed as eager resources because they need to be present in the filesystem when the C extensions that link to them are used extracted together whenever a C extension in the project is imported This is especially important if your project includes shared libraries other than distutils built C extensions and those shared libraries use file extensions other than dll so or dylib which are the extensions that setuptools 0 6a8 and higher automatically detects as shared libraries and adds to the native libs txt file for you Any shared libraries whose names do not end with one of those extensions should be listed as eager resources because they need to be present in the filesystem when he C extensions that link to them are used The pkg resources runtime for compressed packages will automatically extract all C extensions and eager resources at the same time whenever There are several options to control the precise behavior of the develop command see the section on the develop command below for more details Note that you can also apply setuptools commands to non setuptools projects using commands like this python c import setuptools execfile setup py develop That is you can simply list the normal setup commands and options following the quoted part Distributing a setuptools based package Distributing a setuptools based project Using setuptools Without bundling it distributions and then upload them both to PyPI where they ll be easily found by other projects that depend on them By the way if you need to distribute a specific version of setuptools you can specify the exact version and base download URL as parameters to the use setuptools function See the function s docstring for details What Your Users Should Know In general a setuptools based project looks just like any distutils based project as long as your users have an internet connection and are installing to site packages that is But for some users these conditions don t apply and they may become frustrated if this is their first encounter with a setuptools based project To keep these users happy you should review the following topics in your project s installation instructions if they are relevant to your project and your target audience isn t already familiar with setuptools and easy install Network Access If your project is using ez setup you should inform users of the need to either have network access or to preinstall the correct version of setuptools using the EasyInstall installation instructions Those instructions also have tips for dealing with firewalls as well as how to manually download and install setuptools Custom Installation Locations You should inform your users that if they are installing your project to somewhere other than the main site packages directory they should first install setuptools using the instructions for Custom Installation Locations before installing your project Your Project s Dependencies If your project depends on other projects that may need to be downloaded from PyPI or elsewhere you should list them in your installation instructions or tell users how to find out what they are While most users will not need this information any users who don t have unrestricted internet access may have to find download and install the other projects manually Note however that they must still install those projects using easy install or your project will not know they are installed and your setup script will try to download them again If you want to be especially friendly to users with limited network access you may wish to build eggs for your project and its dependencies making them all available for download from your site or at least create a page with links to all of the needed eggs In this way users with limited network access can manually download all the eggs to a single directory then use the f option of easy install to specify the directory to find eggs in Users who have full network access can just use f with the URL of your download page and easy install will find all the needed eggs using your links directly This is also useful when your target audience isn t able to compile packages e g most Windows users and your package or some of its dependencies include C code Subversion or CVS Users and Co Developers Users and co developers who are tracking your in development code using CVS Subversion or some other revision control system should probably read this manual s sections regarding such development Alternately you may wish to create a quick reference guide containing the tips from this manual that apply to your particular situation For example if you recommend that people use setup py develop when tracking your in development code you should let them know that this needs to be run after every update or commit Similarly if you remove modules or data files from your project you should remind them to run setup py clean all and delete any obsolete pyc or pyo This tip applies to the distutils in general not just setuptools but not everybody knows about them be kind to your users by spelling out your project s best practices rather than leaving them guessing Creating System Packages Some users want to manage all Python packages using a single package manager and sometimes that package manager isn t easy install Setuptools currently supports bdist rpm bdist wininst and bdist dumb formats for system packaging If a user has a locally installed bdist packaging tool that internally uses the distutils install command it should be able to work with setuptools Some examples of bdist formats that this should work with include the bdist nsi and bdist msi formats for Windows However packaging tools that build binary distributions by running setup py install on the command line or as a subprocess will require modification to work with setuptools They should use the single version externally managed option to the install command combined with the standard root or record options See the install command documentation below for more details The bdist deb command is an example of a command that currently requires this kind of patching to work with setuptools If you or your users have a problem building a usable system package for your project please report the problem via the mailing list so that either the bdist tool in question or setuptools can be modified to resolve the issue Managing Multiple Projects package it means that the package has no meaningful contents in its init py and that it is merely a container for modules and subpackages The pkg resources runtime will automatically ensure that the contents of namespace packages that are spread over multiple eggs or directories are combined into a single virtual package The pkg resources runtime will then automatically ensure that the contents of namespace packages that are spread over multiple eggs or directories are combined into a single virtual package The namespace packages argument to setup lets you declare your project s namespace packages so that they will be included in your project s metadata Then the runtime will automatically detect this when it adds the distribution to sys path and ensure that the packages are properly merged The argument should list the namespace packages that the egg participates in For example the ZopeInterface project might do this metadata The argument should list the namespace packages that the egg participates in For example the ZopeInterface project might do this setup because it contains a zope interface package that lives in the zope namespace package Similarly a project for a standalone zope publisher would also declare the zope namespace package would also declare the zope namespace package When these projects are installed and used Python will see them both as part of a virtual zope package even though they will be installed in different locations Namespace packages don t have to be top level packages For example Zope 3 s zope app package is a namespace package and in the future PEAK s Note by the way that your project s source tree must include the namespace packages init py files and the init py of any parent packages in a normal Python package layout These init py files should not contain any code or data because only one egg s init py files will be used to construct the parent packages in memory at runtime and there is no guarantee which egg will be used For example if both zope interface and zope publisher have been installed from separate distributions it is unspecified which of the two distributions zope init py files will be used to create the zope package in memory Therefore it is better not to have any code or data in a namespace package s init module so as to prevent any complications This is one reason the concept is called a namespace package it is a package that exists only to provide a namespace under which other modules or packages are gathered In Java for example namespace packages are often used just to avoid naming collisions between different projects using package names like org apache as a namespace for packages that are part of apache org projects must contain the line import pkg resources declare namespace name This code ensures that the namespace package machinery is operating and that the current package is registered as a namespace package You must NOT include any other code and data in a namespace package s init py Even though it may appear to work during development or when projects are installed as egg files it will not work when the projects are installed using system packaging tools in such cases the init py files will not be installed let alone executed You must include the declare namespace line in the init py of every project that has contents for the namespace package in question in order to ensure that the namespace will be declared regardless of which project s copy of init py is loaded first If the first loaded init py doesn t declare it it will never be declared because no other copies will ever be loaded TRANSITIONAL NOTE Setuptools 0 6a automatically calls declare namespace for you at runtime but the 0 7a versions will not This is because the automatic declaration feature has some negative side effects such as needing to import all namespace packages during the initialization of the pkg resources runtime and also the need for pkg resources to be explicitly imported before any namespace packages work at all Beginning with the 0 7a releases you ll be responsible for including your own declaration lines and the automatic declaration feature will be dropped to get rid of the negative side effects During the remainder of the 0 6 development cycle therefore setuptools will warn you about missing declare namespace calls in your init py files and you should correct these as soon as possible before setuptools 0 7a1 is released Namespace packages without declaration lines will not work correctly once a user has upgraded to setuptools 0 7a1 so it s important that you make this change now in order to avoid having your code break in the field Our apologies for the inconvenience and thank you for your patience Tagging and Daily Build or Snapshot Releases egg distributions by adding one or more of the following to the project s official version identifier An identifying string such as build or dev or a manually tracked build or revision number tag build STRING bSTRING A manually specified pre release tag such as build or dev or a manually specified post release tag such as a build or revision number tag build STRING bSTRING A last modified revision number string generated automatically from A last modified revision number string generated automatically from Subversion s metadata assuming your project is being built from a Subversion working copy tag svn revision r An 8 character representation of the build date tag date d An 8 character representation of the build date tag date d as a postrelease tag You can add these tags by adding egg info and the desired options to the command line ahead of the sdist or bdist commands that you want to generate a daily build or snapshot for See the section below on the egg info command for more details Also if you are creating builds frequently and either building them in a Also before you release your project be sure to see the section above on Specifying Your Project s Version for more information about how pre and post release tags affect how setuptools and EasyInstall interpret version numbers This is important in order to make sure that dependency processing tools will know which versions of your project are newer than others Finally if you are creating builds frequently and either building them in a downloadable location or are copying them to a distribution server you should probably also check out the rotate command which lets you automatically delete all but the N most recently modified distributions matching a glob And if you already have one you might consider deleting it the next time you would otherwise have to change it Unlike the distutils setuptools regenerates the source distribution MANIFEST file every time you build a source distribution as long as you don t have a MANIFEST in file If you do have a MANIFEST in e g because you aren t using CVS or Subversion then you ll have to follow the normal distutils procedures for managing what files get included in a source distribution and setuptools enhanced algorithms will not be used Note by the way that if you re using some other revision control system you might consider submitting a patch to the setuptools command sdist module so we can include support for it too NOTE other revision control systems besides CVS and Subversion can be supported using plugins see the section below on Adding Support for Other Revision Control Systems for information on how to write such plugins If you need to include automatically generated files or files that are kept in an unsupported revision control system you ll need to create a MANIFEST in file to specify any files that the default file location algorithm doesn t catch See the distutils documentation for more information on the format of the MANIFEST in file But be sure to ignore any part of the distutils documentation that deals with MANIFEST or how it s generated from MANIFEST in setuptools shields you from these issues and doesn t work the same way in any case Unlike the distutils setuptools regenerates the source distribution manifest file every time you build a source distribution and it builds it inside the project s egg info directory out of the way of your main project directory You therefore need not worry about whether it is up to date or not Indeed because setuptools approach to determining the contents of a source distribution is so much simpler its sdist command omits nearly all of the options that the distutils more complex sdist process requires For all practical purposes you ll probably use only the formats option if you use any option at all By the way if you re using some other revision control system you might consider creating and publishing a revision control plugin for setuptools revision control plugin for setuptools Adding Support for Other Revision Control Systems Making your package available for EasyInstall in order to check out the in development version of projectname Managing Continuous Releases Using Subversion If you expect your users to track in development versions of your project via Subversion there are a few additional steps you should take to ensure that things work smoothly with EasyInstall First you should add the following to your project s setup cfg file egg info tag build dev tag svn revision 1 This will tell setuptools to generate package version numbers like 1 0a1 dev r1263 which will be considered to be an older release than 1 0a1 Thus when you actually release 1 0a1 the entire egg infrastructure including setuptools pkg resources and EasyInstall will know that 1 0a1 supersedes any interim snapshots from Subversion and handle upgrades accordingly Note the project version number you specify in setup py should always be the next version of your software not the last released version Alternately you can leave out the tag build dev and always use the last release as a version number so that your post 1 0 builds are labelled 1 0 r1263 indicating a post 1 0 patchlevel Most projects so far however seem to prefer to think of their project as being a future version still under development rather than a past version being patched It is of course possible for a single project to have both situations using post release numbering on release branches and pre release numbering on the trunk But you don t have to make things this complex if you don t want to Commonly projects releasing code from Subversion will include a PyPI link to their checkout URL as described in the previous section with an egg projectname dev suffix This allows users to request EasyInstall to download projectname dev in order to get the latest in development code Note that if your project depends on such in progress code you may wish to specify your install requires or other requirements to include dev e g install requires OtherProject 0 2a1 dev r143 dev The above example says I really want at least this particular development revision number but feel free to follow and use an egg OtherProject dev link if you find one This avoids the need to have actual source or binary distribution snapshots of in development code available just to be able to depend on the latest and greatest a project has to offer A final note for Subversion development if you are using SVN revision tags as described in this section it s a good idea to run setup py develop after each Subversion checkin or update because your project s version number will be changing and your script wrappers need to be updated accordingly Also if the project s requirements have changed the develop command will take care of fetching the updated dependencies building changed extensions etc Be sure to also remind any of your users who check out your project from Subversion that they need to run setup py develop after every update in order to keep their checkout completely in sync Making Official Non Snapshot Releases When you make an official release creating source or binary distributions you will need to override the tag settings from setup cfg so that you don t end up registering versions like foobar 0 7a1 dev r34832 This is easy to do if you are developing on the trunk and using tags or branches for your releases just make the change to setup cfg after branching or tagging the release so the trunk will still produce development snapshots Alternately if you are not branching for releases you can override the default version options on the command line using something like python setup py egg info RDb sdist bdist egg register upload The first part of this command egg info RDb will override the configured tag information before creating source and binary eggs registering the project with PyPI and uploading the files Thus these commands will use the plain version from your setup py without adding the Subversion revision number or build designation string Of course if you will be doing this a lot you may wish to create a personal alias for this operation e g python setup py alias u release egg info RDb You can then use it like this python setup py release sdist bdist egg register upload Or of course you can create more elaborate aliases that do all of the above See the sections below on the egg info and alias commands for more ideas Distributing Extensions compiled with Pyrex and that your source releases will be similarly usable with or without Pyrex Command Reference script e g changing an entry point definition require you to re run the develop or test commands to keep the distribution updated Here are the options that the develop command accepts Note that they affect the project s dependencies as well as the project itself so if you have dependencies that need to be installed and you use exclude scripts for example the dependencies scripts will not be installed either For this reason you may want to use EasyInstall to install the project s dependencies before using the develop command if you need finer control over the installation options for dependencies Here are some of the options that the develop command accepts Note that they affect the project s dependencies as well as the project itself so if you have dependencies that need to be installed and you use exclude scripts for example the dependencies scripts will not be installed either For this reason you may want to use EasyInstall to install the project s dependencies before using the develop command if you need finer control over the installation options for dependencies uninstall u Un deploy the current project You may use the install dir or d a requirement can be met using a distribution that is already available in a directory on sys path it will not be copied to the staging area egg path DIR Force the generated egg link file to use a specified relative path to the source directory This can be useful in circumstances where your installation directory is being shared by code running under multiple platforms e g Mac and Windows which have different absolute locations for the code under development but the same relative locations with respect to the installation directory If you use this option when installing you must supply the same relative path when uninstalling In addition to the above options the develop command also accepts all of the same options accepted by easy install If you ve configured any easy install settings in your setup cfg or other distutils config files the develop command will use them as defaults unless you override them in a develop section or on the command line easy install Find and install packages This command runs the EasyInstall tool http peak telecommunity com DevCenter EasyInstall for you It is exactly equivalent to running the easy install command All command line arguments following this command are consumed and not processed further by the distutils so this must be the last command listed on the command line Please see the EasyInstall documentation for the options reference and usage examples Normally there is no reason to use this command via the command line as you can just use easy install directly It s only listed here so that you know it s a distutils command which means that you can create command aliases that use it create distutils extensions that invoke it as a subcommand and configure options for it in your setup cfg or other distutils config files egg info metadata directory used by the bdist egg develop and test commands and it allows you to temporarily change a project s version string to support daily builds or snapshot releases It is run automatically by the sdist bdist egg develop and test commands in order to update the project s metadata but you can also specify it explicitly in order to temporarily change the project s version string the sdist bdist egg develop register and test commands in order to update the project s metadata but you can also specify it explicitly in order to temporarily change the project s version string while executing other commands It also generates the egg info SOURCES txt manifest file which is used when you are building source distributions In addition to writing the core egg metadata defined by setuptools and required by pkg resources this command can be extended to write other metadata files as well by defining entry points in the egg info writers group See the section on Adding new EGG INFO Files below for more details Note that using additional metadata writers may require you to include a setup requires argument to setup in order to ensure that the desired writers are available on sys path Release Tagging Options The following options can be used to modify the project s version string for all remaining commands on the setup command line The options are processed Append NAME to the project s version string Due to the way setuptools processes pre release version suffixes beginning with the letters a through e like alpha beta and candidate you will usually want to use a tag like build or dev as this will cause the version number to use a tag like build or dev as this will cause the version number to be considered lower than the project s default version If you want to make the version number higher than the default version you can always leave off tag build and use one or both of the following options always leave off tag build and then use one or both of the following options If you have a default build tag set in your setup cfg you can suppress it on the command line using b or tag build as an argument to the egg info command tag svn revision r If the current directory is a Subversion checkout i e has a svn modification to the current directory as obtained from the svn info command If the current directory is not a Subversion checkout the command will look for a PKG INFO file instead and try to find the revision number from that by looking for a rNNNN string at the end of the version number This is so that building a package from a source distribution of a Subversion snapshot will produce a binary with the correct version number If there is no PKG INFO file or the version number contained therein does not end with r and a number then r0 is used no svn revision R Don t include the Subversion revision in the version number This option is included so you can override a default setting put in setup cfg tag date d Add a date stamp of the form YYYYMMDD e g 20050528 to the project s version number no date D Don t include a date stamp in the version number This option is included so you can override a default setting in setup cfg Note Because these options modify the version number used for source and binary distributions of your project you should first make sure that you know how the resulting version numbers will be interpreted by automated tools like EasyInstall See the section above on Specifying Your Project s Version for an explanation of pre and post release tags as well as tips on how to choose and verify a versioning scheme for your your project For advanced uses there is one other option that can be set to change the location of the project s egg info directory Commands that need to find the project s source directory or metadata should get it from this setting Other egg info Options egg base SOURCEDIR e SOURCEDIR Specify the directory that should contain the egg info directory This should normally be the root of your project s source tree which is not package dir argument to the setup function if any If there is no package dir set this option defaults to the current directory In addition to writing the core egg metadata defined by setuptools and required by pkg resources this command can be extended to write other metadata files as well by defining entry points in the egg info writers group See the section on Adding new EGG INFO Files below for more details Note that using additional metadata writers may require you to include a setup requires argument to setup in order to ensure that the desired writers are available on sys path egg info Examples Creating a dated nightly build snapshot egg python setup py egg info tag date tag build DEV bdist egg Creating and uploading a release with no version tags even if some default tags are specified in setup cfg python setup py egg info RDb sdist bdist egg register upload Notice that egg info must always appear on the command line before any commands that you want the version changes to apply to install command install Run easy install or old style installation The setuptools install command is basically a shortcut to run the easy install command on the current project However for convenience in creating system packages of setuptools based projects you can also use this option single version externally managed This boolean option tells the install command to perform an old style installation with the addition of an egg info directory so that the installed project will still have its metadata available and operate normally If you use this option you must also specify the root or record options or both because otherwise you will have no way to identify and remove the installed files This option is automatically in effect when install is invoked by another distutils command so that commands like bdist wininst and bdist rpm will create system packages of eggs It is also automatically in effect if you specify the root option install egg info Install an egg info directory in site packages Setuptools runs this command as part of install operations that use the single version externally managed options You should not invoke it directly it is documented here for completeness and so that distutils extensions such as system package builders can make use of it This command has only one option install dir DIR d DIR The parent directory where the egg info directory will be placed Defaults to the same as the install dir option specified for the install lib command which is usually the system site packages directory This command assumes that the egg info command has been given valid options via the command line or setup cfg as it will invoke the egg info command and use its options to locate the project s source egg info directory rotate you will use a glob pattern like zip or egg to match files of the specified type Note that each supplied pattern is treated as a distinct group of files for purposes of selecting files to delete keep COUNT k COUNT Number of matching distributions to keep For each group of files identified by a pattern specified with the match option delete all the configuration file options to change where the options are saved For example this command does the same as above but saves the compiler setting to the site wide global distutils configuration setup py build compiler mingw32 saveopts g Note that it doesn t matter where you place the saveopts command on the command line it will still save all the options specified for all commands For example this is another valid way to spell the last example setup py saveopts g build compiler mingw32 setup py saveopts g build compiler mingw32 Note however that all of the commands specified are always run regardless of where

    Original URL path: http://peak.telecommunity.com/DevCenter/setuptools?action=diff&date=1128902524 (2016-04-24)
    Open archived version from archive



  •