Detailed Documentation
**********************
Introduction
============
Namespace packages offer the huge benefit of being able to distribute parts of a large
system in small, self-contained pieces. However, they can be somewhat clunky to navigate,
since you end up with a large list of eggs in your egg cache, and then a seemingly endless
series of directories you need to open to actually find the contents of your egg.
This recipe sets up a directory structure that mirrors the actual python namespaces, with
symlinks to the egg contents. So, instead of this...::
egg-cache/
my.egg.one-1.0-py2.7.egg/
my/
egg/
one/
(contents of first egg)
my.egg.two-1.0-py2.7.egg/
my/
egg/
two/
(contents of second egg)
...you get this::
omelette/
my/
egg/
one/
(contents of first egg)
two/
(contents of second egg)
You can also include non-eggified python packages in the omelette. This makes it simple to
get a single path that you can add to your ``PYTHONPATH`` for use with specialized python environments
like when running under mod_wsgi or PyDev.
Typical usage with Zope and Plone
=================================
For a typical Plone buildout, with a part named ``instance`` that uses the
``plone.recipe.zope2instance`` recipe, the following additions to ``buildout.cfg`` will
result in an omelette including all eggs used by the Zope instance::
[buildout]
parts =
...(other parts)...
omelette
...
[omelette]
recipe = collective.recipe.omelette
eggs = ${instance:eggs}
Supported options
=================
The recipe supports the following options:
eggs
List of eggs which should be included in the omelette.
location
(optional) Override the directory in which the omelette is created (default is parts/[name of buildout part])
ignore-develop
(optional) Ignore eggs that you are currently developing (listed in ${buildout:develop}). Default is False
ignores
(optional) List of eggs to ignore when preparing your omelette.
packages
List of Python packages whose contents should be included in the omelette. Each line should be in the format
[packages_location] [target_directory], where packages_location is the real location of the packages, and
target_directory is the optional (relative) location where the package should be inserted into the omelette (defaults
to ``./``, so directly in the omelette part).
Example: ``packages = ${buildout:directory}/lib/python3.13/site-packages``
Using omelette with zipped eggs
===============================
Omelette doesn't currently know how to deal with eggs that are zipped. If it encounters one, you'll
see a warning something like the following::
omelette: Warning: (While processing egg elementtree) Egg contents not found at
/Users/davidg/.buildout/eggs/elementtree-1.2.7_20070827_preview-py2.4.egg/elementtree. Skipping.
You can tell buildout to unzip all eggs by setting the unzip = true flag in the [buildout] section.
(Note that this will only take effect for eggs downloaded after the flag is set.)
Running the tests
=================
Just grab the recipe from git and run::
tox -p auto
Known issue: The tests run buildout in a separate process, so it's currently
impossible to put a pdb breakpoint in the recipe and debug during the test.
If you need to do this, set up another buildout which installs an omelette
part and includes collective.recipe.omelette as a development egg.
Reporting bugs or asking questions
==================================
There is a bugtracker on gitHub:
https://github.com/collective/collective.recipe.omelette/issues
Change history
**************
2.0.0 (2025-02-14)
==================
Breaking changes:
- No longer generate ``__init__.py`` files with namespace stanza in ``parts/omelette``.
I think this was originally done to be able to go to ``parts/omelette``, start a standard Python, and be able to import everything.
With current Python versions the ``__init__.py`` files are not needed for a directory to be importable.
[maurits]
- Remove ``products`` recipe option and special handling of ``Products`` namespace.
Zope 4 and higher no longer have the concept of a products directory.
You can still use ``packages = path/to/products_dir Products`` if you need something similar.
[maurits]
- Require at least Python 3.9.
[maurits]
Bug fixes:
- Fix handling checkouts of native namespace packages.
[maurits]
1.1.1 (2025-02-12)
==================
- Remove setuptools fossils.
[maurits]
1.1.0 (2021-12-01)
==================
- Fix 2to3 old setuptools hook [goschtl]
- mordernize to python3 code [goschtl]
- update to new zope.testing [goschtl]
- use pytest and tox [goschtl]
- Note: tested on Python 2.7 and 3.6-3.10.
1.0.0 (2020-08-03)
==================
- Fix to run under Windows with Python 3.
[nilshofer, jensens]
0.16 (2013-02-18)
=================
- Fix packaging error.
[davisagli]
- Fix tests to work with buildout 2.
[davisagli]
0.15 (2012-05-12)
=================
- Integration with Travis CI for running tests and pep8/pyflakes.
[hvelarde]
- PEP 8/Pyflakes.
[hvelarde]
- Optimized unlinking of junctioned dirs on Windows.
[lck]
0.14 (2012-04-30)
=================
- Change the approach to building the omelette using NTFS junctions
on Windows. This is now done via the ``ntfsutils`` package, rather
than relying on junction.exe.
[lck]
0.13 (2012-04-14)
=================
- Added forward-compatibility with Python 3.
[mitchell]
0.12 (2011-09-08)
=================
- Replaced os.popen with subprocess equivalent
[tom_gross]
- Quote path on windows to handle paths with spaces correctly
[tom_gross]
0.11 (2011-07-18)
=================
- Sort top_level metadata to avoid error building omelette if they are out of
order. Fixes https://bugs.launchpad.net/collective.buildout/+bug/553005.
Thanks to Leonardo Rochael Almeida.
[davisagli]
0.10 (2010-11-22)
=================
- Provide an update function (equivalent to install) to avoid spurious "recipe
"doesn't define an update method" warning.
[davisagli]
- Print a warning rather than aborting the buildout if junction.exe is missing
on Windows.
[davisagli]
- Made the tests compatible with a zc.buildout installed with Distribute
rather than Setuptools.
[pumazi]
- Handle OSErrors on symlink and warn the user. MacOSX can raise OSError due
to an existing file here even if os.path.exists returns False.
[MatthewWilkes]
- Include modules from namespace packages in the omelette. (Namespace packages
cannot define anything in __init__.py, but they can contain modules.)
[hathawsh]
- Made the tests compatible with virtualenv.
[hathawsh]
0.9 (2009-04-11)
================
- Adjusted log-levels to be slightly less verbose for non-critical
errors. [malthe]
0.8 (2009-01-14)
================
- Fixed 'OSError [Errno 20] Not a directory' on zipped eggs, for
example when adding the z3c.sqlalchemy==1.3.5 egg.
[maurits]
0.7 (2008-09-10)
================
- Actually add namespace declarations to generated __init__.py files.
[davisagli]
- Use egg-info instead of guessing paths from package name. This also fixes
eggs which have a name different from the contents.
[fschulze]
0.6 (2008-08-11)
================
- Documentation changes only.
[davisagli]
0.5 (2008-05-29)
================
- Added uninstall entry point so that the omelette can be uninstalled on
Windows without clobbering things outside the omelette path.
[optilude]
- Support Windows using NTFS junctions (see
http://www.microsoft.com/technet/sysinternals/FileAndDisk/Junction.mspx)
[optilude]
- Ignore zipped eggs and fakezope2eggs-created links.
[davisagli]
- Added 'packages' option to allow merging non-eggified Python packages to
any directory in the omelette (so that, for instance, the contents of
Zope's lib/python can be merged flexibly).
[davisagli]
0.4 (2008-04-07)
================
- Added option to include Products directories.
[davisagli]
- Fixed ignore-develop option.
[davisagli]
0.3 (2008-03-30)
================
- Fixed test infrastructure.
[davisagli]
- Added option to ignore develop eggs
[claytron]
- Added option to ignore eggs
[claytron]
- Added option to override the default omelette location.
[davisagli]
0.2 (2008-03-16)
================
- Fixed so created directories are not normalized to lowercase.
[davisagli]
0.1 (2008-03-10)
================
- Initial basic implementation.
[davisagli]
- Created recipe with ZopeSkel.
[davisagli]
Contributors
************
- David Glick [davisagli]
- Clayton Parker [claytron]
- Martin Aspeli [optilude]
- Florian Schulze [fschulze]
- Maurits van Rees [maurits]
- Malthe Borch [malthe]
- Matthew Wilkes [MatthewWilkes]
- Michael Mulich [pumazi]
- Shane Hathaway [hathawsh]
- Leonardo Rochael Almeida [LeoRochael]
- Tom Gross [tom_gross]
- Richard Mitchell [mitchell]
- Roman Lacko [lck]
- Hector Velarde [hvelarde]
Raw data
{
"_id": null,
"home_page": "https://github.com/collective/collective.recipe.omelette",
"name": "collective.recipe.omelette",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "buildout eggs namespace",
"author": "David Glick, Groundwire",
"author_email": "davidglick@groundwire.org",
"download_url": "https://files.pythonhosted.org/packages/a0/fd/e77f6fbd5f0a200454287651a5142e8f8135dd6260b3ef747242e1ca9203/collective_recipe_omelette-2.0.0.tar.gz",
"platform": null,
"description": "Detailed Documentation\n**********************\n\nIntroduction\n============\n\nNamespace packages offer the huge benefit of being able to distribute parts of a large\nsystem in small, self-contained pieces. However, they can be somewhat clunky to navigate,\nsince you end up with a large list of eggs in your egg cache, and then a seemingly endless\nseries of directories you need to open to actually find the contents of your egg.\n\nThis recipe sets up a directory structure that mirrors the actual python namespaces, with\nsymlinks to the egg contents. So, instead of this...::\n\n egg-cache/\n my.egg.one-1.0-py2.7.egg/\n my/\n egg/\n one/\n (contents of first egg)\n my.egg.two-1.0-py2.7.egg/\n my/\n egg/\n two/\n (contents of second egg)\n\n...you get this::\n\n omelette/\n my/\n egg/\n one/\n (contents of first egg)\n two/\n (contents of second egg)\n\n\nYou can also include non-eggified python packages in the omelette. This makes it simple to\nget a single path that you can add to your ``PYTHONPATH`` for use with specialized python environments\nlike when running under mod_wsgi or PyDev.\n\n\nTypical usage with Zope and Plone\n=================================\n\nFor a typical Plone buildout, with a part named ``instance`` that uses the\n``plone.recipe.zope2instance`` recipe, the following additions to ``buildout.cfg`` will\nresult in an omelette including all eggs used by the Zope instance::\n\n [buildout]\n parts =\n ...(other parts)...\n omelette\n\n ...\n\n [omelette]\n recipe = collective.recipe.omelette\n eggs = ${instance:eggs}\n\n\nSupported options\n=================\n\nThe recipe supports the following options:\n\neggs\n List of eggs which should be included in the omelette.\n\nlocation\n (optional) Override the directory in which the omelette is created (default is parts/[name of buildout part])\n\nignore-develop\n (optional) Ignore eggs that you are currently developing (listed in ${buildout:develop}). Default is False\n\nignores\n (optional) List of eggs to ignore when preparing your omelette.\n\npackages\n List of Python packages whose contents should be included in the omelette. Each line should be in the format\n [packages_location] [target_directory], where packages_location is the real location of the packages, and\n target_directory is the optional (relative) location where the package should be inserted into the omelette (defaults\n to ``./``, so directly in the omelette part).\n Example: ``packages = ${buildout:directory}/lib/python3.13/site-packages``\n\n\nUsing omelette with zipped eggs\n===============================\n\nOmelette doesn't currently know how to deal with eggs that are zipped. If it encounters one, you'll\nsee a warning something like the following::\n\n omelette: Warning: (While processing egg elementtree) Egg contents not found at\n /Users/davidg/.buildout/eggs/elementtree-1.2.7_20070827_preview-py2.4.egg/elementtree. Skipping.\n\nYou can tell buildout to unzip all eggs by setting the unzip = true flag in the [buildout] section.\n(Note that this will only take effect for eggs downloaded after the flag is set.)\n\n\nRunning the tests\n=================\n\nJust grab the recipe from git and run::\n\n tox -p auto\n\nKnown issue: The tests run buildout in a separate process, so it's currently\nimpossible to put a pdb breakpoint in the recipe and debug during the test.\nIf you need to do this, set up another buildout which installs an omelette\npart and includes collective.recipe.omelette as a development egg.\n\n\nReporting bugs or asking questions\n==================================\n\nThere is a bugtracker on gitHub:\nhttps://github.com/collective/collective.recipe.omelette/issues\n\nChange history\n**************\n\n2.0.0 (2025-02-14)\n==================\n\nBreaking changes:\n\n- No longer generate ``__init__.py`` files with namespace stanza in ``parts/omelette``.\n I think this was originally done to be able to go to ``parts/omelette``, start a standard Python, and be able to import everything.\n With current Python versions the ``__init__.py`` files are not needed for a directory to be importable.\n [maurits]\n\n- Remove ``products`` recipe option and special handling of ``Products`` namespace.\n Zope 4 and higher no longer have the concept of a products directory.\n You can still use ``packages = path/to/products_dir Products`` if you need something similar.\n [maurits]\n\n- Require at least Python 3.9.\n [maurits]\n\nBug fixes:\n\n- Fix handling checkouts of native namespace packages.\n [maurits]\n\n\n1.1.1 (2025-02-12)\n==================\n\n- Remove setuptools fossils.\n [maurits]\n\n\n1.1.0 (2021-12-01)\n==================\n\n- Fix 2to3 old setuptools hook [goschtl]\n- mordernize to python3 code [goschtl]\n- update to new zope.testing [goschtl]\n- use pytest and tox [goschtl]\n- Note: tested on Python 2.7 and 3.6-3.10.\n\n1.0.0 (2020-08-03)\n==================\n\n- Fix to run under Windows with Python 3.\n [nilshofer, jensens]\n\n0.16 (2013-02-18)\n=================\n\n- Fix packaging error.\n [davisagli]\n\n- Fix tests to work with buildout 2.\n [davisagli]\n\n0.15 (2012-05-12)\n=================\n\n- Integration with Travis CI for running tests and pep8/pyflakes.\n [hvelarde]\n\n- PEP 8/Pyflakes.\n [hvelarde]\n\n- Optimized unlinking of junctioned dirs on Windows.\n [lck]\n\n0.14 (2012-04-30)\n=================\n\n- Change the approach to building the omelette using NTFS junctions\n on Windows. This is now done via the ``ntfsutils`` package, rather\n than relying on junction.exe.\n [lck]\n\n0.13 (2012-04-14)\n=================\n\n- Added forward-compatibility with Python 3.\n [mitchell]\n\n0.12 (2011-09-08)\n=================\n\n- Replaced os.popen with subprocess equivalent\n [tom_gross]\n\n- Quote path on windows to handle paths with spaces correctly\n [tom_gross]\n\n0.11 (2011-07-18)\n=================\n\n- Sort top_level metadata to avoid error building omelette if they are out of\n order. Fixes https://bugs.launchpad.net/collective.buildout/+bug/553005.\n Thanks to Leonardo Rochael Almeida.\n [davisagli]\n\n0.10 (2010-11-22)\n=================\n\n- Provide an update function (equivalent to install) to avoid spurious \"recipe\n \"doesn't define an update method\" warning.\n [davisagli]\n\n- Print a warning rather than aborting the buildout if junction.exe is missing\n on Windows.\n [davisagli]\n\n- Made the tests compatible with a zc.buildout installed with Distribute\n rather than Setuptools.\n [pumazi]\n\n- Handle OSErrors on symlink and warn the user. MacOSX can raise OSError due\n to an existing file here even if os.path.exists returns False.\n [MatthewWilkes]\n\n- Include modules from namespace packages in the omelette. (Namespace packages\n cannot define anything in __init__.py, but they can contain modules.)\n [hathawsh]\n\n- Made the tests compatible with virtualenv.\n [hathawsh]\n\n0.9 (2009-04-11)\n================\n\n- Adjusted log-levels to be slightly less verbose for non-critical\n errors. [malthe]\n\n0.8 (2009-01-14)\n================\n\n- Fixed 'OSError [Errno 20] Not a directory' on zipped eggs, for\n example when adding the z3c.sqlalchemy==1.3.5 egg.\n [maurits]\n\n0.7 (2008-09-10)\n================\n\n- Actually add namespace declarations to generated __init__.py files.\n [davisagli]\n\n- Use egg-info instead of guessing paths from package name. This also fixes\n eggs which have a name different from the contents.\n [fschulze]\n\n0.6 (2008-08-11)\n================\n\n- Documentation changes only.\n [davisagli]\n\n0.5 (2008-05-29)\n================\n\n- Added uninstall entry point so that the omelette can be uninstalled on\n Windows without clobbering things outside the omelette path.\n [optilude]\n\n- Support Windows using NTFS junctions (see\n http://www.microsoft.com/technet/sysinternals/FileAndDisk/Junction.mspx)\n [optilude]\n\n- Ignore zipped eggs and fakezope2eggs-created links.\n [davisagli]\n\n- Added 'packages' option to allow merging non-eggified Python packages to\n any directory in the omelette (so that, for instance, the contents of\n Zope's lib/python can be merged flexibly).\n [davisagli]\n\n0.4 (2008-04-07)\n================\n\n- Added option to include Products directories.\n [davisagli]\n\n- Fixed ignore-develop option.\n [davisagli]\n\n0.3 (2008-03-30)\n================\n\n- Fixed test infrastructure.\n [davisagli]\n\n- Added option to ignore develop eggs\n [claytron]\n\n- Added option to ignore eggs\n [claytron]\n\n- Added option to override the default omelette location.\n [davisagli]\n\n0.2 (2008-03-16)\n================\n\n- Fixed so created directories are not normalized to lowercase.\n [davisagli]\n\n0.1 (2008-03-10)\n================\n\n- Initial basic implementation.\n [davisagli]\n\n- Created recipe with ZopeSkel.\n [davisagli]\n\nContributors\n************\n\n- David Glick [davisagli]\n- Clayton Parker [claytron]\n- Martin Aspeli [optilude]\n- Florian Schulze [fschulze]\n- Maurits van Rees [maurits]\n- Malthe Borch [malthe]\n- Matthew Wilkes [MatthewWilkes]\n- Michael Mulich [pumazi]\n- Shane Hathaway [hathawsh]\n- Leonardo Rochael Almeida [LeoRochael]\n- Tom Gross [tom_gross]\n- Richard Mitchell [mitchell]\n- Roman Lacko [lck]\n- Hector Velarde [hvelarde]\n",
"bugtrack_url": null,
"license": "GPL",
"summary": "Creates a unified directory structure of installed packages, symlinking to the actual contents, in order to ease navigation.",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/collective/collective.recipe.omelette"
},
"split_keywords": [
"buildout",
"eggs",
"namespace"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b4e583b044906a5b8824f313520b4ab364346b1e55c2484949677c87aa404100",
"md5": "a56764f4f91fb99be7f12d871eaafe31",
"sha256": "1fc6bb33dd40bb59410c3532ceb0151190d41c6c78ca3cf4510fbcd8951265d3"
},
"downloads": -1,
"filename": "collective.recipe.omelette-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a56764f4f91fb99be7f12d871eaafe31",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16785,
"upload_time": "2025-02-14T11:31:56",
"upload_time_iso_8601": "2025-02-14T11:31:56.267630Z",
"url": "https://files.pythonhosted.org/packages/b4/e5/83b044906a5b8824f313520b4ab364346b1e55c2484949677c87aa404100/collective.recipe.omelette-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a0fde77f6fbd5f0a200454287651a5142e8f8135dd6260b3ef747242e1ca9203",
"md5": "5515f67a8b383368295792e614719b96",
"sha256": "f9c58447408f8ecfb866d26f3c6790bc571d52dde97bed03b346a3a30b45b345"
},
"downloads": -1,
"filename": "collective_recipe_omelette-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "5515f67a8b383368295792e614719b96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 18069,
"upload_time": "2025-02-14T11:31:58",
"upload_time_iso_8601": "2025-02-14T11:31:58.164847Z",
"url": "https://files.pythonhosted.org/packages/a0/fd/e77f6fbd5f0a200454287651a5142e8f8135dd6260b3ef747242e1ca9203/collective_recipe_omelette-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-14 11:31:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "collective",
"github_project": "collective.recipe.omelette",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "collective.recipe.omelette"
}
JSON
