Perennial reference¶

Journal¶

Perennial journals can record text and mood entries with Journal.record(). Journal entries may also be associated with a file — such as a Markdown file representing a more comprehensive journal entry, or even a directory of another perennial journal. Streaks are automatically tallied. The default mode to track streak is weekly.

class perennial.Journal(content=None, *, file=None, streak_mode=StreakCheck.WEEKLY, template=None)¶

Represents a journal

Parameters:

content (Optional[str]) – Name or description of this journal

Keyword Arguments:

  • file – Path to the journal’s SQLite database or the path to the journal’s directory that contains the SQLite database. The database is initialized if it does not already exist.

  • streak_mode – The function that computes the streak number given two datetimes and a running streak.

when¶

When this journal was created

content¶

Name or description of this journal

file¶

Path to the SQLite database

streak_mode¶

The streak mode, as saved in the database

template¶

Path to a template file to use for new journal entries

directory¶

Path containing the journal (readonly)

db¶

SQLite database connection (readonly)

Tip

Iterate through the journal entries with for entry in journal

goal(name, state=None, *, when=None)¶

Get or set goal state

Parameters:

  • name (str) – Name of goal (must be exact)

  • state (Optional) – State to assign to goal. If not provided, the current goal state is returned instead.

  • when (Optional) – The date to set or get the goal state. If not provided, uses today’s date.

Raises:

ZeroEntriesFound – if the goal provided was not found in the goals table

Return type:

Goal

Returns:

Optional[str]

for ... in goals(all=False)¶

Iterate through goals

Parameters:

all – Default False, iterate only through the most recent goal states. If True, iterate through all goals items recorded in this journal.

Return type:

Generator[Goal, None, None]

goals_in_state(state, *, start_date=None, end_date=None)¶

Return set of all goals currently in the given state

Parameters:

  • state (str) – State of goals to look for

  • start_date (Optional) – Earliest date to look through journal. If not provided, uses date of earliest journal entry.

  • end_date (Optional) – Latest date to look through journal. If not provided, uses today’s date.

Return type:

set[Goal]

random()¶

Retrieve a single random journal entry

Todo: add start_date and end_date kwargs

Raises:

ZeroEntriesFound – when there are no journal entries yet

Return type:

Entry

record(content=None, *, mood=None, when=None, file=None)¶

Record a journal entry

Return type:

Entry

Returns:

Entry

search(search_term=None, *, start_date=None, end_date=None)¶

Retrieve journal entries (optionally containing a specified search term)

Parameters:

  • search_term (Optional) – Search term to look for. If not provided, returns all entries.

  • start_date (Optional) – Earliest date to search. If not provided, uses date of earliest journal entry.

  • end_date (Optional) – Latest date to search. If not provided, uses today’s date.

Return type:

list[Entry]

Note

Iterate through the journal directly if you want all entries.

streak(when=None)¶

Get streak for given date

Parameters:

when (Optional) – Date to look up streak. If not provided, uses today’s date.

Return type:

int

sync()¶

Synchronize the streak column of the journal entries

time_in_state(name, state, *, start_date=None, end_date=None)¶

Tallies up the total time a goal has been in a given state

Parameters:

  • name (str) – Name of goal (must be exact)

  • state (str) – State of goal

Keyword Arguments:

  • start_date – Earliest date to look through journal. If not provided, uses date of earliest journal entry.

  • end_date – Latest date to look through journal. If not provided, uses today’s date.

Return type:

timedelta

Returns:

timedelta

Entry¶

Use Journal.record() to record new entries, and search or iterate through a journal (for entry in journal: ...) to retrieve previous entries.

class perennial.Entry(when, content, file, mood, streak)¶

Represents a journal entry

when¶

Date of journal entry

content¶

Journal entry summary

file¶

Associated file, if any, as a relative path

mood¶

Mood level

streak¶

Daily streak

Goal¶

Use Journal.goal() to set or get the states of goals. Journal.time_in_state() returns the amount of time a goal has been in a state (optionally given a time range). Use Journal.goals() to iterate through the current states of goals. And use Journal.goals_in_state() to lookup which goals are in a given state.

class perennial.Goal(when, name, state)¶

Represents a goal and its state

when¶

Date of goal state entry

name¶

Exact name of goal

state¶

State of goal

StreakCheck¶

class perennial.StreakCheck(value)¶

An enumeration.

Different ways to keep track of a journaling streak. While a daily streak can keep an individual pressured to maintain consistency every day, missing only a single day then feels demotivating. Changing the perspective to a weekly, monthly, or yearly streak can help bring back motivation by allowing flexibility, leniency, and time to slow down.

DAILY = 'daily'¶

Represents keeping a daily streak, like Duolingo.

WEEKLY = 'weekly'¶

Represents keeping a journal streak, week-to-week, like weekly check-ins or self-care nights.

MONTHLY = 'monthly'¶

Represents keeping a journal streak by month, like tracking menstrual cycles.

YEARLY = 'yearly'¶

Represents keeping a streak on a yearly basis, like New Year’s resolutions.

Exceptions¶

class perennial.PerennialException¶

Base class for all perennial exceptions

class perennial.ZeroEntriesFound¶

Raised when no entries were found in the entries or goals table