aggie_unterprise API

This is the API documentation for aggie_unterprise. See the Github page for examples of usage and installation instructions.

API Reference

aggie_unterprise.aggie_unterprise

Summary dataclass

A summary of all the projects in the AggieEnterprise Excel file created by following these instructions.

Create a Summary object by calling Summary.from_file with the filename of the Excel file:

summary = Summary.from_file('2024-8-5.xlsx')

project_summaries instance-attribute

project_summaries: List[ProjectSummary]

A list of ProjectSummary's, one for each project found in the AggieEnterprise Excel file read by Summary.from_file

date_and_time instance-attribute

date_and_time: datetime

The date and time the summary was generated

date

date() -> date

The date of the summary

from_file staticmethod

from_file(fn: Union[str, Path], names_to_clean: dict[str | Pattern, str] | Callable[[str], str] | None = None, substrings_to_clean: Iterable[str] = (), suffixes_to_clean: Iterable[str] = ()) -> Summary

Read the Excel file named fn (alternately fn can be a pathlib.Path object) and return a list of summaries of projects in the file.

Parameters:

Name	Type	Description	Default
fn	Union[str, Path]	The filename (or pathlib.Path object) of the AggieExpense Excel file to read.	required
names_to_clean	dict[str | Pattern, str] | Callable[[str], str] | None	A dict or function mapping project names to "cleaner" (typcailly shorter) names. For example, if names_to_clean = {'David Doty ENGR COMPUTER SCIENCE PPM Only': 'CS PPM'}, then the project name "David Doty ENGR COMPUTER SCIENCE PPM Only" will be replaced with "CS PPM". This is more flexible than using substrings_to_clean or suffixes_to_clean since it allows arbitrary mappings of project names to cleaner names. Those parameters simply remove substrings or suffixes, respectively, from the project names. This parameter takes precedence over the other two. If a project name appears as a key in this dict, then that project name will not be processed by substrings_to_clean or suffixes_to_clean. The keys can either be strings or compiled regex patterns.	None
substrings_to_clean	Iterable[str]	A list of substrings to remove from the project names.	()
suffixes_to_clean	Iterable[str]	A list of substrings to remove from the project names, including the whole suffix following the substring.	()

Returns:

Type	Description
Summary	A Summary object containing the summaries of all the projects in the file.

table

table(tablefmt: str | TableFormat = 'rounded_outline', headers: Optional[Iterable[str]] = None, show_cents: bool = False) -> str

Return a representation of the summary as a string in tabular form.

Parameters:

Name	Type	Description	Default
tablefmt	str | TableFormat	The format of the table; see the Python package tabulate documentation for options.	'rounded_outline'
headers	Optional[Iterable[str]]	A list of headers to include in the table; must be a subset of {'Expenses', 'Salary', 'Travel', 'Supplies', 'Fringe', 'Fellowship', 'Indirect', 'Balance', 'Budget'} The headers will be displayed in the order they are given, so is also a way to reorder them from the default order even if you include all of them. If not specified, all headers will be included in the default order.	None
show_cents	bool	Whether to show cents in the output. If False, amounts will be rounded to the nearest dollar.	False

Returns:

Type	Description
str	A representation of the summary as a string in tabular form

diff_table

diff_table(summary_earlier: Summary, tablefmt: str | TableFormat = 'rounded_outline', headers: Optional[Iterable[str]] = None, show_cents: bool = False) -> str

Return a representation of the differences between this summary and summary_earlier.

Any project listed in one summary but not the other will be treated as though the other summary had a ProjectSummary object with all fields set to 0. For instance, if a new grant was added to the later summary, the row for that project will show all the fields as the amounts in the later summary. If a grant was removed from the later summary, the row for that project will show all the fields as the negative of the amounts in the earlier summary.

Parameters:

Name	Type	Description	Default
summary_earlier	Summary	The earlier Summary object to compare against	required
tablefmt	str | TableFormat	The format of the table; see the Python package tabulate documentation for options.	'rounded_outline'
headers	Optional[Iterable[str]]	A list of headers to include in the diff table; must be a subset of {'Expenses', 'Salary', 'Travel', 'Supplies', 'Fringe', 'Fellowship', 'Indirect', 'Balance'} (Note that 'Budget' is not included since it should always equal between two summaries.) The headers will be displayed in the order they are given, so is also a way to reorder them from the default order even if you include all of them. If not specified, all headers will be included in the default order.	None
show_cents	bool	Whether to show cents in the output. If False, amounts will be rounded to the nearest dollar.	False

Returns:

Type	Description
str	A representation of the summary of differences as a string in tabular form

year

year() -> int

The year of the summary (as an integer)

month

month() -> str

The month of the summary (as a string)

day

day() -> int

The day of the summary (as an integer)

ProjectSummary dataclass

Object summarizing a single project, with a name and several dollar amounts gathered from the AggieEnterprise Excel file when the ProjectSummary object is constructed when calling Summary.from_file.

project_name instance-attribute

project_name: str

Name of the project. Comes from the column "Project Name" if the project is sponsored (through an external grant) and from the column "Task/Subtask Name" if the project is internal.

balance class-attribute instance-attribute

balance: float = 0

The balance of the project. Comes from the column "Budget Balance (Budget – (Comm & Exp))".

budget class-attribute instance-attribute

budget: float = 0

The total budget of the project. Comes from the column "Budget".

expenses class-attribute instance-attribute

expenses: float = 0

The total expenses of the project. Comes from the column "Expenses" The other specific types of expenses (salary, travel, etc.) should add up to this number.

salary class-attribute instance-attribute

salary: float = 0

The salary expenses of the project. Comes from the column "Salaries and Wages" in the Detail worksheet.

travel class-attribute instance-attribute

travel: float = 0

The travel expenses of the project. Comes from the column "Travel" in the Detail worksheet.

supplies class-attribute instance-attribute

supplies: float = 0

The supplies expenses of the project. Comes from the column "Supplies / Services / Other Expenses" in the Detail worksheet.

fringe class-attribute instance-attribute

fringe: float = 0

The fringe benefits expenses of the project. Comes from the column "Fringe Benefits" in the Detail worksheet.

fellowship class-attribute instance-attribute

fellowship: float = 0

The fellowship and scholarships expenses of the project. Comes from the column "Fellowship & Scholarships" in the Detail worksheet.

equipment class-attribute instance-attribute

equipment: float = 0

The equipment expenses of the project. Comes from the column "Equipment & Facilities" in the Detail worksheet.

indirect class-attribute instance-attribute

indirect: float = 0

The indirect costs of the project. Comes from the column "Indirect Costs" in the Detail worksheet.

diff

diff(other: ProjectSummary) -> ProjectSummary

Return a new ProjectSummary object that is the difference between this ProjectSummary and other.

Parameters:

Name	Type	Description	Default
other	ProjectSummary	The other ProjectSummary object to compare against	required

Returns:

Type	Description
ProjectSummary	A new ProjectSummary object that is the difference between this ProjectSummary and other.

regex_matching_only

regex_matching_only(string: str) -> Pattern[str]

Convert a string to a compiled regular expression pattern that matches only that exact string.

Parameters:

Name	Type	Description	Default
string	str	The input string to convert	required

Returns:

Type	Description
Pattern[str]	Pattern[str]: A compiled regex pattern that will match only the exact input