feat: introduce Kenya Postal Code doctype and initial data patch

csf_ke/csf_ke/doctype/kenya_postal_code/__init__.py

@@ -0,0 +1 @@
+

csf_ke/csf_ke/doctype/kenya_postal_code/kenya_postal_code.json

@@ -0,0 +1,115 @@
+{
+ "actions": [],
+ "allow_import": 1,
+ "allow_rename": 1,
+ "autoname": "field:postal_code",
+ "creation": "2026-05-12 18:08:00.000000",
+ "doctype": "DocType",
+ "engine": "InnoDB",
+ "field_order": [
+  "postal_code",
+  "town",
+  "postal_region_code",
+  "column_break_location",
+  "county",
+  "region",
+  "section_break_meta",
+  "country",
+  "column_break_meta",
+  "source_url"
+ ],
+ "fields": [
+  {
+   "fieldname": "postal_code",
+   "fieldtype": "Data",
+   "in_list_view": 1,
+   "in_standard_filter": 1,
+   "label": "Postal Code",
+   "reqd": 1,
+   "unique": 1
+  },
+  {
+   "fieldname": "town",
+   "fieldtype": "Data",
+   "in_list_view": 1,
+   "in_standard_filter": 1,
+   "label": "Town",
+   "reqd": 1
+  },
+  {
+   "fieldname": "postal_region_code",
+   "fieldtype": "Data",
+   "in_list_view": 1,
+   "in_standard_filter": 1,
+   "label": "Postal Region Code"
+  },
+  {
+   "fieldname": "column_break_location",
+   "fieldtype": "Column Break"
+  },
+  {
+   "fieldname": "county",
+   "fieldtype": "Data",
+   "in_standard_filter": 1,
+   "label": "County"
+  },
+  {
+   "fieldname": "region",
+   "fieldtype": "Data",
+   "in_standard_filter": 1,
+   "label": "Region"
+  },
+  {
+   "fieldname": "section_break_meta",
+   "fieldtype": "Section Break",
+   "label": "Source Information"
+  },
+  {
+   "default": "Kenya",
+   "fieldname": "country",
+   "fieldtype": "Link",
+   "label": "Country",
+   "options": "Country",
+   "read_only": 1
+  },
+  {
+   "fieldname": "column_break_meta",
+   "fieldtype": "Column Break"
+  },
+  {
+   "fieldname": "source_url",
+   "fieldtype": "Data",
+   "label": "Source URL",
+   "read_only": 1
+  }
+ ],
+ "index_web_pages_for_search": 1,
+ "links": [],
+ "modified": "2026-05-12 18:08:00.000000",
+ "modified_by": "Administrator",
+ "module": "CSF KE",
+ "name": "Kenya Postal Code",
+ "naming_rule": "By fieldname",
+ "owner": "Administrator",
+ "permissions": [
+  {
+   "create": 1,
+   "delete": 1,
+   "email": 1,
+   "export": 1,
+   "print": 1,
+   "read": 1,
+   "report": 1,
+   "role": "System Manager",
+   "share": 1,
+   "write": 1
+  }
+ ],
+ "search_fields": "postal_code, town, county",
+ "show_title_field_in_link": 1,
+ "sort_field": "postal_code",
+ "sort_order": "ASC",
+ "states": [],
+ "title_field": "town",
+ "track_changes": 1
+}

csf_ke/csf_ke/doctype/kenya_postal_code/kenya_postal_code.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2026, Navari Ltd and contributors
+# For license information, please see license.txt
+
+from frappe.model.document import Document
+
+
+class KenyaPostalCode(Document):
+	pass

csf_ke/csf_ke/doctype/kenya_postal_code/test_kenya_postal_code.py

@@ -0,0 +1,25 @@
+# Copyright (c) 2026, Navari Ltd and Contributors
+# See license.txt
+
+import frappe
+from frappe.tests.utils import FrappeTestCase
+
+
+class TestKenyaPostalCode(FrappeTestCase):
+	def test_postal_code_creation(self) -> None:
+		"""Test that a Kenya Postal Code can be created with required fields."""
+		if frappe.db.exists("Kenya Postal Code", "99999"):
+			frappe.delete_doc("Kenya Postal Code", "99999", force=True)
+
+		doc = frappe.get_doc(
+			{
+				"doctype": "Kenya Postal Code",
+				"postal_code": "99999",
+				"town": "Test Town",
+				"country": "Kenya",
+			}
+		)
+		doc.insert(ignore_permissions=True)
+		self.assertTrue(doc.name)
+		self.assertEqual(doc.name, "99999")
+		self.assertEqual(doc.town, "Test Town")

csf_ke/csf_ke/patches/create_kenya_postal_codes.py

@@ -0,0 +1,57 @@
+import json
+import os
+
+import frappe
+
+
+def execute():
+	"""One-time import of Kenya Postal Codes from bundled JSON fixture."""
+	base_path = frappe.get_module_path("csf_ke")
+	json_file_path = os.path.join(
+		base_path, "patches", "kenya_postal_code_data.json"
+	)
+
+	if not os.path.exists(json_file_path):
+		frappe.log_error(
+			"Kenya Postal Code data file not found at: " + json_file_path,
+			"Patch Error",
+		)
+		return
+
+	with open(json_file_path) as f:
+		data = json.load(f)
+
+	records = data.get("records", data) if isinstance(data, dict) else data
+
+	existing_codes: set[str] = set(
+		frappe.get_all("Kenya Postal Code", pluck="name")
+	)
+
+	inserted = 0
+	for record in records:
+		postal_code = record.get("postal_code", "")
+		if postal_code in existing_codes:
+			continue
+
+		frappe.get_doc(
+			{
+				"doctype": "Kenya Postal Code",
+				"postal_code": postal_code,
+				"town": record.get("town", ""),
+				"county": record.get("county"),
+				"region": record.get("region"),
+				"postal_region_code": record.get("postal_region_code", ""),
+				"country": record.get("country", "Kenya"),
+				"source_url": record.get("source_url", ""),
+			}
+		).insert(ignore_permissions=True)
+		inserted += 1
+
+		if inserted % 100 == 0:
+			frappe.db.commit()
+
+	if inserted:
+		frappe.db.commit()
+		frappe.logger().info(
+			f"Kenya Postal Codes patch: inserted {inserted} records"
+		)