[IMP] Taxes: changes specific to 18.0

- changes for Python taxes
- changes to the `Included in Price` setting

X-original-commit: 071e782

Author: antoine162

content/applications/finance/accounting/taxes.rst

@@ -81,7 +81,7 @@ price. The following options are available:
   tax-excluded sales price
 - :ref:`Percentage of Price Tax Included <taxes/computation/percentage-of-price-tax-included>`: a
   percentage of the tax-included total
-- :ref:`Python Code <taxes/computation/python-code>`: a custom user-defined formula
+- :ref:`Custom Formula <taxes/computation/python-code>`: a custom user-defined formula
 
 .. _taxes/computation/group-of-taxes:
 
@@ -129,12 +129,12 @@ which determines whether the sales price should be treated as tax-excluded or ta
 .. tabs::
    .. tab:: Tax-excluded
 
-      If :guilabel:`Included in Price` is disabled, the computation is :math:`\text{tax amount}
-      = \text{sales price} \times \text{tax rate}`.
+      If :guilabel:`Included in Price` is :guilabel:`Tax Excluded`, the computation is
+      :math:`\text{tax amount} = \text{sales price} \times \text{tax rate}`.
 
       .. example::
          A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
-         tax that is not :guilabel:`Included in Price`. We then have:
+         tax that is :guilabel:`Tax Excluded`. We then have:
 
          +-------------+-------------+----------+----------+
          | Product     | Price       | Tax      | Total    |
@@ -145,12 +145,13 @@ which determines whether the sales price should be treated as tax-excluded or ta
 
    .. tab:: Tax-included
 
-      If :guilabel:`Included in Price` is enabled, the computation is :math:`\text{tax amount} =
-      \text{sales price} \times \frac{\text{tax rate}}{1 + \text{tax rate}}`.
+      If :guilabel:`Included in Price` is :guilabel:`Tax Included`, the computation is
+      :math:`\text{tax amount} = \text{sales price} \times \frac{\text{tax rate}}{1 +
+      \text{tax rate}}`.
 
       .. example::
          A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
-         tax that is :guilabel:`Included in Price`. We then have:
+         tax that is :guilabel:`Tax Included`. We then have:
 
          +-------------+-------------+----------+----------+
          | Product     | Price       | Tax      | Total    |
@@ -168,8 +169,8 @@ Percentage of price tax included
    This tax computation is rarely used and only useful in countries (e.g., Brazil, Bolivia) that
    quote tax rates as a percentage of the tax-included total.
    For the more common need to compute tax amounts from a tax-included price, use the
-   :ref:`Percentage of Price <taxes/computation/percentage-of-price>` tax computation with the
-   :ref:`Included in Price <taxes/included-in-price>` option.
+   :ref:`Percentage of Price <taxes/computation/percentage-of-price>` tax computation with
+   :ref:`Included in Price <taxes/included-in-price>` set to :guilabel:`Tax Included`.
 
 The tax rate is a percentage of the **tax-included** total.
 
@@ -178,12 +179,13 @@ which determines whether the sales price should be treated as tax-excluded or ta
 
 .. tabs::
    .. tab:: Tax-excluded
-      If :guilabel:`Included in Price` is disabled, the computation is :math:`\text{tax amount}
-      = \text{sales price} \times \frac{\text{tax rate}}{1 - \text{tax rate}}`.
+      If :guilabel:`Included in Price` is set to :guilabel:`Tax Excluded`, the computation is
+      :math:`\text{tax amount} = \text{sales price} \times \frac{\text{tax rate}}{1 -
+      \text{tax rate}}`.
 
       .. example::
          A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price
-         Tax Included` tax that is not :guilabel:`Included in Price`. We then have:
+         Tax Included` tax that is :guilabel:`Tax Excluded`. We then have:
 
          +-------------+-------------+----------+----------+
          | Product     | Price       | Tax      | Total    |
@@ -197,12 +199,12 @@ which determines whether the sales price should be treated as tax-excluded or ta
 
    .. tab:: Tax-included
 
-      If :guilabel:`Included in Price` is enabled, the computation is :math:`\text{tax amount} =
-      \text{sales price} \times \text{tax rate}`.
+      If :guilabel:`Included in Price` is set to :guilabel:`Tax Included`, the computation is
+      :math:`\text{tax amount} = \text{sales price} \times \text{tax rate}`.
 
       .. example::
          A product has a sales price of $1000, and we apply a 10%
-         :guilabel:`Percentage of Price Tax Included` tax that is :guilabel:`Included in Price`.
+         :guilabel:`Percentage of Price Tax Included` tax that is :guilabel:`Tax Included`.
          We then have:
 
          +-------------+-------------+----------+----------+
@@ -217,34 +219,45 @@ which determines whether the sales price should be treated as tax-excluded or ta
 
 .. _taxes/computation/python-code:
 
-Python code
-***********
+Custom formula
+**************
 
 .. important::
    If a tax can be expressed as a multiple of the quantity of the product to which it applies, it
    can be defined as a :ref:`Fixed <taxes/computation/fixed>` tax. Doing so is strongly recommended
-   over defining a :guilabel:`Python Code` tax.
+   over defining a :guilabel:`Custom Formula` tax.
 
-A tax defined as :guilabel:`Python Code` consists of two snippets of Python code that are executed
-in a local environment that can access the unit price, quantity, product, and partner.
-:guilabel:`Python Code` defines the amount of the tax, and :guilabel:`Applicable Code` defines
-whether the tax is applied. Enter a formula for each field at the bottom of the
-:guilabel:`Definition` tab.
+.. note::
+   To use :guilabel:`Custom Formula` taxes, :ref:`install <general/install>` the :guilabel:`Define
+   Taxes as Python Code` (`account_python_tax`) module.
 
-.. example::
-   A product has a sales price of $1000, and we apply a :guilabel:`Python Code` tax with the
-   following configuration:
+For a :guilabel:`Custom Formula` tax, the tax amount is computed according to a Python expression
+defined in the :guilabel:`Formula` field. The Python expression may contain the following tokens:
+
+- any of the following variables:
+
+  - `price_unit`: the unit price of the product
+  - `base`: the taxable basis on which the tax is applied - may differ from the `price_unit` if
+    other taxes are applied first
+  - `quantity`: the quantity of the product
+  - `product`: the product record - product fields can also be accessed
+
+- integers and floating-point numbers
 
-   - :guilabel:`Python Code`: `result = price_unit * 0.10` and
-   - :guilabel:`Applicable Code`: `result = True`.
+- the following permitted tokens: `(`, `)`, `+`, `-`, `*`, `/`, `,`, `<`, `>`, `<=`, `>=`, `and`,
+  `or`, `None`, `min`, and `max`
+
+.. example::
+   A product has a sales price of $1000, and we apply a :guilabel:`Custom Formula` tax with a
+   :guilabel:`Formula` of `max(base, 500) * 0.10 + min(base - 500, 0) * 0.20`
 
    We then have:
 
    +-------------+-------------+----------+----------+
    | Product     | Price       | Tax      | Total    |
    | sales price | without tax |          |          |
    +=============+=============+==========+==========+
-   | 1,000       | 1,000       | 100      | 1,100.00 |
+   | 1,000       | 1,000       | 150      | 1,150.00 |
    +-------------+-------------+----------+----------+
 
 .. _taxes/active:
@@ -405,16 +418,25 @@ invoice line.
 Included in price
 ~~~~~~~~~~~~~~~~~
 
-With this option activated, the tax will treat the sales price on which it is applied as a total
-including the tax amount. The tax computation will split the sales price into a base amount and a
-tax amount. This makes it suitable for B2C sales in most countries where prices are quoted
-tax-inclusive.
+.. tip::
+   To set a company-wide default for this setting, go to :menuselection:`Accounting -->
+   Configuration --> Settings`, find the :guilabel:`Taxes` section, and set the :guilabel:`Prices`
+   setting to :guilabel:`Tax Excluded` or :guilabel:`Tax Included`. This setting cannot be changed
+   once invoices have been created.
+
+When set to :guilabel:`Default`, the company-wide default will be used.
+
+When set to :guilabel:`Tax Excluded`, the tax will always treat the sales price on which it is
+applied as a price excluding the tax amount.
 
-`Total = Sales Price = Computed Tax-Excluded price + Tax`
+When set to :guilabel:`Tax Included`, the tax will always treat the sales price on which it is
+applied as a total including the tax amount. The tax computation will split the sales price into a
+base amount and a tax amount. This makes it suitable for B2C sales in most countries where prices
+are quoted tax-inclusive.
 
 .. example::
    A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price` tax
-   with :guilabel:`Included in Price`. We then have:
+   with :guilabel:`Included in Price` set to :guilabel:`Tax Included`. We then have:
 
    +-------------+-------------+----------+----------+
    | Product     | Price       | Tax      | Total    |
@@ -427,23 +449,21 @@ tax-inclusive.
    For a guide on configuring tax-excluded and tax-included prices for B2B and B2C customers,
    see :doc:`taxes/B2B_B2C`.
 
-   .. image:: taxes/toggle-button.png
-
 .. _taxes/base-subsequent:
 
 Affect base of subsequent taxes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If this setting is enabled, any subsequent tax applied on the same product line that has
 :ref:`taxes/base-affected` will be based on a modified sales price. The exact behavior depends on
-whether the tax with :guilabel:`Affect base of subsequent taxes` is :ref:`taxes/included-in-price`
-or not.
+the :ref:`Included in Price <taxes/included-in-price>` setting of the tax with :guilabel:`Affect
+base of subsequent taxes`.
 
 .. tabs::
    .. tab:: Tax-excluded
-      If :guilabel:`Included in Price` is disabled, subsequent taxes with :guilabel:`Base affected
-      by preceding taxes` will be based on a modified sales price equal to the original sales price
-      plus the tax amount.
+      If :guilabel:`Included in Price` is set to :guilabel:`Tax Excluded`, subsequent taxes with
+      :guilabel:`Base affected by preceding taxes` will be based on a modified sales price equal to
+      the original sales price plus the tax amount.
 
       .. example::
          A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
@@ -452,13 +472,13 @@ or not.
          $1100.
 
    .. tab:: Tax-included
-      If :guilabel:`Included in Price` is enabled, subsequent taxes with :guilabel:`Base affected
-      by preceding taxes` will be based on a modified sales price equal to the original sales price
-      minus the tax amount.
+      If :guilabel:`Included in Price` is set to :guilabel:`Tax Included`, subsequent taxes with
+      :guilabel:`Base affected by preceding taxes` will be based on a modified sales price equal to
+      the original sales price minus the tax amount.
 
       .. example::
          A product has a sales price of $1100, and we apply a 10% :guilabel:`Percentage of Price`
-         tax with :guilabel:`Included in Price` and :guilabel:`Affect base of subsequent taxes`.
+         tax that has :guilabel:`Tax Included` and :guilabel:`Affect base of subsequent taxes`.
          Any subsequent tax with :guilabel:`Base affected by preceding taxes` will be based on a
          modified sales price of $1000.