historia.project#

Functions

add_to_project(*, directory, project_url[, ...])

Add all unique URLs from the derivatives directory to a GitHub Project (v2).

create_project_page(*, owner, title)

Create a GitHub Project (v2) page for the specified owner.

get_project_closing_workflows(project_url, /)

Return the names of enabled project workflows that close the underlying GitHub items when status changes.

transition_status(*, project_url, ...)

Move all items with one Status value to another in a GitHub Project (v2).

update_project_item_dates(*, project_url[, ...])

Update the start and end date fields on all items already added to a GitHub Project (v2).

update_project_item_members(*, project_url)

Update the Members text field on all items already added to a GitHub Project (v2).
historia.project.add_to_project(
*,
directory: Path,
project_url: str,
status: str | None = None,
end_date_placeholder_days: int = 180,
assign_members: bool = False,
) → None[source]#

Add all unique URLs from the derivatives directory to a GitHub Project (v2).

Items that are already present in the project are automatically skipped.

For each new item:

  • If status is provided, all items are assigned that status value.

  • Otherwise, the status is derived from the item type and state: - If the Issue or PR is closed, it is given the ‘Done’ status. - If the item is an open PR, it is given the ‘In Progress’ status. - If the item is an open Issue, it is given the ‘Todo’ status.

  • The start date is set to the item’s creation date.

  • The end date is set to the item’s closed date (if closed), or to end_date_placeholder_days days after the creation date otherwise.

Parameters:

  • directory (pathlib.Path) – The directory containing the derivatives JSON files. Should be a specific username subdirectory, e.g., /path/to/version-1/username-codycbakerphd. If a parent directory with multiple version-* subdirectories is provided, only the latest version is used and a warning is emitted.

  • project_url (str) – The URL of the GitHub Project v2 to add items to, e.g., https://github.com/users/username/projects/1 or https://github.com/orgs/orgname/projects/1.

  • status (str or None, optional) – A custom status value to apply uniformly to all items added to the project. If None (the default), the status is derived from each item’s type and state.

  • end_date_placeholder_days (int, optional) – Number of days after the item’s creation date to use as the placeholder end date when the item has not yet been closed. Default is 180 (approximately 6 months).

  • assign_members (bool, optional) – When True, update the project’s custom Members text field using usernames inferred from username-* directory names in the data tree.

historia.project.create_project_page(*, owner: str, title: str) → dict[str, str][source]#

Create a GitHub Project (v2) page for the specified owner.

Parameters:

  • owner (str) – The GitHub user or organization login under which to create the project.

  • title (str) – The title of the new GitHub Project.

Returns:

A dictionary containing the "id" and "url" of the created project. Returns an empty dictionary if the GitHub API rate limit was hit (HTTP 403); a warning is also issued in that case.

Return type:

dict[str, str]

historia.project.get_project_closing_workflows(project_url: str, /) → list[str][source]#

Return the names of enabled project workflows that close the underlying GitHub items when status changes.

Parameters:

project_url (str) – The URL of the GitHub Project v2, e.g., https://github.com/users/username/projects/1 or https://github.com/orgs/orgname/projects/1.

Returns:

Names of enabled workflows whose names indicate they close underlying items (e.g., Auto-close issue). Returns an empty list when no such workflows are enabled.

Return type:

list[str]

Raises:

ValueError – If the GITHUB_TOKEN environment variable is not set.

historia.project.transition_status(*, project_url: str, current_status: str, new_status: str) → None[source]#

Move all items with one Status value to another in a GitHub Project (v2).

Parameters:

  • project_url (str) – The URL of the GitHub Project v2, e.g., https://github.com/users/username/projects/1 or https://github.com/orgs/orgname/projects/1.

  • current_status (str) – The current Status value to match.

  • new_status (str) – The destination Status value to apply.

Raises:

ValueError – If the GITHUB_TOKEN environment variable is not set, or if the project does not have one of the specified status options.

historia.project.update_project_item_dates(
*,
project_url: str,
end_date_placeholder_days: int = 180,
) → None[source]#

Update the start and end date fields on all items already added to a GitHub Project (v2).

For each item in the project:

  • The start date field (“Start date”) is set to the item’s creation date.

  • The end date field (“End date”) is set to the item’s closed date (if closed), or to end_date_placeholder_days days after the creation date otherwise.

If the project does not have a “Start date” or “End date” field, those updates are skipped.

Parameters:

  • project_url (str) – The URL of the GitHub Project v2, e.g., https://github.com/users/username/projects/1 or https://github.com/orgs/orgname/projects/1.

  • end_date_placeholder_days (int, optional) – Number of days after the item’s creation date to use as the placeholder end date when the item has not yet been closed. Default is 180 (approximately 6 months).

historia.project.update_project_item_members(*, project_url: str) → None[source]#

Update the Members text field on all items already added to a GitHub Project (v2).

Member attribution is inferred from assignee usernames and pull request reviewer usernames. Items without assignees or reviewers are skipped.

Parameters:

project_url (str) – The URL of the GitHub Project v2, e.g., https://github.com/users/username/projects/1 or https://github.com/orgs/orgname/projects/1.