[cubicweb-ctl] respect sys.exit status code when aborting a command
When exploring the stack of all calls to a cubicweb-ctl command, it has been
discovered than on a KeyboardInterrupt and on a SystemExit exception the base
class InstanceCommand (for commands that works on one instance) will always set
the return code of cubicweb-ctl to 8: this mean that if another command do a
`sys.exit(some_code)` the exit code will be ignored and overwritten by '8'.
This behavior is not intuitive, apparently not documented and doesn't seems to
have any justification. It also prevent commands from exciting with different
return codes which could be a desired behavior in the situation of scripting.
.. _foundationsCube:
.. _cubelayout:
Standard structure for a cube
-----------------------------
A cube named "mycube" is Python package "cubicweb-mycube" structured as
follows:
::
cubicweb-mycube/
|
|-- cubicweb_mycube/
| |
| |-- data/
| | |-- cubes.mycube.css
| | |-- cubes.mycube.js
| | `-- external_resources
| |
| |
| |-- entities.py
| |
| |-- i18n/
| | |-- en.po
| | |-- es.po
| | `-- fr.po
| |
| |-- __init__.py
| |
| |
| |-- migration/
| | |-- postcreate.py
| | `-- precreate.py
| |
| |-- __pkginfo__.py
| |
| |-- schema.py
| |
| |
| |-- site_cubicweb.py
| |
| |-- hooks.py
| |
| |
| `-- views.py
|-- debian/
| |-- changelog
| |-- compat
| |-- control
| |-- copyright
| |-- cubicweb-mycube.prerm
| `-- rules
|-- MANIFEST.in
|-- setup.py
`-- test/
|-- data/
| `-- bootstrap_cubes
|-- pytestconf.py
|-- realdb_test_mycube.py
`-- test_mycube.py
We can use subpackages instead of Python modules for ``views.py``, ``entities.py``,
``schema.py`` or ``hooks.py``. For example, we could have:
::
cubicweb-mycube/
|
|-- cubicweb_mycube/
| |
|-- entities.py
. |-- hooks.py
. `-- views/
. |-- __init__.py
|-- forms.py
|-- primary.py
`-- widgets.py
where :
* ``schema`` contains the schema definition (server side only)
* ``entities`` contains the entity definitions (server side and web interface)
* ``hooks`` contains hooks and/or views notifications (server side only)
* ``views`` contains the web interface components (web interface only)
* ``test`` contains tests related to the cube (not installed)
* ``i18n`` contains message catalogs for supported languages (server side and
web interface)
* ``data`` contains data files for static content (images, css,
javascript code)...(web interface only)
* ``migration`` contains initialization files for new instances (``postcreate.py``)
and a file containing dependencies of the component depending on the version
(``depends.map``)
* ``debian`` contains all the files managing debian packaging (you will find
the usual files ``control``, ``rules``, ``changelog``... not installed)
* file ``__pkginfo__.py`` provides component meta-data, especially the distribution
and the current version (server side and web interface) or sub-cubes used by
the cube.
At least you should have the file ``__pkginfo__.py``.
The :file:`__init__.py` and :file:`site_cubicweb.py` files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. XXX WRITEME
The :file:`__pkginfo__.py` file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It contains metadata describing your cube, mostly useful for packaging.
Two important attributes of this module are __depends__ and __recommends__
dictionaries that indicates what should be installed (and each version if
necessary) for the cube to work.
Dependency on other cubes are expected to be of the form 'cubicweb-<cubename>'.
When an instance is created, dependencies are automatically installed, while
recommends are not.
Recommends may be seen as a kind of 'weak dependency'. Eg, the most important
effect of recommending a cube is that, if cube A recommends cube B, the cube B
will be loaded before the cube A (same thing happend when A depends on B).
Having this behaviour is sometime desired: on schema creation, you may rely on
something defined in the other's schema; on database creation, on something
created by the other's postcreate, and so on.
The :file:`setup.py` file
-------------------------
This is standard setuptools based setup module which reads most of its data
from :file:`__pkginfo__.py`. In the ``setup`` function call, it should also
include an entry point definition under the ``cubicweb.cubes`` group so that
CubicWeb can discover cubes (in particular their custom ``cubicweb-ctl``
commands):
::
setup(
# ...
entry_points={
'cubicweb.cubes': [
'mycube=cubicweb_mycube',
],
},
# ...
)
:file:`migration/precreate.py` and :file:`migration/postcreate.py`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. XXX detail steps of instance creation
External resources such as image, javascript and css files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. XXX naming convention external_resources file
Out-of the box testing
~~~~~~~~~~~~~~~~~~~~~~
.. XXX MANIFEST.in, __pkginfo__.include_dirs, debian
Packaging and distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. XXX MANIFEST.in, __pkginfo__.include_dirs, debian