README.rst

============
Odoo Scripts
============

Most commands can be run directly or with the image build from ``Dockerfile`` (xcgd/odoo_scripts) by indicating the command to run, but the best way to use this module is to install it. Installing will also install dependencies.

Scripts
=======

Those scripts are available when installing the package, and can also be run directly.

The recommend way to install this module is to run ``python3 -m pip install hg+https://orus.io/xcg/odoo_scripts#egg=odoo_scripts``, or to clone it then run ``python3 -m pip install .``.

Some scripts are in other sections, because they need some specialized library, in that case you need to indicate the name of section as in ``python3 -m pip install "hg+https://orus.io/xcg/odoo_scripts#egg=odoo_scripts[docker]"``.
The prerequisites for this module or one of its section can be installed by using pip3 or the package manager; the requirements are defined in ``setup.py``.

.. important:: As there is no way of indicating sections (worse, it is handling them incorrectly), do not use ``python3 setup.py install``.

docker_isort
------------

Run dockerized isort on current directory. This uses a configuration file that is adapted to OCA guidelines for imports.

This is part of the docker section.

docker_pylint
-------------

Run dockerized pylint on provided module name. Pylint must be present in the project image.

This is part of the docker section.

docker_prettier
---------------

Run dockerized prettier on provided directory. prettier must be present in the project image.

This is part of the docker section.

conf2reST.py
------------

This script is used to produce a reST file from setup.cfg, the Dockerfile and the ``.hgconf``/``nest.yaml`` file.

When the package is installed, the executable for this script is ``conf2reST``.
This is part of the conf2reST section.

update_duplicate_sources.py
---------------------------

This script will update a project that only contain the sources of the one it is launched from.

It expect the configuration file (`setup.cfg`_) to have the following keys:

- ``modules``: list of directories and files to include (also used by another script)
- ``dependencies``: list of directories and files to include (also used by another script)
- ``other_sources``: list of directories and files to include (only used by this script, used for README, ReleaseNotes, script directories, etc.)
- ``duplicate_repo``: target repository, if none are specified, uses the same URL and append `_sources` to it.
 
No change are made to the name of the directories/files included.

When the package is installed, the executable for this script is ``update_duplicate_sources``.
This is part of the source_control section.

docker_dev_start.py
-------------------

This script starts an odoo from a docker but with the local addons modules mounted, and eventually a local copy of the odoo sources mounted too.

Using it avoids having to create a virtual environment for every project.

Prerequisites:

- Your user needs to be in the docker group.
- It expects the `configuration file <setup.cfg>`_ to have the following keys:

  ``modules``
    list of directories and files to include
  …
    …

When the package is installed, the executable for this script is ``docker_dev_start``.
This is part of the docker section.

docker_pg.py
------------

This script start a postgresql server the same way `docker_dev_start.py`_ does.

By default it provides an interactive psql shell, but can also be used to run SQL commands, use an interactive shell or a shell command.

Prerequisites:

- Your user needs to be in the docker group.
- It uses the `configuration file <setup.cfg>`_’s keys: postgresql_version.

This is part of the docker section.

docker_build.py
---------------

This script builds a docker image of the project.

It uses the super project’s `setup.cfg`_ and ``Dockerfile``.

When the package is installed, the executable for this script is ``docker_build``.
This is part of the docker section.

do_tests.py
-----------

This scripts launches the tests, but with more options than `do_tests`_. It uses docker by default, similar to `docker_dev_start.py`_.

When the package is installed, the executable for this script is ``do_tests``.


import_base_import and import_jsonrpc
-------------------------------------

Import CSV files into an odoo.

import_base_import uses odoo base_import module to import the CSV file.

import_jsonrpc uses jsonrpc calls to import the files.
The format is the same as the one used with the import module, with a couple more restrictions:

- selection fields must use the technical value, not the displayed value or one of its translation.
- many2one and many2many fields must use the xmlid of the field they are referencing, with the column name in the form field_name/id or field_name:id.
- one2many fields in the same file are not supported for now.
- date and datetime must be in ISO format.
- context does not include base.import usual import key, so they need to be added as argument or in the configuration file.

import_jsonrpc tries to find an ``import.yaml`` file alongside any imported file. It will use the delimiter indicated in the file if it finds one and will add the context key to the context used in the jsonrpc calls.

import_sql
----------

Import CSV files into an Odoo database. The import is done directly as SQL insert and update commands.

The format is the similar to the one used with the import module, with many more restrictions:

- selection fields must use the technical value, not the displayed value or one of its translation.
- many2one and many2many fields can not be used.
- one2many fields in the same file are not supported.
- date and datetime must be in ISO format.

When inserting, the create_uid/write_uid are not set.
create_date and write_date is updated as needed, and so is the date_update in ``ir.model.data``.
This is part of the import_sql section.

setup.cfg
=========

The scripts expects configuration in the odoo_scripts section of ``setup.cfg``. This is the file in the super project, not the one in `Odoo Scripts`_.

Configuration keys:

modules
    list of modules to install (relative to project directory), those modules are the ones copied in the Dockerfile
odoo_type
    type of odoo (odoo7, odoo8, odoo10, odoo11, odoo13)
pg.extensions
    postgresql extensions to install (unaccent is added automatically depending on odoo configuration)
load-language
    languages to install into a newly created database
postgresql_version
    version of postgresql to use. defaults to 9.6.

It is possible to reuse another directory containing `setup.cfg`_. These type of keys can be used:

.. code-block:: INI

    # this key allows to define the path to the file to reuse (to expand on)
    # name can be different from the directory name
    # this key is mandatory
    expand.name.path = path/to/directory
    # this key indicates what keys to reuse from the subdirectories
    # this is not required, but will default to all if not provided
    # comma separated list of values.
    expand.base.read = modules,module_list
    # this key is to allow blacklisting some subdirectories
    # the name is the same as the previous key
    # if there is no blacklisting, no need to include it
    # the value is a python regexp
    expand.name.blacklist = regexp

Completion files for zsh
========================

Your ``.zshrc`` should contain a line like this::

  fpath=(~/.local/share/zsh/completion $fpath)

Create completion directory::

  mkdir -p ~/.local/share/zsh/completion

Clone::

  cd
  mkdir -p src
  cd src
  git clone git@github.com:RobSis/zsh-completion-generator.git

Generate completion file for python scripts (from the super project for the scripts that need to be run from there, and with the required requirements too)::

  for command_name in docker_dev_start docker_build docker_build_copy docker_build_clean do_tests conf2reST import_base_import import_jsonrpc import_sql docker_flake8 docker_isort docker_pg; do
    $command_name --help | python3 ~/src/zsh-completion-generator/help2comp.py $command_name > ~/.local/share/zsh/completion/_$command_name
  done

Note that even help2comp.py indicates it is not complient with python3, it seems to work fine enough.

Shell Scripts
=============

Those scripts are not installed when installing this python module. They are meant to be used on a system that has Odoo installed, inside an image for example.

start
-----

This script can be used to start odoo.

It need to be run on a machine with all the odoo requirements installed, either system-wide or in a virtual environment (which need to be activated).

Its arguments are forwarded to the Odoo executable (``odoo-bin`` / ``openerp-server``).

It expect the configuration file (`setup.cfg`_) to have the following keys:

- ``odoo_type``. The environment variable ODOO_TYPE can be also be used instead to override the configuration file.
- ``modules``: list of directories and files to include (also used by another script)
- ``load-language``.

These environment variables can be set:

ODOO_ADDONS_PATH
    can be used to set the path for the addons, it can be empty if there is no path to include.
PRE_ODOO_BIN
    Will be used in the command line calling odoo. Useful to run coverage tests for example.

do_tests
--------

This script create a database, install modules and run the tests on those modules and print the result.

It need to be run on a machine with all the odoo requirements installed, either system-wide or in a virtual environment (which need to be activated).
A postgresql server is also needed.

It takes three optional arguments (those are positional arguments):

- the host of the postgresql server,
- the user for this base (which need database creation rights). If a user is provided, you will need to have a .pgpass with the password if it is not the one in ``conf/dev/odoo.conf``.
- the name of the database to use

Those environment variables are used:

ODOO_NO_DROP
  set to reuse an existing database.

The script call `run_tests`_.

It expects the configuration file (`setup.cfg`_) to have the following keys:

- ``module_list``: list (separated by white space) of odoo modules to install on the database (default to empty list)
- ``unaccent``: boolean to indicate if unaccent is to be installed on the database (default to True)

run_tests
---------

This script run the tests on a database.

It need to be run on a machine with all the odoo requirements installed, either system-wide or in a virtual environment (which need to be activated).
A postgresql server is also needed.

The name of the database is the same as do_tests or can be provided.

The script call `start`_.

It expect the configuration file (`setup.cfg`_) to have the following keys:

- ``module_list_tests``: list (separated by white space) of odoo modules to run tests for on the database (default to empty list)
- ``odoo_type``: type of odoo (bzr, odoo7, odoo8 or odoo10) [default to odoo8]

create_archive
--------------

zsh script to create a tar.xz file containing all sources.