Skip to content

Types Module

The solcadre.types module defines the core data structures for the Solcadre calendar: seasons, transitions, weekdays, solar phases, time-of-day helpers, and the Day/Week/Block/Year/Time objects.

types

Core data types for the Solcadre calendar system.

This module defines the fundamental enums and dataclasses that make up the calendar: seasons, transitions, weekdays, solar phases, time-of-day helpers, and the structural Day/Week/Block/Year objects.

Type Aliases

BlockType 

BlockType = Season | Transition

Type alias for either a Season or Transition, representing a calendar block.

Classes

Block dataclass 

Block(weeks, index)

Represents a block (season or transition) in the Solcadre calendar.

A block is either a Season (12 weeks) or a Transition (1-2 weeks).

Attributes:

Name Type Description
weeks list[Week]

List of Week objects that make up this block.
index Index

Block.Index locating this block within the calendar.
Attributes
end property 
end

Get the end datetime of this block.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the end of the last day of the block.
start property 
start

Get the start datetime of this block.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the start of the first day of the block.
type property 
type

Get the block type (season or transition).

Returns:

Name Type Description
BlockType BlockType

The Season or Transition enum value.
year_number property 
year_number

Get the year number (1-indexed) this block belongs to.

Returns:

Name Type Description
int int

The year number.
Classes
Index dataclass 
Index(year_of_calendar, block_of_year, block_of_calendar)

Indices locating this block within the Solcadre calendar.

Attributes:

Name Type Description
year_of_calendar int

Zero-based year index since the epoch.
block_of_year int

Zero-based block index within the year.
block_of_calendar int

Zero-based block index since the epoch.

Day dataclass 

Day(sunrise, sunset, next_sunrise, solar_event, index)

Represents a day in the Solcadre calendar.

A day is defined by its solar events (sunrise, sunset) and its position within the calendar structure (year, block, day of block).

Attributes:

Name Type Description
sunrise datetime

The datetime of sunrise for this day.
sunset datetime

The datetime of sunset for this day.
next_sunrise datetime

The datetime of sunrise for the next day.
solar_event SolarEvent | None

Optional SolarEvent that occurs on this day, if any.
index Index

Day.Index locating this day within the calendar.
Attributes
block_type property 
block_type

Get the block type (season or transition) this day belongs to.

Returns:

Name Type Description
BlockType BlockType

The Season or Transition this day is part of.
date property 
date

Get the date of this day.

Returns:

Name Type Description
date date

The date corresponding to this day's sunrise.
end property 
end

Get the end datetime of this day.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the end of the day.
start property 
start

Get the start datetime of this day.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the start of the day.
week_number property 
week_number

Get the week number (1-indexed) within the block.

Returns:

Name Type Description
int int

The week number within the current block.
weekday property 
weekday

Get the weekday for this day.

Returns:

Name Type Description
Weekday Weekday

The weekday enum value.
year_number property 
year_number

Get the year number (1-indexed) this day belongs to.

Returns:

Name Type Description
int int

The year number.
Classes
Index dataclass 
Index(year_of_calendar, block_of_year, week_of_block, day_of_week, day_of_calendar)

Indices locating this day within the Solcadre calendar.

Attributes:

Name Type Description
year_of_calendar int

Zero-based year index since the epoch.
block_of_year int

Zero-based block index within the year.
week_of_block int

Zero-based week index within the block.
day_of_week int

Zero-based weekday index (0 = Sunday).
day_of_calendar int

Zero-based day index since the epoch.

Hemisphere

Bases: Enum

Enumeration of the two hemispheres.

Used to determine how seasons are mapped based on geographic location.

Season

Bases: Enum

Enumeration of the four Solcadre seasons.

Attributes
number property 
number

Get the block number (1-indexed).

Returns:

Name Type Description
int

The block number (1-8).
Functions
flip 
flip()

Return the opposite season (180 degrees in the cycle).

Returns:

Name Type Description
Season

The season opposite to this one in the cycle.
Source code in src/solcadre/types.py 
38
39
40
41
42
43
44
def flip(self):
    """Return the opposite season (180 degrees in the cycle).

    Returns:
        Season: The season opposite to this one in the cycle.
    """
    return Season((self.value + 4) % 8)
next 
next()

Return the next transition that follows this season.

Returns:

Name Type Description
Transition

The transition that comes after this season.
Source code in src/solcadre/types.py 
46
47
48
49
50
51
52
def next(self):
    """Return the next transition that follows this season.

    Returns:
        Transition: The transition that comes after this season.
    """
    return Transition(self.value + 1)

SolarPhase

Bases: Enum

Whether a given moment in a Solcadre day is during daylight or night.

Attributes
abbreviation property 
abbreviation

Single-letter abbreviation for the phase.

Time dataclass 

Time(day, time_of_day)

A specific time point in the calendar.

TimeOfDay dataclass 

TimeOfDay(time, solar_phase)

Clock time within a day plus whether it is day or night.

Transition

Bases: Enum

Enumeration of the four Solcadre transitions.

Attributes
number property 
number

Get the block number (1-indexed).

Returns:

Name Type Description
int

The block number (1-8).
Functions
flip 
flip()

Return the opposite transition (180 degrees in the cycle).

Returns:

Name Type Description
Transition

The transition opposite to this one in the cycle.
Source code in src/solcadre/types.py 
74
75
76
77
78
79
80
def flip(self):
    """Return the opposite transition (180 degrees in the cycle).

    Returns:
        Transition: The transition opposite to this one in the cycle.
    """
    return Transition((self.value + 4) % 8)
next 
next()

Return the next season that follows this transition.

Returns:

Name Type Description
Season

The season that comes after this transition.
Source code in src/solcadre/types.py 
82
83
84
85
86
87
88
def next(self):
    """Return the next season that follows this transition.

    Returns:
        Season: The season that comes after this transition.
    """
    return Season((self.value + 1) % 8)

Week dataclass 

Week(days, index)

Represents a week in the Solcadre calendar.

A week consists of seven consecutive days within a block (season or transition).

Attributes:

Name Type Description
days list[Day]

List of seven Day objects that make up this week.
index Index

Week.Index locating this week within the calendar.
Attributes
block_type property 
block_type

Get the block type (season or transition) this week belongs to.

Returns:

Name Type Description
BlockType BlockType

The Season or Transition this week is part of.
end property 
end

Get the end datetime of this week.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the end of the last day of the week.
number property 
number

Get the week number (1-indexed) within the block.

Returns:

Name Type Description
int int

The week number within the current block.
start property 
start

Get the start datetime of this week.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the start of the first day of the week.
year_number property 
year_number

Get the year number (1-indexed) this week belongs to.

Returns:

Name Type Description
int int

The year number.
Classes
Index dataclass 
Index(year_of_calendar, block_of_year, week_of_block, week_of_calendar)

Indices locating this week within the Solcadre calendar.

Attributes:

Name Type Description
year_of_calendar int

Zero-based year index since the epoch.
block_of_year int

Zero-based block index within the year.
week_of_block int

Zero-based week index within the block.
week_of_calendar int

Zero-based week index since the epoch.

Weekday

Bases: Enum

Enumeration of the seven days of the week.

The weekdays are numbered starting from Sunday (0) through Saturday (6).

Attributes
number property 
number

Get the weekday number (1-indexed).

Returns:

Name Type Description
int

The weekday number (1-7, where 1 is Sunday).
Functions
from_datetime staticmethod 
from_datetime(datetime)

Create a Weekday from a datetime object.

Parameters:

Name Type Description Default
datetime

A datetime object to extract the weekday from.

 required

Returns:

Name Type Description
Weekday

The weekday corresponding to the given datetime.
Source code in src/solcadre/types.py 
127
128
129
130
131
132
133
134
135
136
137
@staticmethod
def from_datetime(datetime):
    """Create a Weekday from a datetime object.

    Args:
        datetime: A datetime object to extract the weekday from.

    Returns:
        Weekday: The weekday corresponding to the given datetime.
    """
    return Weekday((datetime.weekday() + 1) % 7)

Year dataclass 

Year(blocks, index)

Represents a year in the Solcadre calendar.

A year consists of a sequence of blocks (seasons and transitions), starting with GREENTIDE season and ending with the VERNAL_EQUINOX transition.

Attributes:

Name Type Description
blocks list[Block]

List of Block objects (seasons and transitions) that make up this year.
index Index

Year.Index locating this year within the calendar.
Attributes
end property 
end

Get the end datetime of this year.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the end of the last day of the year.
number property 
number

Get the year number (1-indexed).

Returns:

Name Type Description
int int

The year number.
start property 
start

Get the start datetime of this year.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the start of the first day of the year.
Classes
Index dataclass 
Index(year_of_calendar)

Indices locating this year within the Solcadre calendar.

Attributes:

Name Type Description
year_of_calendar int

Zero-based year index since the epoch.

Enumerations

Season

Bases: Enum

Enumeration of the four Solcadre seasons.

Attributes

number property 

number

Get the block number (1-indexed).

Returns:

Name Type Description
int

The block number (1-8).

Functions

flip 

flip()

Return the opposite season (180 degrees in the cycle).

Returns:

Name Type Description
Season

The season opposite to this one in the cycle.
Source code in src/solcadre/types.py 
38
39
40
41
42
43
44
def flip(self):
    """Return the opposite season (180 degrees in the cycle).

    Returns:
        Season: The season opposite to this one in the cycle.
    """
    return Season((self.value + 4) % 8)

next 

next()

Return the next transition that follows this season.

Returns:

Name Type Description
Transition

The transition that comes after this season.
Source code in src/solcadre/types.py 
46
47
48
49
50
51
52
def next(self):
    """Return the next transition that follows this season.

    Returns:
        Transition: The transition that comes after this season.
    """
    return Transition(self.value + 1)

Transition

Bases: Enum

Enumeration of the four Solcadre transitions.

Attributes

number property 

number

Get the block number (1-indexed).

Returns:

Name Type Description
int

The block number (1-8).

Functions

flip 

flip()

Return the opposite transition (180 degrees in the cycle).

Returns:

Name Type Description
Transition

The transition opposite to this one in the cycle.
Source code in src/solcadre/types.py 
74
75
76
77
78
79
80
def flip(self):
    """Return the opposite transition (180 degrees in the cycle).

    Returns:
        Transition: The transition opposite to this one in the cycle.
    """
    return Transition((self.value + 4) % 8)

next 

next()

Return the next season that follows this transition.

Returns:

Name Type Description
Season

The season that comes after this transition.
Source code in src/solcadre/types.py 
82
83
84
85
86
87
88
def next(self):
    """Return the next season that follows this transition.

    Returns:
        Season: The season that comes after this transition.
    """
    return Season((self.value + 1) % 8)

Weekday

Bases: Enum

Enumeration of the seven days of the week.

The weekdays are numbered starting from Sunday (0) through Saturday (6).

Attributes

number property 

number

Get the weekday number (1-indexed).

Returns:

Name Type Description
int

The weekday number (1-7, where 1 is Sunday).

Functions

from_datetime staticmethod 

from_datetime(datetime)

Create a Weekday from a datetime object.

Parameters:

Name Type Description Default
datetime

A datetime object to extract the weekday from.

 required

Returns:

Name Type Description
Weekday

The weekday corresponding to the given datetime.
Source code in src/solcadre/types.py 
127
128
129
130
131
132
133
134
135
136
137
@staticmethod
def from_datetime(datetime):
    """Create a Weekday from a datetime object.

    Args:
        datetime: A datetime object to extract the weekday from.

    Returns:
        Weekday: The weekday corresponding to the given datetime.
    """
    return Weekday((datetime.weekday() + 1) % 7)

SolarPhase

Bases: Enum

Whether a given moment in a Solcadre day is during daylight or night.

Attributes

abbreviation property 

abbreviation

Single-letter abbreviation for the phase.

Hemisphere

Bases: Enum

Enumeration of the two hemispheres.

Used to determine how seasons are mapped based on geographic location.

Helpers

block_type_from_index 

block_type_from_index(block_index)
Source code in src/solcadre/types.py 
107
108
109
110
111
def block_type_from_index(block_index: int) -> BlockType:
    if block_index % 2 == 0:
        return Season(block_index)
    else:
        return Transition(block_index)

Time Helpers

TimeOfDay dataclass 

TimeOfDay(time, solar_phase)

Clock time within a day plus whether it is day or night.

Time dataclass 

Time(day, time_of_day)

A specific time point in the calendar.

Calendar Structures

Day dataclass 

Day(sunrise, sunset, next_sunrise, solar_event, index)

Represents a day in the Solcadre calendar.

A day is defined by its solar events (sunrise, sunset) and its position within the calendar structure (year, block, day of block).

Attributes:

Name Type Description
sunrise datetime

The datetime of sunrise for this day.
sunset datetime

The datetime of sunset for this day.
next_sunrise datetime

The datetime of sunrise for the next day.
solar_event SolarEvent | None

Optional SolarEvent that occurs on this day, if any.
index Index

Day.Index locating this day within the calendar.

Attributes

block_type property 

block_type

Get the block type (season or transition) this day belongs to.

Returns:

Name Type Description
BlockType BlockType

The Season or Transition this day is part of.

date property 

date

Get the date of this day.

Returns:

Name Type Description
date date

The date corresponding to this day's sunrise.

end property 

end

Get the end datetime of this day.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the end of the day.

start property 

start

Get the start datetime of this day.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the start of the day.

week_number property 

week_number

Get the week number (1-indexed) within the block.

Returns:

Name Type Description
int int

The week number within the current block.

weekday property 

weekday

Get the weekday for this day.

Returns:

Name Type Description
Weekday Weekday

The weekday enum value.

year_number property 

year_number

Get the year number (1-indexed) this day belongs to.

Returns:

Name Type Description
int int

The year number.

Classes

Index dataclass 

Index(year_of_calendar, block_of_year, week_of_block, day_of_week, day_of_calendar)

Indices locating this day within the Solcadre calendar.

Attributes:

Name Type Description
year_of_calendar int

Zero-based year index since the epoch.
block_of_year int

Zero-based block index within the year.
week_of_block int

Zero-based week index within the block.
day_of_week int

Zero-based weekday index (0 = Sunday).
day_of_calendar int

Zero-based day index since the epoch.

Week dataclass 

Week(days, index)

Represents a week in the Solcadre calendar.

A week consists of seven consecutive days within a block (season or transition).

Attributes:

Name Type Description
days list[Day]

List of seven Day objects that make up this week.
index Index

Week.Index locating this week within the calendar.

Attributes

block_type property 

block_type

Get the block type (season or transition) this week belongs to.

Returns:

Name Type Description
BlockType BlockType

The Season or Transition this week is part of.

end property 

end

Get the end datetime of this week.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the end of the last day of the week.

number property 

number

Get the week number (1-indexed) within the block.

Returns:

Name Type Description
int int

The week number within the current block.

start property 

start

Get the start datetime of this week.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the start of the first day of the week.

year_number property 

year_number

Get the year number (1-indexed) this week belongs to.

Returns:

Name Type Description
int int

The year number.

Classes

Index dataclass 

Index(year_of_calendar, block_of_year, week_of_block, week_of_calendar)

Indices locating this week within the Solcadre calendar.

Attributes:

Name Type Description
year_of_calendar int

Zero-based year index since the epoch.
block_of_year int

Zero-based block index within the year.
week_of_block int

Zero-based week index within the block.
week_of_calendar int

Zero-based week index since the epoch.

Block dataclass 

Block(weeks, index)

Represents a block (season or transition) in the Solcadre calendar.

A block is either a Season (12 weeks) or a Transition (1-2 weeks).

Attributes:

Name Type Description
weeks list[Week]

List of Week objects that make up this block.
index Index

Block.Index locating this block within the calendar.

Attributes

end property 

end

Get the end datetime of this block.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the end of the last day of the block.

start property 

start

Get the start datetime of this block.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the start of the first day of the block.

type property 

type

Get the block type (season or transition).

Returns:

Name Type Description
BlockType BlockType

The Season or Transition enum value.

year_number property 

year_number

Get the year number (1-indexed) this block belongs to.

Returns:

Name Type Description
int int

The year number.

Classes

Index dataclass 

Index(year_of_calendar, block_of_year, block_of_calendar)

Indices locating this block within the Solcadre calendar.

Attributes:

Name Type Description
year_of_calendar int

Zero-based year index since the epoch.
block_of_year int

Zero-based block index within the year.
block_of_calendar int

Zero-based block index since the epoch.

Year dataclass 

Year(blocks, index)

Represents a year in the Solcadre calendar.

A year consists of a sequence of blocks (seasons and transitions), starting with GREENTIDE season and ending with the VERNAL_EQUINOX transition.

Attributes:

Name Type Description
blocks list[Block]

List of Block objects (seasons and transitions) that make up this year.
index Index

Year.Index locating this year within the calendar.

Attributes

end property 

end

Get the end datetime of this year.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the end of the last day of the year.

number property 

number

Get the year number (1-indexed).

Returns:

Name Type Description
int int

The year number.

start property 

start

Get the start datetime of this year.

Returns:

Name Type Description
datetime datetime

The sunrise datetime marking the start of the first day of the year.

Classes

Index dataclass 

Index(year_of_calendar)

Indices locating this year within the Solcadre calendar.

Attributes:

Name Type Description
year_of_calendar int

Zero-based year index since the epoch.