Core APIs#

Configuration#

Resource mode#

Standard resource mode#

A resource mode is a predefined set of settings for various resources directories, such as cubes, instances, etc. to ease development with the framework. There are two running modes with CubicWeb:

  • system: resources are searched / created in the system directories (eg usually requiring root access):

    • instances are stored in <INSTALL_PREFIX>/etc/cubicweb.d

    • temporary files (such as pid file) in <INSTALL_PREFIX>/var/run/cubicweb

    where <INSTALL_PREFIX> is the detected installation prefix (‘/usr/local’ for instance).

  • user: resources are searched / created in the user home directory:

    • instances are stored in ~/etc/cubicweb.d

    • temporary files (such as pid file) in /tmp

Within virtual environment#

When installed within a virtualenv, CubicWeb will look for instances data as in user mode by default, that is in $HOME/etc/cubicweb.d. However the CW_INSTANCES_DIR environment variable should be preferably used.

Custom resource location#

Notice that each resource path may be explicitly set using an environment variable if the default doesn’t suit your needs. Here are the default resource directories that are affected according to mode:

  • system:

    CW_INSTANCES_DIR = <INSTALL_PREFIX>/etc/cubicweb.d/
CW_INSTANCES_DATA_DIR = <INSTALL_PREFIX>/var/lib/cubicweb/instances/
CW_RUNTIME_DIR = <INSTALL_PREFIX>/var/run/cubicweb/

  • user:

    CW_INSTANCES_DIR = ~/etc/cubicweb.d/
CW_INSTANCES_DATA_DIR = ~/etc/cubicweb.d/
CW_RUNTIME_DIR = /tmp

Cubes search path is also affected, see the Cubes section.

Setting Cubicweb Mode#

By default, the mode is set to ‘system’ for standard installation. The mode is set to ‘user’ if cubicweb is used from a mercurial repository. You can force this by setting the CW_MODE environment variable to either ‘user’ or ‘system’ so you can easily:

  • use system wide installation but user specific instances and all, without root privileges on the system (export CW_MODE=user)

  • use local checkout of cubicweb on system wide instances (requires root privileges on the system (export CW_MODE=system)

If you’ve a doubt about the mode you’re currently running, check the first line outputed by the cubicweb-ctl list command.

Development Mode (source)#

If .hg directory is found into the cubicweb package, there are specific resource rules.

<CW_SOFTWARE_ROOT> is the source checkout’s cubicweb directory:

  • cubicweb migration files are searched in <CW_SOFTWARE_ROOT>/misc/migration instead of <INSTALL_PREFIX>/share/cubicweb/migration/.

Development Mode (virtualenv)#

If a virtualenv is found to be activated (i.e. a VIRTUAL_ENV variable is found in environment), the virtualenv root is used as <INSTALL_PREFIX>. This, in particular, makes it possible to work in setuptools development mode (python setup.py develop) without any further configuration.

Environment configuration#

Python#

If you installed CubicWeb by cloning the Mercurial shell repository or from source distribution, then you will need to update the environment variable PYTHONPATH by adding the path to cubicweb:

Add the following lines to either .bashrc or .bash_profile to configure your development environment

export PYTHONPATH=/full/path/to/grshell-cubicweb

If you installed CubicWeb with packages, no configuration is required and your new cubes will be placed in /usr/share/cubicweb/cubes and your instances will be placed in /etc/cubicweb.d.

CubicWeb#

Here are all environment variables that may be used to configure CubicWeb:

CW_MODE#

Resource mode: user or system, as explained in Resource mode.

CW_INSTANCES_DIR#

Directory where cubicweb instances will be found.

CW_INSTANCES_DATA_DIR#

Directory where cubicweb instances data will be written (backup file…)

CW_RUNTIME_DIR#

Directory where pid files will be written

class cubicweb.cwconfig.CubicWebConfiguration(appid, debugmode=False, creating=False, log_to_file=False)[source]#

base class for cubicweb server and web configurations

add_cubes(cubes)[source]#

add given cubes to the list of used cubes

anonymous_user()[source]#

return a login and password to use for anonymous users.

None may be returned for both if anonymous connection is not allowed or if an empty login is used in configuration

classmethod available_cubes()[source]#

Return a list of available cube names.

For cube as package, name is equal to python package’s name.

available_languages(*args)[source]#

return available translation for an instance, by looking for compiled catalog

take *args to be usable as a vocabulary method

check_writeable_uid_directory(path)[source]#

check given directory path exists, belongs to the user running the server process and is writeable.

If not, try to fix this, letting exception propagate when not possible.

classmethod config_for(appid, config=None, debugmode=False, log_to_file=False, creating=False)[source]#

return a configuration instance for the given instance identifier

critical(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘CRITICAL’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.critical(“Houston, we have a %s”, “major disaster”, exc_info=1)

classmethod cube_dependencies(cube)[source]#

return cubicweb cubes used by the given cube

classmethod cube_dir(cube)[source]#

return the cube directory for the given cube id, raise ConfigurationError if it doesn’t exist

classmethod cube_migration_scripts_dir(cube)[source]#

cube migration scripts directory

classmethod cube_pkginfo(cube)[source]#

return the information module for the given cube

classmethod cube_recommends(cube)[source]#

return cubicweb cubes recommended by the given cube

classmethod cube_version(cube)[source]#

return the version of the cube located in the given directory

cubes()[source]#

return the list of cubes used by this instance

result is ordered from the top level cubes to inner dependencies cubes

cubes_path()[source]#

return the list of path to cubes used by this instance, from outer most to inner most cubes

static cubicweb_version()[source]#

return installed cubicweb version

debug(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘DEBUG’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.debug(“Houston, we have a %s”, “thorny problem”, exc_info=1)

default_instance_id()[source]#

return the instance identifier, useful for option which need this as default value

default_log_file()[source]#

return default path to the log file of the instance’server

default_pid_file()[source]#

return default path to the pid file of the instance’server

default_stats_file()[source]#

return default path to the stats file of the instance’server

error(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘ERROR’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.error(“Houston, we have a %s”, “major problem”, exc_info=1)

exception(msg, *args, exc_info=True, **kwargs)#

Convenience method for logging an ERROR with exception information.

classmethod expand_cubes(cubes, with_recommends=False)[source]#

expand the given list of top level cubes used by adding recursivly each cube dependencies

classmethod i18n_lib_dir()[source]#

return instance’s i18n directory

info(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘INFO’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.info(“Houston, we have a %s”, “interesting problem”, exc_info=1)

init_log(logthreshold=None, force=False, logfile=None, syslog=None)[source]#

init the log service

classmethod instance_home(appid)[source]#

return the home directory of the instance with the given instance id

classmethod instances_dir()[source]#

return the control directory

load_configuration(**kw)[source]#

load instance’s configuration files

load_defaults() → None[source]#

overload the parent load_defaults to load REQUIRED variables with environment values

load_site_cubicweb(cubes=())[source]#

load site_cubicweb file for cubes

main_config_file()[source]#

return instance’s control configuration file

migration_handler(schema=None, interactive=True, cnx=None, repo=None, connect=True, verbosity=None)[source]#

return a migration handler instance

classmethod migration_scripts_dir()[source]#

cubicweb migration scripts directory

read_sources_file(**kwargs)#

return a dictionary of values found in the sources file

classmethod reorder_cubes(cubes)[source]#

reorder cubes from the top level cubes to inner dependencies cubes

repository(vreg=None)[source]#

Return a new bootstrapped repository.

save()[source]#

write down current configuration

sendmails(msgs, fromaddr=None)[source]#

msgs: list of 2-uple (message object, recipients). Return False if connection to the smtp server failed, else True.

warning(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘WARNING’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.warning(“Houston, we have a %s”, “bit of a problem”, exc_info=1)

write_sources_file(sourcescfg)[source]#

serialize repository’sources configuration into a INI like file

cubicweb.cwconfig.instance_configuration(appid, config=None, debugmode=False, log_to_file=False, creating=False)#

return a configuration instance for the given instance identifier