Tax modules

[John-Scott]

I'm working on a custom tax module and am trying to use the existing
modules as a reference.

I've run into some snags trying to sort out exactly what I must
implement and how these methods are used.

The following is my attempt at documenting my current understanding of
the built-in tax modules using ``tax.modules.no`` as a starting point
[1]. Please let me know if I've got anything wrong. Once I've got this
sorted out I will submit a patch to at least add docstrings to the
``tax.modules.no`` module so it will hopefully be an easier to
understand starting point.


``by_product()`` is never called as far as I can tell. In fact,
searching through the project this method is merely defined on the
built-in tax modules and there is a similarly named method on
product.ProductPriceLookupManager. Perhaps I'm missing something?


``by_orderitem()`` is only used by ``OrderItem.update_tax()`` to
calculate the total tax for the given quantity of an ``OrderItem``
object.


``by_price()`` is used in several places to calculate the tax on
whatever price is passed in. If you have a tax rate, this should just
return rate * price.


``shipping()`` is only used internally in the ``area`` tax module in
the ``process()`` method so one could optionally calculate tax on the
shipping charges.


``process()`` appears to only be called in
``satchmo_store.shop.Order.force_recalculate_total()``. This method is
apparently required to return a tuple where the first element is the
tax amount expressed as a Decimal object. The second element of the
tuple is expected to be a dictionary which can be empty or optionally
contain taxClass names as keys and their respective rates as values.


``get_percent()`` is only used by the ``tax_rate`` template tag for
display purposes. Seems we could just have the template tag use
``get_rate()`` and push the display logic down to the tag?


``get_rate()`` is never called externally, only some of the processors
call this method internally in other 'public' methods. The ``percent``
module defines ``get_rate()`` but this is never called internally or
otherwise.

Judging from some of the modules, ``get_rate()`` should return
something like Decimal("0.0825") while ``get_percent()`` should return
something like Decimal("8.25"). Does that sound about right? The
naming is a bit confusing as ``get_rate()`` often returns a config
option like ``Decimal(config_value('TAX','PERCENT'))`` or an attribute
like ``rate.percentage``.



Thanks,
John-Scott

[1] http://bitbucket.org/chris1610/satchmo/src/tip/satchmo/apps/tax/modules/no/processor.py

[Chris Moffitt]

John-Scott,

Thanks for taking a stab at documenting this. I think you're on the right track, I'll make a couple comments below:

On Wed, Sep 15, 2010 at 4:29 PM, John-Scott <john.scot...@gmail.com> wrote:

I'm working on a custom tax module and am trying to use the existing
modules as a reference.

I've run into some snags trying to sort out exactly what I must
implement and how these methods are used.

The following is my attempt at documenting my current understanding of
the built-in tax modules using ``tax.modules.no`` as a starting point
[1]. Please let me know if I've got anything wrong. Once I've got this
sorted out I will submit a patch to at least add docstrings to the
``tax.modules.no`` module so it will hopefully be an easier to
understand starting point.


``by_product()`` is never called as far as I can tell. In fact,
searching through the project this method is merely defined on the
built-in tax modules and there is a similarly named method on
product.ProductPriceLookupManager. Perhaps I'm missing something?

I think you are right. I can imagine what the intent was but you're right that it doesn't look like it is implemented in the default satchmo store. I believe it's a helper function that you might want to call in a custom template tag.
 

``by_orderitem()`` is only used by ``OrderItem.update_tax()`` to
calculate the total tax for the given quantity of an ``OrderItem``
object.

Correct.

``by_price()`` is used in several places to calculate the tax on
whatever price is passed in. If you have a tax rate, this should just
return rate * price.

Correct.
 

``shipping()`` is only used internally in the ``area`` tax module in
the ``process()`` method so one could optionally calculate tax on the
shipping charges.

Correct.
 

``process()`` appears to only be called in
``satchmo_store.shop.Order.force_recalculate_total()``. This method is
apparently required to return a tuple where the first element is the
tax amount expressed as a Decimal object. The second element of the
tuple is expected to be a dictionary which can be empty or optionally
contain taxClass names as keys and their respective rates as values.

Correct.
 

``get_percent()`` is only used by the ``tax_rate`` template tag for
display purposes. Seems we could just have the template tag use
``get_rate()`` and push the display logic down to the tag?

You're probably correct that we could refactor it a bit. It is slightly redundant but don't think it's a major issue.
 

``get_rate()`` is never called externally, only some of the processors
call this method internally in other 'public' methods. The ``percent``
module defines ``get_rate()`` but this is never called internally or
otherwise.

Judging from some of the modules, ``get_rate()`` should return
something like Decimal("0.0825") while ``get_percent()`` should return
something like Decimal("8.25"). Does that sound about right? The
naming is a bit confusing as ``get_rate()`` often returns a config
option like ``Decimal(config_value('TAX','PERCENT'))`` or an attribute
like ``rate.percentage``.

That's correct. I believe the  distinction between returning an object or the rate is based on the get_object parameter call to get_rate.


Thanks again for working on this level of documentation. It's always very much appreciated.

-Chris

[John-Scott Atlakson]

Thanks for the feedback Chris.

I'm in a rush to get my custom tax module out the door this morning but hopefully in the next couple of days I can whip up some proper documentation.

Thanks again,

John-Scott

--
You received this message because you are subscribed to the Google Groups "Satchmo users" group.
To post to this group, send email to satchm...@googlegroups.com.
To unsubscribe from this group, send email to satchmo-user...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/satchmo-users?hl=en.