Kenat Class

The Kenat class provides a high-level API for working with Ethiopian calendar dates. You can create instances, format dates, manipulate them, and print calendars.

Constructor

new Kenat(dateStringOrDict?)

Creates a new instance of an Ethiopian date.

If no argument is passed, it uses the current Gregorian system date.
If a string like '2015/6/10' is passed, it’s parsed as an Ethiopian date.
It can also be initialized with a dictionary: {'year': 2015, 'month': 6, 'day': 10}.

undefined


// No argument: uses current system date (Gregorian)
const k = new Kenat();
 
// From a string (Ethiopian date, supports 'YYYY/MM/DD', 'YYYY-MM-DD', or ISO 'YYYY-MM-DD')
const custom = new Kenat('2016/6/10');
const custom2 = new Kenat('2016-6-10');
const iso = new Kenat('2016-06-10'); // ISO format also supported
 
// From an object with year, month, day (Ethiopian)
const fromObj = new Kenat({ year: 2016, month: 6, day: 10 });
 
// From a native JavaScript Date object (Gregorian)
// Note: JS Date months are 0-based (June = 5)
const fromDate = new Kenat(new Date(2016, 5, 10));

undefined


// No argument: uses current system date (Gregorian)
final k = Kenat.now();
 
// From a string (Ethiopian date, supports 'yyyy/mm/dd' or 'yyyy-mm-dd')
final custom = Kenat('2016/6/10');
final custom2 = Kenat('2016-6-10');
 
// From a map with year, month, day (Ethiopian)
final fromMap = Kenat({ 'year': 2016, 'month': 6, 'day': 10 });
 
// From a native Dart DateTime object (Gregorian)
// Note: unlike JS Date, DateTime months are already 1-based (June = 6)
final fromDate = Kenat(DateTime(2016, 6, 10));
 
print(custom.getEthiopian());   // { year: 2016, month: 6, day: 10 }
print(fromDate.getEthiopian()); // { year: 2008, month: 10, day: 3 }

undefined


from kenat import Kenat
 
# Today's date
k = Kenat()
 
# From a string
custom = Kenat('2016/6/10')
 
# From a dictionary
from_dict = Kenat({'year': 2016, 'month': 6, 'day': 10})

undefined


use Kenat\Kenat;
 
// No argument: uses current system date (Gregorian)
$k = new Kenat();
 
// From a string (Ethiopian date, supports 'YYYY/MM/DD' or 'YYYY-MM-DD')
$custom = new Kenat('2016/6/10');
$custom2 = new Kenat('2016-6-10');
 
// From an array with year, month, day (Ethiopian)
$fromArray = new Kenat(['year' => 2016, 'month' => 6, 'day' => 10]);
 
// From a native DateTimeInterface object (Gregorian)
// Note: PHP's DateTime months are already 1-based (June = 6)
$fromDate = new Kenat(new DateTimeImmutable('2016-06-10'));

Date Access & Formatting

Multiple methods are available to get the date in different formats.

Method	Returns	Description
`get_ethiopian()`	`{ 'year', 'month', 'day' }`	Get the Ethiopian date as a dictionary.
`get_gregorian()`	`{ 'year', 'month', 'day' }`	Get the equivalent Gregorian date.
`__str__()`	`"YYYY/MM/DD"`	A simple string representation.
`format_standard(lang='amharic')`	`"መስከረም 5 2016"` or similar	Human-readable string with language options.
`format_in_geez_amharic()`	`"መስከረም ፭ ፳፻፲፮"`	Geez-styled output.
`format_with_weekday(lang, use_geez)`	`"ማክሰኞ, መስከረም 1 2016"`	Includes the day of the week.
`format_with_time(time_obj, lang)`	`"መስከረም 10 2016 08:30 ጠዋት"`	Combines date and a `Time` object.
`to_iso_date_string(time_obj)`	`"YYYY-MM-DDTHH:mm"`	ISO 8601-like format.

undefined


const k = new Kenat('2016/1/5');
console.log(k.getEthiopian()); // { year: 2016, month: 1, day: 5 }
console.log(k.toString()); // Ethiopian: 2016-1-5
console.log(k.formatInGeezAmharic()); // መስከረም ፭ ፳፻፲፮

undefined


final k = Kenat('2016/1/5');
print(k.getEthiopian());     // { year: 2016, month: 1, day: 5 }
print(k.toString());         // መስከረም 5 2016 12:00 ጠዋት
print(k.formatInGeezAmharic()); // መስከረም ፭ ፳፻፲፮

Note: string/map-constructed Kenat instances always carry a default noon-day time internally, so toString() includes it — unlike JS’s bare "Ethiopian: 2016-1-5".

undefined


from kenat import Kenat, Time
 
k = Kenat('2016/1/5')
print(k.get_ethiopian()) # {'year': 2016, 'month': 1, 'day': 5}
print(str(k)) # 2016/01/05
print(k.format_standard('english')) # September 5 2016
print(k.format_in_geez_amharic()) # መስከረም ፭ ፳፻፲፮
print(k.format_with_weekday()) # ማክሰኞ, መስከረም 5 2016
 
t = Time(8, 30, 'day')
print(k.format_with_time(t)) # መስከረም 5 2016 8:30 ቀን

undefined


use Kenat\Kenat;
use Kenat\Time;
use Kenat\Formatting;
 
$k = new Kenat('2016/1/5');
$et = $k->getEthiopian();
echo "{$et->year}-{$et->month}-{$et->day}"; // 2016-1-5
echo $k->toString();                        // መስከረም 5 2016 12:00 ጠዋት
echo $k->format(['lang' => 'english']);      // September 5 2016
echo $k->formatInGeezAmharic();               // መስከረም ፭ ፳፻፲፮
echo $k->formatWithWeekday();                 // ማክሰኞ, መስከረም 5 2016
 
$t = new Time(8, 30, 'day');
echo Formatting::formatWithTime($et, $t); // መስከረም 5 2016 08:30 ጠዋት

Note: like Dart, string/array-constructed Kenat instances always carry a default noon-day time internally, so toString() includes it.

Time Handling

The Time class handles time calculations, conversions, and formatting separately from the date.

Method/Class	Description
`Time(hour, min, period)`	Creates a time object (e.g., 3:30, ‘night’).
`Time.from_gregorian(h, m)`	Creates an Ethiopian `Time` object from Gregorian 24h time.
`time.to_gregorian()`	Converts Ethiopian time back to a 24h dictionary.
`time.format()`	Formats the time into a string (e.g., “፫:፴ ሌሊት”).
`time.add(duration)`	Adds hours/minutes to the time.
`time.diff(other_time)`	Calculates the difference between two `Time` objects.

undefined


const k = new Kenat();
console.log(k.getCurrentTime());

undefined


final k = Kenat.now();
print(k.getCurrentTime()); // e.g. 05:53 night
 
// Create time from Ethiopian
final t1 = Time(3, 30, 'night');
print(t1.toGregorian()); // { hour: 21, minute: 30 }
print(t1.format({ 'lang': 'amharic', 'useGeez': true })); // ፫:፴ ማታ
 
// Create time from Gregorian
final t2 = Time.fromGregorian(22, 0); // 10 PM
print(t2); // 04:_ night

undefined


from kenat import Time
 
# Create time from Ethiopian
t1 = Time(3, 30, 'night') 
print(t1.to_gregorian()) # {'hour': 21, 'minute': 30}
print(t1.format(lang='amharic', use_geez=True)) # ፫:፴ ሌሊት
 
# Create time from Gregorian
t2 = Time.from_gregorian(22, 0) # 10 PM
print(t2) # 4:00 night

undefined


use Kenat\Kenat;
use Kenat\Time;
 
$k = new Kenat();
$t = $k->getCurrentTime();
echo $t->format(); // e.g. ፲፩:፴ ማታ
 
// Create time from Ethiopian
$t1 = new Time(3, 30, 'night');
print_r($t1->toGregorian()); // ['hour' => 21, 'minute' => 30]
echo $t1->format(['lang' => 'amharic', 'useGeez' => true]); // ፫:፴ ማታ
 
// Create time from Gregorian
$t2 = Time::fromGregorian(22, 0); // 10 PM
echo $t2->format(['useGeez' => false]); // 04:_ night

Date Arithmetic

These functions are available in the kenat.day_arithmetic module and take a Kenat object as the first argument.

Function	Description
`add_days(date, n)`	Returns a new date n days away.
`add_months(date, n)`	Returns a new date n months away.
`add_years(date, n)`	Returns a new date n years away.

undefined


const k = new Kenat('2014/5/5');
k.addDays(10);
k.addMonths(-1);
console.log(k.getEthiopian());

undefined


// Kenat is immutable in Dart: addDays/addMonths/addYears return a
// NEW instance rather than mutating in place, but they still chain.
var k = Kenat('2014/5/5');
k = k.addDays(10).addMonths(-1);
print(k.getEthiopian()); // { year: 2014, month: 4, day: 15 }

undefined


from kenat import Kenat
from kenat.day_arithmetic import add_days, add_months
 
k = Kenat('2014/5/5')
k_plus_10_days = add_days(k, 10)
k_minus_1_month = add_months(k, -1)
 
print(k_plus_10_days.get_ethiopian()) # {'year': 2014, 'month': 5, 'day': 15}
print(k_minus_1_month.get_ethiopian()) # {'year': 2014, 'month': 4, 'day': 5}

undefined


use Kenat\Kenat;
 
// Kenat is immutable in PHP too: addDays/addMonths/addYears return a
// NEW instance rather than mutating in place, but they still chain.
$k = new Kenat('2014/5/5');
$k = $k->addDays(10)->addMonths(-1);
$et = $k->getEthiopian();
echo "{$et->year}-{$et->month}-{$et->day}"; // 2014-4-15

DayArithmetic::addDays()/addMonths()/addYears() are also available as static functions operating directly on EthiopianDate value objects, mirroring the module-level functions in Dart/Python.

Compare Dates

These functions take two Kenat objects and return the difference. They are available in the kenat.day_arithmetic module.

Function	Description
`diff_in_days(a, b)`	Calculates the total day difference.
`diff_in_months(a, b)`	Calculates the month difference.
`diff_in_years(a, b)`	Calculates the year difference.

undefined


const a = new Kenat('2015/6/10');
const b = new Kenat('2012/6/10');
console.log(a.diffInYears(b)); // → 3

undefined


final a = Kenat('2015/6/10');
final b = Kenat('2012/6/10');
print(a.diffInYears(b)); // → 3

undefined


from kenat import Kenat
from kenat.day_arithmetic import diff_in_years
 
a = Kenat('2015/6/10')
b = Kenat('2012/6/10')
print(diff_in_years(a, b)) # → 3

undefined


use Kenat\Kenat;
 
$a = new Kenat('2015/6/10');
$b = new Kenat('2012/6/10');
echo $a->diffInYears($b); // → 3
 
// Kenat also exposes isBefore(), isAfter(), isSameDay(),
// isSameMonth(), isSameYear() for comparisons.
echo $a->isAfter($b) ? 'true' : 'false'; // → true

Calendar & Holiday Tools

The library includes powerful tools for generating monthly calendars and retrieving holiday information.

Method/Class	Description
`MonthGrid(config)`	A class to generate a grid for a specific month.
`get_holiday(key, year, lang)`	Get details for a single holiday.
`get_holidays_in_month(y, m)`	Get all holidays in a given month.
`get_holidays_for_year(year)`	Get all holidays for a given year.

undefined


const k = new Kenat('2016/1/1');
k.printThisMonth(true);

undefined


import 'package:kenat/kenat.dart';
 
// Get a calendar grid for Meskerem 2016
final grid = MonthGrid.create({ 'year': 2016, 'month': 1, 'useGeez': true, 'weekStart': 0 });
print(grid['headers']);
// [እሑድ, ሰኞ, ማክሰኞ, ረቡዕ, ሐሙስ, ዓርብ, ቅዳሜ]
 
// Get info for a specific holiday
final gena = getHoliday('gena', 2016);
print(gena?['name']); // ገና
 
// Get all holidays in a year
final allHolidays2016 = getHolidaysForYear(2016);
print(allHolidays2016.length); // 23
 
// Or print an ASCII grid straight to the console
Kenat('2016/1/1').printThisMonth(true);

undefined


from kenat.month_grid import MonthGrid
from kenat.holidays import get_holiday, get_holidays_for_year
 
# Get a calendar grid for Meskerem 2016
grid = MonthGrid.create(2016, 1, use_geez=True)
print(grid['headers'])
# ['እሑድ', 'ሰኞ', 'ማክሰኞ', 'ረቡዕ', 'ሐሙስ', 'ዓርብ', 'ቅዳሜ']
 
# Get info for a specific holiday
christmas = get_holiday('christmas', 2016)
print(christmas['name']) # የገና በዓል
 
# Get all holidays in a year
all_2016_holidays = get_holidays_for_year(2016)
print(len(all_2016_holidays))

undefined


use Kenat\MonthGrid;
use Kenat\Holidays;
use Kenat\Kenat;
 
// Get a calendar grid for Meskerem 2016
$grid = MonthGrid::create(['year' => 2016, 'month' => 1, 'useGeez' => true, 'weekStart' => 0]);
print_r($grid['headers']);
// [እሑድ, ሰኞ, ማክሰኞ, ረቡዕ, ሐሙስ, ዓርብ, ቅዳሜ]
 
// Get info for a specific holiday
$gena = Holidays::getHoliday('gena', 2016);
echo $gena?->name; // ገና
 
// Get all holidays in a year
$allHolidays2016 = Holidays::getHolidaysForYear(2016);
echo count($allHolidays2016); // 23
 
// Or print an ASCII grid straight to the console
(new Kenat('2016/1/1'))->printThisMonth(true);

Advanced Features & Utilities

Kenat Static Methods

Kenat.now() — Returns a Kenat instance for the current date/time.
Kenat.getMonthCalendar(year, month, options) — Returns a calendar grid for a given month.
Kenat.getYearCalendar(year, options) — Returns a full year calendar.
Kenat.generateDateRange(startDate, endDate) — Returns an array of Kenat dates for a range.

Dart equivalent: the same static methods exist, but getMonthCalendar is named getStaticMonthCalendar on the Dart side (the instance already has its own differently-shaped getMonthCalendar, and Dart doesn’t allow a static and instance member to share a name):


final monthCalendar = Kenat.getStaticMonthCalendar(2017, 1, { 'useGeez': false });
final yearCalendar = Kenat.getYearCalendar(2017); // List of 13 month objects
final range = Kenat.generateDateRange(Kenat.fromEthiopian(2017, 1, 1), Kenat.fromEthiopian(2017, 1, 10));

PHP equivalent: same naming as Dart — getStaticMonthCalendar() for the same reason (the instance method getMonthCalendar() already exists with a different shape):


$monthCalendar = Kenat::getStaticMonthCalendar(2017, 1, ['useGeez' => false]);
$yearCalendar = Kenat::getYearCalendar(2017); // array of 13 month arrays
$range = Kenat::generateDateRange(new Kenat(['year' => 2017, 'month' => 1, 'day' => 1]), new Kenat(['year' => 2017, 'month' => 1, 'day' => 10]));

MonthGrid Usage

You can generate a month grid with holidays and weekday headers:


import { MonthGrid } from 'kenat';
const grid = new MonthGrid({ year: 2016, month: 1 });
console.log(grid.headers); // ['እሑድ', ...]
console.log(grid.days); // Array of day objects

Dart equivalent: MonthGrid.create() (or the createMonthGrid() shorthand) returns a Map<String, dynamic> rather than a class instance, and also includes 'up'/'down' closures for navigating months:


final grid = createMonthGrid({ 'year': 2016, 'month': 1 });
print(grid['headers']); // [ሰኞ, ማክሰኞ, ረቡዕ, ሐሙስ, ዓርብ, ቅዳሜ, እሑድ]
print(grid['days']);    // List<Map<String, dynamic>?> (padding entries are null)
 
final nextMonth = (grid['up'] as Function)();

PHP equivalent: MonthGrid::create() also returns a plain array, and also includes 'up'/'down' closures for navigating months:


$grid = MonthGrid::create(['year' => 2016, 'month' => 1]);
print_r($grid['headers']); // [ሰኞ, ማክሰኞ, ረቡዕ, ሐሙስ, ዓርብ, ቅዳሜ, እሑድ]
print_r($grid['days']);    // array<int, array|null> (padding entries are null)
 
$nextMonth = ($grid['up'])();

Holiday Filtering

All holiday functions support filtering by tags:


import { getHolidaysForYear, HolidayTags } from 'kenat';
const publicHolidays = getHolidaysForYear(2016, { filter: [HolidayTags.PUBLIC] });

Dart equivalent:


final publicHolidays = getHolidaysForYear(2016, { 'filter': [HolidayTags.public] });

PHP equivalent:


$publicHolidays = Holidays::getHolidaysForYear(2016, ['filter' => [HolidayTags::PUBLIC]]);

Geez Numeral Conversion

toGeez(number) — Converts numbers to Geez numerals.
toArabic(geezStr) — Converts Geez numerals to Arabic numbers.

Dart equivalent: identical names and behavior — toGeez(2016) → '፳፻፲፮', toArabic('፳፻፲፮') → 2016.

PHP equivalent: GeezConverter::toGeez()/GeezConverter::toArabic(), same behavior — GeezConverter::toGeez(2016) → '፳፻፲፮', GeezConverter::toArabic('፳፻፲፮') → 2016.

Date Validation & Utilities

isValidEthiopianDate(year, month, day) — Checks if a date is valid.
isEthiopianLeapYear(year) — Checks for leap years.
getWeekday({ year, month, day }) — Returns the weekday index.

Dart equivalent: same names, but as positional arguments rather than an options object:


isValidEthiopianDate(2016, 1, 5);      // true
isEthiopianLeapYear(2015);             // true
getWeekday(2016, 1, 5);                // 6

PHP equivalent: the same three checks live as static methods on Utils, also with positional arguments:


Utils::isValidEthiopianDate(2016, 1, 5);      // true
Utils::isEthiopianLeapYear(2015);             // true
Utils::getWeekday(['year' => 2016, 'month' => 1, 'day' => 5]); // 6

Error Classes

Kenat exports error classes for robust error handling:

InvalidEthiopianDateError
InvalidGregorianDateError
InvalidInputTypeError
InvalidTimeError
InvalidGridConfigError
UnknownHolidayError

Dart equivalent: the same six error classes exist (plus a couple of Dart-specific ones, like InvalidDateFormatError and UnrecognizedInputError), all extending a common KenatError and each exposing toJson() with a type field for structured logging.

PHP equivalent: the same six exceptions exist under Kenat\Exceptions as InvalidEthiopianDateException, InvalidGregorianDateException, InvalidInputTypeException, InvalidTimeException, InvalidGridConfigException, and UnknownHolidayException (plus InvalidDateFormatException, UnrecognizedInputException, and GeezConverterException), all extending a common KenatException.