Getting Started

Kenat helps you create and manipulate Ethiopian dates using the intuitive Kenat class. It supports creating dates from various sources and lets you easily switch between Ethiopian and Gregorian formats.

Creating a New Date Instance

The Kenat constructor is flexible. Here are the ways you can create a new date.

Supported Input Types & Error Handling

Kenat automatically detects the type of input you provide:

No arguments: Uses the current system date.
String: Accepts YYYY/MM/DD or YYYY-MM-DD format (Ethiopian or Gregorian).
Date object: Accepts native JavaScript Date or Python datetime objects.
Numbers: Pass year, month, and day as separate numbers.

If you provide an invalid date (e.g., out-of-range month/day, wrong format), Kenat will throw an error describing the issue.

Time Support

You can optionally pass time information (hour, minute, period) when creating a date:

undefined


// Use 'day' or 'night' for the period property
const withTime = new Kenat(2017, 10, 5, { hour: 3, minute: 30, period: 'day' });
// or
const withTimeNight = new Kenat(2017, 10, 5, { hour: 3, minute: 30, period: 'night' });

undefined


// Dart doesn't take year/month/day as separate constructor args — pass a
// Time object as the second argument to fromEthiopian() instead.
// Use 'day' or 'night' for the period property.
final withTime = Kenat.fromEthiopian(2017, 10, 5, Time(3, 30, 'day'));
// or
final withTimeNight = Kenat.fromEthiopian(2017, 10, 5, Time(3, 30, 'night'));
 
print(withTime.formatWithTime());      // ሰኔ 5 2017 03:30 ጠዋት
print(withTimeNight.formatWithTime()); // ሰኔ 5 2017 03:30 ማታ

undefined


# Use 'day' or 'night' for the period property
with_time = Kenat(2017, 10, 5, hour=3, minute=30, period='day')
# or
with_time_night = Kenat(2017, 10, 5, hour=3, minute=30, period='night')

undefined


use Kenat\Kenat;
 
// PHP's constructor takes an array/EthiopianDate/string, not separate
// y/m/d args — pass the date array and a time array together.
// Use 'day' or 'night' for the period property.
$withTime = new Kenat(
    ['year' => 2017, 'month' => 10, 'day' => 5],
    ['hour' => 3, 'minute' => 30, 'period' => 'day']
);
// or
$withTimeNight = new Kenat(
    ['year' => 2017, 'month' => 10, 'day' => 5],
    ['hour' => 3, 'minute' => 30, 'period' => 'night']
);
 
echo $withTime->format(['includeTime' => true]);      // ሰኔ 5 2017 03:30 ጠዋት
echo $withTimeNight->format(['includeTime' => true]); // ሰኔ 5 2017 03:30 ማታ

Language Option

Most methods accept a lang option to choose between Amharic and English output. Example:

undefined


today.getEthiopian({ lang: 'english' })

undefined


// getEthiopian() itself has no lang option in Dart — the language
// choice lives on the formatting methods instead.
today.formatStandard('english'); // e.g. "Hamle 4 2018"

undefined


today.get_ethiopian(lang='english')

undefined


// getEthiopian() returns a plain EthiopianDate value object with no lang
// option in PHP either — the language choice lives on format() instead.
$today->format(['lang' => 'english']); // e.g. "Hamle 4 2018"

Output Types

Date methods like getEthiopian() and getGregorian() return plain objects, not Kenat instances.

From the Current Date

If you create a Kenat instance with no arguments, it will automatically represent the current system date.

undefined


import Kenat from 'kenat';
 
const today = new Kenat(); 
 
console.log('ET:', today.getEthiopian());
// Example Output ET: { year: 2017, month: 10, day: 5 }
 
console.log('GC:', today.getGregorian());
// Example Output GC: { year: 2025, month: 6, 13 }

undefined


import 'package:kenat/kenat.dart';
 
void main() {
  final today = Kenat.now();
 
  print('ET: ${today.getEthiopian()}');
  // Example Output ET: {year: 2018, month: 11, day: 4}
 
  print('GC: ${today.getGregorian()}');
  // Example Output GC: {year: 2026, month: 7, day: 11}
}

undefined


from kenat import Kenat
 
today = Kenat()
 
print('ET:', today.get_ethiopian())
# Example Output ET: { 'year': 2017, 'month': 10, 'day': 5 }
 
print('GC:', today.get_gregorian())
# Example Output GC: { 'year': 2025, 'month': 6, 'day': 13 }

undefined


use Kenat\Kenat;
 
$today = new Kenat();
 
// getEthiopian()/getGregorian() return typed EthiopianDate/GregorianDate
// value objects, not arrays — access fields directly.
echo "ET: {$today->getEthiopian()->year}-{$today->getEthiopian()->month}-{$today->getEthiopian()->day}";
// Example Output ET: 2018-11-4
 
$gc = $today->getGregorian();
echo "GC: {$gc->year}-{$gc->month}-{$gc->day}";
// Example Output GC: 2026-7-12

From a String

You can create a date from a string in YYYY/MM/DD or YYYY-MM-DD format.

undefined


const customDate = new Kenat('2016/10/05');
 
console.log(customDate.getGregorian());
// Output: { year: 2024, month: 6, day: 13 }

undefined


final customDate = Kenat('2016/10/05');
 
print(customDate.getGregorian());
// Output: {year: 2024, month: 6, day: 12}

undefined


from kenat import Kenat
 
custom_date = Kenat('2016/10/05')
 
print(custom_date.get_gregorian())
# Output: { 'year': 2024, 'month': 6, 'day': 13 }

undefined


use Kenat\Kenat;
 
$customDate = new Kenat('2016/10/05');
 
$gc = $customDate->getGregorian();
echo "{$gc->year}-{$gc->month}-{$gc->day}";
// Output: 2024-6-13

From a Native Date Object

You can pass a native date object directly to the constructor: a JavaScript Date, a Python datetime, or a Dart DateTime.

undefined


const gcDate = new Date('2024-08-22');
const fromDate = new Kenat(gcDate);
 
console.log(fromDate.getEthiopian());
// Output: { year: 2016, month: 12, day: 13 }

undefined


// Unlike JS's Date, Dart's DateTime months are already 1-based
// (August = 8), so there's no off-by-one to worry about.
final gcDate = DateTime(2024, 8, 22);
final fromDate = Kenat(gcDate);
 
print(fromDate.getEthiopian());
// Output: {year: 2016, month: 12, day: 16}

undefined


from datetime import datetime
from kenat import Kenat
 
gc_date = datetime(2024, 8, 22)
from_date = Kenat(gc_date)
 
print(from_date.get_ethiopian())
# Output: { 'year': 2016, 'month': 12, 'day': 13 }

undefined


use Kenat\Kenat;
use DateTimeImmutable;
 
// Accepts any DateTimeInterface (DateTime or DateTimeImmutable)
$gcDate = new DateTimeImmutable('2024-08-22');
$fromDate = new Kenat($gcDate);
 
$et = $fromDate->getEthiopian();
echo "{$et->year}-{$et->month}-{$et->day}";
// Output: 2016-12-13

From Individual Components

You can create a date by passing the year, month, and day as separate numbers.

undefined


const fromComponents = new Kenat(2016, 1, 1);
 
console.log(fromComponents.getGregorian());
// Output: { year: 2023, month: 9, day: 11 }

undefined


// Dart's plain constructor takes a single Ethiopian map/string/DateTime,
// not separate y/m/d args — use the fromEthiopian() factory instead.
final fromComponents = Kenat.fromEthiopian(2016, 1, 1);
 
print(fromComponents.getGregorian());
// Output: {year: 2023, month: 9, day: 12}

undefined


from kenat import Kenat
 
from_components = Kenat(2016, 1, 1)
 
print(from_components.get_gregorian())
# Output: { 'year': 2023, 'month': 9, 'day': 11 }

undefined


use Kenat\Kenat;
 
// PHP's constructor also takes a single Ethiopian array, not separate
// y/m/d args.
$fromComponents = new Kenat(['year' => 2016, 'month' => 1, 'day' => 1]);
 
$gc = $fromComponents->getGregorian();
echo "{$gc->year}-{$gc->month}-{$gc->day}";
// Output: 2023-9-11

Working with Holidays

Kenat also provides functions to get holidays for a given year.

undefined


import { getHolidaysForYear, HolidayTags } from 'kenat';
 
const year = 2017; // E.C.
 
// Get only public holidays by passing a single tag.
const publicHolidays = getHolidaysForYear(year, {
    filter: HolidayTags.PUBLIC
});
 
console.log(`Found ${publicHolidays.length} public holidays in ${year} E.C.`);
// Expected: Lists all holidays tagged as 'public'.

undefined


import 'package:kenat/kenat.dart';
 
void main() {
  final year = 2017; // E.C.
 
  // Get only public holidays by passing a single tag.
  final publicHolidays = getHolidaysForYear(year, {
    'filter': HolidayTags.public,
  });
 
  print('Found ${publicHolidays.length} public holidays in $year E.C.');
  // Found 15 public holidays in 2017 E.C.
}

undefined


from kenat import get_holidays_for_year, HolidayTags
 
year = 2017 # E.C.
 
# Get only public holidays by passing a single tag.
public_holidays = get_holidays_for_year(year, filter_by=HolidayTags.PUBLIC)
 
print(f"Found {len(public_holidays)} public holidays in {year} E.C.")
# Expected: Lists all holidays tagged as 'public'.

undefined


use Kenat\Holidays;
use Kenat\HolidayTags;
 
$year = 2017; // E.C.
 
// Get only public holidays by passing a single tag.
$publicHolidays = Holidays::getHolidaysForYear($year, [
    'filter' => HolidayTags::PUBLIC,
]);
 
echo "Found " . count($publicHolidays) . " public holidays in {$year} E.C.";
// Found 15 public holidays in 2017 E.C.