Regional Overrides

# erpnext/__init__.py

import functools
import inspect
import frappe

def allow_regional(fn):
    """Decorator to make a function regionally overridable
    
    Example:
    @erpnext.allow_regional
    def myfunction():
        pass
    """
    @functools.wraps(fn)
    def caller(*args, **kwargs):
        overrides = frappe.get_hooks("regional_overrides", {}).get(get_region())
        function_path = f"{inspect.getmodule(fn).__name__}.{fn.__name__}"
        
        if not overrides or function_path not in overrides:
            return fn(*args, **kwargs)
        
        # Priority given to last installed app
        return frappe.get_attr(overrides[function_path][-1])(*args, **kwargs)
    
    return caller

# erpnext/hooks.py

regional_overrides = {
    "United Arab Emirates": {
        "erpnext.controllers.taxes_and_totals.update_itemised_tax_data": 
            "erpnext.regional.united_arab_emirates.utils.update_itemised_tax_data",
        "erpnext.accounts.doctype.purchase_invoice.purchase_invoice.make_regional_gl_entries": 
            "erpnext.regional.united_arab_emirates.utils.make_regional_gl_entries",
    },
    "Italy": {
        "erpnext.controllers.taxes_and_totals.update_itemised_tax_data": 
            "erpnext.regional.italy.utils.update_itemised_tax_data",
        "erpnext.controllers.accounts_controller.validate_regional": 
            "erpnext.regional.italy.utils.sales_invoice_validate",
    },
    "Saudi Arabia": {
        "erpnext.controllers.taxes_and_totals.update_itemised_tax_data": 
            "erpnext.regional.united_arab_emirates.utils.update_itemised_tax_data"
    }
}

# erpnext/regional/united_arab_emirates/utils.py

import frappe
import erpnext
from erpnext.controllers.taxes_and_totals import get_itemised_tax_breakup_data

def update_itemised_tax_data(doc):
    """Update tax breakup for UAE VAT requirements"""
    if not doc.taxes:
        return
    
    # Get standard tax breakup
    itemised_tax = get_itemised_tax_breakup_data(doc)
    
    # Add UAE-specific zero-rated and exempt flags
    for row in doc.items:
        if row.is_zero_rated:
            itemised_tax[row.item_code]["zero_rated"] = True
        if row.is_exempt:
            itemised_tax[row.item_code]["exempt"] = True
    
    doc._itemised_tax_data = itemised_tax

def make_regional_gl_entries(gl_entries, doc):
    """Add GL entries for reverse charge mechanism"""
    country = frappe.get_cached_value("Company", doc.company, "country")
    
    if country != "United Arab Emirates":
        return gl_entries
    
    if doc.reverse_charge == "Y":
        tax_accounts = get_tax_accounts(doc.company)
        for tax in doc.get("taxes"):
            if tax.category not in ("Total", "Valuation and Total"):
                continue
            gl_entries = make_gl_entry(tax, gl_entries, doc, tax_accounts)
    
    return gl_entries

def make_gl_entry(tax, gl_entries, doc, tax_accounts):
    """Create GL entry for reverse charge tax"""
    from erpnext.accounts.general_ledger import get_account_currency
    from frappe.utils import flt
    
    dr_or_cr = "credit" if tax.add_deduct_tax == "Add" else "debit"
    
    if flt(tax.base_tax_amount_after_discount_amount) and tax.account_head in tax_accounts:
        account_currency = get_account_currency(tax.account_head)
        
        gl_entries.append(
            doc.get_gl_dict(
                {
                    "account": tax.account_head,
                    "against": doc.supplier,
                    dr_or_cr: flt(tax.base_tax_amount_after_discount_amount),
                    "cost_center": tax.cost_center,
                    "remarks": "Reverse charge VAT"
                },
                account_currency,
                item=tax
            )
        )
    
    return gl_entries

# erpnext/regional/italy/utils.py

import frappe
from frappe import _

def sales_invoice_validate(doc):
    """Validate Italian e-invoice requirements"""
    if not doc.company or frappe.get_cached_value("Company", doc.company, "country") != "Italy":
        return
    
    # Validate fiscal code or VAT number
    if doc.customer:
        customer = frappe.get_cached_doc("Customer", doc.customer)
        if not customer.tax_id and not customer.fiscal_code:
            frappe.throw(_("Customer must have either Tax ID or Fiscal Code for Italian invoicing"))
    
    # Validate electronic invoice code
    if not doc.customer_address:
        frappe.throw(_("Customer Address is mandatory for Italian invoicing"))
    
    address = frappe.get_cached_doc("Address", doc.customer_address)
    if address.country == "Italy" and not address.electronic_invoice_code:
        frappe.throw(_("Electronic Invoice Code is required for Italian addresses"))

def update_itemised_tax_data(doc):
    """Add Italian tax nature codes to itemised tax data"""
    itemised_tax = get_itemised_tax_breakup_data(doc)
    
    for row in doc.items:
        if row.item_code in itemised_tax:
            # Add Italian specific tax exemption reason
            if hasattr(row, 'tax_exemption_reason'):
                itemised_tax[row.item_code]["tax_exemption_reason"] = row.tax_exemption_reason
    
    doc._itemised_tax_data = itemised_tax

# custom_app/regional/australia/setup.py

import frappe
from frappe.custom.doctype.custom_field.custom_field import create_custom_fields

def setup(company=None, patch=True):
    """Setup Australian localization"""
    make_custom_fields()
    setup_tax_accounts(company)
    configure_gst_settings()

def make_custom_fields():
    """Add Australian-specific custom fields"""
    custom_fields = {
        "Customer": [
            dict(
                fieldname="abn",
                label="Australian Business Number (ABN)",
                fieldtype="Data",
                insert_after="tax_id"
            ),
            dict(
                fieldname="acn",
                label="Australian Company Number (ACN)",
                fieldtype="Data",
                insert_after="abn"
            )
        ],
        "Sales Invoice": [
            dict(
                fieldname="gst_treatment",
                label="GST Treatment",
                fieldtype="Select",
                options="GST\nGST Free\nInput Taxed\nExport",
                insert_after="taxes_and_charges"
            )
        ],
        "Address": [
            dict(
                fieldname="state_code",
                label="State Code",
                fieldtype="Select",
                options="\nNSW\nVIC\nQLD\nWA\nSA\nTAS\nACT\nNT",
                insert_after="state"
            )
        ]
    }
    
    create_custom_fields(custom_fields, update=True)

def update_regional_tax_settings(country=None, company=None):
    """Configure GST accounts and tax templates"""
    if not company:
        return
    
    # Create GST accounts
    from erpnext.accounts.doctype.account.chart_of_accounts.chart_of_accounts import create_charts
    
    accounts = [
        {
            "account_name": "GST Collected",
            "parent_account": "Current Liabilities - " + company.abbr,
            "account_type": "Tax",
            "tax_rate": 10.0
        },
        {
            "account_name": "GST Paid",
            "parent_account": "Current Assets - " + company.abbr,
            "account_type": "Tax",
            "tax_rate": 10.0
        }
    ]
    
    for account in accounts:
        if not frappe.db.exists("Account", account["account_name"] + " - " + company.abbr):
            doc = frappe.get_doc({
                "doctype": "Account",
                "company": company.name,
                **account
            })
            doc.insert()

@erpnext.allow_regional
def calculate_taxes_and_totals(doc):
    """Base implementation"""
    # Standard tax calculation
    pass

# Regional override
def calculate_taxes_and_totals_india(doc):
    """India-specific tax calculation with GST"""
    # Calculate CGST, SGST, IGST
    pass

@erpnext.allow_regional
def make_regional_gl_entries(gl_entries, doc):
    """Hook for regional GL entry modifications"""
    return gl_entries

# Regional implementation
def make_regional_gl_entries_uae(gl_entries, doc):
    """Add UAE reverse charge GL entries"""
    # Add additional GL entries for VAT
    return gl_entries

@erpnext.allow_regional
def validate_regional(doc):
    """Regional validation hook"""
    pass

# Country-specific validation
def validate_regional_italy(doc):
    """Italian e-invoice validation"""
    if doc.doctype == "Sales Invoice":
        validate_fiscal_code(doc)
        validate_electronic_invoice_code(doc)

# hooks.py

doc_events = {
    "Sales Invoice": {
        "on_submit": [
            "erpnext.regional.italy.utils.sales_invoice_on_submit",
        ],
        "on_cancel": [
            "erpnext.regional.italy.utils.sales_invoice_on_cancel",
        ],
        "on_trash": "erpnext.regional.check_deletion_permission",
    },
    "Purchase Invoice": {
        "validate": [
            "erpnext.regional.united_arab_emirates.utils.update_grand_total_for_rcm",
            "erpnext.regional.united_arab_emirates.utils.validate_returns",
        ]
    },
    "Address": {
        "validate": [
            "erpnext.regional.italy.utils.set_state_code",
        ],
    },
}

@erpnext.allow_regional
def update_itemised_tax_data(doc):
    """Calculate itemised tax breakup"""
    # Base implementation
    pass

def regional_function(doc):
    country = erpnext.get_region(doc.company)
    
    # Provide sensible defaults
    if country not in SUPPORTED_COUNTRIES:
        frappe.log_error(f"Regional logic not implemented for {country}")
        return default_behavior(doc)

"""
UAE VAT Implementation

Requirements:
- Reverse charge mechanism for B2B transactions
- Zero-rated and exempt item tracking
- VAT Return reports (Form 201)

References:
- UAE VAT Law: https://tax.gov.ae/
- Implementation Guide: [link]
"""

fixtures = [
    {
        "dt": "Custom Field",
        "filters": [
            ["name", "in", [
                "Sales Invoice-uae_reverse_charge",
                "Item-is_zero_rated",
                "Item-is_exempt"
            ]]
        ]
    }
]

custom_app/
└── regional/
    ├── __init__.py
    ├── australia/
    │   ├── setup.py
    │   └── utils.py
    ├── canada/
    │   ├── setup.py
    │   └── utils.py
    └── united_kingdom/
        ├── setup.py
        └── utils.py